yapcad.io package

Submodules

yapcad.io.geometry_json module

Geometry JSON serialization/deserialization helpers.

Implements the draft schema described in docs/geometry_json_schema.md.

yapcad.io.geometry_json.geometry_from_json(doc: Dict[str, Any]) → List[list][source]

Deserialize geometry JSON into yapCAD list structures.

yapcad.io.geometry_json.geometry_to_json(entities: Iterable[list], *, units: str | None = None, generator: Dict[str, Any] | None = None, relationships: List[Dict[str, Any]] | None = None, attachments: List[Dict[str, Any]] | None = None) → Dict[str, Any][source]

Serialize solids/surfaces into the geometry JSON document.

yapcad.io.meta_yaml module

Sidecar .meta.yaml emitter for yapCAD STEP/STL exports.

Implements Step 5 of the metadata-namespace-v1.1 migration (RFC rfc_assembly_operation_namespaces.md).

Usage

Call dump_metadata_yaml() immediately after writing a STEP or STL file:

write_step(part, "output/my_part.step")
dump_metadata_yaml(part, "output/my_part.step")   # → my_part.meta.yaml

The sidecar file is placed next to the geometry file by default. Pass an explicit yaml_path to override.

The function is a no-op (and returns None) when the part carries no yapCAD metadata — so callers can always call it unconditionally.

yapcad.io.meta_yaml.dump_metadata_yaml(part: Any, geometry_path: str | PathLike, *, yaml_path: str | PathLike | None = None, source_dsl: str | None = None, source_command: str | None = None) → str | None[source]

Write a sidecar .meta.yaml file next to a STEP or STL export.

Parameters:

  • part – A yapCAD solid, surface, or other geometry object that may carry a metadata dict (retrieved via yapcad.metadata.get_metadata()).

  • geometry_path – Path to the already-written STEP/STL file. Used to derive the default sidecar path and to compute _provenance.source_sha256 when source_dsl is not provided.

  • yaml_path – Explicit output path for the YAML sidecar. When omitted, the file is placed alongside geometry_path with the suffix replaced by .meta.yaml.

  • source_dsl – Path to the originating DSL file. Stored in _provenance and used for the SHA-256 hash when the file exists.

  • source_command – The DSL command name that produced this part (e.g. "FORWARD_BULKHEAD").

Returns:

Absolute path of the written YAML file, or None when no metadata was found on part (the sidecar is not written in that case).

Return type:

str or None

Raises:

ImportError – If PyYAML is not installed and metadata is present (so the caller is aware that the sidecar was not written).

yapcad.io.meta_yaml.load_metadata_yaml(yaml_path: str | PathLike) → Dict[str, Any][source]

Load a .meta.yaml sidecar and return the raw dict.

Parameters:

yaml_path – Path to the .meta.yaml file.

Returns:

The deserialized metadata dictionary.

Return type:

dict

Raises:

  • ImportError – If PyYAML is not installed.

  • FileNotFoundError – If yaml_path does not exist.

yapcad.io.meta_yaml.sidecar_path_for(geometry_path: str | PathLike) → Path[source]

Return the conventional sidecar path for a geometry file.

This is a pure path computation — no file I/O is performed.

Parameters:

geometry_path – Path to a STEP or STL file.

Returns:

The conventional .meta.yaml path.

Return type:

pathlib.Path

yapcad.io.step module

STEP export utilities for yapCAD surfaces and solids.

yapcad.io.step.write_step(obj: Sequence, path_or_file, *, name: str = 'yapCAD', schema: str = 'AUTOMOTIVE_DESIGN_CC2') → None[source]

Export obj (surface or solid) to a STEP file using a faceted BREP.

yapcad.io.step.write_step_analytic(obj: Sequence, path: str, *, name: str = 'yapCAD', fallback_to_faceted: bool = True) → bool[source]

Export obj to a STEP file using analytic BREP if available.

This function attempts to export the object using its native BREP representation (with analytic surfaces like planes, cylinders, spheres). If native BREP data is not available or OCC is not installed, it can fall back to faceted BREP export.

