feat: add debug subcommand with analyze, slice, compare, footprint

- microfinity debug analyze: mesh diagnostics (vertices, faces, volume, issues)
- microfinity debug slice: SVG cross-section at specified Z height
- microfinity debug compare: compare two meshes (dimensions, volume diff)
- microfinity debug footprint: extract 2D footprint as SVG

Author: Your Name

TODO.md

@@ -52,7 +52,7 @@ microfinity debug [subcommand]      # Debug/visualization tools
 - [x] Implement `microfinity meshcut` subcommand
 - [x] Implement `microfinity calibrate` subcommand (stub, delegates to legacy)
 - [x] Implement `microfinity info` subcommand
-- [ ] Implement `microfinity debug` subcommand (see Debug Tooling section)
+- [x] Implement `microfinity debug` subcommand (see Debug Tooling section)
 - [ ] Remove old entry points (`microfinity-box`, `microfinity-meshcut`, etc.)
 - [x] Update pyproject.toml scripts section
 
@@ -155,10 +155,10 @@ microfinity debug footprint <file.stl> --output footprint.svg
 microfinity debug explode <file.stl> --output exploded.stl
 ```
 
-- [ ] Implement `microfinity debug slice`
-- [ ] Implement `microfinity debug compare`
-- [ ] Implement `microfinity debug analyze`
-- [ ] Implement `microfinity debug footprint`
+- [x] Implement `microfinity debug slice`
+- [x] Implement `microfinity debug compare`
+- [x] Implement `microfinity debug analyze`
+- [x] Implement `microfinity debug footprint`
 - [ ] Implement `microfinity debug explode`
 - [ ] Implement `microfinity debug measure`
 

microfinity/cli/debug.py

@@ -0,0 +1,362 @@
+#! /usr/bin/env python3
+"""
+microfinity.cli.debug - Debug tooling for mesh analysis and visualization.
+
+Provides commands for analyzing, comparing, and debugging 3D meshes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+
+def cmd_analyze(args: argparse.Namespace) -> int:
+    """Analyze a mesh file and report diagnostics."""
+    import trimesh
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"Error: File not found: {input_path}", file=sys.stderr)
+        return 1
+
+    print(f"Analyzing: {input_path}")
+    print()
+
+    try:
+        mesh = trimesh.load(str(input_path))
+    except Exception as e:
+        print(f"Error loading mesh: {e}", file=sys.stderr)
+        return 1
+
+    # Handle scene vs mesh
+    if isinstance(mesh, trimesh.Scene):
+        if len(mesh.geometry) == 0:
+            print("Error: Scene contains no geometry", file=sys.stderr)
+            return 1
+        # Combine all geometries
+        mesh = trimesh.util.concatenate(list(mesh.geometry.values()))
+
+    # Collect diagnostics
+    report: Dict[str, Any] = {
+        "file": str(input_path),
+        "format": input_path.suffix.lower(),
+        "geometry": {
+            "vertices": len(mesh.vertices),
+            "faces": len(mesh.faces),
+            "edges": len(mesh.edges_unique),
+        },
+        "bounds": {
+            "min": mesh.bounds[0].tolist(),
+            "max": mesh.bounds[1].tolist(),
+            "dimensions": (mesh.bounds[1] - mesh.bounds[0]).tolist(),
+        },
+        "properties": {
+            "watertight": mesh.is_watertight,
+            "volume": float(mesh.volume) if mesh.is_watertight else None,
+            "area": float(mesh.area),
+            "center_mass": mesh.center_mass.tolist() if mesh.is_watertight else None,
+        },
+        "quality": {
+            "is_convex": mesh.is_convex,
+            "euler_number": mesh.euler_number,
+        },
+    }
+
+    # Check for issues
+    issues = []
+    if not mesh.is_watertight:
+        issues.append("Mesh is not watertight (has holes)")
+    if mesh.euler_number != 2:
+        issues.append(f"Non-manifold geometry (Euler number: {mesh.euler_number}, expected 2)")
+
+    # Check for degenerate faces
+    face_areas = mesh.area_faces
+    degenerate_count = (face_areas < 1e-10).sum()
+    if degenerate_count > 0:
+        issues.append(f"Found {degenerate_count} degenerate (zero-area) faces")
+
+    report["issues"] = issues
+
+    # Output
+    if args.output:
+        output_path = Path(args.output)
+        with open(output_path, "w") as f:
+            json.dump(report, f, indent=2)
+        print(f"Report written to: {output_path}")
+    else:
+        # Pretty print to console
+        dims = report["bounds"]["dimensions"]
+        print("Geometry:")
+        print(f"  Vertices: {report['geometry']['vertices']:,}")
+        print(f"  Faces: {report['geometry']['faces']:,}")
+        print(f"  Edges: {report['geometry']['edges']:,}")
+        print()
+        print("Dimensions:")
+        print(f"  X: {dims[0]:.2f} mm")
+        print(f"  Y: {dims[1]:.2f} mm")
+        print(f"  Z: {dims[2]:.2f} mm")
+        print()
+        print("Properties:")
+        print(f"  Watertight: {report['properties']['watertight']}")
+        if report["properties"]["volume"]:
+            print(f"  Volume: {report['properties']['volume']:.2f} mm^3")
+        print(f"  Surface area: {report['properties']['area']:.2f} mm^2")
+        print()
+
+        if issues:
+            print("Issues:")
+            for issue in issues:
+                print(f"  - {issue}")
+        else:
+            print("No issues detected.")
+
+    return 0
+
+
+def cmd_slice(args: argparse.Namespace) -> int:
+    """Generate SVG cross-section at specified Z height."""
+    import trimesh
+    import numpy as np
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"Error: File not found: {input_path}", file=sys.stderr)
+        return 1
+
+    try:
+        mesh = trimesh.load(str(input_path))
+    except Exception as e:
+        print(f"Error loading mesh: {e}", file=sys.stderr)
+        return 1
+
+    if isinstance(mesh, trimesh.Scene):
+        mesh = trimesh.util.concatenate(list(mesh.geometry.values()))
+
+    z_height = args.z
+    if z_height is None:
+        # Default to middle of mesh
+        z_height = (mesh.bounds[0][2] + mesh.bounds[1][2]) / 2
+        print(f"Using default Z height: {z_height:.2f} mm")
+
+    # Create slice
+    try:
+        slice_2d = mesh.section(plane_origin=[0, 0, z_height], plane_normal=[0, 0, 1])
+    except Exception as e:
+        print(f"Error creating slice: {e}", file=sys.stderr)
+        return 1
+
+    if slice_2d is None:
+        print(f"No intersection at Z={z_height:.2f} mm", file=sys.stderr)
+        return 1
+
+    # Convert to 2D path
+    try:
+        path_2d, _ = slice_2d.to_planar()
+    except Exception as e:
+        print(f"Error converting to 2D: {e}", file=sys.stderr)
+        return 1
+
+    # Export to SVG
+    output_path = args.output or Path(input_path.stem + f"_z{z_height:.1f}.svg")
+
+    try:
+        # Get SVG string
+        svg_data = path_2d.to_svg()
+        with open(output_path, "w") as f:
+            f.write(svg_data)
+        print(f"Slice exported to: {output_path}")
+    except Exception as e:
+        print(f"Error exporting SVG: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def cmd_compare(args: argparse.Namespace) -> int:
+    """Compare two meshes and report differences."""
+    import trimesh
+    import numpy as np
+
+    path_a = Path(args.file_a)
+    path_b = Path(args.file_b)
+
+    for p in [path_a, path_b]:
+        if not p.exists():
+            print(f"Error: File not found: {p}", file=sys.stderr)
+            return 1
+
+    try:
+        mesh_a = trimesh.load(str(path_a))
+        mesh_b = trimesh.load(str(path_b))
+    except Exception as e:
+        print(f"Error loading meshes: {e}", file=sys.stderr)
+        return 1
+
+    # Handle scenes
+    if isinstance(mesh_a, trimesh.Scene):
+        mesh_a = trimesh.util.concatenate(list(mesh_a.geometry.values()))
+    if isinstance(mesh_b, trimesh.Scene):
+        mesh_b = trimesh.util.concatenate(list(mesh_b.geometry.values()))
+
+    print(f"Comparing:")
+    print(f"  A: {path_a}")
+    print(f"  B: {path_b}")
+    print()
+
+    # Basic comparison
+    print("Geometry comparison:")
+    print(f"  Vertices: {len(mesh_a.vertices):,} vs {len(mesh_b.vertices):,}")
+    print(f"  Faces: {len(mesh_a.faces):,} vs {len(mesh_b.faces):,}")
+    print()
+
+    # Bounds comparison
+    dims_a = mesh_a.bounds[1] - mesh_a.bounds[0]
+    dims_b = mesh_b.bounds[1] - mesh_b.bounds[0]
+    print("Dimensions (mm):")
+    print(f"  X: {dims_a[0]:.2f} vs {dims_b[0]:.2f} (diff: {abs(dims_a[0] - dims_b[0]):.3f})")
+    print(f"  Y: {dims_a[1]:.2f} vs {dims_b[1]:.2f} (diff: {abs(dims_a[1] - dims_b[1]):.3f})")
+    print(f"  Z: {dims_a[2]:.2f} vs {dims_b[2]:.2f} (diff: {abs(dims_a[2] - dims_b[2]):.3f})")
+    print()
+
+    # Volume comparison (if both watertight)
+    if mesh_a.is_watertight and mesh_b.is_watertight:
+        vol_a = mesh_a.volume
+        vol_b = mesh_b.volume
+        vol_diff = abs(vol_a - vol_b)
+        vol_pct = (vol_diff / max(vol_a, vol_b)) * 100 if max(vol_a, vol_b) > 0 else 0
+
+        print("Volume comparison:")
+        print(f"  A: {vol_a:.2f} mm^3")
+        print(f"  B: {vol_b:.2f} mm^3")
+        print(f"  Difference: {vol_diff:.2f} mm^3 ({vol_pct:.2f}%)")
+
+        # Boolean difference if requested
+        if args.output:
+            try:
+                # Try to compute symmetric difference
+                diff_mesh = mesh_a.difference(mesh_b)
+                if diff_mesh and len(diff_mesh.faces) > 0:
+                    output_path = Path(args.output)
+                    diff_mesh.export(str(output_path))
+                    print(f"\nDifference mesh exported to: {output_path}")
+            except Exception as e:
+                print(f"\nCould not compute boolean difference: {e}")
+    else:
+        print("Volume comparison: Skipped (one or both meshes not watertight)")
+
+    return 0
+
+
+def cmd_footprint(args: argparse.Namespace) -> int:
+    """Extract and export 2D footprint of mesh."""
+    import trimesh
+    import numpy as np
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"Error: File not found: {input_path}", file=sys.stderr)
+        return 1
+
+    try:
+        mesh = trimesh.load(str(input_path))
+    except Exception as e:
+        print(f"Error loading mesh: {e}", file=sys.stderr)
+        return 1
+
+    if isinstance(mesh, trimesh.Scene):
+        mesh = trimesh.util.concatenate(list(mesh.geometry.values()))
+
+    # Get bottom Z
+    z_min = mesh.bounds[0][2]
+    z_slice = z_min + 0.1  # Slice just above bottom
+
+    print(f"Extracting footprint at Z={z_slice:.2f} mm")
+
+    try:
+        slice_2d = mesh.section(plane_origin=[0, 0, z_slice], plane_normal=[0, 0, 1])
+        if slice_2d is None:
+            # Try projection instead
+            print("No slice found, using convex hull projection")
+            from shapely.geometry import MultiPoint
+
+            bottom_verts = mesh.vertices[mesh.vertices[:, 2] < z_min + 1.0]
+            if len(bottom_verts) == 0:
+                print("Error: No bottom vertices found", file=sys.stderr)
+                return 1
+            points = MultiPoint(bottom_verts[:, :2])
+            footprint = points.convex_hull
+
+            # Export as SVG manually
+            output_path = args.output or Path(input_path.stem + "_footprint.svg")
+            bounds = footprint.bounds
+            width = bounds[2] - bounds[0]
+            height = bounds[3] - bounds[1]
+            svg = f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="{bounds[0]} {bounds[1]} {width} {height}">\n'
+            svg += f'  <path d="M {" L ".join(f"{x},{y}" for x, y in footprint.exterior.coords)}" fill="none" stroke="black" stroke-width="0.5"/>\n'
+            svg += "</svg>"
+            with open(output_path, "w") as f:
+                f.write(svg)
+            print(f"Footprint exported to: {output_path}")
+            return 0
+
+        path_2d, _ = slice_2d.to_planar()
+        output_path = args.output or Path(input_path.stem + "_footprint.svg")
+        svg_data = path_2d.to_svg()
+        with open(output_path, "w") as f:
+            f.write(svg_data)
+        print(f"Footprint exported to: {output_path}")
+
+    except Exception as e:
+        print(f"Error extracting footprint: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def add_debug_subparsers(subparsers: argparse._SubParsersAction) -> None:
+    """Add debug subcommand parsers."""
+
+    # analyze
+    analyze_parser = subparsers.add_parser("analyze", help="Analyze mesh and report diagnostics")
+    analyze_parser.add_argument("input", type=Path, help="Input mesh file (STL, 3MF, OBJ)")
+    analyze_parser.add_argument("-o", "--output", type=Path, help="Output JSON report file")
+    analyze_parser.set_defaults(func=cmd_analyze)
+
+    # slice
+    slice_parser = subparsers.add_parser("slice", help="Generate SVG cross-section")
+    slice_parser.add_argument("input", type=Path, help="Input mesh file")
+    slice_parser.add_argument("-z", type=float, help="Z height for slice (default: middle)")
+    slice_parser.add_argument("-o", "--output", type=Path, help="Output SVG file")
+    slice_parser.set_defaults(func=cmd_slice)
+
+    # compare
+    compare_parser = subparsers.add_parser("compare", help="Compare two meshes")
+    compare_parser.add_argument("file_a", type=Path, help="First mesh file")
+    compare_parser.add_argument("file_b", type=Path, help="Second mesh file")
+    compare_parser.add_argument("-o", "--output", type=Path, help="Output difference mesh")
+    compare_parser.set_defaults(func=cmd_compare)
+
+    # footprint
+    footprint_parser = subparsers.add_parser("footprint", help="Extract 2D footprint")
+    footprint_parser.add_argument("input", type=Path, help="Input mesh file")
+    footprint_parser.add_argument("-o", "--output", type=Path, help="Output SVG file")
+    footprint_parser.set_defaults(func=cmd_footprint)
+
+
+def cmd_debug(args: argparse.Namespace) -> int:
+    """Debug subcommand dispatcher."""
+    if hasattr(args, "func"):
+        return args.func(args)
+    else:
+        print("Usage: microfinity debug <command> [options]")
+        print()
+        print("Commands:")
+        print("  analyze   - Analyze mesh and report diagnostics")
+        print("  slice     - Generate SVG cross-section at Z height")
+        print("  compare   - Compare two meshes")
+        print("  footprint - Extract 2D footprint")
+        return 0