diskpack 0.10.1__tar.gz → 0.10.2__tar.gz

diskpack-0.10.2/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: diskpack
+Version: 0.10.2
+Summary: A high-performance vectorized circle packer with spatial hashing.
+Author-email: James Kelly <mrkellyjam@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# diskpack
+
+State-of-the-art circle packing for arbitrary polygons.
+
+![packed star](star\_packed.png) 
+
+
+
+
+```bash
+pip install diskpack
+```
+
+## Quick Start
+
+```python
+from diskpack import CirclePacker, PackingConfig
+import numpy as np
+
+# Define a polygon (list of vertices)
+square = [(0, 0), (100, 0), (100, 100), (0, 100)]
+
+# Pack circles
+packer = CirclePacker([np.array(square)])
+circles = packer.pack()
+
+# Each circle is (x, y, radius)
+for x, y, r in circles:
+    print(f"Circle at ({x:.1f}, {y:.1f}) with radius {r:.1f}")
+```
+
+## Choosing the Right Algorithm
+
+diskpack offers multiple packing strategies optimized for different use cases:
+
+| Shape Type | Best Algorithm | Config |
+|------------|----------------|--------|
+| Simple convex (square, rectangle) | Random sampling | `PackingConfig()` |
+| Complex/concave (star, L-shape, letters) | Hybrid | `PackingConfig(use_hybrid_packing=True)` |
+| Fixed radius, need speed | Hex grid | `PackingConfig(fixed_radius=5.0)` |
+| Fixed radius, need density | Hybrid | `PackingConfig(fixed_radius=5.0, use_hybrid_packing=True)` |
+| Artistic/organic look | Random | `PackingConfig(use_hex_grid=False)` |
+
+### Simple Convex Shapes
+
+For squares, rectangles, and other simple convex polygons, the default random sampling achieves the best density:
+
+```python
+config = PackingConfig(
+    padding=0.5,
+    min_radius=1.0,
+)
+packer = CirclePacker([np.array(square)], config)
+circles = packer.pack()  # ~86% density
+```
+
+### Complex/Concave Shapes
+
+For stars, L-shapes, letters, and other complex polygons, hybrid mode fills corners better:
+
+```python
+star = [
+    (50, 0), (61, 35), (98, 35), (68, 57), (79, 91),
+    (50, 70), (21, 91), (32, 57), (2, 35), (39, 35)
+]
+
+config = PackingConfig(
+    use_hybrid_packing=True,
+    verbose=True,  # See progress
+)
+packer = CirclePacker([np.array(star)], config)
+circles = packer.pack()  # ~69% density (vs ~64% for random)
+```
+
+### Fixed Radius Packing
+
+When all circles must have the same radius:
+
+```python
+# Fastest (hex grid pattern)
+config = PackingConfig(fixed_radius=3.0)
+
+# Densest (fills corners)
+config = PackingConfig(fixed_radius=3.0, use_hybrid_packing=True)
+
+# Organic look (random placement)
+config = PackingConfig(fixed_radius=3.0, use_hex_grid=False)
+```
+
+## Tuning Hybrid Mode
+
+Hybrid mode works in three phases:
+
+1. **Phase 1 (Large)**: Place circles ≥ 50% of max possible radius
+2. **Phase 2 (Medium)**: Place circles ≥ 25% of max possible radius  
+3. **Phase 3 (Small)**: Fill remaining gaps with random sampling
+
+You can tune the thresholds:
+
+```python
+# For complex shapes with tight corners (default)
+config = PackingConfig(
+    use_hybrid_packing=True,
+    hybrid_large_threshold=0.5,   # Phase 1: >= 50% of max
+    hybrid_medium_threshold=0.25, # Phase 2: >= 25% of max
+)
+
+# For simpler shapes (more circles in Phases 1-2)
+config = PackingConfig(
+    use_hybrid_packing=True,
+    hybrid_large_threshold=0.3,   # Phase 1: >= 30% of max
+    hybrid_medium_threshold=0.1,  # Phase 2: >= 10% of max
+)
+```
+
+## Performance Tuning
+
+```python
+config = PackingConfig(
+    # Stop after N consecutive failed attempts (higher = more circles, slower)
+    max_failed_attempts=200,
+    
+    # Points sampled per iteration (higher = better placements, more memory)
+    sample_batch_size=50,
+    
+    # Minimum gap between circles
+    padding=1.5,
+    
+    # Smallest circle to place
+    min_radius=1.0,
+)
+```
+
+## API Reference
+
+### CirclePacker
+
+```python
+CirclePacker(polygons: List[np.ndarray], config: PackingConfig = None)
+```
+
+- `polygons`: List of polygon vertices. Each polygon is an Nx2 numpy array.
+- `config`: Optional configuration. Uses defaults if not provided.
+
+**Methods:**
+
+- `pack() -> List[Tuple[float, float, float]]`: Pack circles and return as list
+- `generate() -> Iterator[Tuple[float, float, float]]`: Generate circles lazily
+
+### PackingConfig
+
+See the docstring for full parameter documentation:
+
+```python
+from diskpack import PackingConfig
+help(PackingConfig)
+```
+
+## Benchmark Results
+
+Tested on 100×100 unit shapes:
+
+| Shape | Algorithm | Time | Circles | Density |
+|-------|-----------|------|---------|---------|
+| Square | Random | 0.31s | 49 | **86.4%** |
+| Square | Hybrid | **0.15s** | 55 | 85.8% |
+| L-Shape | Random | 0.68s | 50 | 76.9% |
+| L-Shape | Hybrid | **0.30s** | 36 | **79.3%** |
+| Star | Random | 0.32s | 39 | 64.4% |
+| Star | Hybrid | **0.25s** | 27 | **68.8%** |
+
+Fixed radius (r=3.0) on Star shape:
+
+| Algorithm | Time | Circles | Density |
+|-----------|------|---------|---------|
+| Hex Grid | **0.007s** | 40 | 40.0% |
+| Hybrid | 0.08s | **51** | **51.0%** |
+
+## Comparison with Shapely
+
+diskpack achieves higher density and faster packing compared to the Python Shapely library. Where Shapely creates Python objects for each point-in-polygon and distance check, diskpack uses vectorized NumPy operations with precomputed edge geometry and batched candidate evaluation — sampling many points per iteration and greedily placing the largest valid circle. A grid-based spatial index keeps collision detection O(1) as circle count grows. The batched Shapely method can approach similar density by also picking the best of many candidates, but at ~30x the runtime due to per-point object overhead.
+
+![diskpack vs shapely comparison](diskpack_shapely_comp.png)
+
+| Method | Circles | Density | Time |
+|--------|---------|---------|------|
+| **diskpack** | 47 | **86.7%** | **0.679s** |
+| shapely (naive) | 109 | 73.4% | 1.424s |
+| shapely (batched) | 60 | 85.3% | 19.569s |
+
+See [`demo/diskpack_comparisons.ipynb`](demo/diskpack_comparisons.ipynb) for the full benchmark notebook.
+
+## License
+
+MIT

