cut3mf 0.1.0__py3-none-any.whl

cut3mf/__init__.py

@@ -0,0 +1,11 @@
+"""cut3mf: cut a slab off one face of a 3MF/STL model before slicing."""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cut3mf")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+from .core import CutError, CutResult, cut_file, cut_scene, load_scene  # noqa: E402
+
+__all__ = ["CutError", "CutResult", "cut_file", "cut_scene", "load_scene", "__version__"]

cut3mf/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

cut3mf/cli.py

@@ -0,0 +1,80 @@
+"""Command-line interface for cut3mf."""
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import CutError, cut_file
+
+EPILOG = """\
+examples:
+  cut3mf part.3mf                    remove the top 1 mm -> part_cut.3mf
+  cut3mf part.3mf -d 1.2 -o out.3mf  remove the top 1.2 mm
+  cut3mf part.3mf --axis bottom      plate on the bottom (same as --axis -z)
+  cut3mf part.3mf --at 14.5          keep everything below Z = 14.5 mm
+"""
+
+_NEG_AXIS = re.compile(r"^-[xyz]$", re.IGNORECASE)
+
+
+def _fix_negative_axis(argv: list[str]) -> list[str]:
+    """Let '--axis -z' work: argparse would read '-z' as an option."""
+    out, i = [], 0
+    while i < len(argv):
+        if argv[i] == "--axis" and i + 1 < len(argv) and _NEG_AXIS.match(argv[i + 1]):
+            out.append(f"--axis={argv[i + 1]}")
+            i += 2
+        else:
+            out.append(argv[i])
+            i += 1
+    return out
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="cut3mf",
+        description="Cut a slab off one face of a 3MF/STL model before slicing, "
+                    "e.g. a 1 mm helper plate that holds embedded text together.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("input", type=Path, help="input mesh (.3mf, .stl, .obj, ...)")
+    p.add_argument("-o", "--output", type=Path,
+                   help="output file (default: <input>_cut.<ext>)")
+    p.add_argument("-d", "--depth", type=float, default=1.0,
+                   help="thickness to remove from the outermost face, mm (default 1.0)")
+    p.add_argument("--at", "--z", dest="at", type=float,
+                   help="cut at this absolute coordinate (mm) instead of using --depth")
+    p.add_argument("-a", "--axis", default="z",
+                   help="face carrying the plate: top, bottom, front, back, left, right, "
+                        "or x, -x, y, -y, z, -z (default: top)")
+    p.add_argument("--eps", type=float, default=0.001,
+                   help="extra cut depth against coplanar slivers, mm (default 0.001)")
+    p.add_argument("-q", "--quiet", action="store_true", help="only print errors")
+    p.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = _fix_negative_axis(list(sys.argv[1:] if argv is None else argv))
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(level=logging.ERROR if args.quiet else logging.INFO,
+                        format="%(message)s")
+    try:
+        r = cut_file(args.input, args.output, axis=args.axis, depth=args.depth,
+                     at=args.at, eps=args.eps)
+    except (CutError, OSError, ValueError) as e:
+        print(f"cut3mf: error: {e}", file=sys.stderr)
+        return 1
+    if not args.quiet:
+        print(f"cut at {r.axis}={r.cut:.3f} mm (outermost {r.extreme:.3f} mm), "
+              f"{len(r.kept)} object(s) -> {r.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cut3mf/core.py

@@ -0,0 +1,159 @@
+"""Core cutting logic: remove a slab from one face of a multi-object mesh."""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import manifold3d as mf
+import numpy as np
+import trimesh
+
+log = logging.getLogger(__name__)
+
+AXES = {"x": 0, "y": 1, "z": 2}
+ALIASES = {
+    "top": "z", "bottom": "-z",
+    "back": "y", "front": "-y",
+    "right": "x", "left": "-x",
+}
+_MM = ("mm", "millimeter", "millimeters")
+
+
+class CutError(Exception):
+    """Raised when the input cannot be cut."""
+
+
+@dataclass
+class CutResult:
+    axis: str
+    cut: float
+    extreme: float
+    output: Path
+    kept: list[str] = field(default_factory=list)
+    dropped: list[str] = field(default_factory=list)
+
+
+def parse_axis(axis: str) -> tuple[int, float, str]:
+    """Return (axis index, sign, normalized name) for 'z', '-y', 'bottom', ..."""
+    a = ALIASES.get(axis.lower(), axis.lower())
+    name = a.lstrip("+-")
+    if name not in AXES:
+        raise CutError(
+            f"unknown axis '{axis}' (use top/bottom/front/back/left/right, "
+            "or x/y/z with an optional minus sign)"
+        )
+    sign = -1.0 if a.startswith("-") else 1.0
+    return AXES[name], sign, ("-" if sign < 0 else "") + name
+
+
+def _to_manifold(mesh: trimesh.Trimesh) -> mf.Manifold:
+    m = mf.Mesh(
+        vert_properties=np.asarray(mesh.vertices, dtype=np.float32),
+        tri_verts=np.asarray(mesh.faces, dtype=np.uint32),
+    )
+    return mf.Manifold(m)
+
+
+def _from_manifold(man: mf.Manifold) -> trimesh.Trimesh:
+    m = man.to_mesh()
+    return trimesh.Trimesh(
+        vertices=np.asarray(m.vert_properties)[:, :3],
+        faces=np.asarray(m.tri_verts),
+        process=True,
+    )
+
+
+def load_scene(path: Path) -> trimesh.Scene:
+    """Load a mesh file as a scene in millimeters."""
+    scene = trimesh.load(path, force="scene")
+    if scene.units and scene.units not in _MM:
+        # Some CAD tools (e.g. Onshape) write 3MF in meters.
+        log.info("converting units: %s -> millimeters", scene.units)
+        scene = scene.convert_units("millimeters")
+    elif not scene.units:
+        log.info("file has no units, assuming millimeters")
+    return scene
+
+
+def cut_scene(
+    scene: trimesh.Scene,
+    *,
+    axis: str = "z",
+    depth: float = 1.0,
+    at: float | None = None,
+    eps: float = 0.001,
+) -> tuple[trimesh.Scene, dict]:
+    """Cut a slab off one face of a scene. Returns (new scene, info dict)."""
+    ai, sign, axis_name = parse_axis(axis)
+
+    # Bake transforms so all objects share one coordinate system.
+    geoms: dict[str, trimesh.Trimesh] = {}
+    for node in scene.graph.nodes_geometry:
+        tf, gname = scene.graph[node]
+        g = scene.geometry[gname].copy()
+        g.apply_transform(tf)
+        geoms[node] = g
+    if not geoms:
+        raise CutError("no geometry found")
+
+    all_v = np.vstack([g.vertices for g in geoms.values()])
+    extreme = float(all_v[:, ai].max() if sign > 0 else all_v[:, ai].min())
+    cut = at if at is not None else extreme - sign * depth
+    # The plate's underside usually lies exactly on the cut plane; cutting
+    # exactly there leaves zero-thickness slivers, so cut a hair deeper.
+    cut -= sign * eps
+
+    # Keep the side away from the plate. Manifold keeps normal . x >= offset.
+    normal = [0.0, 0.0, 0.0]
+    normal[ai] = -sign
+    offset = -sign * cut
+
+    out = trimesh.Scene()
+    out.units = "millimeters"
+    kept, dropped = [], []
+    for name, g in geoms.items():
+        if not g.is_watertight:
+            log.warning("'%s' is not watertight, trying anyway", name)
+        man = _to_manifold(g)
+        if man.status() != mf.Error.NoError:
+            raise CutError(
+                f"'{name}' is not a valid solid ({man.status()}); "
+                "re-export or repair the mesh first"
+            )
+        trimmed = man.trim_by_plane(normal, offset)
+        res = None if trimmed.is_empty() else _from_manifold(trimmed)
+        if res is not None:
+            parts = [c for c in res.split(only_watertight=False) if abs(c.volume) > 1e-6]
+            res = (trimesh.util.concatenate(parts) if len(parts) > 1 else parts[0]) if parts else None
+        if res is None:
+            log.info("'%s' lies completely in the removed slab, dropped", name)
+            dropped.append(name)
+            continue
+        out.add_geometry(res, node_name=name, geom_name=name)
+        kept.append(name)
+
+    if not kept:
+        raise CutError(
+            f"nothing left after cutting at {axis_name}={cut:.3f} mm; "
+            "check --depth, --axis and the model's units"
+        )
+    return out, {"axis": axis_name, "cut": cut, "extreme": extreme,
+                 "kept": kept, "dropped": dropped}
+
+
+def default_output(path: Path) -> Path:
+    return path.with_name(path.stem + "_cut" + path.suffix)
+
+
+def cut_file(
+    input: str | Path,
+    output: str | Path | None = None,
+    **kwargs,
+) -> CutResult:
+    """Cut a mesh file and write the result. kwargs go to :func:`cut_scene`."""
+    src = Path(input)
+    dst = Path(output) if output else default_output(src)
+    scene, info = cut_scene(load_scene(src), **kwargs)
+    scene.export(dst)
+    return CutResult(output=dst, **info)

cut3mf-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: cut3mf
+Version: 0.1.0
+Summary: Cut a slab off one face of a 3MF/STL model before slicing, e.g. a helper plate holding embedded text together
+Project-URL: Homepage, https://github.com/DrTom/cut3mf
+Project-URL: Issues, https://github.com/DrTom/cut3mf/issues
+Author: Thomas Schank
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printing,3mf,cad,mesh,multi-material,slicer,stl,text
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Requires-Dist: lxml
+Requires-Dist: manifold3d>=3.0
+Requires-Dist: networkx
+Requires-Dist: numpy
+Requires-Dist: trimesh>=4.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cut3mf
+
+Cut a slab off one face of a 3MF or STL model before slicing.
+
+Made for a common CAD-to-slicer workaround: when text is embedded in a
+surface, the many separate letter bodies often cause trouble, in the CAD tool,
+on export, or in the slicer. Model a thin "helper plate" (e.g. 1 mm) on top of
+the surface that holds the letters together, export, then let `cut3mf` remove
+that plate. You get clean, watertight letter bodies flush with the surface,
+still as separate objects, so you can assign them their own filament.
+
+It works with any CAD tool that exports 3MF, STL or OBJ (Onshape, Fusion,
+FreeCAD, SolidWorks, ...) and any slicer that imports them (Bambu Studio,
+OrcaSlicer, PrusaSlicer, Cura, ...).
+
+## Install
+
+```bash
+pipx install cut3mf      # or: pip install cut3mf
+```
+
+## Usage
+
+```bash
+cut3mf part.3mf                    # remove the top 1 mm -> part_cut.3mf
+cut3mf part.3mf -d 1.2 -o out.3mf  # remove the top 1.2 mm
+cut3mf part.3mf --axis bottom      # plate on the bottom (same as --axis -z)
+cut3mf part.3mf --at 14.5          # keep everything below Z = 14.5 mm
+```
+
+| Option | Meaning |
+|---|---|
+| `-d, --depth` | Thickness to remove from the outermost face, mm (default 1.0) |
+| `-a, --axis` | Face with the plate: `top`, `bottom`, `front`, `back`, `left`, `right`, or `x`, `-x`, `y`, `-y`, `z`, `-z` (default `top`) |
+| `--at` | Cut at an absolute coordinate (mm) instead of a depth |
+| `-o, --output` | Output file (default `<input>_cut.<ext>`) |
+| `--eps` | Extra cut depth against coplanar slivers, mm (default 0.001) |
+
+### How it works
+
+- All objects are measured together, so every object is cut at the same plane.
+- 3MF units are respected and converted to millimeters (some tools, e.g. Onshape, export in meters). STL has no units and is taken as millimeters.
+- Use 3MF if you want separate objects (e.g. for a second filament); STL stores
+  only one combined mesh.
+- The cut uses the [Manifold](https://github.com/elalish/manifold) kernel, so cut faces are closed and results stay watertight.
+- The cut goes 1 µm deeper than requested, because the plate's underside usually lies exactly on the cut plane and an exact cut leaves zero-thickness slivers.
+
+Limits: the cut is a flat plane, and the plate must be the outermost part of the
+model in the chosen direction. 3MF output keeps the objects and their names, but
+not slicer project data such as filament assignments or print settings, so
+cut the exported model before you set it up in the slicer.
+
+### Python API
+
+```python
+from cut3mf import cut_file
+
+result = cut_file("part.3mf", axis="bottom", depth=1.0)
+print(result.output, result.kept)
+```
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+## Releasing
+
+Releases are published to PyPI by GitHub Actions using trusted publishing.
+Bump `version` in `pyproject.toml`, commit, then run:
+
+```bash
+scripts/git_tag_and_push
+```
+
+The script runs the tests, tags the commit as `v<version>` and pushes the tag;
+the publish workflow builds and uploads that version.
+
+## License
+
+MIT

cut3mf-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cut3mf/__init__.py,sha256=MT-GglMXk8nmTUmIBls9xOrK6PXBG0tDouWnfKikheQ,442
+cut3mf/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+cut3mf/cli.py,sha256=aRulNEmQLEhMtWXWwlo8W28JPBYuUZ-oLq40Ij86TiE,3144
+cut3mf/core.py,sha256=6IG0L90sV_WoXV5i2swx9z4xu1HDci5AmtX6Q7OZ_VU,5208
+cut3mf-0.1.0.dist-info/METADATA,sha256=2yiNog1Mz-AXLo8HOSJRmWIJ0Mv0ygHYjtoIZaOZU4A,4022
+cut3mf-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+cut3mf-0.1.0.dist-info/entry_points.txt,sha256=D9apIWniI-ZDLfadbvh_SQUNe9MDfO2Jw8PTWAnkSY8,43
+cut3mf-0.1.0.dist-info/licenses/LICENSE,sha256=Ms1llSYy2UX_v1xxNi3yb89rpUYlQncYR7TurGxZ0Xc,1070
+cut3mf-0.1.0.dist-info/RECORD,,

cut3mf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

cut3mf-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cut3mf = cut3mf.cli:main

cut3mf-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Schank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.