sdf-sampler 0.3.0__tar.gz → 0.5.0__tar.gz

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to sdf-sampler will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-01-30
+
+### Added
+
+- **Area-weighted surface sampling** - New sampling mode that distributes surface points uniformly by surface area instead of by vertex count. Essential for meshes with uneven vertex density (e.g., trench floors vs walls).
+  - New `load_mesh()` function returns `Mesh` object with vertices, faces, and normals
+  - Pass `mesh=` parameter to `sampler.generate()` for area-weighted sampling
+  - CLI: `--mesh path/to/mesh.obj` enables area-weighted mode
+  - Supports PLY, OBJ, STL, OFF mesh formats
+- **OBJ/STL/OFF file support** - `load_point_cloud()` now supports additional mesh formats via trimesh
+
+### Example
+
+```python
+from sdf_sampler import SDFSampler, load_mesh, load_point_cloud
+
+# Load mesh for area-weighted sampling
+mesh = load_mesh("model.obj")
+xyz, normals = load_point_cloud("model.obj")
+
+# Area-weighted gives uniform coverage by surface area
+samples = sampler.generate(
+    xyz=xyz, constraints=constraints,
+    include_surface_points=True,
+    surface_point_count=1000,
+    mesh=mesh,  # Enables area-weighted sampling
+)
+```
+
+## [0.4.0] - 2025-01-30
+
+### Changed
+
+- **Default algorithms no longer include `normal_idw`** - The `normal_idw` algorithm is now opt-in only. Default algorithms are: `flood_fill`, `voxel_regions`, `normal_offset`. To use `normal_idw`, explicitly pass `algorithms=["normal_idw"]` or include it in your algorithm list.
+- **Surface point count is now a direct count** - Replaced `surface_point_ratio` with `surface_point_count`. Instead of specifying a percentage, you now specify the exact number of surface points to include.
+  - CLI: `--surface-point-count 1000` (default: 1000)
+  - SDK: `sampler.generate(..., include_surface_points=True, surface_point_count=1000)`
+
 ## [0.3.0] - 2025-01-29
 
 ### Added
@@ -15,8 +53,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Output mode control: `--flood-fill-output`, `--voxel-regions-output` (boxes/samples/both)
 - **Surface point inclusion**
   - `--include-surface-points` flag to include original points with phi=0
-  - `--surface-point-ratio` to control fraction included (default 10%)
-  - SDK: `sampler.generate(..., include_surface_points=True, surface_point_ratio=0.1)`
+  - `--surface-point-count` to specify number of surface points (default 1000)
+  - SDK: `sampler.generate(..., include_surface_points=True, surface_point_count=1000)`
 
 ## [0.2.0] - 2025-01-29
 

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdf-sampler
-Version: 0.3.0
+Version: 0.5.0
 Summary: Auto-analysis and sampling of point clouds for SDF (Signed Distance Field) training data generation
 Project-URL: Repository, https://github.com/Chiark-Collective/sdf-sampler
 Author-email: Liam <liam@example.com>

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdf-sampler"
-version = "0.3.0"
+version = "0.5.0"
 description = "Auto-analysis and sampling of point clouds for SDF (Signed Distance Field) training data generation"
 readme = "README.md"
 license = { text = "MIT" }

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/src/sdf_sampler/__init__.py

@@ -28,7 +28,7 @@ Example usage:
 
 from sdf_sampler.analyzer import SDFAnalyzer
 from sdf_sampler.config import AnalyzerConfig, SamplerConfig
