sdf-sampler 0.4.0__tar.gz → 0.6.0__tar.gz

{sdf_sampler-0.4.0 → sdf_sampler-0.6.0}/CHANGELOG.md

@@ -5,6 +5,35 @@ 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

{sdf_sampler-0.4.0 → sdf_sampler-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdf-sampler
-Version: 0.4.0
+Version: 0.6.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.4.0 → sdf_sampler-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdf-sampler"
-version = "0.4.0"
+version = "0.6.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.4.0 → sdf_sampler-0.6.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.4.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.4.0 → sdf_sampler-0.6.0}/src/sdf_sampler/cli.py

@@ -174,6 +174,14 @@ def add_output_options(parser: argparse.ArgumentParser) -> None:
         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.",
+    )
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -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_count, 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_count, 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,
-    count: int,
-    verbose: bool,
-) -> list:
-    """Add surface points to sample list."""
-    from sdf_sampler.models import TrainingSample
-
-    n_surface = min(count, len(xyz))
-    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.4.0 → sdf_sampler-0.6.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.4.0 → sdf_sampler-0.6.0}/src/sdf_sampler/sampler.py

@@ -67,6 +67,7 @@ class SDFSampler:
         seed: int | None = None,
         include_surface_points: bool = False,
         surface_point_count: int | None = None,
+        mesh: Any = None,
     ) -> list[TrainingSample]:
         """Generate training samples from constraints.
 
@@ -79,6 +80,8 @@ class SDFSampler:
             seed: Random seed for reproducibility
             include_surface_points: If True, include original surface points with phi=0
             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
@@ -163,7 +166,7 @@ class SDFSampler:
             # 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, count, rng)
+                self._generate_surface_points(xyz, normals, count, rng, mesh)
             )
 
         return samples
@@ -174,6 +177,7 @@ class SDFSampler:
         normals: np.ndarray | None,
         count: int,
         rng: np.random.Generator,
+        mesh: Any = None,
     ) -> list[TrainingSample]:
         """Generate surface point samples (phi=0) from the input point cloud.
 
@@ -182,10 +186,19 @@ class SDFSampler:
             normals: Optional point normals (N, 3)
             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
         """
+        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 []
@@ -219,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.4.0 → sdf_sampler-0.6.0}/src/sdf_sampler/sampling/box.py

@@ -80,17 +80,18 @@ def sample_box_inverse_square(
     """Generate samples from a box with inverse-square density distribution.
 
     Samples more points near the surface (point cloud) and fewer far away.
+    Uses actual distance to surface for phi values (signed distance).
 
     Args:
         constraint: Box constraint to sample
         rng: Random number generator
-        near_band: Near-band width for offset
+        near_band: Near-band width for density weighting (not phi assignment)
         n_samples: Number of samples to generate
         surface_tree: KDTree of surface points for distance computation
         falloff: Falloff exponent (higher = faster falloff)
 
     Returns:
