sdf-sampler 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

sdf_sampler/__init__.py

@@ -47,7 +47,7 @@ from sdf_sampler.models import (
 )
 from sdf_sampler.sampler import SDFSampler
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     # Main classes

sdf_sampler/__main__.py

@@ -0,0 +1,17 @@
+# ABOUTME: Entry point for running sdf-sampler as a module
+# ABOUTME: Enables `python -m sdf_sampler` invocation
+
+"""
+Run sdf-sampler as a module.
+
+Usage:
+    python -m sdf_sampler --help
+    python -m sdf_sampler analyze input.ply -o constraints.json
+    python -m sdf_sampler sample input.ply constraints.json -o samples.parquet
+    python -m sdf_sampler pipeline input.ply -o samples.parquet
+"""
+
+from sdf_sampler.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sdf_sampler/cli.py

@@ -0,0 +1,681 @@
+# ABOUTME: Command-line interface for sdf-sampler
+# ABOUTME: Provides analyze, sample, and pipeline commands with full parameter control
+
+"""
+CLI for sdf-sampler.
+
+Usage:
+    python -m sdf_sampler analyze input.ply -o constraints.json
+    python -m sdf_sampler sample input.ply constraints.json -o samples.parquet
+    python -m sdf_sampler pipeline input.ply -o samples.parquet
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+
+def add_analysis_options(parser: argparse.ArgumentParser) -> None:
+    """Add analysis configuration options to a parser."""
+    group = parser.add_argument_group("Analysis Options")
+
+    group.add_argument(
+        "--min-gap-size",
+        type=float,
+        default=0.10,
+        help="Minimum gap size for flood fill in meters (default: 0.10)",
+    )
+    group.add_argument(
+        "--max-grid-dim",
+        type=int,
+        default=200,
+        help="Maximum voxel grid dimension (default: 200)",
+    )
+    group.add_argument(
+        "--cone-angle",
+        type=float,
+        default=15.0,
+        help="Ray propagation cone half-angle in degrees (default: 15.0)",
+    )
+    group.add_argument(
+        "--normal-offset-pairs",
+        type=int,
+        default=40,
+        help="Number of box pairs for normal_offset algorithm (default: 40)",
+    )
+    group.add_argument(
+        "--max-boxes",
+        type=int,
+        default=30,
+        help="Maximum boxes per algorithm (default: 30)",
+    )
+    group.add_argument(
+        "--overlap-threshold",
+        type=float,
+        default=0.5,
+        help="Overlap threshold for box simplification (default: 0.5)",
+    )
+    group.add_argument(
+        "--idw-sample-count",
+        type=int,
+        default=1000,
+        help="Number of IDW samples to generate (default: 1000)",
+    )
+    group.add_argument(
+        "--idw-max-distance",
+        type=float,
+        default=0.5,
+        help="Maximum IDW distance from surface in meters (default: 0.5)",
+    )
+    group.add_argument(
+        "--idw-power",
+        type=float,
+        default=2.0,
+        help="IDW power factor (default: 2.0)",
+    )
+    group.add_argument(
+        "--hull-alpha",
+        type=float,
+        default=1.0,
+        help="Alpha shape parameter for hull filtering (default: 1.0)",
+    )
+    group.add_argument(
+        "--flood-fill-output",
+        type=str,
+        choices=["boxes", "samples", "both"],
+        default="samples",
+        help="Output mode for flood fill (default: samples)",
+    )
+    group.add_argument(
+        "--flood-fill-samples",
+        type=int,
+        default=500,
+        help="Number of sample points from flood fill (default: 500)",
+    )
+    group.add_argument(
+        "--voxel-regions-output",
+        type=str,
+        choices=["boxes", "samples", "both"],
+        default="samples",
+        help="Output mode for voxel regions (default: samples)",
+    )
+    group.add_argument(
+        "--voxel-regions-samples",
+        type=int,
+        default=500,
+        help="Number of sample points from voxel regions (default: 500)",
+    )
+
+
+def add_sampling_options(parser: argparse.ArgumentParser) -> None:
+    """Add sampling configuration options to a parser."""
+    group = parser.add_argument_group("Sampling Options")
+
+    group.add_argument(
+        "-n", "--total-samples",
+        type=int,
+        default=10000,
+        help="Total number of samples to generate (default: 10000)",
+    )
+    group.add_argument(
+        "-s", "--strategy",
+        type=str,
+        choices=["constant", "density", "inverse_square"],
+        default="inverse_square",
+        help="Sampling strategy (default: inverse_square)",
+    )
+    group.add_argument(
+        "--seed",
+        type=int,
+        default=None,
+        help="Random seed for reproducibility",
+    )
+    group.add_argument(
+        "--samples-per-primitive",
+        type=int,
+        default=100,
+        help="Samples per primitive for CONSTANT strategy (default: 100)",
+    )
+    group.add_argument(
+        "--inverse-square-base",
+        type=int,
+        default=100,
+        help="Base samples at surface for INVERSE_SQUARE (default: 100)",
+    )
+    group.add_argument(
+        "--inverse-square-falloff",
+        type=float,
+        default=2.0,
+        help="Falloff exponent for INVERSE_SQUARE (default: 2.0)",
+    )
+    group.add_argument(
+        "--near-band",
+        type=float,
+        default=0.02,
+        help="Near-band width around surface (default: 0.02)",
+    )
+
+
+def add_output_options(parser: argparse.ArgumentParser) -> None:
+    """Add output configuration options to a parser."""
+    group = parser.add_argument_group("Output Options")
+
+    group.add_argument(
+        "--include-surface-points",
+        action="store_true",
+        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%%)",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="sdf-sampler",
+        description="Auto-analysis and sampling of point clouds for SDF training data",
+    )
+    parser.add_argument(
+        "--version", action="store_true", help="Show version and exit"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # analyze command
+    analyze_parser = subparsers.add_parser(
+        "analyze",
+        help="Analyze point cloud to detect SOLID/EMPTY regions",
+    )
+    analyze_parser.add_argument(
+        "input",
+        type=Path,
+        help="Input point cloud file (PLY, LAS, NPZ, CSV, Parquet)",
+    )
+    analyze_parser.add_argument(
+        "-o", "--output",
+        type=Path,
+        default=None,
+        help="Output constraints JSON file (default: <input>_constraints.json)",
+    )
+    analyze_parser.add_argument(
+        "-a", "--algorithms",
+        type=str,
+        nargs="+",
+        default=None,
+        help="Algorithms to run (flood_fill, voxel_regions, normal_offset, normal_idw, pocket)",
+    )
+    analyze_parser.add_argument(
+        "--no-hull-filter",
+        action="store_true",
+        help="Disable hull filtering",
+    )
+    analyze_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+    add_analysis_options(analyze_parser)
+
+    # sample command
+    sample_parser = subparsers.add_parser(
+        "sample",
+        help="Generate training samples from constraints",
+    )
+    sample_parser.add_argument(
+        "input",
+        type=Path,
+        help="Input point cloud file",
+    )
+    sample_parser.add_argument(
+        "constraints",
+        type=Path,
+        help="Constraints JSON file (from analyze command)",
+    )
+    sample_parser.add_argument(
+        "-o", "--output",
+        type=Path,
+        default=None,
+        help="Output parquet file (default: <input>_samples.parquet)",
+    )
+    sample_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+    add_sampling_options(sample_parser)
+    add_output_options(sample_parser)
+
+    # pipeline command
+    pipeline_parser = subparsers.add_parser(
+        "pipeline",
+        help="Full pipeline: analyze + sample + export",
+    )
+    pipeline_parser.add_argument(
+        "input",
+        type=Path,
+        help="Input point cloud file",
+    )
+    pipeline_parser.add_argument(
+        "-o", "--output",
+        type=Path,
+        default=None,
+        help="Output parquet file (default: <input>_samples.parquet)",
+    )
+    pipeline_parser.add_argument(
+        "-a", "--algorithms",
+        type=str,
+        nargs="+",
+        default=None,
+        help="Algorithms to run",
+    )
+    pipeline_parser.add_argument(
+        "--no-hull-filter",
+        action="store_true",
+        help="Disable hull filtering",
+    )
+    pipeline_parser.add_argument(
+        "--save-constraints",
+        type=Path,
+        default=None,
+        help="Also save constraints to JSON file",
+    )
+    pipeline_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+    add_analysis_options(pipeline_parser)
+    add_sampling_options(pipeline_parser)
+    add_output_options(pipeline_parser)
+
+    # info command
+    info_parser = subparsers.add_parser(
+        "info",
+        help="Show information about a point cloud or constraints file",
+    )
+    info_parser.add_argument(
+        "input",
+        type=Path,
+        help="Input file (point cloud or constraints JSON)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.version:
+        from sdf_sampler import __version__
+        print(f"sdf-sampler {__version__}")
+        return 0
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "analyze":
+        return cmd_analyze(args)
+    elif args.command == "sample":
+        return cmd_sample(args)
+    elif args.command == "pipeline":
+        return cmd_pipeline(args)
+    elif args.command == "info":
+        return cmd_info(args)
+
+    return 0
+
+
+def build_analysis_options(args: argparse.Namespace):
+    """Build AutoAnalysisOptions from CLI args."""
+    from sdf_sampler.config import AutoAnalysisOptions
+
+    return AutoAnalysisOptions(
+        min_gap_size=args.min_gap_size,
+        max_grid_dim=args.max_grid_dim,
+        cone_angle=args.cone_angle,
+        normal_offset_pairs=args.normal_offset_pairs,
+        max_boxes=args.max_boxes,
+        overlap_threshold=args.overlap_threshold,
+        idw_sample_count=args.idw_sample_count,
+        idw_max_distance=args.idw_max_distance,
+        idw_power=args.idw_power,
+        hull_filter_enabled=not getattr(args, 'no_hull_filter', False),
+        hull_alpha=args.hull_alpha,
+        flood_fill_output=args.flood_fill_output,
+        flood_fill_sample_count=args.flood_fill_samples,
+        voxel_regions_output=args.voxel_regions_output,
+        voxel_regions_sample_count=args.voxel_regions_samples,
+    )
+
+
+def build_sampler_config(args: argparse.Namespace):
+    """Build SamplerConfig from CLI args."""
+    from sdf_sampler.config import SamplerConfig
+
+    return SamplerConfig(
+        total_samples=args.total_samples,
+        samples_per_primitive=args.samples_per_primitive,
+        inverse_square_base_samples=args.inverse_square_base,
+        inverse_square_falloff=args.inverse_square_falloff,
+        near_band=args.near_band,
+        seed=args.seed or 0,
+    )
+
+
+def cmd_analyze(args: argparse.Namespace) -> int:
+    """Run analyze command."""
+    from sdf_sampler import SDFAnalyzer, load_point_cloud
+
+    if not args.input.exists():
+        print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+        return 1
+
+    output = args.output or args.input.with_suffix(".constraints.json")
+
+    if args.verbose:
+        print(f"Loading point cloud: {args.input}")
+
+    try:
+        xyz, normals = load_point_cloud(str(args.input))
+    except Exception as e:
+        print(f"Error loading point cloud: {e}", file=sys.stderr)
+        return 1
+
+    if args.verbose:
+        print(f"  Points: {len(xyz):,}")
+        print(f"  Normals: {'yes' if normals is not None else 'no'}")
+
+    options = build_analysis_options(args)
+
+    if args.verbose:
+        algos = args.algorithms or ["all"]
+        print(f"Running analysis: {', '.join(algos)}")
+
+    analyzer = SDFAnalyzer()
+    result = analyzer.analyze(
+        xyz=xyz,
+        normals=normals,
+        algorithms=args.algorithms,
+        options=options,
+    )
+
+    if args.verbose:
+        print(f"Generated {len(result.constraints)} constraints")
+        print(f"  SOLID: {result.summary.solid_constraints}")
+        print(f"  EMPTY: {result.summary.empty_constraints}")
+
+    # Save constraints
+    with open(output, "w") as f:
+        json.dump(result.constraints, f, indent=2, default=_json_serializer)
+
+    print(f"Saved constraints to: {output}")
+    return 0
+
+
+def cmd_sample(args: argparse.Namespace) -> int:
+    """Run sample command."""
+    from sdf_sampler import SDFSampler, load_point_cloud
+
+    if not args.input.exists():
+        print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+        return 1
+
+    if not args.constraints.exists():
+        print(f"Error: Constraints file not found: {args.constraints}", file=sys.stderr)
+        return 1
+
+    output = args.output or args.input.with_suffix(".samples.parquet")
+
+    if args.verbose:
+        print(f"Loading point cloud: {args.input}")
+
+    try:
+        xyz, normals = load_point_cloud(str(args.input))
+    except Exception as e:
+        print(f"Error loading point cloud: {e}", file=sys.stderr)
+        return 1
+
+    if args.verbose:
+        print(f"Loading constraints: {args.constraints}")
+
+    with open(args.constraints) as f:
+        constraints = json.load(f)
+
+    if args.verbose:
+        print(f"  Constraints: {len(constraints)}")
+        print(f"Generating {args.total_samples:,} samples with strategy: {args.strategy}")
+
+    config = build_sampler_config(args)
+    sampler = SDFSampler(config=config)
+    samples = sampler.generate(
+        xyz=xyz,
+        normals=normals,
+        constraints=constraints,
+        total_samples=args.total_samples,
+        strategy=args.strategy,
+        seed=args.seed,
+    )
+
+    # 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")
+
+    sampler.export_parquet(samples, str(output))
+    print(f"Saved samples to: {output}")
+    return 0
+
+
+def cmd_pipeline(args: argparse.Namespace) -> int:
+    """Run full pipeline: analyze + sample + export."""
+    from sdf_sampler import SDFAnalyzer, SDFSampler, load_point_cloud
+
+    if not args.input.exists():
+        print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+        return 1
+
+    output = args.output or args.input.with_suffix(".samples.parquet")
+
+    if args.verbose:
+        print(f"Loading point cloud: {args.input}")
+
+    try:
+        xyz, normals = load_point_cloud(str(args.input))
+    except Exception as e:
+        print(f"Error loading point cloud: {e}", file=sys.stderr)
+        return 1
+
+    if args.verbose:
+        print(f"  Points: {len(xyz):,}")
+        print(f"  Normals: {'yes' if normals is not None else 'no'}")
+
+    # Analyze
+    if args.verbose:
+        algos = args.algorithms or ["all"]
+        print(f"Running analysis: {', '.join(algos)}")
+
+    options = build_analysis_options(args)
+    analyzer = SDFAnalyzer()
+    result = analyzer.analyze(
+        xyz=xyz,
+        normals=normals,
+        algorithms=args.algorithms,
+        options=options,
+    )
+
+    if args.verbose:
+        print(f"Generated {len(result.constraints)} constraints")
+        print(f"  SOLID: {result.summary.solid_constraints}")
+        print(f"  EMPTY: {result.summary.empty_constraints}")
+
+    # Optionally save constraints
+    if args.save_constraints:
+        with open(args.save_constraints, "w") as f:
+            json.dump(result.constraints, f, indent=2, default=_json_serializer)
+        if args.verbose:
+            print(f"Saved constraints to: {args.save_constraints}")
+
+    # Sample
+    if args.verbose:
+        print(f"Generating {args.total_samples:,} samples with strategy: {args.strategy}")
+
+    config = build_sampler_config(args)
+    sampler = SDFSampler(config=config)
+    samples = sampler.generate(
+        xyz=xyz,
+        normals=normals,
+        constraints=result.constraints,
+        total_samples=args.total_samples,
+        strategy=args.strategy,
+        seed=args.seed,
+    )
+
+    # 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")
+
+    # Export
+    sampler.export_parquet(samples, str(output))
+    print(f"Saved samples to: {output}")
+    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():
+        print(f"Error: File not found: {args.input}", file=sys.stderr)
+        return 1
+
+    suffix = args.input.suffix.lower()
+
+    if suffix == ".json":
+        # Constraints file
+        with open(args.input) as f:
+            constraints = json.load(f)
+
+        print(f"Constraints file: {args.input}")
+        print(f"  Total constraints: {len(constraints)}")
+
+        # Count by type and sign
+        by_type: dict[str, int] = {}
+        by_sign: dict[str, int] = {}
+        for c in constraints:
+            ctype = c.get("type", "unknown")
+            sign = c.get("sign", "unknown")
+            by_type[ctype] = by_type.get(ctype, 0) + 1
+            by_sign[sign] = by_sign.get(sign, 0) + 1
+
+        print("  By type:")
+        for t, count in sorted(by_type.items()):
+            print(f"    {t}: {count}")
+        print("  By sign:")
+        for s, count in sorted(by_sign.items()):
+            print(f"    {s}: {count}")
+
+    elif suffix == ".parquet":
+        import pandas as pd
+        df = pd.read_parquet(args.input)
+
+        print(f"Parquet file: {args.input}")
+        print(f"  Samples: {len(df):,}")
+        print(f"  Columns: {', '.join(df.columns)}")
+
+        if "source" in df.columns:
+            print("  By source:")
+            for source, count in df["source"].value_counts().items():
+                print(f"    {source}: {count:,}")
+
+        if "phi" in df.columns:
+            print(f"  Phi range: [{df['phi'].min():.4f}, {df['phi'].max():.4f}]")
+
+    else:
+        # Point cloud file
+        from sdf_sampler import load_point_cloud
+
+        try:
+            xyz, normals = load_point_cloud(str(args.input))
+        except Exception as e:
+            print(f"Error loading file: {e}", file=sys.stderr)
+            return 1
+
+        print(f"Point cloud: {args.input}")
+        print(f"  Points: {len(xyz):,}")
+        print(f"  Normals: {'yes' if normals is not None else 'no'}")
+        print(f"  Bounds:")
+        print(f"    X: [{xyz[:, 0].min():.4f}, {xyz[:, 0].max():.4f}]")
+        print(f"    Y: [{xyz[:, 1].min():.4f}, {xyz[:, 1].max():.4f}]")
+        print(f"    Z: [{xyz[:, 2].min():.4f}, {xyz[:, 2].max():.4f}]")
+
+    return 0
+
+
+def _json_serializer(obj):
+    """JSON serializer for numpy types."""
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, (np.integer, np.floating)):
+        return obj.item()
+    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sdf_sampler/sampler.py

@@ -65,6 +65,8 @@ class SDFSampler:
         total_samples: int | None = None,
         strategy: str | SamplingStrategy = SamplingStrategy.INVERSE_SQUARE,
         seed: int | None = None,
+        include_surface_points: bool = False,
+        surface_point_ratio: float = 0.1,
     ) -> list[TrainingSample]:
         """Generate training samples from constraints.
 
