Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

20.0 KB
Raw Blame

Semantic PMI and AP242

PMI records manufacturing and inspection intent in STEP AP242. Explicit GD&T is annotation data: it attaches a typed control to geometry without changing the geometry, solving constraints, or proving that a manufacturing process can meet the tolerance. Camera and label placement are presentation state. Checked compile-time requirements can separately be projected into dimensional PMI.

Native Model export supports planar Datum, HoleDiameter, HoleCallout, the explicit geometric controls below, sizes and locations projected from construction (Dimension, Location) and part Notes. The diameter record targets a named shaft hole; on a counterbore it means the shaft diameter, not counterboreDiameter. Parsed kinds outside the admitted set, including the older Distance and Coplanar forms, remain rejected by normal export rather than silently omitted.

Every size is written twice in the AP242 file: in the Aetheris records that aetheris analyze reports, and in the standard semantic form other CAD and inspection software reads (DIMENSIONAL_SIZE or DIMENSIONAL_LOCATION with a PLUS_MINUS_TOLERANCE, associated with the measured faces). Readers count each size once.

A part specified by its model

The complete example is showcase-bearing-mount.firmament: a composed block with a boss, two pockets, a bearing bore, four counterbored mounting holes and a chamfered edge, with datums, sizes, geometric controls, locations and notes complete enough to make the part without a drawing.

Pmi {
    Datum A { target: face(-Z) }
    Datum B { target: face(-X) }
    Datum C { target: face(-Y) }
    HoleCallout MountSize { target: [mountA, mountB, mountC, mountD] dimension: mountDiameter }
    Position MountLocation { target: [mountA, mountB, mountC, mountD] tolerance: 0.25mm zone: Cylindrical datumRefs: [A, B, C] modifiers: [MaximumMaterial] }
    Parallelism HubFace { target: face(hub.Top) tolerance: 0.03mm datumRefs: [A] }
    Dimension PocketDepth { target: [left.Depth, right.Depth] }
    Location LeftPocketFromB { origin: face(-X) to: left }
    Dimension EdgeBreak { target: perimeterBreak.Distance }
    Note Material { text: "MATERIAL: 6061-T6 ALUMINUM" }
}

Targets.

  • face(-X) and the other axis faces mean the faces lying in the part's extreme plane in that direction, the surface a datum simulator touches. A face split by construction is associated in all its pieces. If the extreme in that direction is not planar, the target does not resolve and the record rejects.
  • On a Compose body, face(op.Top) names a Base or Boss top, face(op.Bottom) a Base bottom and face(pocket.Floor) a Pocket floor. A cap that is not exactly one face rejects.
  • A hole is named directly (target: bore); face(bore.Wall) means the same on a Compose body. A list of holes (target: [a, b, c, d]) is one requirement on every listed hole, written with its quantity ("4X"). It applies to the shaft walls, never to a counterbore or countersink wall.
  • An authored datum that resolves to no face rejects.

HoleCallout takes the same fields as HoleDiameter and adds the hole's counterbore diameter and depth, projected from its construction: 4X Ø6.6 ±0.1 ⌴Ø11 ↧6.5. The counterbore of every listed hole must be alike.

Dimension names a construction parameter; the compiler supplies the value from the built geometry, so it cannot disagree with the part:

Target Value
base.Height, base.Length, base.Width Base thickness; X and Y extent between its walls
boss.Height, boss.Diameter, boss.Length, boss.Width, boss.Radius Boss height above its support; round or rectangular size; corner radius
pocket.Depth, pocket.Diameter, pocket.Length, pocket.Width, pocket.Radius Pocket depth to its floor; size; corner radius
finish.Distance An equal-distance 45° chamfer (EdgeFinish<Chamfer>)

Length runs along X and Width along Y, as Rect2 writes size: [x, y]. A list of the same parameter on several features ([left.Depth, right.Depth]) is one requirement with a quantity; the values must agree. A value with no stated tolerance falls under the part's general-tolerance note; dimension: a toleranced Static or tolerance: PlusMinus(..) attaches one.

Location runs from an axis face (origin: face(-X)) to a hole axis or to the centre of a boss or pocket (to: left). basic: true makes it theoretically exact (drawn boxed) and admits no tolerance.

Note records part-level text such as material, general tolerances and finish. They read back as annotations.

