diskpack 0.1.0__tar.gz

diskpack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Kelly
+
+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.

diskpack-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.1
+Name: diskpack
+Version: 0.1.0
+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
+
+# diskpack
+
+A Python library for packing circles within arbitrary polygon boundaries.
+
+![Circle packing example](https://via.placeholder.com/600x400?text=Circle+Packing+Example)
+
+## Installation
+
+```bash
+pip install git+https://github.com/semajyllek/diskpack.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/semajyllek/diskpack.git
+cd diskpack
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from diskpack import CirclePacker, PackingConfig
+
+# Define a polygon (list of [x, y] vertices)
+square = np.array([
+    [0, 0],
+    [100, 0],
+    [100, 100],
+    [0, 100]
+])
+
+# Pack circles
+packer = CirclePacker([square])
+circles = packer.pack()
+
+# Each circle is (x, y, radius)
+for x, y, r in circles[:5]:
+    print(f"Circle at ({x:.1f}, {y:.1f}) with radius {r:.1f}")
+```
+
+## How It Works
+
+The algorithm uses a **greedy random sampling** approach:
+
+1. **Sample** random points within the polygon's bounding box
+2. **Filter** to keep only points inside the polygon (using the even-odd rule)
+3. **Compute** the maximum radius at each point without overlapping boundaries or existing circles
+4. **Place** the largest valid circle from each batch
+5. **Repeat** until no more circles can be placed
+
+### Key Techniques
+
+**Even-Odd Rule for Point-in-Polygon**
+
+To determine if a point is inside a polygon (including polygons with holes), we cast a ray from the point and count edge crossings. An odd count means inside, even means outside.
+
+**Spatial Indexing**
+
+Checking every existing circle for collisions is O(n) per placement. We use a grid-based spatial index to only check nearby circles, bringing average-case down to O(1).
+
+Large circles that span multiple grid cells are stored separately as "mega circles" and always checked—this prevents missed collisions at cell boundaries.
+
+**Distance Calculations**
+
+The maximum radius at any point is the minimum of:
+- Distance to the nearest polygon edge
+- Distance to the nearest existing circle's boundary
+
+We subtract a configurable padding to prevent circles from touching.
+
+## Configuration
+
+Customize the packing behavior with `PackingConfig`:
+
+```python
+from diskpack import PackingConfig
+
+config = PackingConfig(
+    padding=1.5,                  # Gap between circles and boundaries
+    min_radius=1.0,               # Smallest circle to place
+    max_failed_attempts=200,      # Stop after this many failed attempts
+    sample_batch_size=50,         # Points sampled per iteration
+    grid_resolution_divisor=25,   # Controls spatial index cell size
+    mega_circle_threshold=0.5,    # Radius/cell_size ratio for "mega" circles
+)
+
+packer = CirclePacker([polygon], config)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `padding` | 1.5 | Minimum gap between circles and between circles and edges |
+| `min_radius` | 1.0 | Circles smaller than this won't be placed |
+| `max_failed_attempts` | 200 | Algorithm stops after this many consecutive failed placements |
+| `sample_batch_size` | 50 | Number of random points tested per iteration |
+| `grid_resolution_divisor` | 25 | Higher = smaller grid cells = more memory, faster lookups |
+| `mega_circle_threshold` | 0.5 | Circles with radius > cell_size × this value are tracked globally |
+
+## Progress Tracking
+
+Monitor the packing process with `verbose=True`:
+
+```python
+packer = CirclePacker([polygon], config)
+circles = packer.pack(verbose=True)
+```
+
+Output:
+```
+Placed: 25 | Failed attempts: 0/200 (0%)
+Placed: 50 | Failed attempts: 0/200 (0%)
+Placed: 75 | Failed attempts: 0/200 (0%)
+Placed: 75 | Failed attempts: 50/200 (25%)
+...
+Done! Placed: 82 | Failed attempts: 200/200 (100%)
+```
+
+You can also check progress after packing:
+
+```python
+print(packer.progress)
+# Placed: 82 | Failed attempts: 200/200 (100%)
+```
+
+## Fixed-Radius Mode
+
+Pack circles of uniform size:
+
+```python
+circles = packer.pack(fixed_radius=5.0)
+```
+
+## Complex Polygons
+
+The library handles concave polygons and multiple polygon boundaries:
+
+```python
+# Star shape
+angles = np.linspace(0, 2 * np.pi, 11)[:-1]
+star = []
+for i, a in enumerate(angles):
+    r = 100 if i % 2 == 0 else 40
+    star.append([r * np.cos(a), r * np.sin(a)])
+
+packer = CirclePacker([np.array(star)])
+circles = packer.pack()
+```
+
+```python
+# Multiple boundaries (e.g., polygon with a hole)
+outer = np.array([[0, 0], [100, 0], [100, 100], [0, 100]])
+inner = np.array([[40, 40], [60, 40], [60, 60], [40, 60]])  # hole
+
+packer = CirclePacker([outer, inner])
+```
+
+## Visualization
+
+```python
+import matplotlib.pyplot as plt
+
+def visualize(polygons, circles):
+    fig, ax = plt.subplots(figsize=(10, 10))
+    
+    # Draw polygon boundaries
+    for poly in polygons:
+        closed = np.vstack([poly, poly[0]])
+        ax.plot(closed[:, 0], closed[:, 1], 'k-', linewidth=2)
+    
+    # Draw circles
+    for x, y, r in circles:
+        ax.add_patch(plt.Circle((x, y), r, fill=True, alpha=0.7))
+    
+    ax.set_aspect('equal')
+    ax.autoscale_view()
+    plt.show()
+
+visualize([square], circles)
+```
+
+## Generator Mode
+
+For large packings or progress tracking, use the generator:
+
+```python
+packer = CirclePacker([polygon])
+
+for i, (x, y, r) in enumerate(packer.generate()):
+    print(f"Placed circle {i}: radius {r:.2f}")
+    
+    if i >= 100:  # Stop early
+        break
+```
+
+## Performance Tips
+
+- **Increase `sample_batch_size`** for denser packings (more candidates per iteration)
+- **Decrease `max_failed_attempts`** if you're okay with slightly less dense results
+- **Increase `grid_resolution_divisor`** for polygons with many small circles
+- **Use `fixed_radius`** when you know the circle size—avoids max-radius computation
+
+## Requirements
+
+- Python 3.8+
+- NumPy ≥ 1.20
+
+## License
+
+MIT

diskpack-0.1.0/README.md

@@ -0,0 +1,212 @@
+# diskpack
+
+A Python library for packing circles within arbitrary polygon boundaries.
+
+![Circle packing example](https://via.placeholder.com/600x400?text=Circle+Packing+Example)
+
+## Installation
+
+```bash
+pip install git+https://github.com/semajyllek/diskpack.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/semajyllek/diskpack.git
+cd diskpack
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from diskpack import CirclePacker, PackingConfig
+
+# Define a polygon (list of [x, y] vertices)
+square = np.array([
+    [0, 0],
+    [100, 0],
+    [100, 100],
+    [0, 100]
+])
+
+# Pack circles
+packer = CirclePacker([square])
+circles = packer.pack()
+
+# Each circle is (x, y, radius)
+for x, y, r in circles[:5]:
+    print(f"Circle at ({x:.1f}, {y:.1f}) with radius {r:.1f}")
+```
+
+## How It Works
+
+The algorithm uses a **greedy random sampling** approach:
+
+1. **Sample** random points within the polygon's bounding box
+2. **Filter** to keep only points inside the polygon (using the even-odd rule)
+3. **Compute** the maximum radius at each point without overlapping boundaries or existing circles
+4. **Place** the largest valid circle from each batch
+5. **Repeat** until no more circles can be placed
+
+### Key Techniques
+
+**Even-Odd Rule for Point-in-Polygon**
+
+To determine if a point is inside a polygon (including polygons with holes), we cast a ray from the point and count edge crossings. An odd count means inside, even means outside.
+
+**Spatial Indexing**
+
+Checking every existing circle for collisions is O(n) per placement. We use a grid-based spatial index to only check nearby circles, bringing average-case down to O(1).
+
+Large circles that span multiple grid cells are stored separately as "mega circles" and always checked—this prevents missed collisions at cell boundaries.
+
+**Distance Calculations**
+
+The maximum radius at any point is the minimum of:
+- Distance to the nearest polygon edge
+- Distance to the nearest existing circle's boundary
+
+We subtract a configurable padding to prevent circles from touching.
+
+## Configuration
+
+Customize the packing behavior with `PackingConfig`:
+
+```python
+from diskpack import PackingConfig
+
+config = PackingConfig(
+    padding=1.5,                  # Gap between circles and boundaries
+    min_radius=1.0,               # Smallest circle to place
+    max_failed_attempts=200,      # Stop after this many failed attempts
+    sample_batch_size=50,         # Points sampled per iteration
+    grid_resolution_divisor=25,   # Controls spatial index cell size
+    mega_circle_threshold=0.5,    # Radius/cell_size ratio for "mega" circles
+)
+
+packer = CirclePacker([polygon], config)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `padding` | 1.5 | Minimum gap between circles and between circles and edges |
+| `min_radius` | 1.0 | Circles smaller than this won't be placed |
+| `max_failed_attempts` | 200 | Algorithm stops after this many consecutive failed placements |
+| `sample_batch_size` | 50 | Number of random points tested per iteration |
+| `grid_resolution_divisor` | 25 | Higher = smaller grid cells = more memory, faster lookups |
+| `mega_circle_threshold` | 0.5 | Circles with radius > cell_size × this value are tracked globally |
+
+## Progress Tracking
+
+Monitor the packing process with `verbose=True`:
+
+```python
+packer = CirclePacker([polygon], config)
+circles = packer.pack(verbose=True)
+```
+
+Output:
+```
+Placed: 25 | Failed attempts: 0/200 (0%)
+Placed: 50 | Failed attempts: 0/200 (0%)
+Placed: 75 | Failed attempts: 0/200 (0%)
+Placed: 75 | Failed attempts: 50/200 (25%)
+...
+Done! Placed: 82 | Failed attempts: 200/200 (100%)
+```
+
+You can also check progress after packing:
+
+```python
+print(packer.progress)
+# Placed: 82 | Failed attempts: 200/200 (100%)
+```
+
+## Fixed-Radius Mode
+
+Pack circles of uniform size:
+
+```python
+circles = packer.pack(fixed_radius=5.0)
+```
+
+## Complex Polygons
+
+The library handles concave polygons and multiple polygon boundaries:
+
+```python
+# Star shape
+angles = np.linspace(0, 2 * np.pi, 11)[:-1]
+star = []
+for i, a in enumerate(angles):
+    r = 100 if i % 2 == 0 else 40
+    star.append([r * np.cos(a), r * np.sin(a)])
+
+packer = CirclePacker([np.array(star)])
+circles = packer.pack()
+```
+
+```python
+# Multiple boundaries (e.g., polygon with a hole)
+outer = np.array([[0, 0], [100, 0], [100, 100], [0, 100]])
+inner = np.array([[40, 40], [60, 40], [60, 60], [40, 60]])  # hole
+
+packer = CirclePacker([outer, inner])
+```
+
+## Visualization
+
+```python
+import matplotlib.pyplot as plt
+
+def visualize(polygons, circles):
+    fig, ax = plt.subplots(figsize=(10, 10))
+    
+    # Draw polygon boundaries
+    for poly in polygons:
+        closed = np.vstack([poly, poly[0]])
+        ax.plot(closed[:, 0], closed[:, 1], 'k-', linewidth=2)
+    
+    # Draw circles
+    for x, y, r in circles:
+        ax.add_patch(plt.Circle((x, y), r, fill=True, alpha=0.7))
+    
+    ax.set_aspect('equal')
+    ax.autoscale_view()
+    plt.show()
+
+visualize([square], circles)
+```
+
+## Generator Mode
+
+For large packings or progress tracking, use the generator:
+
+```python
+packer = CirclePacker([polygon])
+
+for i, (x, y, r) in enumerate(packer.generate()):
+    print(f"Placed circle {i}: radius {r:.2f}")
+    
+    if i >= 100:  # Stop early
+        break
+```
+
+## Performance Tips
+
+- **Increase `sample_batch_size`** for denser packings (more candidates per iteration)
+- **Decrease `max_failed_attempts`** if you're okay with slightly less dense results
+- **Increase `grid_resolution_divisor`** for polygons with many small circles
+- **Use `fixed_radius`** when you know the circle size—avoids max-radius computation
+
+## Requirements
+
+- Python 3.8+
+- NumPy ≥ 1.20
+
+## License
+
+MIT

diskpack-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "diskpack"
+version = "0.1.0"
+authors = [{ name="James Kelly", email="mrkellyjam@gmail.com" }]
+description = "A high-performance vectorized circle packer with spatial hashing."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "numpy>=1.20",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

diskpack-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

diskpack-0.1.0/src/diskpack/__init__.py

@@ -0,0 +1,3 @@
+from .packer import CirclePacker, PackingConfig, PackingProgress
+
+__all__ = ["CirclePacker", "PackingConfig", "PackingProgress"]

diskpack-0.1.0/src/diskpack/packer.py

@@ -0,0 +1,208 @@
+import numpy as np
+from dataclasses import dataclass, field
+from typing import List, Optional, Iterator, Tuple, Dict
+
+# Type aliases
+Polygon = np.ndarray
+Point = np.ndarray
+GridKey = Tuple[int, int]
+Circle = Tuple[float, float, float]
+
+
+@dataclass
+class PackingConfig:
+    """Configuration parameters for the circle packing algorithm."""
+    padding: float = 1.5
+    min_radius: float = 1.0
+    grid_resolution_divisor: float = 25
+    max_failed_attempts: int = 200
+    mega_circle_threshold: float = 0.5
+    ray_cast_epsilon: float = 1e-10
+    sample_batch_size: int = 50
+
+
+@dataclass
+class PackingProgress:
+    """Tracks the current state of the packing algorithm."""
+    circles_placed: int = 0
+    failed_attempts: int = 0
+    max_failed_attempts: int = 200
+    
+    @property
+    def progress_ratio(self) -> float:
+        """How close we are to stopping (0.0 = just started, 1.0 = about to stop)."""
+        return self.failed_attempts / self.max_failed_attempts
+    
+    def __str__(self) -> str:
+        return f"Placed: {self.circles_placed} | Failed attempts: {self.failed_attempts}/{self.max_failed_attempts} ({self.progress_ratio:.0%})"
+
+
+class PolygonGeometry:
+    """Handles geometric calculations for polygon boundaries."""
+
+    def __init__(self, polygons: List[Polygon], epsilon: float = 1e-10):
+        self.polygons = [np.array(p, dtype=float) for p in polygons]
+        self.epsilon = epsilon
+        self._compute_bounds()
+
+    def _compute_bounds(self) -> None:
+        all_vertices = np.vstack(self.polygons)
+        self.min_coords = np.min(all_vertices, axis=0)
+        self.max_coords = np.max(all_vertices, axis=0)
+
+    def contains_points(self, points: np.ndarray) -> np.ndarray:
+        """Even-Odd Rule for interior detection, supports holes."""
+        x, y = points[:, 0], points[:, 1]
+        inside = np.zeros(len(points), dtype=bool)
+
+        for poly in self.polygons:
+            n = len(poly)
+            for i in range(n):
+                p1, p2 = poly[i], poly[(i + 1) % n]
+                crosses_edge = (p1[1] > y) != (p2[1] > y)
+                dy = p2[1] - p1[1] + self.epsilon
+                x_intercept = (p2[0] - p1[0]) * (y - p1[1]) / dy + p1[0]
+                inside ^= crosses_edge & (x < x_intercept)
+
+        return inside
+
+    def distance_to_boundary(self, point: Point) -> float:
+        min_distance = float('inf')
+        for poly in self.polygons:
+            for i in range(len(poly)):
+                p1, p2 = poly[i], poly[(i + 1) % len(poly)]
+                min_distance = min(min_distance, self._point_to_segment_distance(point, p1, p2))
+        return min_distance
+
+    @staticmethod
+    def _point_to_segment_distance(point: Point, seg_start: Point, seg_end: Point) -> float:
+        segment_vec = seg_end - seg_start
+        segment_length_sq = np.sum(segment_vec ** 2)
+        if segment_length_sq == 0:
+            return np.linalg.norm(point - seg_start)
+        t = np.clip(np.dot(point - seg_start, segment_vec) / segment_length_sq, 0, 1)
+        projection = seg_start + t * segment_vec
+        return np.linalg.norm(point - projection)
+
+
+@dataclass
+class SpatialIndex:
+    """Grid-based spatial index for efficient collision detection."""
+    cell_size: float
+    origin: np.ndarray
+    mega_threshold: float
+    grid: Dict[GridKey, List[int]] = field(default_factory=dict)
+    mega_circles: List[int] = field(default_factory=list)
+
+    def add_circle(self, index: int, center: Point, radius: float) -> None:
+        if radius > self.cell_size * self.mega_threshold:
+            self.mega_circles.append(index)
+        else:
+            key = self._get_cell_key(center)
+            self.grid.setdefault(key, []).append(index)
+
+    def get_nearby_indices(self, point: Point) -> Iterator[int]:
+        yield from self.mega_circles
+        center_key = self._get_cell_key(point)
+        for dx in range(-1, 2):
+            for dy in range(-1, 2):
+                neighbor_key = (center_key[0] + dx, center_key[1] + dy)
+                if neighbor_key in self.grid:
+                    yield from self.grid[neighbor_key]
+
+    def _get_cell_key(self, point: Point) -> GridKey:
+        cell_coords = ((point - self.origin) // self.cell_size).astype(int)
+        return (int(cell_coords[0]), int(cell_coords[1]))
+
+
+class CirclePacker:
+    """Packs circles within polygon boundaries using random sampling."""
+
+    def __init__(self, polygons: List[Polygon], config: Optional[PackingConfig] = None):
+        self.config = config or PackingConfig()
+        self.geometry = PolygonGeometry(polygons, self.config.ray_cast_epsilon)
+        self.centers: List[Point] = []
+        self.radii: List[float] = []
+        self.progress = PackingProgress(max_failed_attempts=self.config.max_failed_attempts)
+
+        extent = max(self.geometry.max_coords - self.geometry.min_coords)
+        cell_size = extent / self.config.grid_resolution_divisor
+        self.spatial_index = SpatialIndex(
+            cell_size=cell_size,
+            origin=self.geometry.min_coords,
+            mega_threshold=self.config.mega_circle_threshold
+        )
+
+    def _sample_candidate_points(self, count: int) -> np.ndarray:
+        points = np.random.uniform(
+            self.geometry.min_coords,
+            self.geometry.max_coords,
+            size=(count, 2)
+        )
+        return points[self.geometry.contains_points(points)]
+
+    def _compute_max_radius(self, point: Point) -> float:
+        max_radius = self.geometry.distance_to_boundary(point)
+        for idx in self.spatial_index.get_nearby_indices(point):
+            distance_to_circle = np.linalg.norm(self.centers[idx] - point) - self.radii[idx]
+            max_radius = min(max_radius, distance_to_circle)
+        return max_radius - self.config.padding
+
+    def _find_best_placement(self, candidates: np.ndarray, fixed_radius: Optional[float]) -> Optional[Tuple[Point, float]]:
+        best_point, best_radius = None, 0
+        for point in candidates:
+            radius = self._compute_max_radius(point)
+            if fixed_radius is not None:
+                radius = fixed_radius if radius >= fixed_radius else -1
+            if radius > best_radius:
+                best_point, best_radius = point, radius
+
+        if best_point is not None and best_radius >= self.config.min_radius:
+            return best_point, best_radius
+        return None
+
+    def _place_circle(self, center: Point, radius: float) -> None:
+        idx = len(self.centers)
+        self.centers.append(center)
+        self.radii.append(radius)
+        self.spatial_index.add_circle(idx, center, radius)
+
+    def generate(self, fixed_radius: Optional[float] = None, verbose: bool = False) -> Iterator[Circle]:
+        """
+        Generate circles until no more can be placed.
+        
+        Args:
+            fixed_radius: If provided, all circles will have this exact radius.
+            verbose: If True, print progress updates periodically.
+        
+        Yields:
+            Tuples of (x, y, radius) for each placed circle.
+        """
+        self.progress = PackingProgress(max_failed_attempts=self.config.max_failed_attempts)
+        
+        while self.progress.failed_attempts < self.config.max_failed_attempts:
+            candidates = self._sample_candidate_points(self.config.sample_batch_size)
+            result = self._find_best_placement(candidates, fixed_radius)
+            
+            if result is not None:
+                center, radius = result
+                self._place_circle(center, radius)
+                self.progress.circles_placed += 1
+                self.progress.failed_attempts = 0
+                
+                if verbose and self.progress.circles_placed % 25 == 0:
+                    print(self.progress)
+                
+                yield (float(center[0]), float(center[1]), float(radius))
+            else:
+                self.progress.failed_attempts += 1
+                
+                if verbose and self.progress.failed_attempts % 50 == 0:
+                    print(self.progress)
+
+        if verbose:
+            print(f"Done! {self.progress}")
+
+    def pack(self, fixed_radius: Optional[float] = None, verbose: bool = False) -> List[Circle]:
+        """Pack circles and return them as a list."""
+        return list(self.generate(fixed_radius, verbose=verbose))

diskpack-0.1.0/src/diskpack.egg-info/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.1
+Name: diskpack
+Version: 0.1.0
+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
+
+# diskpack
+
+A Python library for packing circles within arbitrary polygon boundaries.
+
+![Circle packing example](https://via.placeholder.com/600x400?text=Circle+Packing+Example)
+
+## Installation
+
+```bash
+pip install git+https://github.com/semajyllek/diskpack.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/semajyllek/diskpack.git
+cd diskpack
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from diskpack import CirclePacker, PackingConfig
+
+# Define a polygon (list of [x, y] vertices)
+square = np.array([
+    [0, 0],
+    [100, 0],
+    [100, 100],
+    [0, 100]
+])
+
+# Pack circles
+packer = CirclePacker([square])
+circles = packer.pack()
+
+# Each circle is (x, y, radius)
+for x, y, r in circles[:5]:
+    print(f"Circle at ({x:.1f}, {y:.1f}) with radius {r:.1f}")
+```
+
+## How It Works
+
+The algorithm uses a **greedy random sampling** approach:
+
+1. **Sample** random points within the polygon's bounding box
+2. **Filter** to keep only points inside the polygon (using the even-odd rule)
+3. **Compute** the maximum radius at each point without overlapping boundaries or existing circles
+4. **Place** the largest valid circle from each batch
+5. **Repeat** until no more circles can be placed
+
+### Key Techniques
+
+**Even-Odd Rule for Point-in-Polygon**
+
+To determine if a point is inside a polygon (including polygons with holes), we cast a ray from the point and count edge crossings. An odd count means inside, even means outside.
+
+**Spatial Indexing**
+
+Checking every existing circle for collisions is O(n) per placement. We use a grid-based spatial index to only check nearby circles, bringing average-case down to O(1).
+
+Large circles that span multiple grid cells are stored separately as "mega circles" and always checked—this prevents missed collisions at cell boundaries.
+
+**Distance Calculations**
+
+The maximum radius at any point is the minimum of:
+- Distance to the nearest polygon edge
+- Distance to the nearest existing circle's boundary
+
+We subtract a configurable padding to prevent circles from touching.
+
+## Configuration
+
+Customize the packing behavior with `PackingConfig`:
+
+```python
+from diskpack import PackingConfig
+
+config = PackingConfig(
+    padding=1.5,                  # Gap between circles and boundaries
+    min_radius=1.0,               # Smallest circle to place
+    max_failed_attempts=200,      # Stop after this many failed attempts
+    sample_batch_size=50,         # Points sampled per iteration
+    grid_resolution_divisor=25,   # Controls spatial index cell size
+    mega_circle_threshold=0.5,    # Radius/cell_size ratio for "mega" circles
+)
+
+packer = CirclePacker([polygon], config)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `padding` | 1.5 | Minimum gap between circles and between circles and edges |
+| `min_radius` | 1.0 | Circles smaller than this won't be placed |
+| `max_failed_attempts` | 200 | Algorithm stops after this many consecutive failed placements |
+| `sample_batch_size` | 50 | Number of random points tested per iteration |
+| `grid_resolution_divisor` | 25 | Higher = smaller grid cells = more memory, faster lookups |
+| `mega_circle_threshold` | 0.5 | Circles with radius > cell_size × this value are tracked globally |
+
+## Progress Tracking
+
+Monitor the packing process with `verbose=True`:
+
+```python
+packer = CirclePacker([polygon], config)
+circles = packer.pack(verbose=True)
+```
+
+Output:
+```
+Placed: 25 | Failed attempts: 0/200 (0%)
+Placed: 50 | Failed attempts: 0/200 (0%)
+Placed: 75 | Failed attempts: 0/200 (0%)
+Placed: 75 | Failed attempts: 50/200 (25%)
+...
+Done! Placed: 82 | Failed attempts: 200/200 (100%)
+```
+
+You can also check progress after packing:
+
+```python
+print(packer.progress)
+# Placed: 82 | Failed attempts: 200/200 (100%)
+```
+
+## Fixed-Radius Mode
+
+Pack circles of uniform size:
+
+```python
+circles = packer.pack(fixed_radius=5.0)
+```
+
+## Complex Polygons
+
+The library handles concave polygons and multiple polygon boundaries:
+
+```python
+# Star shape
+angles = np.linspace(0, 2 * np.pi, 11)[:-1]
+star = []
+for i, a in enumerate(angles):
+    r = 100 if i % 2 == 0 else 40
+    star.append([r * np.cos(a), r * np.sin(a)])
+
+packer = CirclePacker([np.array(star)])
+circles = packer.pack()
+```
+
+```python
+# Multiple boundaries (e.g., polygon with a hole)
+outer = np.array([[0, 0], [100, 0], [100, 100], [0, 100]])
+inner = np.array([[40, 40], [60, 40], [60, 60], [40, 60]])  # hole
+
+packer = CirclePacker([outer, inner])
+```
+
+## Visualization
+
+```python
+import matplotlib.pyplot as plt
+
+def visualize(polygons, circles):
+    fig, ax = plt.subplots(figsize=(10, 10))
+    
+    # Draw polygon boundaries
+    for poly in polygons:
+        closed = np.vstack([poly, poly[0]])
+        ax.plot(closed[:, 0], closed[:, 1], 'k-', linewidth=2)
+    
+    # Draw circles
+    for x, y, r in circles:
+        ax.add_patch(plt.Circle((x, y), r, fill=True, alpha=0.7))
+    
+    ax.set_aspect('equal')
+    ax.autoscale_view()
+    plt.show()
+
+visualize([square], circles)
+```
+
+## Generator Mode
+
+For large packings or progress tracking, use the generator:
+
+```python
+packer = CirclePacker([polygon])
+
+for i, (x, y, r) in enumerate(packer.generate()):
+    print(f"Placed circle {i}: radius {r:.2f}")
+    
+    if i >= 100:  # Stop early
+        break
+```
+
+## Performance Tips
+
+- **Increase `sample_batch_size`** for denser packings (more candidates per iteration)
+- **Decrease `max_failed_attempts`** if you're okay with slightly less dense results
+- **Increase `grid_resolution_divisor`** for polygons with many small circles
+- **Use `fixed_radius`** when you know the circle size—avoids max-radius computation
+
+## Requirements
+
+- Python 3.8+
+- NumPy ≥ 1.20
+
+## License
+
+MIT

diskpack-0.1.0/src/diskpack.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/diskpack/__init__.py
+src/diskpack/packer.py
+src/diskpack.egg-info/PKG-INFO
+src/diskpack.egg-info/SOURCES.txt
+src/diskpack.egg-info/dependency_links.txt
+src/diskpack.egg-info/requires.txt
+src/diskpack.egg-info/top_level.txt
+tests/tests.py

diskpack-0.1.0/src/diskpack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

diskpack-0.1.0/src/diskpack.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.20

diskpack-0.1.0/src/diskpack.egg-info/top_level.txt

@@ -0,0 +1 @@
+diskpack

diskpack-0.1.0/tests/tests.py

@@ -0,0 +1,75 @@
+import unittest
+import numpy as np
+from diskpack.packer import CirclePacker, PackingConfig, PolygonGeometry
+
+
+
+class TestCirclePacker(unittest.TestCase):
+    def setUp(self):
+        """Set up a simple 10x10 square for testing."""
+        self.square_verts = np.array([[0, 0], [10, 0], [10, 10], [0, 10]])
+        self.square = [self.square_verts]
+        # Use small padding/min_radius to allow for dense filling
+        self.config = PackingConfig(padding=0.1, min_radius=0.5, patience_before_stop=100)
+
+    def _calculate_poly_area(self, segments: list) -> float:
+        """Calculates area of polygons (including holes) using the Shoelace Formula."""
+        total_area = 0
+        for poly in segments:
+            x = poly[:, 0]
+            y = poly[:, 1]
+            # Area = 0.5 * |sum(x_i * y_{i+1} - x_{i+1} * y_i)|
+            area = 0.5 * np.abs(np.dot(x, np.roll(y, 1)) - np.dot(y, np.roll(x, 1)))
+            # If it's a hole (clockwise), it naturally subtracts if we don't use abs here,
+            # but since our parser handles holes via Even-Odd, we treat all as positive 
+            # and subtract holes manually if needed. For this test, we assume shells.
+            total_area += area
+        return total_area
+
+    def test_filling_density(self):
+        """Verify that the packer fills a minimum percentage of the polygon area."""
+        packer = CirclePacker(self.square, self.config)
+        circles = list(packer.generate())
+        
+        # Calculate areas
+        poly_area = self._calculate_poly_area(self.square)
+        circle_area = sum(np.pi * (r**2) for _, _, r in circles)
+        
+        fill_percentage = (circle_area / poly_area) * 100
+        
+        print(f"\nFill Analysis: {len(circles)} circles placed.")
+        print(f"Total Area: {poly_area:.2f} | Circle Area: {circle_area:.2f}")
+        print(f"Packing Density: {fill_percentage:.2f}%")
+        
+        # Assert a minimum density threshold. 
+        # For a random packer, 30-50% is a reasonable 'success' floor depending on radius.
+        self.assertGreater(fill_percentage, 25.0, f"Packing density too low: {fill_percentage:.2f}%")
+
+    def test_geometry_containment(self):
+        """Verify the Even-Odd rule correctly identifies the interior."""
+        geo = PolygonGeometry(self.square)
+        test_pts = np.array([
+            [5, 5],   # Center
+            [15, 5],  # Far outside
+            [-1, -1]  # Outside
+        ])
+        results = geo.contains_points(test_pts)
+        self.assertTrue(results[0])
+        self.assertFalse(results[1])
+        self.assertFalse(results[2])
+
+    def test_no_overlap_integrity(self):
+        """Mathematically verify no circles overlap including padding."""
+        packer = CirclePacker(self.square, self.config)
+        circles = list(packer.generate())
+        
+        for i, (x1, y1, r1) in enumerate(circles):
+            for j, (x2, y2, r2) in enumerate(circles):
+                if i == j: continue
+                dist = np.sqrt((x1 - x2)**2 + (y1 - y2)**2)
+                # Distance must be >= sum of radii + padding
+                min_sep = r1 + r2 + self.config.padding
+                self.assertGreaterEqual(dist, min_sep - 1e-9)
+
+if __name__ == '__main__':
+    unittest.main()