sdf-sampler 0.1.0__py3-none-any.whl

sdf_sampler/analyzer.py

@@ -0,0 +1,299 @@
+# ABOUTME: SDFAnalyzer class for auto-analysis of point clouds
+# ABOUTME: Detects SOLID and EMPTY regions using multiple algorithms
+
+import uuid
+from datetime import UTC, datetime
+
+import numpy as np
+
+from sdf_sampler.algorithms.flood_fill import flood_fill_empty_regions
+from sdf_sampler.algorithms.normal_idw import generate_idw_normal_samples
+from sdf_sampler.algorithms.normal_offset import generate_normal_offset_boxes
+from sdf_sampler.algorithms.pocket import detect_pockets
+from sdf_sampler.algorithms.voxel_regions import generate_voxel_region_constraints
+from sdf_sampler.config import AnalyzerConfig, AutoAnalysisOptions
+from sdf_sampler.models.analysis import (
+    ALL_ALGORITHMS,
+    AlgorithmStats,
+    AlgorithmType,
+    AnalysisResult,
+    AnalysisSummary,
+    GeneratedConstraint,
+)
+from sdf_sampler.models.constraints import SignConvention
+
+
+class SDFAnalyzer:
+    """Automatic SDF region detection from point clouds.
+
+    Generates spatial constraints (boxes, samples) that define SOLID (inside)
+    and EMPTY (outside) regions for SDF training data generation.
+
+    Example:
+        >>> analyzer = SDFAnalyzer()
+        >>> result = analyzer.analyze(xyz=points, normals=normals)
+        >>> print(f"Generated {len(result.constraints)} constraints")
+
+    Algorithms:
+        - flood_fill: EMPTY regions reachable from sky
+        - voxel_regions: SOLID underground regions
+        - normal_offset: Paired boxes along surface normals
+        - normal_idw: Point samples with inverse distance weighting
+        - pocket: Interior cavity detection
+    """
+
+    def __init__(self, config: AnalyzerConfig | None = None):
+        """Initialize the analyzer.
+
+        Args:
+            config: Optional configuration. Uses defaults if not provided.
+        """
+        self.config = config or AnalyzerConfig()
+
+    def analyze(
+        self,
+        xyz: np.ndarray,
+        normals: np.ndarray | None = None,
+        algorithms: list[str] | None = None,
+        options: AutoAnalysisOptions | None = None,
+    ) -> AnalysisResult:
+        """Run analysis algorithms and generate constraints.
+
+        This is the main entry point for auto-analysis. It runs the specified
+        algorithms (or all by default) and returns constraints that can be
+        used for sample generation.
+
+        Args:
+            xyz: Point cloud positions (N, 3) as numpy array
+            normals: Point normals (N, 3) or None if not available
+            algorithms: List of algorithm names to run (default: all)
+            options: Fine-grained algorithm options (default: from config)
+
+        Returns:
+            AnalysisResult containing generated constraints and statistics
+
+        Example:
+            >>> result = analyzer.analyze(
+            ...     xyz=points,
+            ...     normals=normals,
+            ...     algorithms=["flood_fill", "voxel_regions"],
+            ... )
+        """
+        if options is None:
+            options = AutoAnalysisOptions.from_analyzer_config(self.config)
+
+        # Validate input
+        xyz = np.asarray(xyz)
+        if xyz.ndim != 2 or xyz.shape[1] != 3:
+            raise ValueError(f"xyz must be (N, 3), got {xyz.shape}")
+
+        if normals is not None:
+            normals = np.asarray(normals)
+            if normals.shape != xyz.shape:
+                raise ValueError(f"normals shape {normals.shape} doesn't match xyz {xyz.shape}")
+
+        # Determine which algorithms to run
+        algo_list = algorithms if algorithms else [a.value for a in ALL_ALGORITHMS]
+        algo_list = [a for a in algo_list if a in [alg.value for alg in ALL_ALGORITHMS]]
+
+        # Run algorithms and collect constraints
+        all_constraints: list[GeneratedConstraint] = []
+        algorithm_stats: dict[str, AlgorithmStats] = {}
+        algorithms_run: list[str] = []
+
+        for algo_name in algo_list:
+            constraints = self._run_algorithm(algo_name, xyz, normals, options)
+            if constraints:
+                all_constraints.extend(constraints)
+                algorithms_run.append(algo_name)
+                algorithm_stats[algo_name] = AlgorithmStats(
+                    constraints_generated=len(constraints),
+                    coverage_description=self._get_algorithm_description(algo_name, len(constraints)),
+                )
+
+        # Remove redundant contained boxes
+        all_constraints = self._simplify_constraints(all_constraints, options.overlap_threshold)
+
+        # Filter out constraints outside the X-Y alpha shape
+        if options.hull_filter_enabled:
+            all_constraints = self._filter_outside_hull(all_constraints, xyz, options.hull_alpha)
+
+        # Compute summary
+        summary = self._compute_summary(all_constraints, len(algorithm_stats))
+
+        return AnalysisResult(
+            analysis_id=str(uuid.uuid4()),
+            computed_at=datetime.now(UTC),
+            algorithms_run=algorithms_run,
+            summary=summary,
+            algorithm_stats=algorithm_stats,
+            generated_constraints=all_constraints,
+        )
+
+    async def analyze_async(
+        self,
+        xyz: np.ndarray,
+        normals: np.ndarray | None = None,
+        algorithms: list[str] | None = None,
+        options: AutoAnalysisOptions | None = None,
+    ) -> AnalysisResult:
+        """Async variant of analyze() for heavy workloads.
+
+        Same interface as analyze() but can be awaited.
+        """
+        # For now, just wrap sync - could be made truly async with executors
+        return self.analyze(xyz, normals, algorithms, options)
+
+    def _run_algorithm(
+        self,
+        name: str,
+        xyz: np.ndarray,
+        normals: np.ndarray | None,
+        options: AutoAnalysisOptions,
+    ) -> list[GeneratedConstraint]:
+        """Run a single analysis algorithm."""
+        if name == AlgorithmType.POCKET.value:
+            return detect_pockets(xyz, self.config)
+        elif name == AlgorithmType.NORMAL_OFFSET.value:
+            return generate_normal_offset_boxes(xyz, normals, options)
+        elif name == AlgorithmType.FLOOD_FILL.value:
+            return flood_fill_empty_regions(xyz, normals, options)
+        elif name == AlgorithmType.VOXEL_REGIONS.value:
+            return generate_voxel_region_constraints(xyz, normals, options)
+        elif name == AlgorithmType.NORMAL_IDW.value:
+            return generate_idw_normal_samples(xyz, normals, options)
+        return []
+
+    def _get_algorithm_description(self, algo_name: str, count: int) -> str:
+        """Get human-readable description for algorithm results."""
+        descriptions = {
+            AlgorithmType.POCKET.value: f"Detected {count} interior cavities",
+            AlgorithmType.NORMAL_OFFSET.value: f"Generated {count} surface offset constraints",
+            AlgorithmType.FLOOD_FILL.value: f"Found {count} sky-reachable exterior regions",
+            AlgorithmType.VOXEL_REGIONS.value: f"Found {count} underground solid regions",
+            AlgorithmType.NORMAL_IDW.value: f"Generated {count} IDW normal samples",
+        }
+        return descriptions.get(algo_name, f"Generated {count} constraints")
+
+    def _compute_summary(
+        self, constraints: list[GeneratedConstraint], algorithms_contributing: int
+    ) -> AnalysisSummary:
+        """Compute summary statistics from generated constraints."""
+        solid_count = sum(
+            1 for c in constraints if c.constraint.get("sign") == SignConvention.SOLID.value
+        )
+        empty_count = sum(
+            1 for c in constraints if c.constraint.get("sign") == SignConvention.EMPTY.value
+        )
+
+        return AnalysisSummary(
+            total_constraints=len(constraints),
+            solid_constraints=solid_count,
+            empty_constraints=empty_count,
+            algorithms_contributing=algorithms_contributing,
+        )
+
+    def _box_intersection_fraction(self, box_a: dict, box_b: dict) -> float:
+        """Calculate what fraction of box_b's volume intersects with box_a."""
+        a_center = np.array(box_a["center"])
+        a_half = np.array(box_a["half_extents"])
+        b_center = np.array(box_b["center"])
+        b_half = np.array(box_b["half_extents"])
+
+        a_min, a_max = a_center - a_half, a_center + a_half
+        b_min, b_max = b_center - b_half, b_center + b_half
+
+        inter_min = np.maximum(a_min, b_min)
+        inter_max = np.minimum(a_max, b_max)
+
+        inter_dims = np.maximum(0, inter_max - inter_min)
+        intersection_volume = float(np.prod(inter_dims))
+
+        b_dims = b_max - b_min
+        b_volume = float(np.prod(b_dims))
+
+        if b_volume <= 0:
+            return 0.0
+
+        return intersection_volume / b_volume
+
+    def _simplify_constraints(
+        self, constraints: list[GeneratedConstraint], overlap_threshold: float = 0.5
+    ) -> list[GeneratedConstraint]:
+        """Remove boxes that significantly overlap with larger boxes."""
+        boxes: list[tuple[int, GeneratedConstraint, float]] = []
+        for i, c in enumerate(constraints):
+            if c.constraint.get("type") == "box":
+                half = np.array(c.constraint["half_extents"])
+                volume = float(np.prod(half * 2))
+                boxes.append((i, c, volume))
+
+        remove_indices: set[int] = set()
+        for i, (_idx_a, box_a, vol_a) in enumerate(boxes):
+            for j, (idx_b, box_b, vol_b) in enumerate(boxes):
+                if i == j:
+                    continue
+                if vol_b < vol_a:
+                    fraction = self._box_intersection_fraction(box_a.constraint, box_b.constraint)
+                    if fraction > overlap_threshold:
+                        remove_indices.add(idx_b)
+
+        return [c for i, c in enumerate(constraints) if i not in remove_indices]
+
+    def _filter_outside_hull(
+        self, constraints: list[GeneratedConstraint], xyz: np.ndarray, alpha: float
+    ) -> list[GeneratedConstraint]:
+        """Filter out constraints whose center falls outside the X-Y alpha shape."""
+        if len(constraints) == 0 or len(xyz) < 3:
+            return constraints
+
+        xy = xyz[:, :2]
+
+        try:
+            import alphashape
+            from shapely.geometry import Point
+
+            shape = alphashape.alphashape(xy, alpha)
+            if shape is None or shape.is_empty:
+                return constraints
+        except Exception:
+            return constraints
+
+        filtered: list[GeneratedConstraint] = []
+        for constraint in constraints:
+            c = constraint.constraint
+            c_type = c.get("type")
+
+            center_xy = self._get_constraint_center_xy(c, c_type)
+            if center_xy is None:
+                filtered.append(constraint)
+                continue
+
+            point = Point(center_xy[0], center_xy[1])
+            if shape.contains(point) or shape.touches(point):
+                filtered.append(constraint)
+
+        return filtered
+
+    def _get_constraint_center_xy(self, constraint: dict, c_type: str | None) -> np.ndarray | None:
+        """Get the X-Y center of a constraint for hull checking."""
+        center = None
+
+        if c_type == "box":
+            center = constraint.get("center")
+        elif c_type == "sample_point":
+            center = constraint.get("position")
+        elif c_type == "sphere":
+            center = constraint.get("center")
+        elif c_type == "pocket":
+            center = constraint.get("centroid")
+        else:
+            for field in ["center", "position", "point", "centroid"]:
+                if field in constraint:
+                    center = constraint[field]
+                    break
+
+        if center is None:
+            return None
+
+        return np.array(center[:2])