-        List of TrainingSample objects
+        List of TrainingSample objects with phi = actual signed distance to surface
     """
     samples = []
     center = np.array(constraint.center)
@@ -109,8 +110,11 @@ def sample_box_inverse_square(
         weight = (near_band / min_dist) ** falloff
 
         if rng.random() < min(1.0, weight):
-            offset = near_band if constraint.sign == SignConvention.EMPTY else -near_band
-            phi = offset
+            # Use actual distance to surface for phi, with sign based on constraint type
+            # EMPTY regions have positive phi (outside surface)
+            # SOLID regions have negative phi (inside surface)
+            sign = 1.0 if constraint.sign == SignConvention.EMPTY else -1.0
+            phi = sign * float(dist_to_surface)
 
             samples.append(
                 TrainingSample(

{sdf_sampler-0.4.0 → sdf_sampler-0.6.0}/tests/test_sampler.py

@@ -229,3 +229,161 @@ class TestSamplerSignConvention:
         for s in samples:
             assert s.phi > 0, f"EMPTY sample should have positive phi, got {s.phi}"
             assert s.is_free
+
+
+class TestBoxInverseSquarePhiValues:
+    """Tests that box inverse_square samples use actual distance to surface for phi."""
+
+    @pytest.fixture
+    def plane_surface(self):
+        """Flat plane at z=0 for easy distance calculation."""
+        x = np.linspace(-2, 2, 50)
+        y = np.linspace(-2, 2, 50)
+        xx, yy = np.meshgrid(x, y)
+        xyz = np.column_stack([xx.ravel(), yy.ravel(), np.zeros(2500)])
+        return xyz
+
+    @pytest.fixture
+    def box_above_plane(self):
+        """Box constraint above z=0 plane (empty region above surface)."""
+        return {
+            "type": "box",
+            "sign": "empty",  # Above surface = empty/positive phi
+            "center": (0.0, 0.0, 0.5),  # Center at z=0.5
+            "half_extents": (1.0, 1.0, 0.5),  # Extends from z=0 to z=1
+            "weight": 1.0,
+        }
+
+    @pytest.fixture
+    def box_below_plane(self):
+        """Box constraint below z=0 plane (solid region below surface)."""
+        return {
+            "type": "box",
+            "sign": "solid",  # Below surface = solid/negative phi
+            "center": (0.0, 0.0, -0.5),  # Center at z=-0.5
+            "half_extents": (1.0, 1.0, 0.5),  # Extends from z=-1 to z=0
+            "weight": 1.0,
+        }
+
+    def test_inverse_square_phi_is_actual_distance(self, plane_surface, box_above_plane):
+        """Verify phi is based on distance to nearest surface point, not constant near_band."""
+        sampler = SDFSampler(config=SamplerConfig(total_samples=500))
+        samples = sampler.generate(
+            xyz=plane_surface,
+            constraints=[box_above_plane],
+            strategy=SamplingStrategy.INVERSE_SQUARE,
+            seed=42,
+        )
+
+        assert len(samples) > 0, "Should generate samples"
+
+        for s in samples:
+            # For a flat plane at z=0, distance to surface is approximately |z|
+            # (exact value depends on nearest point in the discrete point cloud)
+            z_distance = abs(s.z)
+
+            # phi should be approximately |z| (within grid spacing tolerance)
+            # Grid spacing is ~0.08 units, so allow some tolerance
+            assert abs(s.phi - z_distance) < 0.1, (
+                f"phi should be approximately equal to |z| distance. "
+                f"Got phi={s.phi}, z={s.z}, expected ~{z_distance}"
+            )
+
+            # phi should definitely be positive for empty constraint
+            assert s.phi > 0, f"EMPTY sample should have positive phi, got {s.phi}"
+
+    def test_inverse_square_phi_varies_with_distance(self, plane_surface, box_above_plane):
+        """Verify phi values vary based on sample distance from surface."""
+        sampler = SDFSampler(config=SamplerConfig(total_samples=500))
+        samples = sampler.generate(
+            xyz=plane_surface,
+            constraints=[box_above_plane],
+            strategy=SamplingStrategy.INVERSE_SQUARE,
+            seed=42,
+        )
+
+        phi_values = [s.phi for s in samples]
+
+        # Phi should vary (not be constant ±near_band)
+        phi_std = np.std(phi_values)
+        assert phi_std > 0.01, (
+            f"phi values should vary with distance, got std={phi_std}. "
+            "This suggests phi is constant (bug: using near_band instead of distance)"
+        )
+
+        # Should have a range of values, not just near_band=0.02
+        phi_min, phi_max = min(phi_values), max(phi_values)
+        phi_range = phi_max - phi_min
+        assert phi_range > 0.1, (
+            f"phi range should be > 0.1, got {phi_range}. "
+            "Values: min={phi_min}, max={phi_max}"
+        )
+
+    def test_inverse_square_solid_has_negative_phi(self, plane_surface, box_below_plane):
+        """Verify solid box samples have negative phi with magnitude proportional to distance."""
+        sampler = SDFSampler(config=SamplerConfig(total_samples=500))
+        samples = sampler.generate(
+            xyz=plane_surface,
+            constraints=[box_below_plane],
+            strategy=SamplingStrategy.INVERSE_SQUARE,
+            seed=42,
+        )
+
+        for s in samples:
+            # SOLID constraint should always have negative phi
+            assert s.phi < 0, f"SOLID sample should have negative phi, got {s.phi}"
+
+            # For flat plane at z=0, solid samples are at z<0
+            # Distance to nearest surface point is approximately |z|
+            z_distance = abs(s.z)
+
+            # phi magnitude should be approximately |z| (within grid spacing tolerance)
+            assert abs(abs(s.phi) - z_distance) < 0.1, (
+                f"phi magnitude should be approximately |z|. "
+                f"Got phi={s.phi}, z={s.z}, expected ~{-z_distance}"
+            )
+
+    def test_inverse_square_phi_correlates_with_z_coordinate(self, plane_surface, box_above_plane):
+        """For plane at z=0, phi should be correlated with |z| coordinate."""
+        sampler = SDFSampler(config=SamplerConfig(total_samples=200))
+        samples = sampler.generate(
+            xyz=plane_surface,
+            constraints=[box_above_plane],
+            strategy=SamplingStrategy.INVERSE_SQUARE,
+            seed=123,
+        )
+
+        # Collect z values and phi values
+        z_values = np.array([abs(s.z) for s in samples])
+        phi_values = np.array([s.phi for s in samples])
+
+        # phi should be positively correlated with |z|
+        # (samples further from z=0 should have larger phi)
+        correlation = np.corrcoef(z_values, phi_values)[0, 1]
+        assert correlation > 0.9, (
+            f"phi should be strongly correlated with |z|. "
+            f"Got correlation={correlation:.3f}"
+        )
+
+    def test_inverse_square_not_constant_near_band(self, plane_surface, box_above_plane):
+        """Explicitly verify phi is NOT the constant near_band value."""
+        near_band = 0.02  # Default near_band value
+        sampler = SDFSampler(config=SamplerConfig(total_samples=200, near_band=near_band))
+        samples = sampler.generate(
+            xyz=plane_surface,
+            constraints=[box_above_plane],
+            strategy=SamplingStrategy.INVERSE_SQUARE,
+            seed=42,
+        )
+
+        # Count how many samples have phi approximately equal to near_band
+        near_band_count = sum(1 for s in samples if abs(abs(s.phi) - near_band) < 0.001)
+        total = len(samples)
+
+        # With actual distance-based phi, very few samples should be exactly at near_band
+        # (only those that happen to be exactly 0.02 away from surface)
+        ratio = near_band_count / total
+        assert ratio < 0.1, (
+            f"{near_band_count}/{total} ({ratio:.0%}) samples have phi≈±near_band. "
+            "This suggests phi is still using constant near_band instead of actual distance."
+        )

{sdf_sampler-0.4.0 → sdf_sampler-0.6.0}/uv.lock

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