Fillet radii, countersink callouts and locations between two features are not yet projected. A Dimension or Location that does not resolve to faces rejects.

Explicit GD&T

The complete buildable example is explicit-gdt.firmament. Its Box and Hole are ordinary construction. The following records annotate them independently of Concept requirements or dimensional projections:

Pmi {
    Datum A { target: face(-Z) }
    Datum B { target: face(-X) }
    Datum C { target: face(-Y) }
    Flatness Seat { target: face(+Z) tolerance: 0.03mm }
    Position MountLocation {
        target: face(Mount.Wall)
        tolerance: 0.0254mm
        zone: Cylindrical
        datumRefs: [A, B, C]
        modifiers: [MaximumMaterial]
    }
}
Controls Datum references
Straightness, Flatness, Roundness, Cylindricity Omitted
Parallelism, Perpendicularity, Angularity, CircularRunout, TotalRunout Required
Position, LineProfile, SurfaceProfile Optional

target must resolve to geometry. tolerance is a finite nonnegative Length in millimeters, including for Angularity; it describes a length-valued tolerance zone. datumRefs lists up to three distinct, previously declared datums in primary/secondary/tertiary order. Legacy datum: A, Parallel and Perpendicular spellings remain admitted. Form controls reject datum references.

Optional modifiers admits MaximumMaterial, LeastMaterial, FreeState, CommonZone and Statistical. Unknown, duplicate or contradictory modifiers reject. Optional zone admits Cylindrical, Spherical and BetweenSurfaces. Omitting it does not invent an explicit zone form. The compiler validates the record and its references; the author remains responsible for selecting an appropriate control, feature, zone and modifier combination.

Common-datum groups, datum-reference modifiers, composite frames, projected zone parameters and other advanced forms are not yet authoring syntax. Imported semantic forms can be retained as described below. Unknown fields reject.

Imported semantic PMI and units

An unchanged InlineStep part retains source semantic PMI by default, together with its datum systems, modifiers, tolerance-zone definitions, dimensional allowances and proved geometry associations. Aetheris resolves source face and edge identities through importer provenance rather than entity ordering. Authored annotations may be added; their names must not collide with retained source annotation names. CLI analyze --json reports geometricItemEntityIds for the direct source usage items (faces, edges, solids or auxiliary datum geometry). Its geometricFaceEntityIds is the face projection used for presentation; an edge's adjacent faces do not replace its source association identity. Unique retained datum labels are available directly in an authored control's datumRefs; they bind to the imported AP242 datum entities rather than creating duplicate datums. See the complete nist-ctc01-passthrough.firmament witness. Existing source-integrity receipts (sha256, textSha256, or a project lock) still apply to foreign STEP inputs.

Length-valued measures are normalized using their own declared units. An inch tolerance of 0.001 exports as 0.0254 mm. This conversion does not use the 0.1 mm authoring placement grid or round away small tolerances. Angular units are separate. Firmament authoring itself continues to require metric lengths.

Source graphical PMI is distinct from semantic PMI. Foreign glyphs are excluded with an explicit diagnostic because they may contain inch text; metric labels are regenerated from semantic records where the presentation path supports the target and all of its parameters. Advanced controls whose labels cannot be projected completely reject annotated 3D export rather than omit parameters. This does not preserve a vendor's camera, font or label arrangement. Graphical-only annotations reject default passthrough. Missing dependencies, unresolved units, unsupported compound measures, unmapped body topology and changed bodies reject. Derived units retain their dimensional exponents while their length components and values normalize to mm. Non-metric auxiliary PMI pcurves also reject when their parameter domains cannot be proved safe to normalize. Geometry-only editing of annotated imports still requires explicit geometryOnly: true; source-PMI migration through topology edits is not admitted. Unchanged annotation/re-export uses strict output admission: valid topology and bindings, closed imported shells, canonical geometry and 3D boundary consistency. A source hash proves identity; it does not require complete UV reconstruction. Unqualified optional UV traces are omitted with a diagnostic, while the emitted STEP retains its 3D edge curves, vertices and face associations. Source recovery status remains inspectable and is not promoted to fully qualified. Geometry edits which depend on reconstructed trims still require those trims to be qualified. A physical boundary contradiction or unsupported normalization rejects export, including when geometryOnly: true is requested.

