object-healer 0.1.0__py3-none-any.whl

object_healer/__init__.py

@@ -0,0 +1,3 @@
+"""ObjectHealer: repair meshes for 3D printing with headless Blender."""
+
+__version__ = "0.1.0"

object_healer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

object_healer/blender.py

@@ -0,0 +1,169 @@
+"""Find Blender and run the repair pass (heal.py) in it, one Blender process per file."""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from importlib import resources
+
+from . import gltf
+
+# Exactly the formats heal.py imports and exports. Never .blend: a Blender file can carry
+# Python (drivers, registered text blocks) that runs if auto-run is ever on.
+SUPPORTED = (".obj", ".stl", ".ply", ".glb", ".gltf")
+MAC_APP_PATHS = (
+    "/Applications/Blender.app/Contents/MacOS/Blender",
+    "~/Applications/Blender.app/Contents/MacOS/Blender",
+)
+RESULT_PREFIX = "OBJECT_HEALER_RESULT "
+DEFAULT_TIMEOUT = 300
+
+NOT_FOUND = (
+    "Blender was not found. Install Blender 4.0 or later from https://www.blender.org/download/ "
+    "or set BLENDER to its executable (on a Mac, /Applications/Blender.app/Contents/MacOS/Blender)."
+)
+
+
+class BlenderNotFound(RuntimeError):
+    pass
+
+
+def _executable(path):
+    return os.path.isfile(path) and os.access(path, os.X_OK)
+
+
+def find_blender(env=None, which=shutil.which, app_paths=MAC_APP_PATHS):
+    """$BLENDER, then the usual Blender.app locations, then `blender` on PATH."""
+    env = os.environ if env is None else env
+    configured = env.get("BLENDER")
+    if configured:
+        path = os.path.expanduser(configured)
+        if _executable(path):
+            return path
+        raise BlenderNotFound(f"BLENDER is set to {configured!r}, which is not an executable file.")
+    for path in app_paths:
+        path = os.path.expanduser(path)
+        if _executable(path):
+            return path
+    found = which("blender")
+    if found:
+        return found
+    raise BlenderNotFound(NOT_FOUND)
+
+
+def heal_script():
+    return str(resources.files("object_healer") / "heal.py")
+
+
+def default_output(path):
+    stem, ext = os.path.splitext(path)
+    return stem + "_healed" + ext
+
+
+@dataclass
+class HealResult:
+    ok: bool
+    input: str
+    output: str | None = None
+    vertices: int | None = None
+    faces: int | None = None
+    reason: str | None = None
+    floaters_removed: int | None = None
+
+
+def check_paths(src, dst):
+    """Return a reason the pair can't be healed, or None."""
+    if not os.path.isfile(src):
+        return "no such file"
+    if any(os.path.splitext(p)[1].lower() in (".blend", ".blend1") for p in (src, dst)):
+        return "Blender files (.blend) are refused: they can carry embedded Python"
+    for path, what in ((src, "input"), (dst, "output")):
+        ext = os.path.splitext(path)[1].lower()
+        if ext not in SUPPORTED:
+            return f"unsupported {what} format {ext or '(none)'}; use one of {', '.join(SUPPORTED)}"
+    if os.path.realpath(src) == os.path.realpath(dst):
+        return "the output would overwrite the input"
+    if not os.path.isdir(os.path.dirname(dst)):
+        return f"the output folder {os.path.dirname(dst)} does not exist"
+    return None
+
+
+def run_blender(src, dst, blender, timeout=DEFAULT_TIMEOUT, run=subprocess.run, *, cwd):
+    """Run heal.py in Blender with factory settings (no user add-ons or startup scripts) and
+    auto-run of embedded Python off, from cwd, a folder object-healer created."""
+    cmd = [blender, "--background", "--factory-startup", "--disable-autoexec",
+           "--python-exit-code", "1", "--python", heal_script(), "--", src, "--output", dst]
+    try:
+        proc = run(cmd, capture_output=True, text=True, timeout=timeout, cwd=cwd)
+    except subprocess.TimeoutExpired:
+        return HealResult(False, src, reason=f"Blender took longer than {timeout:g} s")
+    except OSError as e:
+        return HealResult(False, src, reason=f"could not start Blender: {e}")
+    for line in proc.stdout.splitlines():
+        if line.startswith(RESULT_PREFIX):
+            r = json.loads(line[len(RESULT_PREFIX):])
+            return HealResult(r["status"] == "ok", src, r["output"], r["vertices"], r["faces"], r["reason"])
+    tail = [l for l in proc.stderr.splitlines() if l.strip()] or \
+           [l for l in proc.stdout.splitlines() if l.strip()]
+    return HealResult(False, src, reason=f"Blender exited with status {proc.returncode} and no result"
+                      + (f": {tail[-1].strip()}" if tail else ""))
+
+
+def strip_in_subprocess(src, dst, timeout=DEFAULT_TIMEOUT, run=subprocess.run, *, cwd):
+    """Run floaters.strip_floaters in its own Python (PyMeshLab's Qt 5 must stay out of the
+    window's process); return the number of pieces removed or raise RuntimeError.
+
+    -I keeps the working directory, PYTHONPATH and user site-packages off sys.path, so a
+    planted object_healer/ folder can't stand in for the installed package; cwd is a folder
+    object-healer created as well.
+    """
+    try:
+        proc = run([sys.executable, "-I", "-m", "object_healer.floaters", src, dst],
+                   capture_output=True, text=True, timeout=timeout, cwd=cwd)
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(f"took longer than {timeout:g} s") from None
+    for line in reversed(proc.stdout.splitlines()):
+        try:
+            r = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(r, dict) and "removed" in r:
+            return r["removed"]
+        if isinstance(r, dict) and "error" in r:
+            raise RuntimeError(r["error"])
+    tail = [l for l in proc.stderr.splitlines() if l.strip()]
+    raise RuntimeError(f"exited with status {proc.returncode}" + (f": {tail[-1].strip()}" if tail else ""))
+
+
+def heal_file(src, dst=None, *, blender, strip_floaters=False, timeout=DEFAULT_TIMEOUT,
+              run=subprocess.run):
+    """Heal one mesh into dst (default <name>_healed.<ext> next to src)."""
+    src = os.path.abspath(src)
+    dst = os.path.abspath(dst or default_output(src))
+    problem = check_paths(src, dst)
+    if problem:
+        return HealResult(False, src, reason=problem)
+
+    with tempfile.TemporaryDirectory(prefix="object-healer-") as tmp:
+        source = src
+        if os.path.splitext(src)[1].lower() in (".gltf", ".glb"):
+            # Blender (and PyMeshLab) get a private copy holding only the files the model may
+            # reference, so nothing outside its folder is read and nothing can be swapped in.
+            try:
+                source = gltf.stage(src, os.path.join(tmp, "model"))
+            except gltf.Refused as e:
+                return HealResult(False, src, reason=str(e))
+        removed = None
+        if strip_floaters:
+            stripped = os.path.join(tmp, "stripped.ply")
+            try:
+                removed = strip_in_subprocess(source, stripped, timeout, run, cwd=tmp)
+            except (RuntimeError, OSError) as e:
+                return HealResult(False, src, reason=f"floater removal failed: {e}")
+            source = stripped
+        result = run_blender(source, dst, blender, timeout, run, cwd=tmp)
+    result.input = src
+    result.floaters_removed = removed
+    return result

