`visualdynamics.io.threemf`¶

threemf ¶

3MF meshes — the CAD hand-off format that keeps parts and units.

A .3mf is a zip holding one XML model: already-tessellated triangles (our tri3 face elements verbatim), named objects for an assembly's parts — each becomes a named block — and a declared unit, so nothing has to be asked at import. SolidWorks writes it from Save As, which is why this importer exists: "import my SolidWorks model" is an export to 3MF away, where the native format is closed and STEP needs a geometry kernel this project deliberately does not carry (see PLAN.md).

Assemblies arrive as component references with affine transforms; they are resolved recursively, so each placed instance of a part gets its triangles where the assembly put them. Everything here is the standard library — zipfile and xml.etree — plus numpy.

Functions:

Name	Description
`load`	Read a 3MF file as a geometry — one named block per placed part.
`save`	Write the geometry's face elements as 3MF — one named object

Classes¶

Functions:¶

load ¶

load(path: str | PathLike) -> Geometry

Read a 3MF file as a geometry — one named block per placed part.

Parameters:

Name	Type	Description	Default
`path`	`str or path - like`	The `.3mf` file.	required

Returns:

Type	Description
`Geometry`	Triangle face elements in metres (the file's declared unit is converted, so `length_unit` arrives set) — one block per part instance the build places, carrying the part's own name.

Source code in src/visualdynamics/io/threemf.py

def load(path: str | os.PathLike) -> Geometry:
    """Read a 3MF file as a geometry — one named block per placed part.

    Parameters
    ----------
    path : str or path-like
        The ``.3mf`` file.

    Returns
    -------
    Geometry
        Triangle face elements in metres (the file's declared unit is
        converted, so `length_unit` arrives set) — one block per part
        instance the build places, carrying the part's own name.
    """
    with zipfile.ZipFile(path) as archive:
        model_name = next(
            (n for n in archive.namelist() if n.endswith('.model')), None)
        if model_name is None:
            raise ValueError(f'{path} holds no 3D model document')
        root = ET.fromstring(archive.read(model_name))
    scale = UNITS.get(root.get('unit', 'millimeter'))
    if scale is None:
        raise ValueError(f"unknown 3MF unit {root.get('unit')!r}")
    resources = root.find(f'{{{CORE}}}resources')
    objects = {node.get('id'): node for node in
               ([] if resources is None else
                resources.findall(f'{{{CORE}}}object'))}
    build = root.find(f'{{{CORE}}}build')
    parts: list[tuple[str, np.ndarray]] = []
    for item in ([] if build is None else
                 build.findall(f'{{{CORE}}}item')):
        parts += _placed_corners(objects, item.get('objectid'),
                                 _transform(item.get('transform')))
    if not parts:
        raise ValueError(f'{path} places no meshes in its build')
    parts = [(name, corners * scale) for name, corners in parts]
    return mesh_geometry(parts, length_unit='m')

save ¶

save(
    obj: Geometry,
    path: str | PathLike,
    unit_system: Any = None,
) -> None

Write the geometry's face elements as 3MF — one named object per block, in metres (3MF can say so, so nothing is lost to an assumed unit; unit_system is accepted for the exporter registry and unused, because the file declares its own).

A geometry with no face elements is refused, like STL.