sdf-sampler 0.1.0__tar.gz

sdf_sampler-0.1.0/.github_token.env

@@ -0,0 +1 @@
+GITHUB_TOKEN=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

sdf_sampler-0.1.0/.gitignore

@@ -0,0 +1,81 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Local development
+*.parquet
+*.npz
+
+# Secrets
+.pypi_token.env

sdf_sampler-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+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.1.0] - 2025-01-29
+
+### Added
+
+- Initial release extracted from sdf-labeler backend
+- **SDFAnalyzer** class for auto-analysis of point clouds
+  - `flood_fill` algorithm: EMPTY region detection via ray propagation from sky
+  - `voxel_regions` algorithm: SOLID region detection from underground
+  - `normal_offset` algorithm: Paired SOLID/EMPTY boxes along surface normals
+  - `normal_idw` algorithm: Inverse distance weighted sampling along normals
+  - `pocket` algorithm: Interior cavity detection via voxel flood fill
+  - Hull filtering to remove constraints outside X-Y alpha shape
+  - Configurable via `AnalyzerConfig` dataclass
+- **SDFSampler** class for training sample generation
+  - Supports multiple constraint types: box, sphere, halfspace, brush_stroke, etc.
+  - Three sampling strategies: CONSTANT, DENSITY, INVERSE_SQUARE
+  - Export to Parquet and DataFrame
+  - Configurable via `SamplerConfig` dataclass
+- **I/O helpers**
+  - `load_point_cloud()` for PLY, LAS/LAZ, CSV, NPZ, Parquet formats
+  - `export_parquet()` for survi-compatible training data export
+- Pydantic models for all constraint types and training samples
+- Comprehensive test suite (56 tests including equivalence tests vs sdf-labeler backend)
+
+### Dependencies
+
+- pydantic>=2.5.0 (data validation)
+- numpy>=1.26.0 (core arrays)
+- pandas>=2.1.0 (Parquet I/O)
+- scipy>=1.11.0 (KDTree, spatial, ndimage)
+- alphashape>=1.3.1 (concave hull filtering)
+- pyarrow>=14.0.0 (Parquet export)
+
+### Optional Dependencies
+
+- trimesh>=4.0.0 (PLY loading, `[io]` extra)
+- laspy[laszip]>=2.5.0 (LAS/LAZ loading, `[io]` extra)

sdf_sampler-0.1.0/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.

sdf_sampler-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,182 @@
+# 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/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "sdf-sampler"
+version = "0.1.0"
+description = "Auto-analysis and sampling of point clouds for SDF (Signed Distance Field) training data generation"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Liam", email = "liam@example.com" }]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["sdf", "signed-distance-field", "point-cloud", "sampling", "machine-learning"]
+
+dependencies = [
+    "pydantic>=2.5.0",
+    "numpy>=1.26.0",
+    "pandas>=2.1.0",
+    "scipy>=1.11.0",
+    "alphashape>=1.3.1",
+    "pyarrow>=14.0.0",
+]
+
+[project.optional-dependencies]
+io = [
+    "trimesh>=4.0.0",
+    "laspy[laszip]>=2.5.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.5.0",
+    "mypy>=1.8.0",
+]
+all = ["sdf-sampler[io,dev]"]
+
+[project.urls]
+Repository = "https://github.com/chiark/sdf-sampler"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sdf_sampler"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sdf_sampler"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true