object_healer/cli.py

@@ -0,0 +1,74 @@
+"""object-healer: with no command, open the window; `object-healer heal` repairs from the shell.
+
+Exit status: 0 when every file healed, 1 when any failed, 2 for a usage or setup error.
+"""
+import argparse
+import sys
+
+from . import __version__, floaters
+from .blender import (DEFAULT_TIMEOUT, SUPPORTED, BlenderNotFound, HealResult, find_blender,
+                      heal_file)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="object-healer",
+        description="Repair meshes for 3D printing in headless Blender. "
+                    "With no command, opens the drag-and-drop window.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.add_parser("gui", help="open the drag-and-drop window (the default)")
+    heal = sub.add_parser(
+        "heal", help="heal files from the command line",
+        description="Merge duplicate vertices, make normals consistent and fill holes. "
+                    f"Formats: {' '.join(SUPPORTED)}. Each IN is written to <name>_healed.<ext> "
+                    "next to it unless -o names the output.",
+    )
+    heal.add_argument("inputs", nargs="+", metavar="IN", help="mesh file(s) to heal")
+    heal.add_argument("-o", "--output", metavar="OUT",
+                      help="output path for a single IN; its extension picks the format")
+    heal.add_argument("--strip-floaters", action="store_true",
+                      help="first remove pieces smaller than 5%% of the biggest piece "
+                           "(scan debris); needs object-healer[scan]")
+    heal.add_argument("--blender", metavar="PATH",
+                      help="Blender executable (default: $BLENDER, then Blender.app, then PATH)")
+    heal.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT, metavar="SECONDS",
+                      help=f"limit per file (default {DEFAULT_TIMEOUT})")
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command in (None, "gui"):
+        from .gui import run_gui
+        return run_gui()
+
+    if args.output and len(args.inputs) > 1:
+        parser.error("-o/--output takes a single IN")
+    if args.timeout <= 0:
+        parser.error("--timeout must be positive")
+    if args.strip_floaters and not floaters.available():
+        print(f"object-healer: error: {floaters.MISSING_EXTRA}", file=sys.stderr)
+        return 2
+    try:
+        blender = find_blender({"BLENDER": args.blender} if args.blender else None)
+    except BlenderNotFound as e:
+        print(f"object-healer: error: {e}", file=sys.stderr)
+        return 2
+
+    failed = 0
+    for src in args.inputs:
+        try:
+            r = heal_file(src, args.output, blender=blender, strip_floaters=args.strip_floaters,
+                          timeout=args.timeout)
+        except Exception as e:  # one bad file must not stop the rest of the batch
+            r = HealResult(False, src, reason=f"unexpected error: {type(e).__name__}: {e}")
+        if r.ok:
+            extra = f"; removed {r.floaters_removed} floating piece(s)" if r.floaters_removed else ""
+            print(f"healed {src} -> {r.output} ({r.vertices:,} vertices, {r.faces:,} faces{extra})")
+        else:
+            failed += 1
+            print(f"failed {src}: {r.reason}", file=sys.stderr)
+    return 1 if failed else 0

