Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

11.1 KB
Raw Blame

Domains and modules

Firmament covers several engineering domains with one syntax. Each domain has its own compiler front end and its own rules about what is admitted. Sharing syntax does not make every operation legal everywhere: a field or statement a domain does not own is rejected there.

Choosing a domain: schema

An optional schema Name header selects a front end explicitly. Write it once, before any other directive or declaration, preferably on its own line. Comments before or after it are fine. Names are case-sensitive. An unknown name, a second or late header, or source that does not match the selected domain rejects, and the compiler does not retry with another front end. A Template specialization stays in the domain it was admitted to.

Schema Guide
Mechanical Geometry, Revolve, gears. Revolve is an operation here, not a schema.
WireForm Formed wire
Sweep Circular-section sweeps
SectionChain Framed section chains
Piping Ports, connections and routing
Structural Nodes, straight members and weldments
Sculpting Immutable body and surfacing states
PlasticShell Molded shell manufacturing intent
Analysis Linear-elastic analysis
Garment Panels and stitches (experimental)

Assembly, Scene, SheetMetal and Drawing are not schemas; each has its own entry form, described in its guide. Piping uses its documented Model/PipingSystem form, with schema Piping optional. Do not invent schema Assembly, and do not wrap another domain's declarations in a Model.

Task Start here
Parts, ports, constraints, occurrences Assemblies, components and sites
Spatial layout and presentation Scenes
Sheet parts, regions and bends Sheet metal
Engineering annotation PMI
Body states and bounded surface edits Sculpting
Multi-file projects Project snapshots, Inventory

Body states

BodyState: keep an engineering body

BodyState can reference the Model's admitted engineering body. It does not convert that geometry into the old rectangular housing prototype.

Complete file:

Model Sleeve {
  units: mm
  Cylinder stock { radius: 6mm height: 17mm }
  BodyState base { input: stock }
  output: base
}

The ordinary engineering compiler admits stock, including its modifications and explicit PMI. The state retains that exact product, semantic correspondence where available, and its source recipe for replay. input must name an admitted body or final Compose; it cannot select an unrelated Record, Profile guide or an intermediate stage of the same construction. Use separate Parts for separate products, as in ordinary mechanical authoring. Primitive, profile/Compose, Gear, Sweep and Revolve products retain their existing engineering lowerers. When adding a state output to a file with an explicit schema Mechanical, select schema Sculpting for the state-owning document; an explicit conflicting selector is still an error.

The older BodyState base { size: [...] Hole ... } form remains a housing construction. Holes are optional. Its named crown and mounting regions belong to that construction; they are not inferred on arbitrary engineering bodies. The existing surface-edit materializers still have explicit topology/support requirements. An unsupported edit or history combination rejects before it can replace earlier geometry. See the operation boundaries.

Exact face edits and mesh sculpting

ReplaceRegion grafts a bounded patch onto an engineering-source BodyState. Inspect the state for current FaceN and EdgeN handles, then bind every patch side explicitly. The supported case is an outward, non-rational bicubic Bezier graph over a planar four-line face. It retains all topology, edge curves, vertices and neighboring supports. A replaced face handle becomes stale; its named SurfacePatch is the successor. Raw STEP PMI that lacks a complete editable projection rejects before editing. See the complete exact-face example. Imported engineering sources and edits to PMI/interface-bearing faces remain outside this native adapter's qualified contract.

Use MeshState for explicit conversion to an editable subdivision control cage. It produces a mesh artifact, not an exact BodyState. There is no automatic mesh fallback when an exact edit fails.

Complete file — convert a box, soften its creases and edit its cage:

Model CageSculpt {
  units: mm
  Box stock { size: [20mm, 16mm, 8mm] }
  BodyState exact { input: stock }
  MeshState cage {
    input: exact
    cage: Box
    segments: 1
    maximumDeviation: 0.01mm
  }
  MeshState smooth {
    input: cage
    Crease { edges: [All]; mode: Smooth }
  }
  MeshState refined { input: smooth; Subdivide { levels: 2 } }
  MeshState edited {
    input: refined
    preserve: [v1]
    Move { vertices: [v0]; offset: [0mm, 0mm, 1mm] }
  }
  output: edited
}