@@ -75,6 +77,8 @@ class SDFSampler:
             total_samples: Total samples to generate (default from config)
             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%)
 
         Returns:
             List of TrainingSample objects
@@ -85,6 +89,7 @@ class SDFSampler:
             ...     constraints=result.constraints,
             ...     strategy="inverse_square",
             ...     total_samples=50000,
+            ...     include_surface_points=True,
             ... )
         """
         xyz = np.asarray(xyz)
@@ -153,6 +158,63 @@ class SDFSampler:
             elif isinstance(constraint, SamplePointConstraint):
                 samples.extend(self._sample_sample_point(constraint))
 
+        # Add surface points if requested
+        if include_surface_points:
+            samples.extend(
+                self._generate_surface_points(xyz, normals, surface_point_ratio, rng)
+            )
+
+        return samples
+
+    def _generate_surface_points(
+        self,
+        xyz: np.ndarray,
+        normals: np.ndarray | None,
+        ratio: float,
+        rng: np.random.Generator,
+    ) -> 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)
+            rng: Random number generator
+
+        Returns:
+            List of TrainingSample objects with phi=0
+        """
+        n_surface = int(len(xyz) * ratio)
+        if n_surface == 0:
+            return []
+
+        # Subsample if needed
+        if n_surface < len(xyz):
+            indices = rng.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
+
+        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,
+                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 to_dataframe(self, samples: list[TrainingSample]) -> pd.DataFrame:

{sdf_sampler-0.1.0.dist-info → sdf_sampler-0.3.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: sdf-sampler
-Version: 0.1.0
+Version: 0.3.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
+Project-URL: Repository, https://github.com/Chiark-Collective/sdf-sampler
 Author-email: Liam <liam@example.com>
 License: MIT
 License-File: LICENSE
@@ -60,7 +60,88 @@ For additional I/O format support (PLY, LAS/LAZ):
 pip install sdf-sampler[io]
 ```
 
-## Quick Start
+## Command-Line Interface
+
+sdf-sampler provides a CLI for common workflows:
+
+```bash
+# Run as module
+python -m sdf_sampler --help
+
+# Or use the installed command
+sdf-sampler --help
+```
+
+### Commands
+
+#### `pipeline` - Full workflow (recommended)
+
+Run the complete pipeline: analyze point cloud → generate samples → export.
+
+```bash
+# Basic usage
+sdf-sampler pipeline scan.ply -o training_data.parquet
+
+# With options
+sdf-sampler pipeline scan.ply \
+    -o training_data.parquet \
+    -n 50000 \
+    -s inverse_square \
+    --save-constraints constraints.json \
+    -v
+```
+
+Options:
+- `-o, --output`: Output parquet file (default: `<input>_samples.parquet`)
+- `-n, --total-samples`: Number of samples to generate (default: 10000)
+- `-s, --strategy`: Sampling strategy: `constant`, `density`, `inverse_square` (default: `inverse_square`)
+- `-a, --algorithms`: Specific algorithms to run (default: all)
+- `--save-constraints`: Also save constraints to JSON
+- `--seed`: Random seed for reproducibility
+- `-v, --verbose`: Verbose output
+
+#### `analyze` - Detect regions
+
+Analyze a point cloud to detect SOLID/EMPTY regions.
+
+```bash
+sdf-sampler analyze scan.ply -o constraints.json -v
+```
+
+Options:
+- `-o, --output`: Output JSON file (default: `<input>_constraints.json`)
+- `-a, --algorithms`: Algorithms to run (see below)
+- `--no-hull-filter`: Disable hull filtering
+- `-v, --verbose`: Verbose output
+
+#### `sample` - Generate training samples
+
+Generate training samples from a constraints file.
+
+```bash
+sdf-sampler sample scan.ply constraints.json -o samples.parquet -n 50000
+```
+
+Options:
+- `-o, --output`: Output parquet file
+- `-n, --total-samples`: Number of samples (default: 10000)
+- `-s, --strategy`: Sampling strategy (default: `inverse_square`)
+- `--seed`: Random seed
+- `-v, --verbose`: Verbose output
+
+#### `info` - Inspect files
+
+Show information about point clouds, constraints, or sample files.
+
+```bash
+sdf-sampler info scan.ply
+sdf-sampler info constraints.json
+sdf-sampler info samples.parquet
+```
+
+## Python SDK
+
+### Quick Start
 
 ```python
 from sdf_sampler import SDFAnalyzer, SDFSampler, load_point_cloud
@@ -86,28 +167,13 @@ samples = sampler.generate(
 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
 
+Analyzes point clouds to detect SOLID and EMPTY regions.
+
 ```python
-from sdf_sampler import SDFAnalyzer, AnalyzerConfig
+from sdf_sampler import SDFAnalyzer
+from sdf_sampler.config import AnalyzerConfig, AutoAnalysisOptions
 
 # With default config
 analyzer = SDFAnalyzer()
@@ -136,10 +202,23 @@ print(f"EMPTY: {result.summary.empty_constraints}")
 constraints = result.constraints
 ```
 
+#### Analysis Algorithms
+
+| Algorithm | Description | Output |
+|-----------|-------------|--------|
+| `flood_fill` | Detects EMPTY (outside) regions by ray propagation from sky | Box or SamplePoint constraints |
+| `voxel_regions` | Detects SOLID (underground) regions | Box or SamplePoint constraints |
+| `normal_offset` | Generates paired SOLID/EMPTY boxes along surface normals | Box constraints |
+| `normal_idw` | Inverse distance weighted sampling along normals | SamplePoint constraints |
+| `pocket` | Detects interior cavities | Pocket constraints |
+
 ### SDFSampler
 
+Generates training samples from constraints.
+
 ```python
-from sdf_sampler import SDFSampler, SamplerConfig
+from sdf_sampler import SDFSampler
+from sdf_sampler.config import SamplerConfig
 
 # With default config
 sampler = SDFSampler()
@@ -167,6 +246,14 @@ sampler.export_parquet(samples, "output.parquet")
 df = sampler.to_dataframe(samples)
 ```
 
+#### Sampling Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `constant` | Fixed number of samples per constraint |
+| `density` | Samples proportional to constraint volume |
+| `inverse_square` | More samples near surface, fewer far away (recommended) |
+
 ### Constraint Types
 
 The analyzer generates various constraint types:
@@ -180,6 +267,22 @@ Each constraint has:
 - `sign`: "solid" (negative SDF) or "empty" (positive SDF)
 - `weight`: Sample weight (default 1.0)
 
+### I/O Helpers
+
+```python
+from sdf_sampler import load_point_cloud, export_parquet
+
+# Load various formats
+xyz, normals = load_point_cloud("scan.ply")    # PLY (requires trimesh)
+xyz, normals = load_point_cloud("scan.las")    # LAS/LAZ (requires laspy)
+xyz, normals = load_point_cloud("scan.csv")    # CSV with x,y,z columns
+xyz, normals = load_point_cloud("scan.npz")    # NumPy archive
+xyz, normals = load_point_cloud("scan.parquet") # Parquet
+
+# Export samples
+export_parquet(samples, "output.parquet")
+```
+
 ## Output Format
 
 The exported parquet file contains columns:
@@ -194,32 +297,40 @@ The exported parquet file contains columns:
 | is_surface | bool | Whether sample is on surface |
 | is_free | bool | Whether sample is in free space (EMPTY) |
 
-## Configuration Options
+## Configuration Reference
 
 ### 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 |
+| `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 |
+| `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 |
+
+## Integration with Ubik
+
+sdf-sampler is the core analysis engine for [Ubik](https://github.com/Chiark-Collective/ubik), an interactive web application for SDF labeling. Use sdf-sampler directly for:
+
+- Automated batch processing pipelines
+- Integration into ML training workflows
+- Custom analysis scripts
 
 ## License
 

{sdf_sampler-0.1.0.dist-info → sdf_sampler-0.3.0.dist-info}/RECORD

@@ -1,8 +1,10 @@
-sdf_sampler/__init__.py,sha256=9LyfRS8RsgknQvp5TKUKKknuQD9Ovm74qlfbxlOvfCE,1891
+sdf_sampler/__init__.py,sha256=Kd5g1IROdKbRTR_gNSO4ff1ddNVP4WZJ30JFUbILa5k,1891
+sdf_sampler/__main__.py,sha256=6N7jJs2Efs1AmM7qXXXN9V-ErFTWpPqKzWTeiujtGhU,490
 sdf_sampler/analyzer.py,sha256=p5Pkoa01dBGFqqQs2wpWrr8ilPMsjkB4ODJEI2IWbdo,11674
+sdf_sampler/cli.py,sha256=ykW1_cPBV6G1ZtKmq0ZyjgUmVK-ESqk3Ey6SLMRIhSQ,20144
 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/sampler.py,sha256=3yVT5LHB7-rIxdor-aSdkC6Qew5M-7UvZCKwtIZG0IQ,17744
 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
@@ -19,7 +21,8 @@ sdf_sampler/sampling/box.py,sha256=qRAumR1z_7vU9rfNvk-B6xNu62UeHSyQNghYiTwVR_Y,3
 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.3.0.dist-info/METADATA,sha256=MU48zB7pLEhlGEO5ZTDcfP0l7DBXH3u3_iZI0oZJ4FU,10481
+sdf_sampler-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sdf_sampler-0.3.0.dist-info/entry_points.txt,sha256=2IMWFbDYEqVUkpiRF1BlRMOhipeirPJSbv5PIOIZrvA,53
+sdf_sampler-0.3.0.dist-info/licenses/LICENSE,sha256=eeB8aLnEG-dgFYs2KqfMJaP52GFQT8sZPHwaYnHRW8E,1061
+sdf_sampler-0.3.0.dist-info/RECORD,,

sdf_sampler-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sdf-sampler = sdf_sampler.cli:main