-from sdf_sampler.io import export_parquet, load_point_cloud
+from sdf_sampler.io import Mesh, export_parquet, load_mesh, load_point_cloud
 from sdf_sampler.models import (
     AlgorithmType,
     AnalysisResult,
@@ -47,7 +47,7 @@ from sdf_sampler.models import (
 )
 from sdf_sampler.sampler import SDFSampler
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = [
     # Main classes
@@ -58,6 +58,8 @@ __all__ = [
     "SamplerConfig",
     # I/O
     "load_point_cloud",
+    "load_mesh",
+    "Mesh",
     "export_parquet",
     # Models
     "SignConvention",

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/src/sdf_sampler/analyzer.py

@@ -14,6 +14,7 @@ from sdf_sampler.algorithms.voxel_regions import generate_voxel_region_constrain
 from sdf_sampler.config import AnalyzerConfig, AutoAnalysisOptions
 from sdf_sampler.models.analysis import (
     ALL_ALGORITHMS,
+    DEFAULT_ALGORITHMS,
     AlgorithmStats,
     AlgorithmType,
     AnalysisResult,
@@ -93,7 +94,7 @@ class SDFAnalyzer:
                 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 = algorithms if algorithms else [a.value for a in DEFAULT_ALGORITHMS]
         algo_list = [a for a in algo_list if a in [alg.value for alg in ALL_ALGORITHMS]]
 
         # Run algorithms and collect constraints

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/src/sdf_sampler/cli.py

@@ -169,10 +169,18 @@ def add_output_options(parser: argparse.ArgumentParser) -> None:
         help="Include original surface points (phi=0) in output",
     )
     group.add_argument(
-        "--surface-point-ratio",
-        type=float,
-        default=0.1,
-        help="Ratio of surface points to include (default: 0.1 = 10%%)",
+        "--surface-point-count",
+        type=int,
+        default=1000,
+        help="Number of surface points to include (default: 1000)",
+    )
+    group.add_argument(
+        "--mesh",
+        type=Path,
+        default=None,
+        help="Mesh file for area-weighted surface sampling (PLY/OBJ/STL). "
+             "If provided, surface points are sampled uniformly by surface area "
+             "instead of by vertex count. Recommended for meshes with uneven vertex density.",
     )
 
 
@@ -418,7 +426,7 @@ def cmd_analyze(args: argparse.Namespace) -> int:
 
 def cmd_sample(args: argparse.Namespace) -> int:
     """Run sample command."""
-    from sdf_sampler import SDFSampler, load_point_cloud
+    from sdf_sampler import SDFSampler, load_mesh, load_point_cloud
 
     if not args.input.exists():
         print(f"Error: Input file not found: {args.input}", file=sys.stderr)
@@ -439,6 +447,19 @@ def cmd_sample(args: argparse.Namespace) -> int:
         print(f"Error loading point cloud: {e}", file=sys.stderr)
         return 1
 
+    # Load mesh for area-weighted surface sampling if provided
+    mesh = None
+    if args.mesh:
+        if args.verbose:
+            print(f"Loading mesh for area-weighted sampling: {args.mesh}")
+        try:
+            mesh = load_mesh(str(args.mesh))
+            if args.verbose:
+                print(f"  Vertices: {len(mesh.vertices):,}, Faces: {len(mesh.faces):,}")
+        except Exception as e:
+            print(f"Error loading mesh: {e}", file=sys.stderr)
+            return 1
+
     if args.verbose:
         print(f"Loading constraints: {args.constraints}")
 
@@ -448,6 +469,9 @@ def cmd_sample(args: argparse.Namespace) -> int:
     if args.verbose:
         print(f"  Constraints: {len(constraints)}")
         print(f"Generating {args.total_samples:,} samples with strategy: {args.strategy}")
+        if args.include_surface_points:
+            mode = "area-weighted" if mesh else "vertex-based"
+            print(f"  Including {args.surface_point_count:,} surface points ({mode})")
 
     config = build_sampler_config(args)
     sampler = SDFSampler(config=config)
@@ -458,14 +482,11 @@ def cmd_sample(args: argparse.Namespace) -> int:
         total_samples=args.total_samples,
         strategy=args.strategy,
         seed=args.seed,
+        include_surface_points=args.include_surface_points,
+        surface_point_count=args.surface_point_count,
+        mesh=mesh,
     )
 
-    # Include surface points if requested
-    if args.include_surface_points:
-        samples = _add_surface_points(
-            samples, xyz, normals, args.surface_point_ratio, args.verbose
-        )
-
     if args.verbose:
         print(f"Generated {len(samples)} samples")
 
@@ -476,7 +497,7 @@ def cmd_sample(args: argparse.Namespace) -> int:
 
 def cmd_pipeline(args: argparse.Namespace) -> int:
     """Run full pipeline: analyze + sample + export."""
-    from sdf_sampler import SDFAnalyzer, SDFSampler, load_point_cloud
+    from sdf_sampler import SDFAnalyzer, SDFSampler, load_mesh, load_point_cloud
 
     if not args.input.exists():
         print(f"Error: Input file not found: {args.input}", file=sys.stderr)
@@ -497,6 +518,19 @@ def cmd_pipeline(args: argparse.Namespace) -> int:
         print(f"  Points: {len(xyz):,}")
         print(f"  Normals: {'yes' if normals is not None else 'no'}")
 
+    # Load mesh for area-weighted surface sampling if provided
+    mesh = None
+    if args.mesh:
+        if args.verbose:
+            print(f"Loading mesh for area-weighted sampling: {args.mesh}")
+        try:
+            mesh = load_mesh(str(args.mesh))
+            if args.verbose:
+                print(f"  Vertices: {len(mesh.vertices):,}, Faces: {len(mesh.faces):,}")
+        except Exception as e:
+            print(f"Error loading mesh: {e}", file=sys.stderr)
+            return 1
+
     # Analyze
     if args.verbose:
         algos = args.algorithms or ["all"]
@@ -526,6 +560,9 @@ def cmd_pipeline(args: argparse.Namespace) -> int:
     # Sample
     if args.verbose:
         print(f"Generating {args.total_samples:,} samples with strategy: {args.strategy}")
+        if args.include_surface_points:
+            mode = "area-weighted" if mesh else "vertex-based"
+            print(f"  Including {args.surface_point_count:,} surface points ({mode})")
 
     config = build_sampler_config(args)
     sampler = SDFSampler(config=config)
@@ -536,14 +573,11 @@ def cmd_pipeline(args: argparse.Namespace) -> int:
         total_samples=args.total_samples,
         strategy=args.strategy,
         seed=args.seed,
+        include_surface_points=args.include_surface_points,
+        surface_point_count=args.surface_point_count,
+        mesh=mesh,
     )
 
-    # Include surface points if requested
-    if args.include_surface_points:
-        samples = _add_surface_points(
-            samples, xyz, normals, args.surface_point_ratio, args.verbose
-        )
-
     if args.verbose:
         print(f"Generated {len(samples)} samples")
 
@@ -553,52 +587,6 @@ def cmd_pipeline(args: argparse.Namespace) -> int:
     return 0
 
 
-def _add_surface_points(
-    samples: list,
-    xyz: np.ndarray,
-    normals: np.ndarray | None,
-    ratio: float,
-    verbose: bool,
-) -> list:
-    """Add surface points to sample list."""
-    from sdf_sampler.models import TrainingSample
-
-    n_surface = int(len(xyz) * ratio)
-    if n_surface == 0:
-        return samples
-
-    # Subsample if needed
-    if n_surface < len(xyz):
-        indices = np.random.choice(len(xyz), n_surface, replace=False)
-        surface_xyz = xyz[indices]
-        surface_normals = normals[indices] if normals is not None else None
-    else:
-        surface_xyz = xyz
-        surface_normals = normals
-
-    if verbose:
-        print(f"Adding {len(surface_xyz):,} surface points (phi=0)")
-
-    for i in range(len(surface_xyz)):
-        sample = TrainingSample(
-            x=float(surface_xyz[i, 0]),
-            y=float(surface_xyz[i, 1]),
-            z=float(surface_xyz[i, 2]),
-            phi=0.0,
-            weight=1.0,
-            source="surface",
-            is_surface=True,
-            is_free=False,
-        )
-        if surface_normals is not None:
-            sample.nx = float(surface_normals[i, 0])
-            sample.ny = float(surface_normals[i, 1])
-            sample.nz = float(surface_normals[i, 2])
-        samples.append(sample)
-
-    return samples
-
-
 def cmd_info(args: argparse.Namespace) -> int:
     """Show information about a file."""
     if not args.input.exists():

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/src/sdf_sampler/io.py

@@ -1,6 +1,7 @@
 # ABOUTME: I/O utilities for point cloud loading and sample export
 # ABOUTME: Supports PLY, LAS/LAZ, CSV, NPZ, and Parquet formats
 
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -10,6 +11,79 @@ import pandas as pd
 from sdf_sampler.models.samples import TrainingSample
 
 
+@dataclass
+class Mesh:
+    """Triangle mesh with vertices, faces, and optional normals.
+
+    Used for area-weighted surface sampling where we need face information.
+    """
+
+    vertices: np.ndarray  # (N, 3) vertex positions
+    faces: np.ndarray  # (M, 3) triangle face indices
+    vertex_normals: np.ndarray | None = None  # (N, 3) per-vertex normals
+
+
+def load_mesh(
+    path: str | Path,
+    **kwargs: Any,
+) -> Mesh:
+    """Load mesh from file (preserves face information).
+
+    Use this instead of load_point_cloud() when you need area-weighted
+    surface sampling, which requires face information.
+
+    Supported formats:
+    - PLY (requires trimesh in [io] extras)
+    - OBJ (requires trimesh in [io] extras)
+    - STL (requires trimesh in [io] extras)
+    - OFF (requires trimesh in [io] extras)
+
+    Args:
+        path: Path to mesh file
+        **kwargs: Additional arguments for trimesh loader
+
+    Returns:
+        Mesh object with vertices, faces, and optional normals
+
+    Example:
+        >>> mesh = load_mesh("model.ply")
+        >>> print(f"Vertices: {len(mesh.vertices)}, Faces: {len(mesh.faces)}")
+    """
+    try:
+        import trimesh
+    except ImportError as e:
+        raise ImportError(
+            "trimesh is required for mesh loading. "
+            "Install with: pip install sdf-sampler[io]"
+        ) from e
+
+    path = Path(path)
+    loaded = trimesh.load(path, **kwargs)
+
+    # Handle Scene objects (multiple meshes)
+    if isinstance(loaded, trimesh.Scene):
+        # Combine all meshes into one
+        meshes = [g for g in loaded.geometry.values() if isinstance(g, trimesh.Trimesh)]
+        if not meshes:
+            raise ValueError(f"No triangle meshes found in {path}")
+        loaded = trimesh.util.concatenate(meshes)
+
+    if not isinstance(loaded, trimesh.Trimesh):
+        raise ValueError(
+            f"File {path} did not load as a triangle mesh. "
+            "Use load_point_cloud() for point cloud files."
+        )
+
+    vertices = np.asarray(loaded.vertices)
+    faces = np.asarray(loaded.faces)
+
+    vertex_normals = None
+    if loaded.vertex_normals is not None and len(loaded.vertex_normals) == len(vertices):
+        vertex_normals = np.asarray(loaded.vertex_normals)
+
+    return Mesh(vertices=vertices, faces=faces, vertex_normals=vertex_normals)
+
+
 def load_point_cloud(
     path: str | Path,
     **kwargs: Any,
@@ -37,8 +111,8 @@ def load_point_cloud(
     path = Path(path)
     suffix = path.suffix.lower()
 
-    if suffix == ".ply":
-        return _load_ply(path, **kwargs)
+    if suffix in (".ply", ".obj", ".stl", ".off"):
+        return _load_mesh_vertices(path, **kwargs)
     elif suffix in (".las", ".laz"):
         return _load_las(path, **kwargs)
     elif suffix == ".csv":
@@ -76,27 +150,33 @@ def export_parquet(
     return path
 
 
-def _load_ply(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
-    """Load PLY file using trimesh."""
+def _load_mesh_vertices(path: Path, **kwargs: Any) -> tuple[np.ndarray, np.ndarray | None]:
+    """Load mesh file using trimesh and return vertices."""
     try:
         import trimesh
     except ImportError as e:
         raise ImportError(
-            "trimesh is required for PLY support. "
+            "trimesh is required for mesh file support. "
             "Install with: pip install sdf-sampler[io]"
         ) from e
 
-    mesh = trimesh.load(path, **kwargs)
+    loaded = trimesh.load(path, **kwargs)
+
+    # Handle Scene objects (multiple meshes)
+    if isinstance(loaded, trimesh.Scene):
+        meshes = [g for g in loaded.geometry.values() if isinstance(g, trimesh.Trimesh)]
+        if meshes:
+            loaded = trimesh.util.concatenate(meshes)
 
     # Handle both PointCloud and Trimesh objects
-    if hasattr(mesh, "vertices"):
-        xyz = np.asarray(mesh.vertices)
+    if hasattr(loaded, "vertices"):
+        xyz = np.asarray(loaded.vertices)
     else:
-        xyz = np.asarray(mesh.points if hasattr(mesh, "points") else mesh)
+        xyz = np.asarray(loaded.points if hasattr(loaded, "points") else loaded)
 
     normals = None
-    if hasattr(mesh, "vertex_normals") and mesh.vertex_normals is not None:
-        normals = np.asarray(mesh.vertex_normals)
+    if hasattr(loaded, "vertex_normals") and loaded.vertex_normals is not None:
+        normals = np.asarray(loaded.vertex_normals)
         if normals.shape != xyz.shape:
             normals = None
 

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/src/sdf_sampler/models/analysis.py

@@ -26,6 +26,13 @@ ALL_ALGORITHMS = [
     AlgorithmType.NORMAL_IDW,
 ]
 
+# Default algorithms (excludes normal_idw which is opt-in)
+DEFAULT_ALGORITHMS = [
+    AlgorithmType.FLOOD_FILL,
+    AlgorithmType.VOXEL_REGIONS,
+    AlgorithmType.NORMAL_OFFSET,
+]
+
 
 class GeneratedConstraint(BaseModel):
     """A constraint generated by auto-analysis.

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/src/sdf_sampler/sampler.py

@@ -66,7 +66,8 @@ class SDFSampler:
         strategy: str | SamplingStrategy = SamplingStrategy.INVERSE_SQUARE,
         seed: int | None = None,
         include_surface_points: bool = False,
-        surface_point_ratio: float = 0.1,
+        surface_point_count: int | None = None,
+        mesh: Any = None,
     ) -> list[TrainingSample]:
         """Generate training samples from constraints.
 
@@ -78,7 +79,9 @@ class SDFSampler:
             strategy: Sampling strategy (CONSTANT, DENSITY, or INVERSE_SQUARE)
             seed: Random seed for reproducibility
             include_surface_points: If True, include original surface points with phi=0
-            surface_point_ratio: Fraction of surface points to include (default 0.1 = 10%)
+            surface_point_count: Number of surface points to include (default: 1000, or len(xyz) if smaller)
+            mesh: Optional Mesh object for area-weighted surface sampling. If provided,
+                  surface points are sampled uniformly by surface area instead of by vertex.
 
         Returns:
             List of TrainingSample objects
@@ -160,8 +163,10 @@ class SDFSampler:
 
         # Add surface points if requested
         if include_surface_points:
+            # Default to 1000 surface points, or all points if smaller
+            count = surface_point_count if surface_point_count is not None else min(1000, len(xyz))
             samples.extend(
-                self._generate_surface_points(xyz, normals, surface_point_ratio, rng)
+                self._generate_surface_points(xyz, normals, count, rng, mesh)
             )
 
         return samples
@@ -170,22 +175,32 @@ class SDFSampler:
         self,
         xyz: np.ndarray,
         normals: np.ndarray | None,
-        ratio: float,
+        count: int,
         rng: np.random.Generator,
+        mesh: Any = None,
     ) -> list[TrainingSample]:
         """Generate surface point samples (phi=0) from the input point cloud.
 
         Args:
             xyz: Point cloud positions (N, 3)
             normals: Optional point normals (N, 3)
-            ratio: Fraction of points to include (0.0 to 1.0)
+            count: Number of surface points to include
             rng: Random number generator
+            mesh: Optional Mesh object for area-weighted sampling
 
         Returns:
             List of TrainingSample objects with phi=0
         """
-        n_surface = int(len(xyz) * ratio)
-        if n_surface == 0:
+        if count <= 0:
+            return []
+
+        # Use area-weighted sampling if mesh is provided
+        if mesh is not None:
+            return self._generate_surface_points_area_weighted(mesh, count, rng)
+
+        # Fallback to vertex-based sampling
+        n_surface = min(count, len(xyz))
+        if n_surface <= 0:
             return []
 
         # Subsample if needed
@@ -217,6 +232,107 @@ class SDFSampler:
 
         return samples
 
+    def _generate_surface_points_area_weighted(
+        self,
+        mesh: Any,
+        count: int,
+        rng: np.random.Generator,
+    ) -> list[TrainingSample]:
+        """Generate surface points using area-weighted sampling.
+
+        Samples points uniformly by surface area, not by vertex count.
+        This ensures uniform coverage even when vertex density varies.
+
+        Args:
+            mesh: Mesh object with vertices, faces, and optional vertex_normals
+            count: Number of surface points to generate
+            rng: Random number generator
+
+        Returns:
+            List of TrainingSample objects with phi=0
+        """
+        vertices = mesh.vertices
+        faces = mesh.faces
+
+        # Compute face areas
+        v0 = vertices[faces[:, 0]]
+        v1 = vertices[faces[:, 1]]
+        v2 = vertices[faces[:, 2]]
+        face_areas = 0.5 * np.linalg.norm(np.cross(v1 - v0, v2 - v0), axis=1)
+
+        # Sample faces proportional to their area
+        total_area = face_areas.sum()
+        if total_area <= 0:
+            return []
+
+        face_probs = face_areas / total_area
+        sampled_faces = rng.choice(len(faces), size=count, p=face_probs)
+
+        # Sample random point within each selected face using barycentric coordinates
+        # Generate random barycentric coordinates
+        r1 = rng.random(count)
+        r2 = rng.random(count)
+        # Ensure uniform distribution within triangle
+        sqrt_r1 = np.sqrt(r1)
+        u = 1 - sqrt_r1
+        v = sqrt_r1 * (1 - r2)
+        w = sqrt_r1 * r2
+
+        # Get vertices for sampled faces
+        f_v0 = vertices[faces[sampled_faces, 0]]
+        f_v1 = vertices[faces[sampled_faces, 1]]
+        f_v2 = vertices[faces[sampled_faces, 2]]
+
+        # Compute sample positions
+        surface_xyz = (
+            u[:, np.newaxis] * f_v0 +
+            v[:, np.newaxis] * f_v1 +
+            w[:, np.newaxis] * f_v2
+        )
+
+        # Compute normals (interpolated from vertex normals if available, else face normals)
+        if mesh.vertex_normals is not None:
+            n0 = mesh.vertex_normals[faces[sampled_faces, 0]]
+            n1 = mesh.vertex_normals[faces[sampled_faces, 1]]
+            n2 = mesh.vertex_normals[faces[sampled_faces, 2]]
+            surface_normals = (
+                u[:, np.newaxis] * n0 +
+                v[:, np.newaxis] * n1 +
+                w[:, np.newaxis] * n2
+            )
+            # Normalize
+            norms = np.linalg.norm(surface_normals, axis=1, keepdims=True)
+            norms = np.where(norms > 0, norms, 1)
+            surface_normals = surface_normals / norms
+        else:
+            # Compute face normals
+            edge1 = f_v1 - f_v0
+            edge2 = f_v2 - f_v0
+            surface_normals = np.cross(edge1, edge2)
+            norms = np.linalg.norm(surface_normals, axis=1, keepdims=True)
+            norms = np.where(norms > 0, norms, 1)
+            surface_normals = surface_normals / norms
+
+        # Build samples
+        samples = []
+        for i in range(len(surface_xyz)):
+            sample = TrainingSample(
+                x=float(surface_xyz[i, 0]),
+                y=float(surface_xyz[i, 1]),
+                z=float(surface_xyz[i, 2]),
+                phi=0.0,
+                nx=float(surface_normals[i, 0]),
+                ny=float(surface_normals[i, 1]),
+                nz=float(surface_normals[i, 2]),
+                weight=1.0,
+                source="surface",
+                is_surface=True,
+                is_free=False,
+            )
+            samples.append(sample)
+
+        return samples
+
     def to_dataframe(self, samples: list[TrainingSample]) -> pd.DataFrame:
         """Convert samples to pandas DataFrame.
 

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/tests/test_equivalence.py

@@ -759,3 +759,120 @@ class TestFullPipelineEquivalence:
                 f"Sample count ratio too high: {ratio:.2f} "
                 f"(standalone={standalone_sample_count}, backend={backend_sample_count})"
             )
+
+    @requires_backend
+    def test_inverse_square_pipeline_equivalence(self, trench_pointcloud):
+        """Test inverse_square sampling produces equivalent results.
+
+        This is the recommended production workflow: auto-analyze + inverse_square sampling.
+        """
+        xyz, normals = trench_pointcloud
+
+        # Shared analysis options
+        analysis_options = AutoAnalysisOptions(
+            flood_fill_output="samples",
+            flood_fill_sample_count=100,
+            voxel_regions_output="samples",
+            voxel_regions_sample_count=100,
+            idw_sample_count=100,
+            hull_filter_enabled=False,
+        )
+
+        # Run standalone with inverse_square
+        standalone_analyzer = SDFAnalyzer()
+        standalone_result = standalone_analyzer.analyze(
+            xyz=xyz,
+            normals=normals,
+            algorithms=["flood_fill", "voxel_regions", "normal_idw"],
+            options=analysis_options,
+        )
+
+        standalone_sampler = SDFSampler()
+        standalone_samples = standalone_sampler.generate(
+            xyz=xyz,
+            normals=normals,
+            constraints=standalone_result.constraints,
+            strategy="inverse_square",
+            total_samples=5000,
+            seed=42,
+            include_surface_points=False,  # Test without surface points first
+        )
+
+        # Run backend with inverse_square
+        from sdf_labeler_api.config import Settings
+        from sdf_labeler_api.services.auto_analysis_service import AutoAnalysisService
+        from sdf_labeler_api.services.sampling_service import SamplingService
+        from sdf_labeler_api.services.project_service import ProjectService
+        from sdf_labeler_api.services.constraint_service import ConstraintService
+        from sdf_labeler_api.models.project import ProjectCreate
+        from sdf_labeler_api.models.samples import SampleGenerationRequest, SamplingStrategy
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            data_dir = Path(tmpdir)
+
+            import sdf_labeler_api.config as backend_config
+            original_settings = backend_config.settings
+            backend_config.settings = Settings(data_dir=data_dir)
+
+            try:
+                project_service = ProjectService(data_dir)
+                project = project_service.create(ProjectCreate(name="test"))
+                project_id = project.id
+
+                setup_backend_project(data_dir, project_id, xyz, normals)
+
+                # Analyze
+                backend_analysis = AutoAnalysisService(backend_config.settings)
+                backend_options = get_backend_options(analysis_options)
+                backend_result = asyncio.run(backend_analysis.analyze(
+                    project_id=project_id,
+                    algorithms=["flood_fill", "voxel_regions", "normal_idw"],
+                    recompute=True,
+                    options=backend_options,
+                ))
+
+                # Add constraints to project
+                constraint_service = ConstraintService()
+                for gc in backend_result.generated_constraints:
+                    constraint_service.add_from_dict(project_id, gc.constraint)
+
+                # Sample with inverse_square
+                sampling_service = SamplingService()
+                request = SampleGenerationRequest(
+                    total_samples=5000,
+                    strategy=SamplingStrategy.INVERSE_SQUARE,
+                    seed=42,
+                )
+                backend_sample_result = sampling_service.generate(project_id, request)
+                backend_samples = backend_sample_result.samples
+            finally:
+                backend_config.settings = original_settings
+
+        # Compare results
+        print(f"\nInverse square pipeline comparison:")
+        print(f"  Standalone constraints: {len(standalone_result.constraints)}")
+        print(f"  Backend constraints: {len(backend_result.generated_constraints)}")
+        print(f"  Standalone samples: {len(standalone_samples)}")
+        print(f"  Backend samples: {len(backend_samples)}")
+
+        # Verify phi distribution is similar (more samples near 0)
+        standalone_near_surface = sum(1 for s in standalone_samples if abs(s.phi) < 0.1)
+        backend_near_surface = sum(1 for s in backend_samples if abs(s.phi) < 0.1)
+
+        print(f"  Standalone near-surface (|phi|<0.1): {standalone_near_surface}")
+        print(f"  Backend near-surface (|phi|<0.1): {backend_near_surface}")
+
+        # Both should have majority of samples near surface (inverse_square characteristic)
+        standalone_ratio = standalone_near_surface / len(standalone_samples) if standalone_samples else 0
+        backend_ratio = backend_near_surface / len(backend_samples) if backend_samples else 0
+
+        assert standalone_ratio > 0.3, f"Standalone should have >30% near-surface, got {standalone_ratio:.1%}"
+        assert backend_ratio > 0.3, f"Backend should have >30% near-surface, got {backend_ratio:.1%}"
+
+        # Ratios should be similar
+        if standalone_ratio > 0 and backend_ratio > 0:
+            ratio_diff = abs(standalone_ratio - backend_ratio)
+            assert ratio_diff < 0.2, (
+                f"Near-surface ratio difference too high: {ratio_diff:.1%} "
+                f"(standalone={standalone_ratio:.1%}, backend={backend_ratio:.1%})"
+            )

{sdf_sampler-0.3.0 → sdf_sampler-0.5.0}/uv.lock

@@ -855,7 +855,7 @@ wheels = [
 
 [[package]]
 name = "sdf-sampler"
-version = "0.2.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "alphashape" },