Superlattix

Superlattix model format

The XML schema and serialisation convention behind Superlattix model files – for anyone who reads, writes or scripts them outside the editor.

Schema 2.1 · Convention 2.1.9 · Download the XSD (v2.1.xsd)

Provisional. The schema and the convention may change during the current development phase, and a file valid under one version is not guaranteed to be interpreted the same way by a later one. Changes will be listed in the version history below and communicated where practical. See the Terms of Service, Section 7.

1. Purpose and scope

A Superlattix model is stored as an XML file: the format the editor uses to save models and to open them from local files, and the format of XML export.

The format has two parts, which serve different purposes and carry different stability guarantees.

The schema (XSD) defines the container: the elements and attributes a model file may contain, their order, and their primitive types. It is published at a stable URL and versioned publicly.

The serialisation convention defines the meaning: for each element variety, which fields are significant, how their values are interpreted, and what constraints apply to them. The schema deliberately constrains little – a single generic element type carries every variety – so most of what makes a file interpretable lives in the convention.

A file can be valid against the schema and still be misread if it does not follow the convention. Both are required, and a file is conformant only when it satisfies both.

This page specifies the general-purpose convention used by the editor itself. Conventions optimised for specific downstream workflows may be specified separately against the same schema.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119. Field names refer to the XML: pos is the <pos> child of an element, size/@l is the l attribute of its <size> child, @specifier is the element's specifier attribute.

2. Schema and convention

The schema fixes the shape of a file: one <model>, its <metadata>, then any number of <element>s followed by any number of <body>s, each carrying the same generic fields – pos, start, end, dir, size, and the attributes variety, uid and specifier. The convention gives those fields their meaning for each variety, and adds the rules the schema cannot express.

Every field of every variety is one of three kinds:

KindWritersReaders
SignificantMUST write a value meeting the variety's constraintsMUST interpret it as specified
UnusedMUST write zero (empty for uid)MUST ignore its value
ReservedMUST write zeroMUST treat the element as unreadable (Section 5.5) if the value is non-zero

Reserved fields are kept free for a meaning a later convention may give them; rejecting non-zero values now guarantees that no accepted file can be misread when that happens.

A file is a snapshot of a model's state. The format records no history and no identity across saves.

3. Versioning

The <format> element carries three version components:

ComponentMeaning
version_major, version_minorThe schema version. MUST match the XSD named in schema/@href: 2.1 means v2.1.xsd.
version_patchThe convention's serial number within that schema version: 2.1.9 reads as "convention 9 of schema 2.1".

A higher convention number means a later convention, not a better or more compatible one. When the schema version changes, the convention serial restarts. A published schema is immutable: any change to the schema produces a new major.minor and a new XSD at a new URL.

A reader MUST reject a file whose convention it does not support, and a file whose schema/@href does not name the XSD for its major.minor. The current editor supports convention 2.1.9.

The version components are typed as tokens, not numbers, so that later conventions may be named rather than numbered.

4. Document structure

<model>
  <metadata>
    <format id="superlattix" version_major="2" version_minor="1" version_patch="9"/>
    <schema href="https://superlattix.com/schema/v2.1.xsd"/>
    <created at="2026-10-04T12:00:00Z" tool="superlattix-editor" tool_version="0.6.24"/>
  </metadata>
  <element variety="…" uid="…" specifier="…">…</element>
  …
  <body variety="…" uid="…" specifier="…">…</body>
  …
</model>

<format> – id MUST be superlattix. All four attributes are required.

<schema> – href names the XSD the file follows.

<created> – at is the time the file was written (UTC, RFC 3339, seconds precision); tool and tool_version identify the writer.

All <element>s precede all <body>s. A model MAY contain no elements and no bodies. The order of elements carries no meaning, and neither does the order of bodies: writers MAY emit them in any order, and readers MUST NOT attach meaning to it. Within an element or body, the children appear in the order pos, start, end, dir, size; a body's genesis children precede them.

5. Common rules

5.1 Coordinates and units

Coordinates are in model units in a right-handed coordinate system with axes X, Y and Z. Model units are abstract: Superlattix models are schematic, not dimensionally accurate. All values are 32-bit floats. Every coordinate and size MUST be finite. -0 is equivalent to 0; writers SHOULD NOT write -0, and readers MUST treat it as 0.

5.2 Vectors, directions and tolerances

A field described as a unit vector need not be exactly unit length in the file: readers normalise it. It MUST be non-zero and finite. A field described as an axis direction (for example "+X, +Y or +Z") is accepted when it lies within DIR_TOL of one of those directions after normalisation, and is then treated as exactly that direction.

