sdf-sampler 0.1.0__py3-none-any.whl

sdf_sampler/sampling/ray_carve.py

@@ -0,0 +1,134 @@
+# ABOUTME: Ray carve constraint sampling functions
+# ABOUTME: Generates training samples from ray-scribble interactions
+
+import numpy as np
+
+from sdf_sampler.models.constraints import RayCarveConstraint
+from sdf_sampler.models.samples import TrainingSample
+
+
+def sample_ray_carve(
+    constraint: RayCarveConstraint,
+    rng: np.random.Generator,
+    n_samples_per_ray: int,
+) -> list[TrainingSample]:
+    """Generate samples from ray-carve constraint.
+
+    For each ray:
+    1. Sample EMPTY points uniformly along ray from origin to (hit - empty_band)
+    2. Sample SURFACE points in band around hit point
+
+    Args:
+        constraint: Ray carve constraint to sample
+        rng: Random number generator
+        n_samples_per_ray: Number of samples per ray
+
+    Returns:
+        List of TrainingSample objects
+    """
+    samples = []
+
+    # Pre-compute ray data for outlier detection
+    ray_data = []
+    for ray in constraint.rays:
+        origin = np.array(ray.origin)
+        direction = np.array(ray.direction)
+        direction = direction / np.linalg.norm(direction)
+        hit_point = origin + direction * ray.hit_distance
+        ray_data.append(
+            {
+                "origin": origin,
+                "direction": direction,
+                "hit_distance": ray.hit_distance,
+                "hit_point": hit_point,
+                "local_spacing": ray.local_spacing,
+                "surface_normal": ray.surface_normal,
+            }
+        )
+
+    # Detect outliers: rays that pass through gaps
+    effective_hit_distances = []
+    for i, ray in enumerate(ray_data):
+        effective_dist = ray["hit_distance"]
+
+        for j, other in enumerate(ray_data):
+            if i == j:
+                continue
+
+            dir_dot = np.dot(ray["direction"], other["direction"])
+            if dir_dot > 0.95:
+                to_hit = ray["hit_point"] - other["origin"]
+                proj_dist = np.dot(to_hit, other["direction"])
+
+                if proj_dist > other["hit_distance"] * 1.1:
+                    effective_dist = min(effective_dist, other["hit_distance"])
+
+        effective_hit_distances.append(effective_dist)
+
+    for idx, ray in enumerate(ray_data):
+        origin = ray["origin"]
+        direction = ray["direction"]
+        hit_dist = effective_hit_distances[idx]
+
+        if ray["local_spacing"] is not None:
+            buffer_zone = ray["local_spacing"] * constraint.back_buffer_coefficient
+        else:
+            buffer_zone = constraint.back_buffer_width
+
+        # EMPTY samples along ray (before hit, stopping at buffer zone)
+        empty_end = hit_dist - buffer_zone
+        n_empty = n_samples_per_ray // 2
+
+        if empty_end > 0:
+            for _ in range(n_empty):
+                t = rng.uniform(0, empty_end)
+                point = origin + t * direction
+
+                samples.append(
+                    TrainingSample(
+                        x=float(point[0]),
+                        y=float(point[1]),
+                        z=float(point[2]),
+                        phi=hit_dist - t,
+                        nx=float(direction[0]),
+                        ny=float(direction[1]),
+                        nz=float(direction[2]),
+                        weight=constraint.weight,
+                        source="ray_carve_empty",
+                        is_surface=False,
+                        is_free=True,
+                    )
+                )
+
+        # SURFACE samples near hit
+        n_surface = n_samples_per_ray - n_empty
+        for _ in range(n_surface):
+            t = rng.uniform(
+                hit_dist - constraint.surface_band_width,
+                hit_dist,
+            )
+            point = origin + t * direction
+            phi = 0.0
+
+            if ray["surface_normal"]:
+                nx, ny, nz = ray["surface_normal"]
+            else:
+                nx, ny, nz = -direction[0], -direction[1], -direction[2]
+
+            samples.append(
+                TrainingSample(
+                    x=float(point[0]),
+                    y=float(point[1]),
+                    z=float(point[2]),
+                    phi=phi,
+                    nx=float(nx),
+                    ny=float(ny),
+                    nz=float(nz),
+                    weight=constraint.weight,
+                    source="ray_carve_surface",
+                    is_surface=True,
+                    is_free=False,
+                )
+            )
+
+    return samples