object_healer/floaters.py

@@ -0,0 +1,110 @@
+"""Optional pre-pass for raw scans: drop small disconnected pieces (turntable and background
+debris) with PyMeshLab before the Blender pass. Blender's hole filling closes the object but
+keeps every floating piece, so scans that include their surroundings need this first.
+
+PyMeshLab bundles its own Qt 5, which must not load into a process that already has PyQt6's
+Qt 6 (the window), so object-healer runs this module in a subprocess:
+
+    python -m object_healer.floaters SRC DST    # prints {"removed": N} or {"error": "..."}
+"""
+import importlib.util
+import json
+import sys
+
+MISSING_EXTRA = (
+    "--strip-floaters needs PyMeshLab, which ships with the scan extra: "
+    "uv tool install 'object-healer[scan]' (or pipx install 'object-healer[scan]')"
+)
+DEFAULT_PERCENT = 5.0
+
+
+class MissingExtra(RuntimeError):
+    pass
+
+
+def available():
+    """Whether PyMeshLab is installed, without importing it (see the module docstring)."""
+    return importlib.util.find_spec("pymeshlab") is not None
+
+
+def _components(ms):
+    return ms.get_topological_measures()["connected_components_number"]
+
+
+def largest_piece_diagonal(vertices, faces):
+    """Bounding-box diagonal of the biggest piece, where faces sharing a vertex join a piece.
+
+    Union-find in numpy (hook roots to the smaller root, then compress), so the cost tracks
+    the face count rather than the number of pieces.
+    """
+    import numpy as np
+
+    parent = np.arange(len(vertices))
+    a = np.concatenate([faces[:, 0], faces[:, 1]])
+    b = np.concatenate([faces[:, 1], faces[:, 2]])
+    while True:
+        ra, rb = parent[a], parent[b]
+        if (ra == rb).all():
+            break
+        low = np.minimum(ra, rb)
+        np.minimum.at(parent, ra, low)
+        np.minimum.at(parent, rb, low)
+        while True:
+            jumped = parent[parent]
+            if (jumped == parent).all():
+                break
+            parent = jumped
+
+    used = np.unique(faces)
+    labels, points = parent[used], vertices[used]
+    order = np.argsort(labels, kind="stable")
+    labels, points = labels[order], points[order]
+    starts = np.flatnonzero(np.r_[True, labels[1:] != labels[:-1]])
+    lo = np.minimum.reduceat(points, starts, axis=0)
+    hi = np.maximum.reduceat(points, starts, axis=0)
+    return float(np.sqrt(((hi - lo) ** 2).sum(axis=1)).max())
+
+
+def strip_floaters(src, dst, percent=DEFAULT_PERCENT):
+    """Write src to dst without pieces smaller than percent of the biggest piece; return how
+    many pieces were removed.
+
+    The size is each piece's bounding-box diagonal. The threshold is taken from the biggest
+    piece, not from the whole mesh: MeshLab's own percentage is of the whole mesh's bounding
+    box, so one far-off speck can make it delete the object itself.
+    """
+    try:
+        import pymeshlab
+    except ImportError:
+        raise MissingExtra(MISSING_EXTRA) from None
+
+    ms = pymeshlab.MeshSet()
+    ms.load_new_mesh(src)
+    mesh = ms.current_mesh()
+    if mesh.face_number() == 0:
+        raise ValueError("the file has no faces (a point cloud?), so there are no pieces to compare")
+    before = _components(ms)
+    if before > 1:
+        threshold = largest_piece_diagonal(mesh.vertex_matrix(), mesh.face_matrix()) * percent / 100
+        ms.meshing_remove_connected_component_by_diameter(
+            mincomponentdiag=pymeshlab.PureValue(threshold))
+    removed = before - _components(ms)
+    ms.save_current_mesh(dst)
+    return removed
+
+
+def main(argv):
+    if len(argv) != 2:
+        print(json.dumps({"error": "usage: python -m object_healer.floaters SRC DST"}))
+        return 2
+    try:
+        removed = strip_floaters(*argv)
+    except Exception as e:
+        print(json.dumps({"error": " ".join(str(e).split()) or type(e).__name__}))
+        return 1
+    print(json.dumps({"removed": removed}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

object_healer/gltf.py

@@ -0,0 +1,164 @@
+"""Stage a glTF or GLB, and only the files it may reference, into a private folder for Blender.
+
+A .gltf (and the JSON chunk of a .glb) names its buffers and images by URI, and Blender's
+importer reads whatever they resolve to. A crafted model could otherwise pull a local file's
+bytes into the healed output. So before Blender sees anything:
+
+- every buffers[].uri and images[].uri must be a base64 data: URI or a relative path that stays
+  inside the model's own folder, judged with Blender's own rules (below), both on the path as
+  written and after symlinks are followed;
+- the model and each file it references are copied into a private folder, every referenced file
+  read through a descriptor that is checked to still be the in-folder file, and Blender is given
+  only the copy, so nothing can be swapped between the check and the import.
+
+Blender 5.1 (io_scene_gltf2, io/imp/gltf2_io_gltf.py load_uri) decodes a URI as data only when
+it starts with "data:" and contains ";base64,"; anything else, including "data:/../x", is
+read as a file at join(dirname(model), uri_to_path(uri)), where uri_to_path turns "\\" into "/",
+percent-decodes and normpaths (io/com/path.py). The data test here is stricter than Blender's,
+so whatever passes it Blender also decodes as data.
+"""
+import json
+import os
+import re
+import stat
+import struct
+from urllib.parse import unquote, urlsplit
+
+GLB_MAGIC = b"glTF"
+GLB_JSON_CHUNK = 0x4E4F534A
+DATA_URI = re.compile(r"data:[^,]*;base64,")
+
+
+class Refused(Exception):
+    pass
+
+
+def uri_to_path(uri):
+    """Blender's io_scene_gltf2 uri_to_path, verbatim in effect."""
+    return os.path.normpath(unquote(uri.replace("\\", "/")))
+
+
+def _json_from(data, glb):
+    if glb:
+        if len(data) < 20 or data[:4] != GLB_MAGIC:
+            raise ValueError("not a GLB file")
+        length, kind = struct.unpack_from("<II", data, 12)
+        if kind != GLB_JSON_CHUNK or 20 + length > len(data):
+            raise ValueError("the GLB has no JSON chunk")
+        data = data[20:20 + length]
+    doc = json.loads(data.decode("utf-8"))
+    if not isinstance(doc, dict):
+        raise ValueError("the JSON is not an object")
+    return doc
+
+
+def _uris(doc):
+    for key in ("buffers", "images"):
+        items = doc.get(key) or []
+        if not isinstance(items, list):
+            raise ValueError(f"{key} is not a list")
+        for i, item in enumerate(items):
+            if isinstance(item, dict) and "uri" in item:
+                yield f"{key}[{i}].uri", item["uri"]
+
+
+def _inside(folder, path):
+    return os.path.commonpath([folder, path]) == folder
+
+
+def reference(uri, folder):
+    """The path, relative to folder, that Blender would read for uri; None for embedded data.
+    Raises Refused naming the problem."""
+    if not isinstance(uri, str):
+        raise Refused("is not a string")
+    if uri == "" or DATA_URI.match(uri):
+        return None  # Blender skips an empty buffer URI; base64 data is decoded, not read
+    if uri.startswith("data:"):
+        raise Refused("is a data: URI without ;base64, (Blender would read it as a file path)")
+    if urlsplit(uri).scheme:
+        raise Refused("uses a URI scheme; only base64 data: URIs and files next to the model are allowed")
+    rel = uri_to_path(uri)
+    if "\x00" in rel:
+        raise Refused("contains a NUL character")
+    if os.path.isabs(rel):
+        raise Refused("is an absolute path")
+    lexical = os.path.normpath(os.path.join(folder, rel))
+    real_folder = os.path.realpath(folder)
+    if not _inside(folder, lexical) or rel in (os.curdir, os.pardir):
+        raise Refused("points outside the model's folder")
+    if not _inside(real_folder, os.path.realpath(lexical)):
+        raise Refused("points outside the model's folder (through a symlink)")
+    return rel
+
+
+def _copy_inside(folder, rel, dest):
+    """Copy folder/rel to dest through one descriptor, checked to be a regular file that is still
+    the in-folder file after symlinks are followed."""
+    path = os.path.join(folder, rel)
+    try:
+        fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+    except FileNotFoundError:
+        raise Refused("names a file that does not exist") from None
+    except OSError as e:
+        raise Refused(f"can't be opened ({e.strerror})") from None
+    opened = os.fstat(fd)
+    if not stat.S_ISREG(opened.st_mode):
+        os.close(fd)
+        raise Refused("is not a regular file")
+    with os.fdopen(fd, "rb") as f:
+        real = os.path.realpath(path)
+        try:
+            now = os.stat(real)
+        except OSError:
+            now = None
+        if (not _inside(os.path.realpath(folder), real) or now is None
+                or (now.st_dev, now.st_ino) != (opened.st_dev, opened.st_ino)):
+            raise Refused("changed or moved outside the model's folder while it was being read")
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        try:
+            out = open(dest, "xb")
+        except FileExistsError:
+            return  # the same file under another case on a case-insensitive disk
+        with out:
+            while chunk := f.read(1 << 20):
+                out.write(chunk)
+
+
+def stage(src, dest):
+    """Copy the model at src and every file it references into the new folder dest, keeping the
+    relative layout; return the copy of the model. Raises Refused with a reason for the user."""
+    glb = src.lower().endswith(".glb")
+    folder = os.path.dirname(os.path.abspath(src))
+    with open(src, "rb") as f:
+        data = f.read()
+    try:
+        doc = _json_from(data, glb)
+        uris = list(_uris(doc))
+    except (ValueError, UnicodeDecodeError) as e:
+        raise Refused(f"not a readable glTF file ({e})") from None
+
+    refs = {}
+    for label, uri in uris:
+        try:
+            rel = reference(uri, folder)
+        except Refused as e:
+            raise Refused(f"refused: {label} {uri!r} {e}") from None
+        except ValueError as e:  # a path os functions reject outright
+            raise Refused(f"refused: {label} {uri!r} is not a usable path ({e})") from None
+        if rel is not None:
+            refs.setdefault(rel, (label, uri))
+
+    os.makedirs(dest)
+    staged = os.path.join(dest, os.path.basename(src))
+    for rel, (label, uri) in refs.items():
+        if os.path.normcase(rel) == os.path.normcase(os.path.basename(src)):
+            continue  # the model naming itself; the copy written below serves
+        try:
+            _copy_inside(folder, rel, os.path.join(dest, rel))
+        except Refused as e:
+            raise Refused(f"refused: {label} {uri!r} {e}") from None
+        except ValueError as e:
+            raise Refused(f"refused: {label} {uri!r} is not a usable path ({e})") from None
+    with open(staged, "wb") as f:
+        f.write(data)  # the exact bytes that were checked
+    return staged