cut3mf 0.1.0__tar.gz

cut3mf-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest -v

cut3mf-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag matches pyproject version
+        run: |
+          version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "tag ${GITHUB_REF_NAME} does not match pyproject version ${version}" >&2
+            exit 1
+          fi
+      - run: pip install pytest -e .
+      - run: pytest -q
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cut3mf
+    permissions:
+      id-token: write             # trusted publishing, no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

cut3mf-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*_cut.3mf

cut3mf-0.1.0/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.

cut3mf-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,84 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cut3mf"
+version = "0.1.0"
+description = "Cut a slab off one face of a 3MF/STL model before slicing, e.g. a helper plate holding embedded text together"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Thomas Schank" }]
+requires-python = ">=3.10"
+keywords = ["3mf", "stl", "3d-printing", "mesh", "slicer", "cad", "multi-material", "text"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Manufacturing",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+]
+dependencies = [
+    "trimesh>=4.0",
+    "manifold3d>=3.0",
+    "numpy",
+    "lxml",
+    "networkx",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+cut3mf = "cut3mf.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/DrTom/cut3mf"
+Issues = "https://github.com/DrTom/cut3mf/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cut3mf-0.1.0/scripts/git_tag_and_push

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Tag the current commit with the version from pyproject.toml and push the tag.
+# The GitHub workflow (.github/workflows/publish.yml) then builds and publishes
+# that version to PyPI via Trusted Publishing.
+#
+# Usage: scripts/git_tag_and_push [remote]     (default remote: origin)
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+remote="${1:-origin}"
+
+# Prefer the project's virtualenv (pip install -e ".[test]").
+if [ -x .venv/bin/python ]; then
+  python=.venv/bin/python
+else
+  python=python3
+fi
+
+version="$("${python}" -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+tag="v${version}"
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "error: working tree is not clean; commit or stash first" >&2
+  exit 1
+fi
+if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then
+  echo "error: tag ${tag} already exists (bump the version in pyproject.toml)" >&2
+  exit 1
+fi
+# The tests must pass before a version goes out.
+if ! "${python}" -c 'import pytest, cut3mf' 2>/dev/null; then
+  echo "error: pytest or cut3mf not installed in ${python}; run: pip install -e \".[test]\"" >&2
+  exit 1
+fi
+"${python}" -m pytest -q
+git fetch -q "${remote}" main 2>/dev/null || true
+if ! git merge-base --is-ancestor HEAD "${remote}/main" 2>/dev/null; then
+  echo "note: HEAD is not on ${remote}/main yet; pushing the branch first"
+  git push "${remote}" HEAD:main
+fi
+
+git tag -a "${tag}" -m "cut3mf ${version}"
+git push "${remote}" "${tag}"
+echo "tagged and pushed ${tag}; the publish workflow releases it to PyPI"

cut3mf-0.1.0/src/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-0.1.0/src/cut3mf/__main__.py

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

cut3mf-0.1.0/src/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-0.1.0/src/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/tests/test_cut.py

@@ -0,0 +1,98 @@
+"""Tests build a model like the intended workflow: a body with text sunk 1 mm
+into its top, plus a 1 mm plate above the surface that joins the letters."""
+import zipfile
+from pathlib import Path
+
+import pytest
+import trimesh
+
+from cut3mf import CutError, cut_file
+from cut3mf.cli import _fix_negative_axis, main
+
+
+def _box(extents, center):
+    b = trimesh.creation.box(extents)
+    b.apply_translation(center)
+    return b
+
+
+def _model(path: Path, units: str = "millimeters", scale: float = 1.0) -> Path:
+    body = _box((40, 20, 10), (0, 0, 5))                       # z 0..10
+    l1 = _box((4, 8, 2), (-8, 0, 10))                         # z 9..11
+    l2 = _box((4, 8, 2), (8, 0, 10))
+    plate = _box((24, 12, 1), (0, 0, 10.5))                   # z 10..11
+    text = trimesh.boolean.union([l1, l2, plate], engine="manifold")
+    s = trimesh.Scene()
+    s.add_geometry(body, node_name="body", geom_name="body")
+    s.add_geometry(text, node_name="text", geom_name="text")
+    if scale != 1.0:
+        s = s.scaled(scale)
+    s.export(path)
+    if units != "millimeters":
+        # trimesh always writes unit="millimeter"; patch it like a CAD tool exporting in meters.
+        with zipfile.ZipFile(path) as z:
+            files = {n: z.read(n) for n in z.namelist()}
+        files["3D/3dmodel.model"] = files["3D/3dmodel.model"].replace(
+            b'unit="millimeter"', f'unit="{units}"'.encode(), 1)
+        with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
+            for n, data in files.items():
+                z.writestr(n, data)
+    return path
+
+
+def _load(path):
+    s = trimesh.load(path, force="scene")
+    if s.units not in (None, "millimeters"):
+        s = s.convert_units("millimeters")
+    return s
+
+
+def test_top_plate_removed(tmp_path):
+    r = cut_file(_model(tmp_path / "m.3mf"))
+    assert r.output == tmp_path / "m_cut.3mf"
+    s = _load(r.output)
+    text, body = s.geometry["text"], s.geometry["body"]
+    parts = text.split()
+    assert len(parts) == 2                                   # letters now separate
+    assert all(p.is_watertight for p in parts)
+    assert text.volume == pytest.approx(2 * 4 * 8 * 1, rel=1e-2)
+    assert text.bounds[1][2] == pytest.approx(10.0, abs=0.01)
+    assert body.volume == pytest.approx(40 * 20 * 10, rel=1e-3)
+
+
+def test_meter_units(tmp_path):
+    src = _model(tmp_path / "m.3mf", units="meter", scale=0.001)
+    r = cut_file(src)
+    assert r.extreme == pytest.approx(11.0, abs=0.01)        # read as mm
+    s = _load(r.output)
+    assert len(s.geometry["text"].split()) == 2
+
+
+def test_bottom_axis(tmp_path):
+    r = cut_file(_model(tmp_path / "m.3mf"), axis="bottom", depth=2)
+    assert r.axis == "-z"
+    s = _load(r.output)
+    assert s.geometry["body"].bounds[0][2] == pytest.approx(2.0, abs=0.01)
+
+
+def test_everything_removed_raises(tmp_path):
+    with pytest.raises(CutError):
+        cut_file(_model(tmp_path / "m.3mf"), depth=100)
+
+
+def test_bad_axis_raises(tmp_path):
+    with pytest.raises(CutError):
+        cut_file(_model(tmp_path / "m.3mf"), axis="w")
+
+
+def test_negative_axis_argv():
+    assert _fix_negative_axis(["f.3mf", "--axis", "-z"]) == ["f.3mf", "--axis=-z"]
+    assert _fix_negative_axis(["f.3mf", "--axis", "top"]) == ["f.3mf", "--axis", "top"]
+
+
+def test_cli(tmp_path, capsys):
+    src = _model(tmp_path / "m.3mf")
+    assert main([str(src), "--axis", "-z", "-o", str(tmp_path / "o.3mf")]) == 0
+    assert (tmp_path / "o.3mf").exists()
+    assert main([str(src), "-d", "100"]) == 1
+    assert "nothing left" in capsys.readouterr().err