geometryOnly: true explicitly excludes source PMI and reports that exclusion; it never modifies the original STEP file. Imported assembly-wide PMI and automatic promotion of part annotations into assembly requirements remain outside this single-part transfer path.

Project a compile-time tolerance

Declare a requirement once, use its nominal value for construction, and select it explicitly with dimension: in PMI. The complete witness is typed-tolerance.firmament:

Model TypedHole {
  units: mm
  Static drillDiameter: Length = 8mm tol +0.10mm -0.05mm
  Box Body { size: [40mm, 30mm, 8mm] }
  Modify Body {
    Hole<Shaft> Mount {
      on: +Z
      center: Point2(0mm, 0mm)
      diameter: drillDiameter
      end: ThroughAll
    }
  }
  Pmi {
    HoleDiameter MountSize { target: Mount dimension: drillDiameter }
  }
}

The exported diameter is nominally 8 mm with upper allowance +0.10 mm and lower allowance −0.05 mm. tol 0.1mm supplies equal allowances on both sides. The typed value and allowance survive Static aliases, Record members, Template specialization and Feature parameter/local bindings; normal geometry uses only the nominal. Unprojected values generate no PMI. dimension: requires a toleranced Length; Angle values can be checked at compile time but are not a HoleDiameter target and do not grant angular PMI export. The scalar admission scope and arithmetic policy are in syntax. The complete Record/Template/Feature witness projects the original Record requirement after using it in a named Hole recipe. Validation JSON includes the authored projection source and structured dimensionOrigins; those receipts describe binding provenance, not additional PMI annotations. AP242 continues to carry the admitted nominal, allowances and geometric association through the existing semantic exporter.

HoleDiameter projection exports a size requirement attached to the hole wall. A Datum may be exported separately. A datum:/DatumRefs: relationship on a size record rejects normal compilation for every spelling, including legacy literal records: native size export cannot preserve that association. Parse-only analysis can bind it, but identifies the record as export-deferred at ParsedNotBuilt. Use an explicit geometric control for a datum-referenced geometric requirement. The shipped size examples request independent datums and size dimensions; they no longer request a relationship that was never emitted.

This is semantic product-definition PMI, recovered by aetheris analyze; graphical dimension-label placement is separate. An annotated GLB draws it in 3D: callouts sit on their features, feature control frames and datum symbols follow ASME Y14.5 shapes, basic dimensions locate position-toleranced holes, and each feature's leaders share a colour. Explicit value: and tolerance: PlusMinus(upper, lower) remain supported compatibility forms. Existing Require-based from: / as: projections continue to mean a checked semantic constraint, rather than an implicit export of all Static values.

Sheet-metal requirements

The authored sheet-metal frontend also admits dimension: references to checked toleranced Length values from Static/Record data. It preserves nominal geometry, allowances and binding origins. Its Dimension kinds are Thickness, Linear and Diameter; targets are bound sheet regions, bends, parts and cuts, including Pattern members. DatumFeature and Position retain the sheet exporter's datum relationships and geometric associations. Native Model explicit GD&T uses the controls described above. See sheet-metal layout and release syntax and the complete typed example.

Use one owning Pmi block. Unknown kinds/fields, missing targets, duplicate blocks, negative allowance magnitudes and nonpositive quantities reject. Manufacturing process metadata is optional and does not implicitly create PMI. A successful export can be inspected with aetheris analyze file.step --json.

Targets and inspection

For a simple Hole<Shaft> constructed in a Box, face(H.Wall) names the stable wall output of Hole H. It is a semantic role selector, independent of the current BRep face number. HoleDiameter accepts it as a target:

Model WallReference {
    Units: mm
    Box Body { Size: [40mm, 30mm, 8mm] }
    Modify Body { Hole<Shaft> H { On: +Z Center: Point2(0mm, 0mm) Diameter: 8mm End: ThroughAll } }
    Pmi { HoleDiameter WallDiameter { Target: face(H.Wall) Value: 8mm } }
}