ConstantValueMeaning
DIR_TOL1 × 10⁻⁴Tolerance for unit directions, perpendicularity and axis alignment
PLANE_TOLERANCE0.001Tolerance, in model units, for a point lying in a plane
MIN_EXTENT0.1Smallest extent, length or radius of any element, in model units

5.3 Guide planes

Most elements are drawn on a guide plane: an axis plane whose normal is +X, +Y or +Z. Where a variety records its guide plane, it does so in dir. For elements drawn from start to end on a guide plane, the plane passes through start; end MUST lie in it within PLANE_TOLERANCE, and writers write end projected exactly into it.

5.4 Minimum size

Every extent, length and radius MUST be at least MIN_EXTENT. An element below this size is degenerate: it would be invisible, and the editor never creates one.

5.5 Elements that cannot be read or written

An element that violates the convention – degenerate, or invalid in any other way – is unreadable. An unreadable element never prevents the rest of a model from being read or written:

  • A reader omits each unreadable element, and every body that depends on it, and loads the rest of the model.
  • A writer omits any element that fails validation, and every body that depends on it, and writes the rest.

Only file-level problems fail a load: XML that cannot be parsed, a file that is not a Superlattix model, an unsupported schema or convention version, or a schema/@href that does not match the version.

5.6 Identifiers

@uid identifies an element that a body can reference. In this convention, every rect carries a uid and no other element does; other varieties and all bodies write an empty uid. A uid is a decimal unsigned 64-bit integer, unique within a file, and MUST NOT be 18446744073709551615. uids are opaque – neither dense nor ordered – and readers MUST NOT infer anything from their values. If two elements share a uid, the reader loads the first and omits the others as unreadable.

5.7 The specifier

@specifier is an unsigned byte (0–255) whose meaning depends on the variety. Varieties that do not use it write 0.

5.8 The start direction of round shapes

The helix and the circle start at a fixed angle that depends only on their axis n: the canonical start direction below, rotated right-handedly about n by HELIX_PHASE (currently 0). It is not stored in the file.

Axis nCanonical direction
+X+Y
+Y+Z
+Z+X

6. Element catalogue

Varieties are grouped for navigation only; a shared group does not imply a shared convention. Unless stated otherwise, every field not listed for a variety is unused.

GroupVarieties
Linessegment, arrow, belgian_arrow, british_arrow, wave_line
Planar shapesrect, hexagon, circle
Non-planar shapeshelix, sphere
Symbolsparticle, normal_arrow

6.1 Lines

segment

A straight line between two points on a guide plane.

FieldMeaningConstraints
startFirst endpointFinite
endSecond endpointIn the guide plane through start; at least MIN_EXTENT from start
dirGuide-plane normal+X, +Y or +Z
<element variety="segment" uid="" specifier="0">
  <pos x="0" y="0" z="0"/>
  <start x="597.65625" y="707.70264" z="0"/>
  <end x="697.0215" y="796.26465" z="0"/>
  <dir x="0" y="0" z="1"/>
  <size l="0" w="0" h="0"/>
</element>

arrow

A line from tail to tip with a triangular arrowhead: a golden triangle (36° apex) whose base is perpendicular to the shaft.

FieldMeaningConstraints
startTailFinite
endTipIn the guide plane through start; at least MIN_EXTENT from start
dirGuide-plane normal+X, +Y or +Z
size/@wArrowhead base lengthAt least MIN_EXTENT; the editor writes 8

belgian_arrow and british_arrow

Block arrows from the midpoint of their base to the apex of their head. Their proportions are fixed; neither variety has size parameters.

FieldMeaningConstraints
startMidpoint of the baseFinite
endApex of the headIn the guide plane through start; at least MIN_EXTENT from start
dirGuide-plane normal+X, +Y or +Z

wave_line

A sine-like wave along a centreline on a guide plane.

FieldMeaningConstraints
start, endEndpoints of the centrelineend in the guide plane through start; at least MIN_EXTENT apart
dirGuide-plane normalUnit vector; the editor writes +X, +Y or +Z
size/@wAmplitude: the peak deviation from the centreline, i.e. half the wave's peak-to-peak heightFinite; zero draws a straight line
@specifierNumber of periods1–255

For a positive amplitude, the first half-period bulges towards dir × (end − start); a negative amplitude mirrors the wave.

<element variety="wave_line" uid="" specifier="3">
  <pos x="0" y="0" z="0"/>
  <start x="197.20459" y="554.07715" z="0"/>
  <end x="403.19824" y="553.833" z="0"/>
  <dir x="0" y="0" z="1"/>
  <size l="0" w="50" h="0"/>
</element>

6.2 Planar shapes

rect

A rectangle with one axis-aligned edge.