sdf_sampler/sampling/sphere.py

@@ -0,0 +1,57 @@
+# ABOUTME: Sphere constraint sampling functions
+# ABOUTME: Generates training samples from spherical region constraints
+
+import numpy as np
+
+from sdf_sampler.models.constraints import SignConvention, SphereConstraint
+from sdf_sampler.models.samples import TrainingSample
+
+
+def sample_sphere(
+    constraint: SphereConstraint,
+    rng: np.random.Generator,
+    near_band: float,
+    n_samples: int,
+) -> list[TrainingSample]:
+    """Generate samples from a sphere constraint.
+
+    Args:
+        constraint: Sphere constraint to sample
+        rng: Random number generator
+        near_band: Near-band width for offset
+        n_samples: Number of samples to generate
+
+    Returns:
+        List of TrainingSample objects
+    """
+    samples = []
+    center = np.array(constraint.center)
+    radius = constraint.radius
+
+    for _ in range(n_samples):
+        direction = rng.standard_normal(3)
+        direction /= np.linalg.norm(direction)
+
+        point = center + radius * direction
+
+        offset = near_band if constraint.sign == SignConvention.EMPTY else -near_band
+        point = point + offset * direction
+        phi = offset
+
+        samples.append(
+            TrainingSample(
+                x=float(point[0]),
+                y=float(point[1]),
+                z=float(point[2]),
+                phi=phi,
+                nx=float(direction[0]),
+                ny=float(direction[1]),
+                nz=float(direction[2]),
+                weight=constraint.weight,
+                source=f"sphere_{constraint.sign.value}",
+                is_surface=False,
+                is_free=constraint.sign == SignConvention.EMPTY,
+            )
+        )
+
+    return samples