sdf_sampler/config.py

@@ -0,0 +1,171 @@
+# ABOUTME: Configuration dataclasses for analyzer and sampler
+# ABOUTME: Simple config objects replacing FastAPI Settings dependency
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AnalyzerConfig:
+    """Configuration for SDFAnalyzer.
+
+    Controls voxel grid parameters, ray propagation, and filtering options.
+    """
+
+    # Voxel grid parameters
+    min_gap_size: float = 0.10
+    """Minimum gap size in meters that flood fill can traverse."""
+
+    max_grid_dim: int = 200
+    """Maximum voxel grid dimension (caps at max_grid_dim³ voxels)."""
+
+    # Ray propagation
+    cone_angle: float = 15.0
+    """Ray propagation cone half-angle in degrees."""
+
+    # Normal offset algorithm
+    normal_offset_pairs: int = 40
+    """Number of SOLID/EMPTY box pairs for normal_offset algorithm."""
+
+    # Filtering
+    max_boxes: int = 30
+    """Maximum boxes per algorithm."""
+
+    overlap_threshold: float = 0.5
+    """Fraction overlap required to remove redundant boxes."""
+
+    # IDW Normal sampling
+    idw_sample_count: int = 1000
+    """Total IDW samples to generate."""
+
+    idw_max_distance: float = 0.5
+    """Maximum distance from surface in meters."""
+
+    idw_power: float = 2.0
+    """IDW power factor (higher = more weight near surface)."""
+
+    # Hull filtering
+    hull_filter_enabled: bool = True
+    """Filter out constraints outside the X-Y alpha shape of point cloud."""
+
+    hull_alpha: float = 1.0
+    """Alpha shape parameter (smaller = tighter fit to concave boundaries)."""
+
+    # Output modes
+    flood_fill_output: str = "samples"
+    """Output mode for flood fill: 'boxes', 'samples', or 'both'."""
+
+    flood_fill_sample_count: int = 500
+    """Number of sample points from empty voxels."""
+
+    voxel_regions_output: str = "samples"
+    """Output mode for voxel regions: 'boxes', 'samples', or 'both'."""
+
+    voxel_regions_sample_count: int = 500
+    """Number of sample points from solid voxels."""
+
+    # Pocket detection
+    pocket_voxel_target: int = 100
+    """Target number of voxels along longest axis for pocket detection."""
+
+    pocket_min_voxel_size: float = 0.01
+    """Minimum voxel size for pocket detection."""
+
+    pocket_max_voxels_per_axis: int = 200
+    """Maximum voxels per axis for pocket grid."""
+
+    pocket_occupancy_dilation: int = 1
+    """Dilation iterations for pocket occupancy grid."""
+
+    pocket_min_volume_voxels: int = 10
+    """Minimum voxels for a pocket to be considered significant."""
+
+
+@dataclass
+class SamplerConfig:
+    """Configuration for SDFSampler.
+
+    Controls sample generation strategy and parameters.
+    """
+
+    # Default sampling parameters
+    total_samples: int = 10000
+    """Default total number of samples to generate."""
+
+    samples_per_primitive: int = 100
+    """Samples per primitive constraint (CONSTANT strategy)."""
+
+    samples_per_cubic_meter: float = 10000.0
+    """Sample density per cubic meter (DENSITY strategy)."""
+
+    inverse_square_base_samples: int = 100
+    """Base samples at surface (INVERSE_SQUARE strategy)."""
+
+    inverse_square_falloff: float = 2.0
+    """Falloff exponent for inverse-square sampling."""
+
+    # Band widths
+    near_band: float = 0.02
+    """Near-band width around surface."""
+
+    # Random seed
+    seed: int = 0
+    """Random seed for reproducibility."""
+
+
+@dataclass
+class AutoAnalysisOptions:
+    """Tunable hyperparameters for auto-analysis algorithms.
+
+    This is a standalone version of the AutoAnalysisOptions from sdf-labeler,
+    allowing fine-grained control over each algorithm.
+    """
+
+    # Voxel grid parameters
+    min_gap_size: float = 0.10
+    max_grid_dim: int = 200
+
+    # Ray propagation
+    cone_angle: float = 15.0
+
+    # Normal offset
+    normal_offset_pairs: int = 40
+
+    # Filtering
+    max_boxes: int = 30
+    overlap_threshold: float = 0.5
+
+    # IDW Normal sampling
+    idw_sample_count: int = 1000
+    idw_max_distance: float = 0.5
+    idw_power: float = 2.0
+
+    # Hull filtering
+    hull_filter_enabled: bool = True
+    hull_alpha: float = 1.0
+
+    # Output modes
+    flood_fill_output: str = "samples"
+    flood_fill_sample_count: int = 500
+    voxel_regions_output: str = "samples"
+    voxel_regions_sample_count: int = 500
+
+    @classmethod
+    def from_analyzer_config(cls, config: AnalyzerConfig) -> "AutoAnalysisOptions":
+        """Create options from AnalyzerConfig."""
+        return cls(
+            min_gap_size=config.min_gap_size,
+            max_grid_dim=config.max_grid_dim,
+            cone_angle=config.cone_angle,
+            normal_offset_pairs=config.normal_offset_pairs,
+            max_boxes=config.max_boxes,
+            overlap_threshold=config.overlap_threshold,
+            idw_sample_count=config.idw_sample_count,
+            idw_max_distance=config.idw_max_distance,
+            idw_power=config.idw_power,
+            hull_filter_enabled=config.hull_filter_enabled,
+            hull_alpha=config.hull_alpha,
+            flood_fill_output=config.flood_fill_output,
+            flood_fill_sample_count=config.flood_fill_sample_count,
+            voxel_regions_output=config.voxel_regions_output,
+            voxel_regions_sample_count=config.voxel_regions_sample_count,
+        )

