Struct StepBuilder 

pub struct StepBuilder { /* private fields */ }

Ergonomic writer for the standard AP242 file shape: shared contexts and units up front, one product chain per part, everything bound and emitted by finish.

Implementations

impl StepBuilder

pub fn new() -> Result<Self, AuthorError>

Set up the shared skeleton with the default units (millimetre, 1e-7 uncertainty) — see new_with to choose.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn new_with(units: &UnitsInput) -> Result<Self, AuthorError>

Set up the shared skeleton: application context + protocol definition (the AP242 identity values), product contexts, and the geometric context complex carrying the chosen SI length unit, radian, steradian, and the given length uncertainty.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn header(&mut self, h: &HeaderInput)

Set the Part 21 HEADER fields (file name, description, authors, organizations, originating system, authorisation, timestamp) applied on finish. May be called any time before finish; the last call wins. Without it the header carries only the automatic timestamp and preprocessor stamp.

pub fn author(&mut self) -> &mut Ap242Author

Escape hatch to the strict low-level layer — the write-side counterpart of the read side’s Scene::model(). Entities the builder does not cover go through Ap242Author’s generated constructors directly; ids cross freely in both directions (builder-produced ids feed low-level calls and vice versa — same model, same validation).

Only borrowed access is offered: taking the author out would bypass finish, which still has to materialize the pending shape representations, placements, style anchors, category, and header.

pub fn style( &mut self, target: StyleTarget, color: Rgb, transparency: Option<f64>, ) -> Result<StyledItemId, AuthorError>

Colour target (a solid or one face), optionally with a transparency (0.0 = opaque, 1.0 = fully transparent). Styling the same target again adds another style record; readers use the first they find.

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn layer( &mut self, name: &str, targets: Vec<StyleTarget>, ) -> Result<PresentationLayerAssignmentId, AuthorError>

Assign targets to a named presentation layer; the returned id can be fed to hide_layer to switch the whole layer off by default.

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn hide(&mut self, target: StyleTarget) -> Result<(), AuthorError>

Mark target invisible by default. Implemented the way STEP requires it: an INVISIBILITY cannot point at geometry directly, so the builder attaches an empty (.NULL.-styled) styled item to the target and registers that — colour styles on the same target are unaffected.

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn hide_layer(&mut self, layer: PresentationLayerAssignmentId)

Switch a whole layer (from layer) invisible by default. Infallible at call time — a foreign or stale id is caught by the INVISIBILITY validation inside finish.

pub fn vertex(&mut self, p: [f64; 3]) -> Result<Vertex, AuthorError>

Add a topological vertex at p.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn edge( &mut self, from: Vertex, to: Vertex, curve: CurveInput, ) -> Result<EdgeCurveId, AuthorError>

Add an edge between two vertices over the given curve. A straight edge derives its line from the vertex positions (a zero-length segment gets a placeholder direction — degenerate geometry is the caller’s responsibility); a circle with from == to is a closed full-circle edge.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn face( &mut self, surface: SurfaceInput, same_sense: bool, bounds: Vec<FaceBoundInput>, ) -> Result<AdvancedFaceId, AuthorError>

Add a face over an analytic surface, bounded by the given loops.

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn solid( &mut self, part: Part, name: &str, faces: Vec<AdvancedFaceId>, ) -> Result<ManifoldSolidBrepId, AuthorError>

Close the faces into a shell and add the solid to part; the solid lands in the part’s shape representation on finish (as an ADVANCED_BREP_SHAPE_REPRESENTATION).

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn solid_with_voids( &mut self, part: Part, name: &str, outer_faces: Vec<AdvancedFaceId>, voids: Vec<Vec<AdvancedFaceId>>, normals: VoidShellNormals, ) -> Result<BrepWithVoidsId, AuthorError>

Close outer_faces into the outer shell and each group in voids into an internal cavity shell, then add a solid with internal voids (BREP_WITH_VOIDS) to part — a cavity-bearing body such as a hollow casting. The solid lands in the part’s shape representation on finish (as an ADVANCED_BREP_SHAPE_REPRESENTATION, like solid).