diskpack-0.10.2/README.md

@@ -0,0 +1,195 @@
+# diskpack
+
+State-of-the-art circle packing for arbitrary polygons.
+
+![packed star](star\_packed.png) 
+
+
+
+
+```bash
+pip install diskpack
+```
+
+## Quick Start
+
+```python
+from diskpack import CirclePacker, PackingConfig
+import numpy as np
+
+# Define a polygon (list of vertices)
+square = [(0, 0), (100, 0), (100, 100), (0, 100)]
+
+# Pack circles
+packer = CirclePacker([np.array(square)])
+circles = packer.pack()
+
+# Each circle is (x, y, radius)
+for x, y, r in circles:
+    print(f"Circle at ({x:.1f}, {y:.1f}) with radius {r:.1f}")
+```
+
+## Choosing the Right Algorithm
+
+diskpack offers multiple packing strategies optimized for different use cases:
+
+| Shape Type | Best Algorithm | Config |
+|------------|----------------|--------|
+| Simple convex (square, rectangle) | Random sampling | `PackingConfig()` |
+| Complex/concave (star, L-shape, letters) | Hybrid | `PackingConfig(use_hybrid_packing=True)` |
+| Fixed radius, need speed | Hex grid | `PackingConfig(fixed_radius=5.0)` |
+| Fixed radius, need density | Hybrid | `PackingConfig(fixed_radius=5.0, use_hybrid_packing=True)` |
+| Artistic/organic look | Random | `PackingConfig(use_hex_grid=False)` |
+
+### Simple Convex Shapes
+
+For squares, rectangles, and other simple convex polygons, the default random sampling achieves the best density:
+
+```python
+config = PackingConfig(
+    padding=0.5,
+    min_radius=1.0,
+)
+packer = CirclePacker([np.array(square)], config)
+circles = packer.pack()  # ~86% density
+```
+
+### Complex/Concave Shapes
+
+For stars, L-shapes, letters, and other complex polygons, hybrid mode fills corners better:
+
+```python
+star = [
+    (50, 0), (61, 35), (98, 35), (68, 57), (79, 91),
+    (50, 70), (21, 91), (32, 57), (2, 35), (39, 35)
+]
+
+config = PackingConfig(
+    use_hybrid_packing=True,
+    verbose=True,  # See progress
+)
+packer = CirclePacker([np.array(star)], config)
+circles = packer.pack()  # ~69% density (vs ~64% for random)
+```
+
+### Fixed Radius Packing
+
+When all circles must have the same radius:
+
+```python
+# Fastest (hex grid pattern)
+config = PackingConfig(fixed_radius=3.0)
+
+# Densest (fills corners)
+config = PackingConfig(fixed_radius=3.0, use_hybrid_packing=True)
+
+# Organic look (random placement)
+config = PackingConfig(fixed_radius=3.0, use_hex_grid=False)
+```
+
+## Tuning Hybrid Mode
+
+Hybrid mode works in three phases:
+
+1. **Phase 1 (Large)**: Place circles ≥ 50% of max possible radius
+2. **Phase 2 (Medium)**: Place circles ≥ 25% of max possible radius  
+3. **Phase 3 (Small)**: Fill remaining gaps with random sampling
+
+You can tune the thresholds:
+
+```python
+# For complex shapes with tight corners (default)
+config = PackingConfig(
+    use_hybrid_packing=True,
+    hybrid_large_threshold=0.5,   # Phase 1: >= 50% of max
+    hybrid_medium_threshold=0.25, # Phase 2: >= 25% of max
+)
+
+# For simpler shapes (more circles in Phases 1-2)
+config = PackingConfig(
+    use_hybrid_packing=True,
+    hybrid_large_threshold=0.3,   # Phase 1: >= 30% of max
+    hybrid_medium_threshold=0.1,  # Phase 2: >= 10% of max
+)
+```
+
+## Performance Tuning
+
+```python
+config = PackingConfig(
+    # Stop after N consecutive failed attempts (higher = more circles, slower)
+    max_failed_attempts=200,
+    
+    # Points sampled per iteration (higher = better placements, more memory)
+    sample_batch_size=50,
+    
+    # Minimum gap between circles
+    padding=1.5,
+    
+    # Smallest circle to place
+    min_radius=1.0,
+)
+```
+
+## API Reference
+
+### CirclePacker
+
+```python
+CirclePacker(polygons: List[np.ndarray], config: PackingConfig = None)
+```
+
+- `polygons`: List of polygon vertices. Each polygon is an Nx2 numpy array.
+- `config`: Optional configuration. Uses defaults if not provided.
+
+**Methods:**
+
+- `pack() -> List[Tuple[float, float, float]]`: Pack circles and return as list
+- `generate() -> Iterator[Tuple[float, float, float]]`: Generate circles lazily
+
+### PackingConfig
+
+See the docstring for full parameter documentation:
+
+```python
+from diskpack import PackingConfig
+help(PackingConfig)
+```
+
+## Benchmark Results
+
+Tested on 100×100 unit shapes:
+
+| Shape | Algorithm | Time | Circles | Density |
+|-------|-----------|------|---------|---------|
+| Square | Random | 0.31s | 49 | **86.4%** |
+| Square | Hybrid | **0.15s** | 55 | 85.8% |
+| L-Shape | Random | 0.68s | 50 | 76.9% |
+| L-Shape | Hybrid | **0.30s** | 36 | **79.3%** |
+| Star | Random | 0.32s | 39 | 64.4% |
+| Star | Hybrid | **0.25s** | 27 | **68.8%** |
+
+Fixed radius (r=3.0) on Star shape:
+
+| Algorithm | Time | Circles | Density |
+|-----------|------|---------|---------|
+| Hex Grid | **0.007s** | 40 | 40.0% |
+| Hybrid | 0.08s | **51** | **51.0%** |
+
+## Comparison with Shapely
+
+diskpack achieves higher density and faster packing compared to the Python Shapely library. Where Shapely creates Python objects for each point-in-polygon and distance check, diskpack uses vectorized NumPy operations with precomputed edge geometry and batched candidate evaluation — sampling many points per iteration and greedily placing the largest valid circle. A grid-based spatial index keeps collision detection O(1) as circle count grows. The batched Shapely method can approach similar density by also picking the best of many candidates, but at ~30x the runtime due to per-point object overhead.
+
+![diskpack vs shapely comparison](diskpack_shapely_comp.png)
+
+| Method | Circles | Density | Time |
+|--------|---------|---------|------|
+| **diskpack** | 47 | **86.7%** | **0.679s** |
+| shapely (naive) | 109 | 73.4% | 1.424s |
+| shapely (batched) | 60 | 85.3% | 19.569s |
+
+See [`demo/diskpack_comparisons.ipynb`](demo/diskpack_comparisons.ipynb) for the full benchmark notebook.
+
+## License
+
+MIT

