urdf-mesh-optimizer 0.2.0__py3-none-any.whl

optimizer/__init__.py

@@ -0,0 +1,3 @@
+"""urdf-mesh-optimizer: lightweight visual and collision meshes for ROS 2 / MoveIt."""
+
+__version__ = "0.2.0"

optimizer/cli.py

@@ -0,0 +1,404 @@
+"""
+cli.py - Command-line interface for urdf-mesh-optimizer.
+
+Single file:
+    urdf-mesh-optimizer --input model.stl --output model_small.obj --triangles 5000
+    urdf-mesh-optimizer --input model.stl --output model_small.obj --reduction 80
+
+URDF pair (visual + collision):
+    urdf-mesh-optimizer --input cell.stl --urdf-output ./output \
+        --visual 20000 --collision 3000
+
+Batch (folder):
+    urdf-mesh-optimizer --folder ./cell_assets --output ./output --collision 5000
+
+Whole robot (every mesh in a URDF, URIs rewritten):
+    urdf-mesh-optimizer --urdf my_robot.urdf --output ./optimized --collision 3000
+
+Exit codes:
+    0  success
+    1  a known, reported error (bad input, bad mesh, bad arguments combination
+       caught at runtime rather than by argparse)
+    2  argument parsing error (raised by argparse itself, e.g. missing a
+       required flag)
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from optimizer import __version__
+from optimizer.core import (
+    SUPPORTED_FORMATS,
+    clean_mesh,
+    load_mesh,
+    resolve_output_path,
+    resolve_target_triangles,
+    save_mesh,
+    simplify_mesh,
+)
+from optimizer.metrics import build_report, print_report, save_report
+from optimizer.urdf_export import export_urdf_pair
+from optimizer.urdf_robot import UrdfError, optimize_urdf, print_urdf_summary
+
+log = logging.getLogger("optimizer")
+
+
+class CliError(Exception):
+    """A known, user-facing error. Caught in main() and reported with exit code 1."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _process_single(args: argparse.Namespace) -> None:
+    log.info("Loading '%s' …", args.input)
+    mesh = load_mesh(args.input)
+    mesh = clean_mesh(mesh)
+
+    target = resolve_target_triangles(mesh, args.triangles, args.reduction)
+    output_path = resolve_output_path(args.output, args.format)
+
+    if args.dry_run:
+        print(
+            f"[dry-run] Would simplify '{args.input}' ({len(mesh.triangles):,} triangles) "
+            f"→ {target:,} triangles"
+        )
+        print(f"[dry-run] Would write → '{output_path}'")
+        if args.save_report:
+            report_path = str(Path(output_path).with_suffix(".report.json"))
+            print(f"[dry-run] Would save report → '{report_path}'")
+        return
+
+    log.info("Simplifying to %s triangles …", f"{target:,}")
+    result, elapsed = simplify_mesh(mesh, target)
+
+    save_mesh(result, output_path)
+    log.info("Saved → '%s'", output_path)
+
+    report = build_report(
+        args.input,
+        output_path,
+        mesh,
+        result,
+        elapsed,
+        compute_hausdorff=not args.skip_hausdorff,
+    )
+    print_report(report)
+
+    if args.save_report:
+        report_path = str(Path(output_path).with_suffix(".report.json"))
+        save_report(report, report_path)
+
+
+def _process_urdf(args: argparse.Namespace) -> None:
+    if args.visual is None or args.collision is None:
+        raise CliError("--urdf-output requires both --visual and --collision triangle counts.")
+
+    if args.dry_run:
+        mesh = load_mesh(args.input)
+        stem = Path(args.input).stem
+        out = Path(args.urdf_output)
+        visual_path = out / f"{stem}_visual.stl"
+        collision_path = out / f"{stem}_collision.stl"
+        snippet_path = out / f"{stem}_urdf_snippet.xml"
+        print(f"[dry-run] Would simplify '{args.input}' ({len(mesh.triangles):,} triangles)")
+        print(f"[dry-run] Would write → '{visual_path}' ({args.visual:,} triangles)")
+        print(f"[dry-run] Would write → '{collision_path}' ({args.collision:,} triangles)")
+        print(f"[dry-run] Would write → '{snippet_path}'")
+        return
+
+    export_urdf_pair(
+        input_path=args.input,
+        output_dir=args.urdf_output,
+        visual_triangles=args.visual,
+        collision_triangles=args.collision,
+        compute_hausdorff=not args.skip_hausdorff,
+    )
+
+
+def _process_batch(args: argparse.Namespace) -> None:
+    folder = Path(args.folder)
+    if not folder.is_dir():
+        raise CliError(f"'{folder}' is not a directory.")
+
+    out_dir = Path(args.output) if args.output else folder / "optimized"
+    files = sorted(f for f in folder.iterdir() if f.suffix.lower() in SUPPORTED_FORMATS)
+
+    if not files:
+        raise CliError(f"No supported mesh files found in '{folder}'.")
+
+    if args.dry_run:
+        print(f"[dry-run] Would process {len(files)} mesh(es) in '{folder}' → '{out_dir}'")
+        for f in files:
+            print(f"[dry-run]   {f.name}")
+        return
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    log.info("Found %d mesh(es) in '%s'. Processing …", len(files), folder)
+    all_reports = []
+    failures = 0
+
+    for f in files:
+        try:
+            mesh = load_mesh(str(f))
+            mesh = clean_mesh(mesh)
+            target = resolve_target_triangles(mesh, args.triangles, args.reduction)
+            result, elapsed = simplify_mesh(mesh, target)
+            out_path = resolve_output_path(str(out_dir / f.name), args.format)
+            save_mesh(result, out_path)
+            report = build_report(
+                str(f),
+                out_path,
+                mesh,
+                result,
+                elapsed,
+                compute_hausdorff=not args.skip_hausdorff,
+            )
+            print_report(report)
+            all_reports.append(report)
+        except Exception as exc:
+            log.warning("Skipping '%s': %s", f.name, exc)
+            failures += 1
+
+    if args.save_report:
+        import json
+
+        report_path = out_dir / "batch_report.json"
+        with open(report_path, "w") as fh:
+            json.dump(all_reports, fh, indent=2)
+        log.info("Batch report saved → %s", report_path)
+
+    if failures and not all_reports:
+        raise CliError(f"All {failures} file(s) in the batch failed to process.")
+
+
+def _parse_package_paths(entries: list[str] | None) -> dict[str, str]:
+    paths = {}
+    for entry in entries or []:
+        name, sep, path = entry.partition("=")
+        if not sep or not name or not path:
+            raise CliError(f"--package-path expects NAME=DIR, got '{entry}'.")
+        paths[name] = path
+    return paths
+
+
+def _process_robot_urdf(args: argparse.Namespace) -> None:
+    if args.collision is None:
+        raise CliError("--urdf requires --collision (per-mesh collision triangle budget).")
+    if args.output is None:
+        raise CliError("--urdf requires --output (directory for the rewritten URDF + meshes).")
+    try:
+        summary = optimize_urdf(
+            args.urdf,
+            args.output,
+            collision_triangles=args.collision,
+            visual_triangles=args.visual,
+            package_paths=_parse_package_paths(args.package_path),
+            mesh_uri_prefix=args.mesh_uri_prefix,
+            compute_hausdorff=not args.skip_hausdorff,
+            dry_run=args.dry_run,
+        )
+    except UrdfError as exc:
+        raise CliError(str(exc)) from exc
+    print_urdf_summary(summary, dry_run=args.dry_run)
+    if not args.dry_run and not args.mesh_uri_prefix:
+        log.info(
+            "Mesh URIs are relative to the output URDF. For RViz / MoveIt, install the output "
+            "into a package and pass --mesh-uri-prefix package://<pkg>/<dir>."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="urdf-mesh-optimizer",
+        description=(
+            "Mesh optimization toolkit for ROS2, MoveIt, and digital twins: "
+            "decimation, URDF export, and geometric validation."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Reduce a single file to 5 000 triangles
+  urdf-mesh-optimizer --input gear.stl --output gear_small.obj --triangles 5000
+
+  # Reduce by percentage
+  urdf-mesh-optimizer --input env.ply --output env_small.ply --reduction 80
+
+  # Preview what a run would do without writing anything
+  urdf-mesh-optimizer --input gear.stl --output gear_small.obj --triangles 5000 --dry-run
+
+  # Generate URDF-ready visual + collision pair
+  urdf-mesh-optimizer --input robot_cell.stl --urdf-output ./output \\
+      --visual 20000 --collision 3000
+
+  # Batch-process a whole folder, forcing OBJ output regardless of source format
+  urdf-mesh-optimizer --folder ./cell_assets --output ./optimized \\
+      --collision 5000 --format obj
+
+  # Optimize every mesh in a robot description, rewriting the URDF to match
+  urdf-mesh-optimizer --urdf ur5e.urdf --output ./ur5e_optimized --collision 2000 \\
+      --mesh-uri-prefix package://ur5e_description/meshes_optimized
+
+  # Verbose logging for debugging a large batch job
+  urdf-mesh-optimizer --folder ./cell_assets --collision 5000 -v
+""",
+    )
+
+    p.add_argument("--version", action="version", version=f"urdf-mesh-optimizer {__version__}")
+
+    # --- Input modes ---
+    input_group = p.add_mutually_exclusive_group(required=True)
+    input_group.add_argument("--input", metavar="FILE", help="Single input mesh file.")
+    input_group.add_argument("--folder", metavar="DIR", help="Folder of mesh files (batch mode).")
+    input_group.add_argument(
+        "--urdf",
+        metavar="FILE",
+        help="Robot URDF: optimize every mesh it references and write a rewritten copy "
+        "(robot mode). Requires --output DIR and --collision N; --visual N is optional.",
+    )
+
+    # --- Output ---
+    p.add_argument(
+        "--output",
+        metavar="PATH",
+        help="Output file (single mode) or output directory (batch mode).",
+    )
+    p.add_argument(
+        "--urdf-output",
+        metavar="DIR",
+        help="Output directory for URDF pair (activates URDF mode).",
+    )
+    p.add_argument(
+        "--format",
+        metavar="EXT",
+        help="Force output format (e.g. 'obj', 'stl'), overriding the output "
+        "path's extension. Applies to single and batch modes.",
+    )
+
+    # --- Target size ---
+    size_group = p.add_mutually_exclusive_group()
+    size_group.add_argument(
+        "--triangles", type=int, metavar="N", help="Target triangle count (absolute)."
+    )
+    size_group.add_argument(
+        "--reduction", type=float, metavar="PCT", help="Reduction percentage, e.g. 80 → keep 20%%."
+    )
+
+    # --- URDF pair sizes ---
+    p.add_argument(
+        "--visual",
+        type=int,
+        metavar="N",
+        help="Triangle count for visual mesh (URDF pair mode; optional per-mesh budget in "
+        "robot mode).",
+    )
+    p.add_argument(
+        "--collision",
+        type=int,
+        metavar="N",
+        help="Triangle count for collision mesh (URDF pair / batch mode; per-mesh budget "
+        "in robot mode).",
+    )
+
+    # --- Robot (URDF) mode ---
+    p.add_argument(
+        "--package-path",
+        action="append",
+        metavar="NAME=DIR",
+        help="Where to find a ROS package referenced as package://NAME/... (repeatable). "
+        "Otherwise found next to the URDF or via AMENT_PREFIX_PATH.",
+    )
+    p.add_argument(
+        "--mesh-uri-prefix",
+        metavar="URI",
+        help="Prefix for rewritten mesh URIs in robot mode, e.g. "
+        "package://my_robot_description/meshes_optimized (default: relative paths).",
+    )
+
+    # --- Extras ---
+    p.add_argument(
+        "--save-report",
+        action="store_true",
+        help="Persist a JSON performance/quality report alongside output.",
+    )
+    p.add_argument(
+        "--skip-hausdorff",
+        action="store_true",
+        help="Skip Hausdorff distance computation (faster for large meshes).",
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would happen without reading targets or writing any files.",
+    )
+    p.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase logging verbosity. Repeat for more detail (-v, -vv).",
+    )
+
+    return p
+
+
+def _configure_logging(verbosity: int) -> None:
+    """Default shows progress (INFO); -v adds debug detail from dependencies too."""
+    level = logging.DEBUG if verbosity >= 1 else logging.INFO
+    logging.basicConfig(level=level, format="[%(name)s] %(message)s")
+    if verbosity == 0:
+        logging.getLogger("open3d").setLevel(logging.WARNING)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    _configure_logging(args.verbose)
+
+    try:
+        # ---- Routing ----
+        if args.folder:
+            if args.triangles is None and args.reduction is None and args.collision is None:
+                parser.error("Batch mode requires --triangles, --reduction, or --collision.")
+            # In batch mode --collision is a shorthand for --triangles
+            if args.collision and args.triangles is None and args.reduction is None:
+                args.triangles = args.collision
+            _process_batch(args)
+
+        elif args.urdf:
+            _process_robot_urdf(args)
+
+        elif args.urdf_output:
+            _process_urdf(args)
+
+        else:
+            if args.output is None:
+                parser.error("--output is required in single-file mode.")
+            if args.triangles is None and args.reduction is None:
+                parser.error("Single-file mode requires --triangles or --reduction.")
+            _process_single(args)
+
+    except CliError as exc:
+        log.error("%s", exc)
+        sys.exit(1)
+    except (FileNotFoundError, ValueError, RuntimeError) as exc:
+        log.error("%s", exc)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

optimizer/core.py

@@ -0,0 +1,111 @@
+"""
+core.py - Mesh loading, simplification, and cleaning logic.
+Supports: STL, OBJ, PLY, OFF, GLB/GLTF
+"""
+
+import time
+from pathlib import Path
+
+import open3d as o3d
+
+SUPPORTED_FORMATS = {".stl", ".obj", ".ply", ".off", ".glb", ".gltf"}
+
+
+def load_mesh(path: str) -> o3d.geometry.TriangleMesh:
+    """Load a mesh from any supported format."""
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"Input file not found: '{path}'.")
+    if p.suffix.lower() not in SUPPORTED_FORMATS:
+        raise ValueError(
+            f"Unsupported format: '{p.suffix}'. " f"Supported: {', '.join(SUPPORTED_FORMATS)}"
+        )
+    mesh = o3d.io.read_triangle_mesh(str(p))
+    if len(mesh.triangles) == 0:
+        raise RuntimeError(f"No triangles found in '{path}'. File may be empty or corrupt.")
+    return mesh
+
+
+def clean_mesh(mesh: o3d.geometry.TriangleMesh) -> o3d.geometry.TriangleMesh:
+    """Remove duplicated vertices, degenerate triangles, and unreferenced geometry."""
+    mesh.remove_duplicated_vertices()
+    mesh.remove_duplicated_triangles()
+    mesh.remove_degenerate_triangles()
+    mesh.remove_unreferenced_vertices()
+    return mesh
+
+
+def simplify_mesh(
+    mesh: o3d.geometry.TriangleMesh,
+    target_triangles: int,
+) -> tuple[o3d.geometry.TriangleMesh, float]:
+    """
+    Simplify a mesh using Quadric Error Metrics (QEM).
+
+    Returns:
+        (simplified_mesh, processing_time_sec)
+    """
+    t0 = time.perf_counter()
+    # open3d renamed this method to simplify_quadric_decimation in 0.19;
+    # support both so the tool works across the >=0.18 range we advertise.
+    if hasattr(mesh, "simplify_quadric_decimation"):
+        simplified = mesh.simplify_quadric_decimation(target_number_of_triangles=target_triangles)
+    else:
+        simplified = mesh.simplify_quadric_error_metrics(
+            target_number_of_triangles=target_triangles
+        )
+    elapsed = time.perf_counter() - t0
+    simplified = clean_mesh(simplified)
+    return simplified, elapsed
+
+
+def save_mesh(mesh: o3d.geometry.TriangleMesh, path: str) -> None:
+    """Save a mesh; output format is inferred from the file extension."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # STL export silently fails (writes a 0-byte file) without triangle
+    # normals. simplify_quadric_decimation doesn't carry normals through,
+    # so recompute them unconditionally before every write.
+    mesh.compute_triangle_normals()
+    success = o3d.io.write_triangle_mesh(str(p), mesh)
+    if not success:
+        raise RuntimeError(f"Failed to write mesh to '{path}'.")
+
+
+def resolve_output_path(path: str, format_override: str | None) -> str:
+    """
+    Apply an explicit --format override to an output path, replacing its
+    extension. Validates the requested format is supported.
+    """
+    if format_override is None:
+        return path
+    fmt = format_override.lower().lstrip(".")
+    suffix = f".{fmt}"
+    if suffix not in SUPPORTED_FORMATS:
+        raise ValueError(
+            f"Unsupported --format '{format_override}'. "
+            f"Supported: {', '.join(sorted(s.lstrip('.') for s in SUPPORTED_FORMATS))}"
+        )
+    return str(Path(path).with_suffix(suffix))
+
+
+def resolve_target_triangles(
+    mesh: o3d.geometry.TriangleMesh,
+    target_triangles: int | None,
+    reduction_percent: float | None,
+) -> int:
+    """
+    Resolve target triangle count from either an absolute value or a percentage.
+    Exactly one of the two arguments must be provided.
+    """
+    original = len(mesh.triangles)
+    if target_triangles is not None and reduction_percent is not None:
+        raise ValueError("Provide --triangles OR --reduction, not both.")
+    if target_triangles is not None:
+        return int(target_triangles)
+    if reduction_percent is not None:
+        if not (0 < reduction_percent < 100):
+            raise ValueError("--reduction must be between 0 and 100 (exclusive).")
+        keep = 1.0 - (reduction_percent / 100.0)
+        return max(1, int(original * keep))
+    raise ValueError("Provide --triangles or --reduction.")

optimizer/metrics.py

@@ -0,0 +1,122 @@
+"""
+metrics.py - Geometry validation and performance reporting.
+
+Computes:
+  - Triangle counts (before / after)
+  - File size delta
+  - Processing time
+  - Hausdorff distance (geometric deviation estimate)
+"""
+
+import json
+import logging
+from pathlib import Path
+
+import numpy as np
+import open3d as o3d
+
+log = logging.getLogger("optimizer")
+
+
+# ---------------------------------------------------------------------------
+# Hausdorff distance
+# ---------------------------------------------------------------------------
+
+
+def hausdorff_distance(
+    original: o3d.geometry.TriangleMesh,
+    simplified: o3d.geometry.TriangleMesh,
+    n_samples: int = 10_000,
+) -> dict[str, float]:
+    """
+    Estimate one-sided and symmetric Hausdorff distances by sampling
+    points on both surfaces and querying nearest-neighbour distances.
+
+    Returns a dict with keys: max_mm, mean_mm, rms_mm
+    (assumes mesh units are millimetres; adjust label if metres).
+    """
+    pcd_orig = original.sample_points_uniformly(number_of_points=n_samples)
+    pcd_simp = simplified.sample_points_uniformly(number_of_points=n_samples)
+
+    dists_orig_to_simp = np.asarray(pcd_orig.compute_point_cloud_distance(pcd_simp))
+    dists_simp_to_orig = np.asarray(pcd_simp.compute_point_cloud_distance(pcd_orig))
+
+    all_dists = np.concatenate([dists_orig_to_simp, dists_simp_to_orig])
+
+    return {
+        "hausdorff_max": float(np.max(all_dists)),
+        "hausdorff_mean": float(np.mean(all_dists)),
+        "hausdorff_rms": float(np.sqrt(np.mean(all_dists**2))),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Performance report
+# ---------------------------------------------------------------------------
+
+
+def build_report(
+    input_path: str,
+    output_path: str,
+    original_mesh: o3d.geometry.TriangleMesh,
+    result_mesh: o3d.geometry.TriangleMesh,
+    processing_time_sec: float,
+    compute_hausdorff: bool = True,
+    hausdorff_samples: int = 10_000,
+) -> dict:
+    """Build a structured performance/quality report dict."""
+    orig_tri = len(original_mesh.triangles)
+    red_tri = len(result_mesh.triangles)
+    reduction_pct = round((1 - red_tri / orig_tri) * 100, 2) if orig_tri > 0 else 0.0
+
+    in_size = Path(input_path).stat().st_size / (1024 * 1024)
+    out_size = (
+        Path(output_path).stat().st_size / (1024 * 1024) if Path(output_path).exists() else 0.0
+    )
+
+    report = {
+        "input_file": str(input_path),
+        "output_file": str(output_path),
+        "original_triangles": orig_tri,
+        "reduced_triangles": red_tri,
+        "reduction_percent": reduction_pct,
+        "file_size_before_mb": round(in_size, 3),
+        "file_size_after_mb": round(out_size, 3),
+        "processing_time_sec": round(processing_time_sec, 4),
+    }
+
+    if compute_hausdorff:
+        h = hausdorff_distance(original_mesh, result_mesh, n_samples=hausdorff_samples)
+        report.update(h)
+
+    return report
+
+
+def print_report(report: dict) -> None:
+    """Pretty-print the report to stdout."""
+    sep = "─" * 52
+    print(f"\n{sep}")
+    print("  Mesh Preprocessing Report")
+    print(sep)
+    print(f"  Input         : {report['input_file']}")
+    print(f"  Output        : {report['output_file']}")
+    print(
+        f"  Triangles     : {report['original_triangles']:,}  →  {report['reduced_triangles']:,}"
+    )
+    print(f"  Reduction     : {report['reduction_percent']}%")
+    before, after = report["file_size_before_mb"], report["file_size_after_mb"]
+    print(f"  File size     : {before} MB  →  {after} MB")
+    print(f"  Time          : {report['processing_time_sec']} s")
+    if "hausdorff_max" in report:
+        print(f"  Hausdorff max : {report['hausdorff_max']:.6f} (mesh units)")
+        print(f"  Hausdorff RMS : {report['hausdorff_rms']:.6f} (mesh units)")
+    print(sep + "\n")
+
+
+def save_report(report: dict, path: str) -> None:
+    """Persist the report as JSON."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, "w") as fh:
+        json.dump(report, fh, indent=2)
+    log.info("Report saved → %s", p)