voids must be non-empty (a solid with no voids is a plain solid); each inner group is one closed cavity shell.

Void shell orientation (normals)

STEP orients every bounding shell so its face normals point away from the solid material: outward into free space for the outer shell, and into the empty cavity for a void. Each void group is wrapped in an ORIENTED_CLOSED_SHELL; normals tells step-io whether the faces you pass already follow that rule or must be flipped to it.

• AwayFromMaterial: the faces already point out of the solid (into the cavity) — the same rule your outer shell follows. Natural, and what most kernels produce when they emit a cavity as a reversed shell; kept as authored (.T.). Use this if your kernel orients cavities consistently with the outer shell. When in doubt, this is the right choice.
• TowardMaterial: the faces point into the material — you built the cavity like an ordinary outward-facing box (normals facing outward from the cavity volume, toward the surrounding solid). step-io reverses them (.F.).

Quick test: look along a cavity wall’s normal. Into the empty hole → AwayFromMaterial; into the surrounding solid → TowardMaterial. step-io does not evaluate geometry — it trusts this declaration, and the wrong value inverts the void (validators and mass-property sign conventions will reject it).

Errors

Empty voids, or empty face lists, fail validation with AuthorError (the strict CLOSED_SHELL / BREP_WITH_VOIDS cardinality checks). An id that did not come from this builder fails the same way; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn part(&mut self, name: &str) -> Result<Part, AuthorError>

Add one part: the full product chain (product → formation → definition → definition shape) plus its origin placement. Shape items collected for the part are bound into its shape representation by finish.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn part_with( &mut self, name: &str, opts: &PartOptions, ) -> Result<Part, AuthorError>

part with metadata overrides: part number, version label, and the description fields.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn mesh( &mut self, part: Part, name: &str, input: &MeshInput, of_solid: Option<SolidRef>, ) -> Result<TessellatedSolidId, AuthorError>

Attach a display mesh to part, optionally linked to the b-rep solid it tessellates (the link is what MeshGroup::solid() resolves on the read side). Triangle indices are 0-based into points; the builder converts to STEP’s 1-based strip encoding. The mesh lands in its own TESSELLATED_SHAPE_REPRESENTATION on finish.

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn person_and_org( &mut self, p: &PersonOrg, ) -> Result<PersonAndOrganizationId, AuthorError>

A person at an organization — reusable across contributor and approver roles.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn contributor( &mut self, part: Part, role: &str, who: PersonAndOrganizationId, ) -> Result<(), AuthorError>

Record who as a contributor to the part’s version under the given role (customary roles: "creator", "design_owner", "checker").

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn approve( &mut self, part: Part, input: &ApprovalInput, ) -> Result<ApprovalId, AuthorError>

Attach an approval to the part’s version: a status word, a level, any approvers with their roles, and an optional approval date.

Errors

An id that did not come from this builder (another builder’s, or out of range) fails validation with AuthorError; beyond that the wiring is fixed, so an error indicates a bug in the builder itself.

pub fn document( &mut self, part: Part, d: &DocumentInput, ) -> Result<(), AuthorError>

Attach an external document reference to the part’s version.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn security( &mut self, part: Part, name: &str, purpose: &str, level: &str, ) -> Result<(), AuthorError>

Attach a security classification to the part’s version.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn place( &mut self, parent: Part, child: Part, at: Frame, ) -> Result<NextAssemblyUsageOccurrenceId, AuthorError>

Place child inside parent at the given frame — one assembly occurrence (the same child may be placed any number of times; each call is one instance). The usage occurrence is created immediately; its shape wiring is bound in finish.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.

pub fn finish(self) -> Result<String, AuthorError>

Materialize each part’s shape representation (its origin placement plus the collected items) with its shape-definition link, add the customary product category, and emit the Part 21 text.

Errors

Propagates AuthorError from the strict constructors; the wiring here is fixed, so an error indicates a bug in the builder itself.