`visualdynamics.io.threemf`¶

threemf ¶

Read and write 3MF meshes, a CAD export format that keeps parts and units.

A .3mf is a zip holding one XML model: triangles that are already tessellated (read as tri3 face elements as they are), named objects for an assembly's parts, each of which becomes a named element group, and a declared unit, so there is nothing to ask at import. SolidWorks writes it from Save As, so a SolidWorks model can be imported by exporting it to 3MF; the native format is closed. STEP (io.step) is read through a CAD kernel; 3MF needs none.

Assemblies are component references with affine transforms. They are resolved recursively, so each placed instance of a part has its triangles where the assembly put them. Only the standard library (zipfile and xml.etree) and numpy are used.

Functions:

Name	Description
`load`	Read a 3MF file as a geometry, one named element group per placed
`save`	Write the geometry's face elements as 3MF, one named object per

Classes¶

Functions:¶

load ¶

load(path: str | PathLike) -> Geometry

Read a 3MF file as a geometry, one named element group per placed part.

Parameters:

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

Returns:

Type	Description
`Geometry`	Triangle face elements, converted from the file's declared unit (millimeters when it declares none) with the units defined. There is one element group per part instance the build places, named with the part's own name, or 'object ' when it has none.

Raises:

Type	Description
`ValueError`	When the file has no model document, declares a unit 3MF does not define, or places no meshes in its build.

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

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

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

    Returns
    -------
    Geometry
        Triangle face elements, converted from the file's declared unit
        (millimeters when it declares none) with the units defined. There
        is one element group per part instance the build places, named
        with the part's own name, or 'object <id>' when it has none.

    Raises
    ------
    ValueError
        When the file has no model document, declares a unit 3MF does
        not define, or places no meshes in its build.
    """
    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 element group.

The coordinates are written as stored. The file declares them in meters when the geometry's units are defined, which is what they are, and declares no unit when they are not, which 3MF reads as millimeters. unit_system is accepted because every exporter takes it, and is not used, since the file declares its own unit. A geometry with no face elements is refused with ValueError, as for STL.