cage: Box requires a pure axis-aligned box, and starts with sharp stock edges. cage: Sphere requires a pure exact spherical support; it creates a welded cube-sphere quad cage. segments is 1..16 per cube side (default 1 for Box, 4 for Sphere). Required maximumDeviation bounds the finite conversion's radial error for Sphere, including output quantization; the native Box cage retains its exact boundary. The same budget limits 32-bit coordinate quantization for every selected mesh successor. It does not constrain an explicit Move/Scale to stay near the original body. A tighter sphere budget may require more segments. This is not arbitrary BRep retopology or a certificate for the infinite subdivision limit surface.

Each successor has exactly one operation:

Operation Fields Meaning
Subdivide levels: 1 Finite Catmull-Clark refinement, 1..4 levels per operation
Move vertices: [v0], offset: [0mm, 0mm, 1mm] Move selected current cage vertices in world space
Scale vertices: [All], factor: [1.5, 1, 0.75], origin: [0mm, 0mm, 0mm] Explicit positive scale about a required origin; factors are dimensionless
Crease edges: [All], mode: Sharp or Smooth Mark or unmark current cage edges as sharp

Use inspect --json for current vertex/edge identities; edge handles are derived from their endpoint identities. [All] is an explicit whole-cage selection. Existing vertex IDs survive refinement; new edge/face points have parent-derived IDs. Old edge handles are replaced by their child edges. Optional preserve: [v1] requires those input vertices to retain their exact coordinates and identities in that successor. A conflict rejects atomically. There are at most 64 mesh states/operations and 24,576 cage faces.

The sphere example uses Scale to create an ellipsoid-like subdivision mesh. Its original sphere remains an unchanged exact BodyState. Mesh states carry their source body, conversion evidence, typed construction recipe and edit history. Finite meshes are checked for enclosure, directed winding and local edit foldover. Global self-intersection is not certified; unsupported requirements are errors.

Export a mesh output with aetheris mesh part.firmament --format glb or --format stl, or build --out artifacts/local/part.glb. GLB is binary glTF 2.0. Each output has a .sculpt.json sidecar with the cage and replayable construction. STL does not embed those semantics, so retain its sidecar. GLB uses the existing millimeter/Z-up to meter/Y-up projection and finite, flat-shaded triangles. Both formats use 32-bit coordinates; export reports quantization and rejects precision collapse. validate reports MeshBuilt, SubdivisionMesh and stepExportAvailable: false. A normal STEP build of that output rejects; select the retained exact state as output when STEP is required. The existing STEP-based view/verify commands explicitly reject mesh-only outputs.

Modules: include and Inventory

Use include bolt: Part = Step("vendor/bolt"); for a short typed resource reference, or include "parts/bolt"; when shared declarations are convenient. For larger compositions, give Part, Subassembly, Assembly and Scene dependencies typed names in an Inventory Record:

Inventory Record Components {
  bracket: Part = Firmament("parts/bracket").Bracket
  drive: Subassembly = Firmament("assemblies/drive").Drive
  bearing: Part = Step("vendor/bearing")
  gearbox: Assembly = Step("vendor/gearbox")
}

This fragment requires the named resources. Locators normally omit the extension; ambiguous matches reject. Place Components.bracket through a Part occurrence, Components.drive through an Assembly occurrence, or a Scene entry through a Scene occurrence. The catalog makes definitions available; occurrences determine quantity and placement. Part and Subassembly entries may reference typed Template exports; supply their named arguments at the occurrence. Definition-private names remain in the defining module. Assembly and Scene entries currently import concrete exports.

Inventory follows lexical scope and retains imported file identity. Existing untyped include remains the concise declaration-composition form. A typed include follows the same reference rules as an Inventory member. STEP Assembly imports retain product hierarchy and transforms; no implicit flattening occurs. Optional metadata: selects an ordinary typed Static Record. An optional generated firmament.lock.toml pins dependencies; existing locks are enforced without automatic refresh. InlineStep { from: Components.housing } binds one STEP Part for local annotation or surgery, with a lock-supplied or explicit source pin. Use geometryOnly: true explicitly when excluding imported PMI. See Inventory Records for complete projects, source snapshots, STEP boundaries and extension resolution.

Assembly occurrence trees use <Assembly> / <Part> tags as well as brace bodies. Tree nesting does not create a Mate. Inclusion is owned by the consuming project/domain; include is not a universal mechanical preprocessor.

Standalone part compilation rejects an unresolved include explicitly, even if the named file exists. Use a documented Assembly/project loader to resolve file dependencies before part compilation. The shipped Use Profile.Modifications import retains its existing library owner. Other unconsumed directives reject.