Handoff — HighwayData XML schema 1.1: downstream decomposer

Continuation target

The XML is the only agreed interface between the ioLabs detection pipeline and HBW's Grasshopper script (spec R-1.1.1). Both sides are implemented independently; do not invent side channels.

Current state (producer side)

• done Writer implements schema 1.1 in full: src/iolabs_point_cloud_modelling_export/write_xml.py (create_xml + prettify_xml) and feature_classes.py (Profile, PROFILES, builders, check_profiles).
• verified 1064 tests pass (producer repo test suite).
• verified Byte-identity guarantee (R-2.4.1): for a producer dict containing no 1.1 key, 1.1 output equals the 0.9.0 output except for one inserted line <SchemaVersion>1.1</SchemaVersion> as the last child of MetaData. The example builder re-asserts this on real run7 data every time it runs.
• done Example document built from real pipeline output + synthetic coverage of 26 of the 28 §7.1 classes and every 1.1 element (see Verification).
• Branch ai3d-376-xml-schema-1-1, HEAD 44428b8 (was c8e0c8b before this handoff's spec-HTML sync commit). History since 67047e6 (v0.9.0 release): S1 compat+SchemaVersion → S2 Feature+Point → S3 Polyline/Spline/Line → S4 profiles+fixture+docs → adversarial-review fixes → example XML.
• not yet pyproject.toml still says version = "0.9.0"; release 0.10.0 is not cut. Nothing consumer-visible depends on that, but the package you get from Nexus today is still the 1.0 writer.
• Spec status: draft for review, 2026-08-28 revision 2. It is stable in structure; only the informative notes have moved recently (latest: N-8.8.4, numpy scalars).

Document structure & ordering guarantees

HighwayData
├─ MetaData            CreationDate, Source, SoftwareVersion, PipelineVersions?, SchemaVersion
├─ Geoshift?           X, Y, Z
└─ Features
   └─ Feature*         Type, ID, LaneID,
                       Lines,     NumberOfLines,
                       Points,    NumberOfPoints,
                       Polylines, NumberOfPolylines,
                       Splines,   NumberOfSplines,
                       Attributes?

• Child order is normative (R-3.1) and a consumer MAY rely on it — but parse by name, not by index. The one moving slot: Polyline/Type sits immediately after Polyline/LaneID (R-2.3.2), so Polyline child index 2 is not reliably RoadPoint. Every other NEW element is appended after all 1.0 children of its parent (R-2.3.1).
• All four containers and their four NumberOf* siblings are always emitted, interleaved as shown, empty (<Lines/>) and 0 when unused (R-2.2.1, R-3.3). NumberOf* equals the count in the preceding container (R-3.4) — cheap sanity check.
• No XML namespaces. No attributes except: Step/@name @date, SegmentRange/@segments @date, Package/@name @version, Attribute/@name @type, Shape/@role @type (R-3.6). No mixed content: every element is element-only or text-only (R-3.5).
• UTF-8, declaration <?xml version="1.0" encoding="UTF-8"?>, two-space pretty-printed, non-ASCII (ä ö ü ß Ø ⌀) as literal UTF-8, never character references (R-5.3.1–3).
• Version: MetaData/SchemaVersion is text 1.1, matching ^[0-9]+\.[0-9]+$. Absent ⇒ treat the document as schema 1.0 (R-2.1.2). A minor bump is additive; treat an unknown minor as 1.1 + ignorable extras, a major bump as unsupported.
• Coordinates are metres in the geoshifted local right-handed export frame. Absolute coordinate = export value + the matching Geoshift/X|Y|Z. Geoshift is optional.
• There is no Feature/Layer (R-2.2.4). The CAD layer is a drawing artefact the consumer derives from Feature/Type — informative mapping in spec Appendix C (Tree → PLC_Laubbaum, Fence → pPLC_Zaun, Cross Section → PLC_Punkte_Symbole, …). Pedestrian Road is the one class whose layer also depends on the container used (Polylines → pPLC_Gehweg, Splines → sPLC_Gehweg, R-7.12.1). Layer names are unconfirmed with HBW (O-21) — keep the table in one swappable lookup.
• Feature/Type is the only class key (R-2.5.1); dispatch on it, never on Point/FeatureClass. It is an open vocabulary — the writer never validates it, so new classes can appear without a writer release. Unknown Type ⇒ decompose generically, don't crash.

Per-element parsing rules

Scalars

• Numbers: Python str(value) output — no fixed precision, no padding, no localisation. You will see 0.1, 1.0, 12, -40.199348933220996. Decimal separator is always . in numeric elements (R-5.1.4). Parse with a plain float parse; never assume decimals. A decimal comma is legal only inside Annotation/Text (display strings, e.g. Ø= 0,30/7,0m).
• Booleans: exactly lower-case true / false (R-5.2.1). True, 1, yes are not valid and need not be accepted.
• Text: the writer never trims. Strip leading/trailing whitespace when reading (R-5.3.4). & < > arrive XML-escaped; your XML library un-escapes them.
• IDs: producer-supplied strings, intended unique per document, SHOULD match ^[A-Za-z0-9_.:-]+$. See tolerance — uniqueness is not guaranteed.
• LaneID is text, not numeric. "0" = not lane-bound (every 1.1 profile, R-7.0.3). Frozen classes carry real lane ids ("A", "B" in the run7 example).

Point

Order: ID, LaneID, PointerNumber, X, Y, Z, Color, FeatureClass, FeatureID, RoadPoint?, Direction?, Shapes?, Annotation?, Attributes?

• PointerNumber is integer text — for Cross Section it is the cross-section plane index; for 1.1 point symbols the writer defaults it to the 1-based index within the Points container.
• Color, FeatureClass, FeatureID are always emitted; for 1.1 symbols they default to empty / owning Feature/Type / owning Feature/ID. Legacy cross sections carry the literal string None — see tolerance.
• Point/RoadPoint is a scalar (chainage along the road), unlike the From/To pair on Line/Polyline/Spline (R-4.17). It is optional in 1.1 (point symbols with no chainage omit it).

Point/Direction NEW

• Children X, Y, Z: a full 3D unit vector in the export frame, |v| = 1 ± 1e-6. Z may be non-zero (tilted plates) — do not assume planar.
• Semantics depend on the class (R-5.5.5): for Traffic Sign and KM Sign it is the plate normal pointing towards oncoming traffic; for Gully, Shaft, Emergency Call Box, Terrain Point, Tree, Verge Post it is the road-axis tangent at the point.
• For a 2D plan rotation: project onto XY and re-normalise there (N-5.5.4 — catalog rotation mode VEC). Direction is present for every 1.1 point class even when the catalog rotation mode ignores it (NO, ORD, DRW) — R-5.5.6.
• An Attribute name="direction_source" with value measured | fallback may accompany it (R-5.5.7). fallback = orientation was not measurable; treat the vector as a placeholder.

Point/Shapes/Shape NEW

• @role REQUIRED, free text scoped by class — known: trunk, crown, post. @type REQUIRED, exactly cylinder | cone.
• cylinder ⇒ Base, Top, Diameter; cone ⇒ Base, Apex, Diameter. Exactly one of Top/Apex, selected by @type (R-4.20.3).
• Base = centre of the bottom circle, Top = centre of the top circle, Apex = cone tip. Absolute points in the export frame, independent of the owning Point's coordinates — the shape locks its own 3D position, leaning trunks included (R-5.8.1/2/3).
• Diameter = diameter of the base circle, metres, finite and > 0; constant along a cylinder's axis. Axis is Base→Top / Base→Apex and is non-degenerate (R-5.8.5).
• Producer order within Shapes is preserved. Tree carries exactly one trunk cylinder + one crown cylinder-or-cone (R-5.8.7) — but this is only a writer warning, so handle deviations.

Annotation NEW (on Point, Polyline, Spline, Line)

• Children in order: Display (1, boolean), Legible (0..1, enum), Text (0..n).
• Display=true means render a label at this geometry. Whether the label text travels in the document is per-class (see the §7.1 table).
• Text = one element per rendered line, in draw order. Never contains \n/\r. Render verbatim: it is a finished display string produced upstream (decimal comma, Ø=, unit suffixes are all already in it) — do not re-format, re-round, localise or reorder (R-4.24.4).
• Text absent while Display=true is legal and means one of two things: (a) the consumer derives the label itself — Terrain Point and Cross Section elevation labels, rendered from Point/Z; or (b) it was unrecoverable (Legible=none).
• Elevation label rendering (N-5.7.2, agreed but consumer-side): absolute height = export-frame Z + Geoshift/Z, exactly three decimals, dot separator, no unit suffix, no thousands separator — e.g. 47.333.
• Text is never emitted when Display=false.

Annotation/Legible — enumeration, not a boolean

• Exactly one of full | partial | none, lower-case (R-5.10.1). Enumerations are closed: an unknown value ⇒ treat the element as absent, never guess (N-5.10.4).
• Only meaningful where the text is transcribed from a physical object — today KM Sign only (Traffic Sign plates later). It describes the legibility of the inscription, never detection confidence (N-4.23.5).
• Substitution marks (R-4.24.5): under partial, one unreadable character is a single ?; an unreadable run of unknown length is ?… (U+003F + U+2026). Render them verbatim — stripping them silently fabricates a complete label (N-4.24.6).
• KM Sign text is up to three lines, in order: KM <km>, Abs. <section>, Station <station>; an unknown line is omitted and the rest keep their order (R-5.7.4). The machine values also ride as attributes km, section, station, so you can re-format without a re-export.

Attributes / Attribute NEW

• Always the last child of its parent (Feature, Point, Polyline, Spline, Line). Never emitted empty. 1..n Attribute, sorted ascending by @name, @name unique within the parent.
• @name is snake_case with the unit in the name (length_m, height_m, top_height_p90_m; _m metres, _deg degrees, _s seconds — a convention, not a grammar).
• @type ∈ string | integer | float | boolean; element text is the serialised value (boolean ⇒ true/false; float/integer ⇒ str(v)). Values are always scalar — no nesting is representable. A None-valued attribute is skipped entirely, so an absent attribute means "no value", never "null".
• Names seen in the example document: detector_reviewed, direction_source, faces, guardrail_type, halfwidth_m, height_m, km, lateral_offset_m, length_m, outline_source, parent_guardrail_id, plate_class, post_confidence, post_count, post_spacing_m, section, side, species_class, station, top_height_p90_m, tree_count, width_m. Treat the set as open — build a generic bag, then read known keys out of it.
• Legacy note: the guardrails stand-in exporter used non-uniform tags (<Guardrailtype>, <Topheightp90m>, …). Schema 1.1 never emits those; the uniform <Attribute name= type=> form replaces them (N-8.6.4).

Polyline

Order: ID, LaneID, Type?, RoadPoint?, Vertices, SortingCode?, Closed?, Annotation?, Attributes?

• Vertices always present; Vertex = ID, X, Y, Z. Vertex ids are writer-generated as {polyline_id}-{i}, 1-based (R-4.29.3) — informational only, don't key on them.
• Polyline/Type is an open string, used today as top / bottom for trench and slope outlines (human readability; the SortingCode is the actual contract).
• Closed: true = the vertex list is a closed ring, the first vertex is not repeated as the last, and there are ≥3 vertices — the consumer closes it (R-4.27.1).
• SortingCode — regex, the single normative definition:

  ^[A-Z]+(0|[1-9][0-9]*)\$[AB]$

  [A-Z]+ = family (G = Graben/Grabensohle, B = Böschung); digits = pair index, unbounded non-negative integer, no leading zeros; $ = separator; trailing A = top outline, B = bottom outline. Example values in the sample docs: G1$A, G1$B, B1$A, B1$B.
  • Pair index is unique per family per document; every (family, index) should occur exactly twice — once A, once B. The two halves may come from different detectors or segments, so an incomplete pair is possible (writer only warns) — degrade gracefully: draw the outline, skip the hatch.
  • Hatches are never exported. The consumer derives the trench/slope hatch from the A/B outline pair (§7.1 last row, N-C.2). Two SortingCode values are never equal within a document, so the code is a safe pairing key.
  • Note the class asymmetry: Trench (G<i>$A) and Trench Bottom (G<i>$B) are two separate Features; Slope is one Feature with two Polylines (B<i>$A + B<i>$B).

Spline and Line

• Spline: ID, LaneID, Type?, RoadPoint?, Width?, Fit_Points, Control_Points, Annotation?, Attributes?. Fit_Points is always emitted and may be empty (<Fit_Points/>) so the child layout never varies; Control_Points carries the curve. Point ids run {spline_id}_{n+1} continuously across fit points then control points.
• gap The spline is underspecified for exact 3D reconstruction (O-22, pre-existing since 1.0): degree, knots and weights are not carried. Producer and consumer must assume the same convention — pin yours explicitly and raise it with HBW.
• Line: ID, LaneID, Type?, StartPoint, EndPoint, RoadPoint, Width?, Annotation?, Attributes?. StartPoint/EndPoint have X, Y, Z; RoadPoint has From/To.
• Line/Type and Spline/Type are open strings; the vocabulary in use today is solid | dashed (lane markings) — informative only, do not validate.
• Width (on Line and Spline): optional element with optional children Value, Sigma, Status, Flagged — each present only when the producer had a value. Flagged is lower-case boolean text.

§7.1 feature classes — what the decomposer must produce per Feature/Type

Geometry kind = which container carries the class. "Annot." = the required Annotation/Display value, — = the class MUST NOT carry Annotation. "Text" = whether label text travels in the document. Derived from spec §7.1 (cross-checked against the producer's profile table); this table is self-sufficient — no repo access needed.

Frozen vs 1.1-touched. The three frozen groups (§7.21 lane markings, §7.22 road axes, §7.23 cross sections) carry no NEW element whatsoever — no Direction, no Shapes, no Annotation, no Attributes, no SortingCode, no Closed, no Polyline/Type — and keep their real LaneID and RoadPoint semantics. Everything else is "1.1-touched" and follows R-7.0.3: LaneID = "0" and RoadPoint omitted, unless the profile says otherwise (guardrail keeps its RoadPoint). Your decomposer can safely take a frozen-path branch (pure 1.0 parsing) and a 1.1 path, keyed by Feature/Type.

What the decomposer must tolerate

Spec §6.1 defines a conforming document; §6.2 lists what the writer rejects; §6.3 lists what it only warns about and still emits. Everything in §6.3 can and does reach you. Be liberal: log and continue, never abort the document.

• Unknown elements at any depth — ignore them (R-2.5.3, N-2.3.4). All NEW elements are appended after the 1.0 children of their parent precisely so that a name-based reader is unaffected. Pre-release drafts may even contain a Feature/Layer child; ignore it.
• Duplicate IDs are real. ID uniqueness is a producer obligation the writer only warns about. The published example (run7_branch_001_schema_1_1.xml) contains 103 distinct duplicated geometry ids across 276 elements, all from the real frozen-type export. Never build a global id → object dictionary. Key by (feature index, container, geometry index) or (Feature/ID, geometry ID), and treat ID as a label.
• Literal "None" strings. Legacy cross-section points carry <Color>None</Color>, <FeatureClass>None</FeatureClass>, <FeatureID>None</FeatureID> — a Python str(None) coercion preserved from 1.0 for byte-identity. Map the exact string None to null for these three 1.0 text fields (do not apply this to Annotation/Text or attribute values).
• Empty text is legal for 1.0 elements (<Color/>, an empty Step/@date). NEW elements never carry empty/whitespace-only text.
• Meaningless RoadPoint on real Line/Spline data: the pipeline emits From=0.0, To=0.0 for lane-marking segments. Do not derive chainage from it.
• §6.3 warn-class irregularities you may encounter: a Polyline with <2 vertices or a Spline with <2 control points (legacy content only); a Direction whose length is outside 1 ± 1e-6; an incomplete (family, index) sorting-code pair; Legible on a class that should not carry it; a Text containing a newline; Closed=true with a repeated closing vertex or fewer than 3 vertices; a Tree whose shapes are not exactly one trunk + one crown; a non-snake_case @name; a non-finite coordinate outside a NEW element; a 1.1 key on a frozen-profile feature; an Annotation missing where §7.1 requires it (a legacy guardrail polyline that has not migrated yet is the common case).
• Not all §7.1 classes appear in any one document, and classes outside §7.1 can appear at any time — Feature/Type is an open vocabulary (R-4.9.1, R-6.4.1).
• Legacy 1.0 documents (no SchemaVersion) must still parse. For guard-rail labels in 1.0 files, the fallback is the legacy Point/FeatureClass convention Guard Rails_<type> (N-2.5.4); in 1.1 read the guardrail_type attribute and Annotation/Text.

Key artifacts

Sections worth reading first, in order: spec §3 (element tree), §4 (element reference), §5 (value types, regexes, enums), §7.1 + §7.2–§7.25 (profiles), §6.3 (what you must tolerate), §9 (six complete worked documents), Appendix C (layer mapping). §8 is the producer dict contract — read it only if you also emit documents.

Verification — numbers to assert against the published example

Parse run7_branch_001_schema_1_1.xml and assert the following. These are the exact figures the build script prints; they are stable (the script is deterministic, jitter seeded 20260828). File: 378 632 bytes, 11 806 lines. The real half is byte-identical to the 0.9.0 writer's 331 528-byte output apart from SchemaVersion.

Features per Type — 39 total (11 real + 28 synthetic), 26 of 28 §7.1 classes

Absent from this document (this run has none): Both-Sides Central Axis, Single-Side Central Axis — both are present in sample_v1_1.xml.

Schema-1.1 element counts (example document)

Geometry totals

Suggested consumer-side test set

• Parse both published documents; assert the tables above (feature counts per Type, 1.1 element counts, geometry totals). Assert every NumberOf* equals its container's count.
• sample_v1_1.xml is the coverage fixture: exactly one feature per profile, all 28 classes including Both-Sides / Single-Side Central Axis. Use it to prove the dispatch table is complete; use the run7 example to prove robustness on real, messy data.
• Assert 103 duplicated geometry ids / 276 elements in the run7 example are handled without collision or data loss (this is the regression test for the "no global id map" rule).
• Round-trip: decompose → re-emit → compare per-feature geometry counts and coordinates. Do not aim for byte round-trip; number formatting is str()-shaped and not reproducible from floats.
• Negative tests: a document with no SchemaVersion (treat as 1.0), an unknown Feature/Type, an unknown Legible value, an unknown trailing child, a Legible=none annotation with no Text, an incomplete SortingCode pair.
• Assert the elevation-label rendering of N-5.7.2 on a Terrain Point and a Cross Section point: Z + Geoshift.Z, 3 decimals, dot separator (e.g. 47.333).

Next steps (ordered)

1. Decide the language and the deployment shape first — a Python library, or a C#/.NET assembly loadable by a Grasshopper component. That decision drives everything else, and it interacts with open item O-18 (which XML component HBW uses).
2. Read spec §3, §4, §5, §7.1 and mirror §7.1 into a single class-profile table (Type → container, geometry kind, expected optional elements, layer). The §7.1 table on this page already encodes exactly this in a compact form.
3. Write the structural reader: name-based traversal, unknown elements ignored, NumberOf* cross-check as a warning (not a failure). No index-based child access anywhere.
4. Write the value layer: number/boolean/text parsing, the SortingCode regex, the Legible and Attribute/@type and Shape/@type enums, the "None"-literal mapping, the two RoadPoint shapes.
5. Build the typed objects: point symbol (position, direction, shapes, annotation, attributes), polyline (vertices, closed, sorting code, type), spline (fit + control points), line segment (start/end, width), cross-section point set. Keep a raw-attribute bag on every object so unknown keys survive.
6. Dispatch on Feature/Type into the profile table: frozen path (pure 1.0 parsing) vs 1.1 path. Unknown type ⇒ generic geometry + a diagnostic, never an exception.
7. Add the consumer-only derivations that the document deliberately does not carry: layer from Appendix C; elevation labels from Z (N-5.7.2); trench/slope hatches from the A/B SortingCode pairs; 2D rotation from the XY projection of Direction; closing of Closed=true rings; symbol placement along Tree Line/Bush splines.
8. Run the acceptance pass with HBW: feed the published example XML through the real Grasshopper component and confirm it tolerates unknown trailing children (O-18). Do this before the 0.10.0 release — it is the one open item that could still force a schema change.
9. Confirm the Appendix C layer names and the elevation-label format with HBW (O-21, O-20) and fold the answers back into the spec.

Risks & open questions

Non-spec risks

• release pyproject.toml still reads 0.9.0; 0.10.0 has not been cut. The 1.1 writer only exists on branch ai3d-376-xml-schema-1-1. Real pipeline output you receive today is still schema 1.0 — the legacy path is not hypothetical, build it first.
• convention Every 1.1 profile in the example uses LaneID = "0" (R-7.0.3, correct per spec). The example builder has a LANE_BOUND switch producing a side-bound variant ("A"/"B") for experiments — do not treat LaneID as always "0" for 1.1 classes, and do not treat it as numeric.
• data 28 of the 39 example features are synthetic (placed around the real road by the build script). They are spec-conformant but not detector output: coordinate distributions, attribute values and label strings are illustrative. The 11 real features are the frozen classes only — there is no real detector output yet for any 1.1 class.
• producer TBD Tree Group is specified but the outline detector has not shipped; documents will not contain it until then. Implement against the profile, but don't block on real data.
• The spec is still draft for review. Track it by rule number (R-x.y.z) in code comments — the numbering is stable across revisions, prose is not.