{diskpack-0.10.1 → diskpack-0.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "diskpack"
-version = "0.10.1"
+version = "0.10.2"
 authors = [{ name="James Kelly", email="mrkellyjam@gmail.com" }]
 description = "A high-performance vectorized circle packer with spatial hashing."
 readme = "README.md"

diskpack-0.10.2/src/diskpack/config.py

@@ -0,0 +1,155 @@
+"""
+Configuration and type definitions for circle packing.
+"""
+
+import numpy as np
+from dataclasses import dataclass
+from typing import Optional, Tuple
+from enum import Enum
+
+# Type aliases
+Polygon = np.ndarray
+Point = np.ndarray
+GridKey = Tuple[int, int]
+Circle = Tuple[float, float, float]  # (x, y, radius)
+
+
+class PackingMode(Enum):
+    """Available packing strategies."""
+    RANDOM = "random"
+    HEX_GRID = "hex_grid"
+    FRONT = "front"
+    HYBRID = "hybrid"
+
+
+@dataclass
+class PackingConfig:
+    """
+    Configuration parameters for the circle packing algorithm.
+    
+    Quick Start
+    -----------
+    # Best density for simple convex shapes (squares, rectangles, circles):
+    config = PackingConfig()  # Uses random sampling (default)
+    
+    # Best density for complex/concave shapes (stars, L-shapes, letters):
+    config = PackingConfig(use_hybrid_packing=True)
+    
+    # Fixed radius circles - fastest:
+    config = PackingConfig(fixed_radius=5.0)
+    
+    # Fixed radius circles - best density on complex shapes:
+    config = PackingConfig(fixed_radius=5.0, use_hybrid_packing=True)
+    
+    
+    Algorithm Selection Guide
+    -------------------------
+    | Shape Type          | Best Algorithm              | Config                          |
+    |---------------------|-----------------------------|---------------------------------|
+    | Simple convex       | Random sampling (default)   | PackingConfig()                 |
+    | Complex/concave     | Hybrid                      | use_hybrid_packing=True         |
+    | Fixed radius, speed | Hex grid (default for fixed)| fixed_radius=X                  |
+    | Fixed radius, dense | Hybrid                      | fixed_radius=X, use_hybrid_packing=True |
+    | Artistic/organic    | Random sampling             | use_hex_grid=False              |
+    
+    
+    Tuning Hybrid Mode
+    ------------------
+    Hybrid mode works in phases:
+      Phase 1: Place large circles (>= hybrid_large_threshold * max_radius)
+      Phase 2: Place medium circles (>= hybrid_medium_threshold * max_radius)
+      Phase 3: Fill remaining space with random sampling
+    
+    For complex shapes with tight corners (stars, letters):
+      - Use higher thresholds: hybrid_large_threshold=0.5, hybrid_medium_threshold=0.25
+      - This prioritizes filling corners with appropriately-sized circles
+    
+    For simpler shapes where you want hybrid's speed:
+      - Use lower thresholds: hybrid_large_threshold=0.3, hybrid_medium_threshold=0.1
+      - This lets the front-based algorithm place more circles before random cleanup
+    
+    
+    Parameters
+    ----------
+    padding : float, default=1.5
+        Minimum gap between circles and between circles and polygon edges.
+        
+    min_radius : float, default=1.0
+        Smallest circle that will be placed. Circles below this size are skipped.
+        
+    fixed_radius : float, optional
+        If set, all circles will have exactly this radius. Enables hex grid mode
+        by default (override with use_hex_grid=False for organic placement).
+        
+    use_hex_grid : bool, default=True
+        Use hexagonal grid for fixed radius packing. Fastest option but creates
+        a regular pattern. Set to False for organic/random placement.
+        
+    use_front_packing : bool, default=False
+        Use front-based algorithm. Good for filling corners but may produce
+        many small circles. Usually better to use use_hybrid_packing instead.
+        
+    use_hybrid_packing : bool, default=False
+        Use state-of-the-art multi-phase algorithm. Best for complex shapes.
+        Combines front-based (for corners) with random sampling (for gaps).
+        
+    max_failed_attempts : int, default=200
+        Stop after this many consecutive failed placement attempts.
+        Higher values may find more circles but take longer.
+        
+    sample_batch_size : int, default=50
+        Number of random points sampled per iteration. Higher values find
+        better placements per iteration but use more memory.
+        
+    hybrid_large_threshold : float, default=0.5
+        Phase 1 minimum radius as fraction of max possible radius.
+        Only circles >= this fraction are placed in Phase 1.
+        
+    hybrid_medium_threshold : float, default=0.25
+        Phase 2 minimum radius as fraction of max possible radius.
+        Only circles >= this fraction are placed in Phase 2.
+        
+    verbose : bool, default=False
+        Print progress information during packing.
+    """
+    # Basic parameters
+    padding: float = 1.5
+    min_radius: float = 1.0
+    fixed_radius: Optional[float] = None
+    
+    # Algorithm selection
+    use_hex_grid: bool = True
+    use_front_packing: bool = False
+    use_hybrid_packing: bool = False
+    
+    # Performance tuning
+    max_failed_attempts: int = 200
+    sample_batch_size: int = 50
+    grid_resolution_divisor: float = 25
+    mega_circle_threshold: float = 0.5
+    ray_cast_epsilon: float = 1e-10
+    
+    # Hybrid mode parameters
+    hybrid_large_threshold: float = 0.5
+    hybrid_medium_threshold: float = 0.25
+    
+    # Output
+    verbose: bool = False
+
+
+@dataclass
+class PackingProgress:
+    """Tracks the current state of the packing algorithm."""
+    circles_placed: int = 0
+    failed_attempts: int = 0
+    max_failed_attempts: int = 200
+    phase: str = ""
+
+    @property
+    def progress_ratio(self) -> float:
+        """How close to stopping (0.0 = just started, 1.0 = done)."""
+        return self.failed_attempts / self.max_failed_attempts if self.max_failed_attempts > 0 else 0
+
+    def __str__(self) -> str:
+        phase_str = f"[{self.phase}] " if self.phase else ""
+        return f"{phase_str}Placed: {self.circles_placed} | Failed: {self.failed_attempts}/{self.max_failed_attempts} ({self.progress_ratio:.0%})"