The complete file is hole-wall-selector.firmament. The compiler binds H as a Hole symbol, then resolves Wall through the construction-owned Hole-wall correspondence. Renaming H changes the selector spelling; diameter and position edits preserve it. Deleting H gives a Hole-specific unresolved-symbol diagnostic. Box face(+Z), imported face(#id), and existing PMI targets retain their meanings. face(H.Wall) is currently qualified for shaft walls in direct Box/Hole construction; it does not name blind bottoms, entry/exit rims, counterbore sections, patterned instances, or imported Hole-like faces. A planar Datum cannot consume a cylindrical Hole wall.

The complete qualified example is multiple-hole-dimensions-with-chamfer.firmament:

aetheris validate fixtures/Canonical/PMI/multiple-hole-dimensions-with-chamfer.firmament --json
aetheris build fixtures/Canonical/PMI/multiple-hole-dimensions-with-chamfer.firmament --output artifacts/pmi.step --json
aetheris analyze artifacts/pmi.step --json

The build's pmiExportEvidence and the analyzer's semanticPmi are independent public evidence surfaces. Supported validate records and inspected AP242 records must agree at the semantic-record level; one record may lower to several STEP entities.

Pattern-generated geometry may coexist with PMI, but the native lane does not yet publish a stable selector for individual generated pattern instances or quantity/repeated-feature PMI authoring.

Assembly release records and design notes

PMI is owned by the document that declares it. A Part's Pmi describes that Part; assembling it does not copy, promote or reinterpret those requirements as assembly requirements. An assembly exported without its own Pmi or Provenance declaration has no assembly-owned PMI, even when its component sources contain PMI. This is intentional. Declare assembly requirements explicitly in the root .firmasm file, using the admitted assembly PMI forms below. The standalone Part export retains its own supported PMI. Mates determine placement; they do not infer manufacturing requirements or propagate tolerances.

The assembly lane supports root-owned product annotations and a selected typed release Record. These lower through the existing semantic PMI note emitter to AP242 SHAPE_ASPECT and PROPERTY_DEFINITION entities, and are recovered by aetheris analyze assembly guitar.step --json under semanticPmi. They are semantic notes, not rendered dimension labels or newly qualified manufacturing requirements.

Record ReleaseInfo {
    Author: String
    Date: Date
    Version: Version
    Description: String
    AuthoringTolerance: Length
}
Static Release: ReleaseInfo {
    Author: "GPT 6.1 Sol Codex"
    Date: 2026-10-01
    Version: 0.1.0
    Description: "Carved-top guitar presentation witness"
    AuthoringTolerance: 0.1mm
}
Assembly GuitarX0 {
    Provenance: Release;
    Pmi {
        Note DesignIntent {
            Target: GuitarX0;
            Text: "Presentation demonstrator; not released for manufacture.";
        }
    }
    // Ordinary XML-like occurrence tree and placement declarations follow.
}

Provenance selects one ordinary Static Record. The common Record binder checks its fields, including real calendar dates, three-component semantic versions, and dimensioned lengths. Author: String, Date: Date, Version: Version, and Description: String are required. Optional fields are flat String, Date, Version, Length, Angle, Int, Float, or Bool data; Organization: String sets the STEP organization when present. Field values are exported as annotations named Release.Field, in stable field-name order. The selected date supplies a deterministic midnight STEP header timestamp; it is the authored release date, not the time of export. There is no implicit wall-clock mutation.

Pmi and Provenance belong directly to the root Assembly. Note takes Target then Text, with explicit semicolon terminators. A target must resolve to a complete occurrence path, including the root, such as GuitarX0.Bridge; unknown targets, duplicate note names, malformed text, and unsupported PMI kinds stop compilation. Text supports JSON string escapes and preserves apostrophes, braces, semicolons, and literal // without interpreting them as geometry or comments. Control characters are rejected.

Notes are associated with the target's AP242 product-definition shape. For a shared definition the explicit occurrence path remains in the semantic target; this does not invent an occurrence-specific BRep face association. Face-targeted assembly tolerances, assembly GD&T, nested reusable-definition annotation authoring, and graphical PMI presentation remain outside this bounded lane. Existing Model PMI contracts above retain their separate selector rules. Assembly package reconstruction does not yet reauthor these annotations; inspect the original STEP directly rather than assuming package import/re-export preserves release metadata.

The assembly IR preserves the release data and note source spans. USD also carries them as root aetheris:provenance:* and aetheris:pmi:* custom attributes. Editing metadata refreshes these outputs while reusing unchanged geometry. The complete guitar example is guitar.firmasm.