Parameters:

  • obj (Sequence) – A yapCAD solid or surface to export.

  • path (str) – The output file path.

  • name (str, optional) – The product name in the STEP file. Default ‘yapCAD’.

  • fallback_to_faceted (bool, optional) – If True and analytic export fails, fall back to faceted export. Default True.

Returns:

True if analytic export succeeded, False if fell back to faceted.

Return type:

bool

Raises:

  • RuntimeError – If OCC is not available and fallback_to_faceted is False.

  • ValueError – If native BREP is not available and fallback_to_faceted is False.

yapcad.io.step.write_step_with_meta(obj: Sequence, path: str, *, name: str = 'yapCAD', source_dsl: str | None = None, source_command: str | None = None, emit_sidecar: bool = True) → str | None[source]

Export obj to STEP and optionally write a .meta.yaml sidecar.

Thin wrapper around write_step() that calls dump_metadata_yaml() immediately after the geometry is written.

Parameters:

  • obj – yapCAD solid or surface.

  • path – Output STEP file path.

  • name – Product name embedded in the STEP header.

  • source_dsl – Path to the originating DSL file (forwarded to the sidecar emitter).

  • source_command – DSL command name that produced this part.

  • emit_sidecar – When False, behaves identically to write_step().

Returns:

Path of the written sidecar, or None when no metadata was present or emit_sidecar is False.

Return type:

str or None

yapcad.io.step_importer module

STEP import utilities backed by pythonocc-core.

yapcad.io.step_importer.import_step(path) → List[Geometry][source]

Read a STEP file and return a list of yapCAD Geometry objects.

Parameters:

path – filesystem path or string to the STEP file.

yapcad.io.stl module

STL import and export utilities for yapCAD surfaces and solids.

yapcad.io.stl.import_stl(path: str, *, deduplicate: bool = True) → list[source]

Import an STL file as a yapCAD solid.

This is an alias for read_stl() for API consistency with yapcad.io.step_importer.import_step().

Parameters:

  • path (str) – Path to STL file.

  • deduplicate (bool, optional) – If True (default), merge coincident vertices.

Returns:

yapCAD solid containing the imported mesh.

Return type:

solid

yapcad.io.stl.read_stl(path_or_file, *, deduplicate: bool = True) → list[source]

Read an STL file and return a yapCAD solid.

Parameters:

  • path_or_file (str or path-like or file-like) – Path to STL file, or an open binary file object.

  • deduplicate (bool, optional) – If True (default), merge coincident vertices to create a proper indexed mesh. If False, each triangle gets its own vertices.

Returns:

yapCAD solid containing a single surface with the imported mesh. The solid structure is: [‘solid’, [surface], boundary, holes]

Return type:

solid

Examples

>>> from yapcad.io.stl import read_stl, write_stl
>>> my_solid = read_stl('model.stl')
>>> # Round-trip: export and re-import
>>> write_stl(my_solid, 'copy.stl')
>>> copy_solid = read_stl('copy.stl')
yapcad.io.stl.write_stl(obj: Sequence, path_or_file, *, binary: bool = True, name: str = 'yapCAD') → None[source]

Write obj (surface or solid) to STL.

path_or_file can be a filesystem path or an open binary/text stream.

yapcad.io.stl.write_stl_with_meta(obj: Sequence, path: str, *, binary: bool = True, name: str = 'yapCAD', source_dsl: str | None = None, source_command: str | None = None, emit_sidecar: bool = True) → str | None[source]

Export obj to STL and optionally write a .meta.yaml sidecar.

Thin wrapper around write_stl() that calls dump_metadata_yaml() immediately after the geometry is written.

Parameters:

  • obj – yapCAD solid or surface.

  • path – Output STL file path.

  • binary – Write binary STL (default) or ASCII.

  • name – Solid name embedded in the STL header.

  • source_dsl – Path to the originating DSL file.

  • source_command – DSL command name that produced this part.

  • emit_sidecar – When False, behaves identically to write_stl().

Returns:

Path of the written sidecar, or None when no metadata was present or emit_sidecar is False.

Return type:

str or None

Module contents

I/O utilities for yapCAD.