sdf_sampler-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: sdf-sampler
+Version: 0.1.0
+Summary: Auto-analysis and sampling of point clouds for SDF (Signed Distance Field) training data generation
+Project-URL: Repository, https://github.com/chiark/sdf-sampler
+Author-email: Liam <liam@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: machine-learning,point-cloud,sampling,sdf,signed-distance-field
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: alphashape>=1.3.1
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: scipy>=1.11.0
+Provides-Extra: all
+Requires-Dist: laspy[laszip]>=2.5.0; extra == 'all'
+Requires-Dist: mypy>=1.8.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
+Requires-Dist: pytest>=8.0.0; extra == 'all'
+Requires-Dist: ruff>=0.5.0; extra == 'all'
+Requires-Dist: trimesh>=4.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: io
+Requires-Dist: laspy[laszip]>=2.5.0; extra == 'io'
+Requires-Dist: trimesh>=4.0.0; extra == 'io'
+Description-Content-Type: text/markdown
+
+# sdf-sampler
+
+Auto-analysis and sampling of point clouds for SDF (Signed Distance Field) training data generation.
+
+A lightweight, standalone Python package for generating SDF training hints from point clouds. Automatically detects SOLID (inside) and EMPTY (outside) regions and generates training samples suitable for SDF regression models.
+
+## Installation
+
+```bash
+pip install sdf-sampler
+```
+
+For additional I/O format support (PLY, LAS/LAZ):
+
+```bash
+pip install sdf-sampler[io]
+```
+
+## Quick Start
+
+```python
+from sdf_sampler import SDFAnalyzer, SDFSampler, load_point_cloud
+
+# 1. Load point cloud (supports PLY, LAS, CSV, NPZ, Parquet)
+xyz, normals = load_point_cloud("scan.ply")
+
+# 2. Auto-analyze to detect EMPTY/SOLID regions
+analyzer = SDFAnalyzer()
+result = analyzer.analyze(xyz=xyz, normals=normals)
+print(f"Generated {len(result.constraints)} constraints")
+
+# 3. Generate training samples
+sampler = SDFSampler()
+samples = sampler.generate(
+    xyz=xyz,
+    constraints=result.constraints,
+    strategy="inverse_square",
+    total_samples=50000,
+)
+
+# 4. Export to parquet
+sampler.export_parquet(samples, "training_data.parquet")
+```
+
+## Features
+
+### Auto-Analysis Algorithms
+
+- **flood_fill**: Detects EMPTY (outside) regions by ray propagation from sky
+- **voxel_regions**: Detects SOLID (underground) regions
+- **normal_offset**: Generates paired SOLID/EMPTY boxes along surface normals
+- **normal_idw**: Inverse distance weighted sampling along normals
+- **pocket**: Detects interior cavities
+
+### Sampling Strategies
+
+- **CONSTANT**: Fixed number of samples per constraint
+- **DENSITY**: Samples proportional to constraint volume
+- **INVERSE_SQUARE**: More samples near surface, fewer far away (recommended)
+
+## API Reference
+
+### SDFAnalyzer
+
+```python
+from sdf_sampler import SDFAnalyzer, AnalyzerConfig
+
+# With default config
+analyzer = SDFAnalyzer()
+
+# With custom config
+analyzer = SDFAnalyzer(config=AnalyzerConfig(
+    min_gap_size=0.10,      # Minimum gap for flood fill
+    max_grid_dim=200,       # Maximum voxel grid dimension
+    cone_angle=15.0,        # Ray propagation cone angle
+    hull_filter_enabled=True,  # Filter outside X-Y hull
+))
+
+# Run analysis
+result = analyzer.analyze(
+    xyz=xyz,                    # (N, 3) point positions
+    normals=normals,            # (N, 3) point normals (optional)
+    algorithms=["flood_fill", "voxel_regions"],  # Which algorithms to run
+)
+
+# Access results
+print(f"Total constraints: {result.summary.total_constraints}")
+print(f"SOLID: {result.summary.solid_constraints}")
+print(f"EMPTY: {result.summary.empty_constraints}")
+
+# Get constraint dicts for sampling
+constraints = result.constraints
+```
+
+### SDFSampler
+
+```python
+from sdf_sampler import SDFSampler, SamplerConfig
+
+# With default config
+sampler = SDFSampler()
+
+# With custom config
+sampler = SDFSampler(config=SamplerConfig(
+    total_samples=10000,
+    inverse_square_base_samples=100,
+    inverse_square_falloff=2.0,
+    near_band=0.02,
+))
+
+# Generate samples
+samples = sampler.generate(
+    xyz=xyz,                     # Point cloud for distance computation
+    constraints=constraints,      # From analyzer.analyze().constraints
+    strategy="inverse_square",    # Sampling strategy
+    seed=42,                      # For reproducibility
+)
+
+# Export
+sampler.export_parquet(samples, "output.parquet")
+
+# Or get DataFrame
+df = sampler.to_dataframe(samples)
+```
+
+### Constraint Types
+
+The analyzer generates various constraint types:
+
+- **BoxConstraint**: Axis-aligned bounding box
+- **SphereConstraint**: Spherical region
+- **SamplePointConstraint**: Direct point with signed distance
+- **PocketConstraint**: Detected cavity region
+
+Each constraint has:
+- `sign`: "solid" (negative SDF) or "empty" (positive SDF)
+- `weight`: Sample weight (default 1.0)
+
+## Output Format
+
+The exported parquet file contains columns:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| x, y, z | float | 3D position |
+| phi | float | Signed distance (negative=solid, positive=empty) |
+| nx, ny, nz | float | Normal vector (if available) |
+| weight | float | Sample weight |
+| source | string | Sample origin (e.g., "box_solid", "flood_fill_empty") |
+| is_surface | bool | Whether sample is on surface |
+| is_free | bool | Whether sample is in free space (EMPTY) |
+
+## Configuration Options
+
+### AnalyzerConfig
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| min_gap_size | 0.10 | Minimum gap size for flood fill (meters) |
+| max_grid_dim | 200 | Maximum voxel grid dimension |
+| cone_angle | 15.0 | Ray propagation cone half-angle (degrees) |
+| normal_offset_pairs | 40 | Number of box pairs for normal_offset |
+| idw_sample_count | 1000 | Total IDW samples |
+| idw_max_distance | 0.5 | Maximum IDW distance (meters) |
+| hull_filter_enabled | True | Filter outside X-Y alpha shape |
+| hull_alpha | 1.0 | Alpha shape parameter |
+
+### SamplerConfig
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| total_samples | 10000 | Default total samples |
+| samples_per_primitive | 100 | Samples per constraint (CONSTANT) |
+| samples_per_cubic_meter | 10000 | Sample density (DENSITY) |
+| inverse_square_base_samples | 100 | Base samples (INVERSE_SQUARE) |
+| inverse_square_falloff | 2.0 | Falloff exponent |
+| near_band | 0.02 | Near-band width |
+| seed | 0 | Random seed |
+
+## License
+
+MIT