FieldMeaningConstraints
@uidIdentifier, referenced by cuboidsRequired (Section 5.6)
posOrigin corner: the corner from which the rect extends by l along start and by w along dir × startFinite
startEdge direction u+X, +Y or +Z
dirNormal nUnit vector, perpendicular to start
size/@lExtent along startAt least MIN_EXTENT
size/@wExtent along dir × startAt least MIN_EXTENT

With v = n × u, the vertices are pos, pos + l·u, pos + l·u + w·v and pos + w·v, counter-clockwise about n. The handedness v = n × u is part of the convention. The normal need not be axis-aligned: a tilted rect has start along an axis and dir anywhere in the plane perpendicular to it.

<element variety="rect" uid="647" specifier="0">
  <pos x="700" y="0" z="100"/>
  <start x="0" y="0" z="1"/>
  <end x="0" y="0" z="0"/>
  <dir x="0" y="1" z="0"/>
  <size l="200" w="200" h="0"/>
</element>

Here u = +Z and v = +Y × +Z = +X, so the rect spans x 700–900 and z 100–300 in the plane y = 0.

hexagon

A regular hexagon.

FieldMeaningConstraints
posCentreFinite
startDirection from the centre to vertex v0; fixes the rotation about the normalUnit vector, perpendicular to dir
dirNormalUnit vector, any direction
size/@lCircumradiusAt least MIN_EXTENT

circle

FieldMeaningConstraints
posCentreFinite
dirNormal of the circle's plane+X, +Y or +Z
size/@lRadiusAt least MIN_EXTENT
<element variety="circle" uid="" specifier="0">
  <pos x="459.72162" y="0" z="244.87115"/>
  <start x="0" y="0" z="0"/>
  <end x="0" y="0" z="0"/>
  <dir x="0" y="1" z="0"/>
  <size l="57.84457" w="0" h="0"/>
</element>

6.3 Non-planar shapes

helix

FieldMeaningConstraints
posCentre of the base circle, on the axisFinite
dirAxis direction: the way the helix rises+X, +Y or +Z
size/@lRadiusAt least MIN_EXTENT
size/@hHeight: the rise from the first point to the lastAt least MIN_EXTENT
@specifierHandedness with respect to dir: 0 right-handed, 1 left-handed0 or 1
startReserved (phase)MUST be zero
size/@wReserved (pitch)MUST be zero

The helix makes exactly NUMBER_OF_HELIX_WINDS turns. Its first point lies on the base circle in the canonical start direction (Section 5.8); its last point lies exactly size/@h above the first, so helices with the same axis, radius and handedness can be stacked without a kink.

<element variety="helix" uid="" specifier="0">
  <pos x="396.3865" y="0" z="589.0807"/>
  <start x="0" y="0" z="0"/>
  <end x="0" y="0" z="0"/>
  <dir x="0" y="1" z="0"/>
  <size l="38.97389" w="0" h="75"/>
</element>

sphere

FieldMeaningConstraints
posCentreFinite
dirNormal of the guide plane the sphere was drawn on; recorded but not interpreted, sign irrelevantUnit vector; the editor writes +X, +Y or +Z
size/@lRadiusAt least MIN_EXTENT

6.4 Symbols

particle

A particle, optionally with a spin arrow through its centre.

FieldMeaningConstraints
posCentreFinite
size/@lRadiusAt least MIN_EXTENT
dirSpin direction, or (0, 0, 0) for a particle without spin; the sign is the way the arrow pointsExactly zero, or ±X, ±Y or ±Z
size/@hSpin arrow shaft length: always 6 × radiusInformative; ignored on read
@specifierPlanes of the spin arrow's head blades (below)0–2
@specifierSpin along ±XSpin along ±YSpin along ±Z
0XY planeXY planeXZ plane
1XY planeXY planeYZ plane
2XZ planeXY planeYZ plane

normal_arrow

An arrow perpendicular to a guide plane, touching the plane at pos – at its tail when it points away from the plane, at its head when it points towards it.

FieldMeaningConstraints
posPoint on the guide planeFinite
dirDirection the arrowhead points; the guide plane's normal is |dir|, and the plane passes through pos±X, ±Y or ±Z
@specifierSide of the guide plane: 0 the side its positive normal points to, 1 the other side0 or 1
size/@lShaft lengthAt least MIN_EXTENT

On a horizontal guide plane (normal +Y):

dir@specifierDrawn
(0, 1, 0)0Above the plane, pointing up
(0, −1, 0)0Above the plane, pointing down to it
(0, −1, 0)1Below the plane, pointing down
(0, 1, 0)1Below the plane, pointing up to it

7. Bodies

A body is a solid derived from one or more elements, which it references by uid in its <genesis> children. A body's own uid is empty.

cuboid