sdf_sampler/io.py

@@ -0,0 +1,178 @@
+# ABOUTME: I/O utilities for point cloud loading and sample export
+# ABOUTME: Supports PLY, LAS/LAZ, CSV, NPZ, and Parquet formats
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from sdf_sampler.models.samples import TrainingSample
+
+
+def load_point_cloud(
+    path: str | Path,
+    **kwargs: Any,
+) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load point cloud from file.
+
+    Supported formats:
+    - PLY (requires trimesh in [io] extras)
+    - LAS/LAZ (requires laspy in [io] extras)
+    - CSV (columns: x, y, z, [nx, ny, nz])
+    - NPZ (arrays: xyz, [normals])
+    - Parquet (columns: x, y, z, [nx, ny, nz])
+
+    Args:
+        path: Path to point cloud file
+        **kwargs: Additional arguments for specific loaders
+
+    Returns:
+        Tuple of (xyz, normals) where xyz is (N, 3) and normals is (N, 3) or None
+
+    Example:
+        >>> xyz, normals = load_point_cloud("scan.ply")
+        >>> xyz, normals = load_point_cloud("points.csv")
+    """
+    path = Path(path)
+    suffix = path.suffix.lower()
+
+    if suffix == ".ply":
+        return _load_ply(path, **kwargs)
+    elif suffix in (".las", ".laz"):
+        return _load_las(path, **kwargs)
+    elif suffix == ".csv":
+        return _load_csv(path, **kwargs)
+    elif suffix == ".npz":
+        return _load_npz(path, **kwargs)
+    elif suffix == ".parquet":
+        return _load_parquet(path, **kwargs)
+    else:
+        raise ValueError(f"Unsupported file format: {suffix}")
+
+
+def export_parquet(
+    samples: list[TrainingSample],
+    path: str | Path,
+) -> Path:
+    """Export training samples to Parquet file.
+
+    Creates a survi-compatible Parquet file with columns:
+    x, y, z, phi, nx, ny, nz, weight, source, is_surface, is_free
+
+    Args:
+        samples: List of TrainingSample objects
+        path: Output file path
+
+    Returns:
+        Path to created file
+
+    Example:
+        >>> export_parquet(samples, "training_data.parquet")
+    """
+    path = Path(path)
+    df = pd.DataFrame([s.to_dict() for s in samples])
+    df.to_parquet(path)
+    return path
+
+
+def _load_ply(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load PLY file using trimesh."""
+    try:
+        import trimesh
+    except ImportError as e:
+        raise ImportError(
+            "trimesh is required for PLY support. "
+            "Install with: pip install sdf-sampler[io]"
+        ) from e
+
+    mesh = trimesh.load(path, **kwargs)
+
+    # Handle both PointCloud and Trimesh objects
+    if hasattr(mesh, "vertices"):
+        xyz = np.asarray(mesh.vertices)
+    else:
+        xyz = np.asarray(mesh.points if hasattr(mesh, "points") else mesh)
+
+    normals = None
+    if hasattr(mesh, "vertex_normals") and mesh.vertex_normals is not None:
+        normals = np.asarray(mesh.vertex_normals)
+        if normals.shape != xyz.shape:
+            normals = None
+
+    return xyz, normals
+
+
+def _load_las(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load LAS/LAZ file using laspy."""
+    try:
+        import laspy
+    except ImportError as e:
+        raise ImportError(
+            "laspy is required for LAS/LAZ support. "
+            "Install with: pip install sdf-sampler[io]"
+        ) from e
+
+    las = laspy.read(path, **kwargs)
+
+    xyz = np.column_stack([las.x, las.y, las.z])
+
+    # LAS files typically don't have normals
+    normals = None
+
+    return xyz, normals
+
+
+def _load_csv(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load CSV file with pandas."""
+    df = pd.read_csv(path, **kwargs)
+
+    # Required columns
+    if not all(c in df.columns for c in ["x", "y", "z"]):
+        raise ValueError("CSV must have x, y, z columns")
+
+    xyz = df[["x", "y", "z"]].values
+
+    # Optional normal columns
+    normals = None
+    if all(c in df.columns for c in ["nx", "ny", "nz"]):
+        normals = df[["nx", "ny", "nz"]].values
+
+    return xyz, normals
+
+
+def _load_npz(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load NPZ file."""
+    data = np.load(path, **kwargs)
+
+    # Support different naming conventions
+    if "xyz" in data:
+        xyz = data["xyz"]
+    elif "points" in data:
+        xyz = data["points"]
+    else:
+        raise ValueError("NPZ must have 'xyz' or 'points' array")
+
+    normals = None
+    if "normals" in data and data["normals"].size > 0:
+        normals = data["normals"]
+
+    return xyz, normals
+
+
+def _load_parquet(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load Parquet file with pandas."""
+    df = pd.read_parquet(path, **kwargs)
+
+    # Required columns
+    if not all(c in df.columns for c in ["x", "y", "z"]):
+        raise ValueError("Parquet must have x, y, z columns")
+
+    xyz = df[["x", "y", "z"]].values
+
+    # Optional normal columns
+    normals = None
+    if all(c in df.columns for c in ["nx", "ny", "nz"]):
+        normals = df[["nx", "ny", "nz"]].values
+
+    return xyz, normals

sdf_sampler/models/__init__.py

@@ -0,0 +1,49 @@
+# ABOUTME: Public model exports for sdf-sampler
+# ABOUTME: Constraint types, analysis results, and training samples
+
+from sdf_sampler.models.analysis import (
+    AlgorithmStats,
+    AlgorithmType,
+    AnalysisResult,
+    AnalysisSummary,
+    GeneratedConstraint,
+)
+from sdf_sampler.models.constraints import (
+    BoxConstraint,
+    BrushStrokeConstraint,
+    Constraint,
+    HalfspaceConstraint,
+    PocketConstraint,
+    RayCarveConstraint,
+    RayInfo,
+    SamplePointConstraint,
+    SeedPropagationConstraint,
+    SignConvention,
+    SphereConstraint,
+)
+from sdf_sampler.models.samples import SamplingStrategy, TrainingSample
+
+__all__ = [
+    # Enums
+    "SignConvention",
+    "AlgorithmType",
+    "SamplingStrategy",
+    # Constraints
+    "Constraint",
+    "BoxConstraint",
+    "SphereConstraint",
+    "HalfspaceConstraint",
+    "BrushStrokeConstraint",
+    "SeedPropagationConstraint",
+    "RayCarveConstraint",
+    "RayInfo",
+    "PocketConstraint",
+    "SamplePointConstraint",
+    # Analysis
+    "AnalysisResult",
+    "AnalysisSummary",
+    "AlgorithmStats",
+    "GeneratedConstraint",
+    # Samples
+    "TrainingSample",
+]