sdf_sampler-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+sdf_sampler/__init__.py,sha256=9LyfRS8RsgknQvp5TKUKKknuQD9Ovm74qlfbxlOvfCE,1891
+sdf_sampler/analyzer.py,sha256=p5Pkoa01dBGFqqQs2wpWrr8ilPMsjkB4ODJEI2IWbdo,11674
+sdf_sampler/config.py,sha256=lrPM1ktFkv32RRtOz6R-ShUFlBZ2LvoAl1hRLThmgKw,5185
+sdf_sampler/io.py,sha256=DfdXJa_2KQhja_T_a-jlVADcAABeF-NR8e3_vnIJHnk,4968
+sdf_sampler/sampler.py,sha256=QVrI1TxfnSgQWYcJdRCEQqvFekPvFBUYJfrbjQj-ABY,15551
+sdf_sampler/algorithms/__init__.py,sha256=pp7tSZ8q0zRXZ5S8D3tho7bJ62pmW8jceuuRXtiXIzU,777
+sdf_sampler/algorithms/flood_fill.py,sha256=iWGPPtOPSs0Cg7pxUlXUKGloFNCr8PuCHguRNy3c56c,7042
+sdf_sampler/algorithms/normal_idw.py,sha256=uX3MQDTDX0wVilwxDE9dFj9hm2xuBDHV-AZqspjz7sk,3270
+sdf_sampler/algorithms/normal_offset.py,sha256=SzWMaK_Ws2Bg-vu_b5_viCEqJts92ezdXaFfhE97RaE,3712
+sdf_sampler/algorithms/pocket.py,sha256=d6cvFz8C1ZFGgaOEySnFcKMPlHZ-kqOU_bBvOoXTUpw,4978
+sdf_sampler/algorithms/voxel_grid.py,sha256=LJz5V02AxSBRL0-kNEV3yEN_cMWFymGiepX0yysE6dw,11133
+sdf_sampler/algorithms/voxel_regions.py,sha256=YHr-apdq9wTo_po6v5L9HxQLkcZ1kP3KfJhoaQDZJOE,2422
+sdf_sampler/models/__init__.py,sha256=XWzMnPgvZyZF1ZUSfqlspIitLkzMn_0Yxj-hRF-ALEQ,1134
+sdf_sampler/models/analysis.py,sha256=h9CIxBeTQ89Z2-B3qdrlHM8qtOA0caijTYwzd9HsyUw,3251
+sdf_sampler/models/constraints.py,sha256=k0v6-JwXmUkFXGycDpPG44amjoRo13xz1ggqdr9NVtE,7316
+sdf_sampler/models/samples.py,sha256=0DD7Z8D70zJKRTq16pik9SgGiRDeXh56EqmBZfql_sk,1474
+sdf_sampler/sampling/__init__.py,sha256=mbeU9DTHxR4R1D4WqjEzaYHq7bV1nSv-wywc3YoD_Lg,492
+sdf_sampler/sampling/box.py,sha256=qRAumR1z_7vU9rfNvk-B6xNu62UeHSyQNghYiTwVR_Y,3912
+sdf_sampler/sampling/brush.py,sha256=CcAgOYLdYXMM3y_H4fIwyzRJ8PZivFxkUHP7d0ElpNM,1991
+sdf_sampler/sampling/ray_carve.py,sha256=EsfzEGk33q0iWVzOJKDAJi2iWEsY-JZXmEfEZ0dmNdg,4444
+sdf_sampler/sampling/sphere.py,sha256=Xqpwq-RcEnAD6HhoyIC-ErxRHDknDKMtYf6aWUJ43_U,1680
+sdf_sampler-0.1.0.dist-info/METADATA,sha256=CygvgjodkmWtCsBMMXz1MLEGufR1XGZUSabpA7dII-w,7165
+sdf_sampler-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sdf_sampler-0.1.0.dist-info/licenses/LICENSE,sha256=eeB8aLnEG-dgFYs2KqfMJaP52GFQT8sZPHwaYnHRW8E,1061
+sdf_sampler-0.1.0.dist-info/RECORD,,

sdf_sampler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sdf_sampler-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Liam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.