A rect extruded along its normal.

FieldMeaningConstraints
genesisThe uid of the base rectExactly one entry, referencing a rect in the same file
size/@hExtrusion height along the base rect's normal; a negative value extrudes against itFinite
<body variety="cuboid" uid="" specifier="0">
  <genesis>647</genesis>
  <pos x="0" y="0" z="0"/>
  <start x="0" y="0" z="0"/>
  <end x="0" y="0" z="0"/>
  <dir x="0" y="0" z="0"/>
  <size l="0" w="0" h="150"/>
</body>

A cuboid whose base rect is unreadable is omitted with it.

8. Conformance

A conforming file is valid against the XSD for its schema version and satisfies every rule of the convention it declares.

A conforming writer writes every significant field within its constraints, every unused field as zero (or empty) and every reserved field as zero; writes only conforming elements; and declares its convention in <format> and the matching XSD in <schema>.

A conforming reader rejects files with an unsupported schema or convention or a mismatched schema/@href; interprets every significant field as specified and ignores unused fields; and omits unreadable elements – including those with non-zero reserved fields or a duplicate uid – together with the bodies that depend on them, without rejecting the file.

Anything a conforming writer writes, a conforming reader accepts.

9. Version history

Convention 2.1.9 – schema 2.1

The first published convention of schema 2.1. Earlier conventions were used only during development and are not supported.

Appendix A – XSD

The schema is published at https://superlattix.com/schema/v2.1.xsd.

Show the schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="model" type="modelType"/>

  <xs:simpleType name="versionComponentType">
    <xs:restriction base="xs:token">
      <xs:pattern value="[A-Za-z0-9][A-Za-z0-9_\-]*"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="uidType">
    <xs:restriction base="xs:string">
      <xs:pattern value="[0-9]*"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="formatType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute type="xs:string" name="id" use="required"/>
        <xs:attribute type="versionComponentType" name="version_major" use="required"/>
        <xs:attribute type="versionComponentType" name="version_minor" use="required"/>
        <xs:attribute type="versionComponentType" name="version_patch" use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:complexType name="schemaType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute type="xs:string" name="href"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:complexType name="createdType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute type="xs:dateTime" name="at"/>
        <xs:attribute type="xs:string" name="tool"/>
        <xs:attribute type="xs:string" name="tool_version"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:complexType name="metadataType">
    <xs:sequence>
      <xs:element type="formatType" name="format"/>
      <xs:element type="schemaType" name="schema"/>
      <xs:element type="createdType" name="created"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="vecType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute type="xs:float" name="x" use="optional"/>
        <xs:attribute type="xs:float" name="y" use="optional"/>
        <xs:attribute type="xs:float" name="z" use="optional"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:complexType name="sizeType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute type="xs:float" name="l" use="optional"/>
        <xs:attribute type="xs:float" name="w" use="optional"/>
        <xs:attribute type="xs:float" name="h" use="optional"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:complexType name="elementType">
    <xs:sequence>
      <xs:element type="vecType" name="pos" minOccurs="0"/>
      <xs:element type="vecType" name="start" minOccurs="0"/>
      <xs:element type="vecType" name="end" minOccurs="0"/>
      <xs:element type="vecType" name="dir" minOccurs="0"/>
      <xs:element type="sizeType" name="size" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute type="xs:string" name="variety" use="optional"/>
    <xs:attribute type="uidType" name="uid" use="optional"/>
    <xs:attribute type="xs:unsignedByte" name="specifier" use="optional"/>
  </xs:complexType>

  <xs:complexType name="bodyType">
    <xs:sequence>
      <xs:element type="xs:unsignedLong" name="genesis" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element type="vecType" name="pos"/>
      <xs:element type="vecType" name="start"/>
      <xs:element type="vecType" name="end"/>
      <xs:element type="vecType" name="dir"/>
      <xs:element type="sizeType" name="size"/>
    </xs:sequence>
    <xs:attribute type="xs:string" name="variety"/>
    <xs:attribute type="uidType" name="uid"/>
    <xs:attribute type="xs:unsignedByte" name="specifier"/>
  </xs:complexType>

  <xs:complexType name="modelType">
    <xs:sequence>
      <xs:element type="metadataType" name="metadata"/>
      <xs:element type="elementType" name="element" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element type="bodyType" name="body" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

Appendix B – Constants

ConstantValueUsed by
MIN_EXTENT0.1All varieties
DIR_TOL1 × 10⁻⁴Directions and axis alignment
PLANE_TOLERANCE0.001Points in a guide plane
HELIX_PHASE0 radHelix, circle
NUMBER_OF_HELIX_WINDSTODOHelix
Wave line periods1–255Wave line