polyforge 0.1.0a1__py3-none-any.whl

polyforge/__init__.py

@@ -0,0 +1,154 @@
+"""Polyforge - Polygon processing and manipulation library.
+
+This library provides utilities for processing, simplifying, and manipulating
+polygon geometries using Shapely.
+"""
+
+__version__ = "0.1.0a1"
+
+# Simplification functions
+from .simplify import (
+    simplify_rdp,
+    simplify_vw,
+    simplify_vwp,
+    collapse_short_edges,
+    deduplicate_vertices,
+    remove_small_holes,
+    remove_narrow_holes,
+)
+
+# Clearance fixing functions
+from .clearance import (
+    fix_clearance,
+    fix_hole_too_close,
+    fix_narrow_protrusion,
+    remove_narrow_protrusions,
+    fix_sharp_intrusion,
+    fix_narrow_passage,
+    fix_near_self_intersection,
+    fix_parallel_close_edges,
+)
+
+# Overlap handling functions
+from .overlap import (
+    split_overlap,
+    remove_overlaps,
+    count_overlaps,
+    find_overlapping_groups,
+    resolve_overlap_pair,
+)
+
+# Merge functions
+from .merge import merge_close_polygons
+
+# Topology functions
+from .topology import align_boundaries
+
+# Geometry repair functions
+from .repair import (
+    repair_geometry,
+    analyze_geometry,
+    batch_repair_geometries,
+)
+
+# Robust constraint-aware repair
+from .repair.robust import (
+    robust_fix_geometry,
+    robust_fix_batch,
+)
+
+# Core types (enums)
+from .core import (
+    OverlapStrategy,
+    MergeStrategy,
+    RepairStrategy,
+    CollapseMode,
+)
+
+# Core exceptions
+from .core import (
+    PolyforgeError,
+    ValidationError,
+    RepairError,
+    OverlapResolutionError,
+    MergeError,
+    ClearanceError,
+    ConfigurationError,
+    FixWarning,
+)
+
+# Constraint framework
+from .core import (
+    GeometryConstraints,
+    ConstraintStatus,
+    ConstraintViolation,
+    ConstraintType,
+    MergeConstraints,
+)
+
+__all__ = [
+
+    # Simplification
+    'simplify_rdp',
+    'simplify_vw',
+    'simplify_vwp',
+    'collapse_short_edges',
+    'deduplicate_vertices',
+    'remove_small_holes',
+    'remove_narrow_holes',
+
+    # Clearance fixing
+    'fix_clearance',
+    'fix_hole_too_close',
+    'fix_narrow_protrusion',
+    'remove_narrow_protrusions',
+    'fix_sharp_intrusion',
+    'fix_narrow_passage',
+    'fix_near_self_intersection',
+    'fix_parallel_close_edges',
+
+    # Overlap handling
+    'split_overlap',
+    'remove_overlaps',
+    'count_overlaps',
+    'find_overlapping_groups',
+    'resolve_overlap_pair',
+
+    # Merge
+    'merge_close_polygons',
+
+    # Topology
+    'align_boundaries',
+
+    # Geometry repair
+    'repair_geometry',
+    'analyze_geometry',
+    'batch_repair_geometries',
+
+    # Robust constraint-aware repair
+    'robust_fix_geometry',
+    'robust_fix_batch',
+
+    # Core types (enums)
+    'OverlapStrategy',
+    'MergeStrategy',
+    'RepairStrategy',
+    'CollapseMode',
+
+    # Core exceptions
+    'PolyforgeError',
+    'ValidationError',
+    'RepairError',
+    'OverlapResolutionError',
+    'MergeError',
+    'ClearanceError',
+    'ConfigurationError',
+    'FixWarning',
+
+    # Constraint framework
+    'GeometryConstraints',
+    'ConstraintStatus',
+    'ConstraintViolation',
+    'ConstraintType',
+    'MergeConstraints',
+]

polyforge/clearance/__init__.py

@@ -0,0 +1,62 @@
+"""Geometry clearance fixing functions.
+
+This module provides functions for fixing geometries with low minimum clearance
+by applying minimal geometric modifications. Each function targets a specific
+type of clearance issue.
+
+The minimum_clearance (from Shapely) represents the smallest distance by which
+a vertex could be moved to create an invalid geometry. Higher values indicate
+more robust, stable geometries.
+"""
+
+# Import public API functions from the ops layer
+from polyforge.ops.clearance import (
+    fix_hole_too_close,
+    fix_narrow_protrusion,
+    fix_sharp_intrusion,
+    remove_narrow_protrusions,
+    fix_narrow_passage,
+    fix_near_self_intersection,
+    fix_parallel_close_edges,
+)
+from .fix_clearance import (
+    fix_clearance,
+    diagnose_clearance,
+    ClearanceIssue,
+    ClearanceDiagnosis,
+    ClearanceFixSummary,
+)
+
+# Import utility functions from ops
+from polyforge.ops.clearance import (
+    _find_nearest_vertex_index,
+    _find_nearest_edge_index,
+    _point_to_segment_distance,
+    _point_to_line_perpendicular_distance,
+    _get_vertex_neighborhood,
+    _calculate_curvature_at_vertex,
+    _remove_vertices_between,
+)
+
+__all__ = [
+    # Main public API
+    'fix_clearance',  # Auto-detection and fixing
+    'diagnose_clearance',  # Diagnosis without fixing
+    'ClearanceIssue',
+    'ClearanceDiagnosis',
+    'ClearanceFixSummary',
+    'fix_hole_too_close',
+    'fix_narrow_protrusion',
+    'remove_narrow_protrusions',
+    'fix_sharp_intrusion',
+    'fix_narrow_passage',
+    'fix_near_self_intersection',
+    'fix_parallel_close_edges',
+    # Utility functions (for advanced users and tests)
+    # '_find_nearest_vertex_index',
+    # '_find_nearest_edge_index',
+    # '_point_to_segment_distance',
+    # '_get_vertex_neighborhood',
+    # '_calculate_curvature_at_vertex',
+    # '_remove_vertices_between',
+]

polyforge/clearance/fix_clearance.py

@@ -0,0 +1,474 @@
+"""Automatic clearance detection and fixing.
+
+This module provides an intelligent function that automatically diagnoses
+clearance issues and applies the most appropriate fixing strategy.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, Dict, List, Optional, Tuple, Union
+import numpy as np
+import shapely
+from shapely.geometry import Polygon, MultiPolygon, Point, LineString, LinearRing
+from shapely.geometry.base import BaseGeometry
+
+from polyforge.ops.clearance import (
+    fix_hole_too_close,
+    fix_narrow_protrusion,
+    remove_narrow_protrusions,
+    fix_narrow_passage,
+    fix_near_self_intersection,
+    fix_parallel_close_edges,
+    _find_nearest_vertex_index,
+    _calculate_curvature_at_vertex,
+)
+from polyforge.core.geometry_utils import to_single_polygon
+from polyforge.core.types import HoleStrategy, PassageStrategy, IntersectionStrategy
+from polyforge.core.iterative_utils import iterative_improve
+
+
+class ClearanceIssue(Enum):
+    """Enumerates the types of clearance problems we can detect."""
+
+    NONE = "none"
+    HOLE_TOO_CLOSE = "hole_too_close"
+    NARROW_PROTRUSION = "narrow_protrusion"
+    NARROW_PASSAGE = "narrow_passage"
+    NEAR_SELF_INTERSECTION = "near_self_intersection"
+    PARALLEL_CLOSE_EDGES = "parallel_close_edges"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ClearanceDiagnosis:
+    """
+    Result of analyzing a polygon's clearance.
+
+    Attributes:
+        issue: Detected issue type.
+        meets_requirement: Whether min_clearance is already satisfied.
+        current_clearance: Measured minimum clearance.
+        clearance_ratio: current_clearance / min_clearance.
+        clearance_line: Location of the bottleneck if available.
+        recommended_fix: Name of the suggested fix function.
+    """
+
+    issue: ClearanceIssue
+    meets_requirement: bool
+    current_clearance: float
+    clearance_ratio: float
+    clearance_line: Optional[LineString]
+    recommended_fix: str
+
+    @property
+    def has_issues(self) -> bool:
+        return not self.meets_requirement
+
+
+@dataclass
+class ClearanceFixSummary:
+    """Metadata describing the fix process."""
+
+    initial_clearance: float
+    final_clearance: float
+    area_ratio: float
+    iterations: int
+    issue: ClearanceIssue
+    fixed: bool
+    valid: bool
+    history: List[ClearanceIssue]
+
+
+def fix_clearance(
+    geometry: Polygon,
+    min_clearance: float,
+    max_iterations: int = 10,
+    min_area_ratio: float = 0.9,
+    return_diagnosis: bool = False,
+) -> Union[Polygon, Tuple[Polygon, ClearanceFixSummary]]:
+    """Automatically diagnose and fix low minimum clearance in a polygon."""
+    if not isinstance(geometry, Polygon):
+        raise TypeError(f"Expected Polygon, got {type(geometry).__name__}")
+
+    if min_area_ratio <= 0 or min_area_ratio > 1.0:
+        raise ValueError("min_area_ratio must be in (0, 1].")
+
+    initial_clearance = geometry.minimum_clearance
+    original_area = geometry.area
+    summary = ClearanceFixSummary(
+        initial_clearance=initial_clearance,
+        final_clearance=initial_clearance,
+        area_ratio=1.0,
+        iterations=0,
+        issue=ClearanceIssue.NONE,
+        fixed=initial_clearance >= min_clearance,
+        valid=geometry.is_valid,
+        history=[ClearanceIssue.NONE],
+    )
+
+    if summary.fixed:
+        return (geometry, summary) if return_diagnosis else geometry
+
+    issue_history: List[ClearanceIssue] = []
+    best_valid = geometry
+
+    def improve(poly: Polygon, target: float) -> Optional[Polygon]:
+        diagnosis = diagnose_clearance(poly, target)
+        issue_history.append(diagnosis.issue)
+        if diagnosis.issue == ClearanceIssue.NONE:
+            return None
+        candidate = _apply_clearance_strategy(poly, target, diagnosis)
+        if candidate is None or not candidate.is_valid or candidate.is_empty:
+            return None
+        nonlocal best_valid
+        if candidate.area < min_area_ratio * original_area:
+            return None
+        if _safe_clearance(candidate) > _safe_clearance(best_valid):
+            best_valid = candidate
+        return candidate
+
+    metric = lambda poly: _safe_clearance(poly)  # noqa: E731
+    improved = iterative_improve(
+        geometry,
+        target_value=min_clearance,
+        improve_func=improve,
+        metric_func=metric,
+        max_iterations=max_iterations,
+    )
+
+    if improved is None or not improved.is_valid or improved.is_empty:
+        improved = best_valid
+    if improved.area < min_area_ratio * original_area:
+        improved = best_valid
+
+    final_clearance = _safe_clearance(improved)
+    final_area_ratio = improved.area / original_area if original_area > 0 else float("inf")
+    final_diag = diagnose_clearance(improved, min_clearance)
+    summary = ClearanceFixSummary(
+        initial_clearance=initial_clearance,
+        final_clearance=final_clearance,
+        area_ratio=final_area_ratio,
+        iterations=len(issue_history),
+        issue=final_diag.issue,
+        fixed=final_diag.meets_requirement,
+        valid=improved.is_valid,
+        history=issue_history or [final_diag.issue],
+    )
+
+    return (improved, summary) if return_diagnosis else improved
+
+
+StrategyFunc = Callable[[Polygon, float, ClearanceDiagnosis], Optional[Polygon]]
+
+RECOMMENDED_FIXES: Dict[ClearanceIssue, str] = {
+    ClearanceIssue.NONE: "none",
+    ClearanceIssue.HOLE_TOO_CLOSE: "fix_hole_too_close",
+    ClearanceIssue.NARROW_PROTRUSION: "remove_narrow_protrusions",
+    ClearanceIssue.NARROW_PASSAGE: "fix_narrow_passage",
+    ClearanceIssue.NEAR_SELF_INTERSECTION: "fix_near_self_intersection",
+    ClearanceIssue.PARALLEL_CLOSE_EDGES: "fix_parallel_close_edges",
+    ClearanceIssue.UNKNOWN: "fix_narrow_passage",
+}
+
+STRATEGY_REGISTRY: Dict[ClearanceIssue, StrategyFunc] = {}
+
+
+def _strategy(issue: ClearanceIssue) -> StrategyFunc:
+    return STRATEGY_REGISTRY.get(issue, _strategy_default)
+
+
+def _apply_clearance_strategy(
+    geometry: Polygon,
+    min_clearance: float,
+    diagnosis: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    handler = _strategy(diagnosis.issue)
+    candidate = handler(geometry, min_clearance, diagnosis)
+    return _normalize_polygon(candidate)
+
+
+def _register_strategy(issue: ClearanceIssue):
+    def decorator(func: StrategyFunc) -> StrategyFunc:
+        STRATEGY_REGISTRY[issue] = func
+        return func
+
+    return decorator
+
+
+@_register_strategy(ClearanceIssue.HOLE_TOO_CLOSE)
+def _strategy_hole_too_close(
+    geometry: Polygon,
+    min_clearance: float,
+    _: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    fixed = fix_hole_too_close(geometry, min_clearance, strategy=HoleStrategy.REMOVE)
+    return fixed
+
+
+@_register_strategy(ClearanceIssue.NARROW_PROTRUSION)
+def _strategy_narrow_protrusion(
+    geometry: Polygon,
+    min_clearance: float,
+    diagnosis: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    baseline = diagnosis.current_clearance
+    first_pass = remove_narrow_protrusions(geometry, aspect_ratio_threshold=10.0)
+    if first_pass.is_valid and _safe_clearance(first_pass) > baseline:
+        return first_pass
+    return fix_narrow_protrusion(geometry, min_clearance)
+
+
+@_register_strategy(ClearanceIssue.NARROW_PASSAGE)
+def _strategy_narrow_passage(
+    geometry: Polygon,
+    min_clearance: float,
+    _: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    return fix_narrow_passage(geometry, min_clearance, strategy=PassageStrategy.WIDEN)
+
+
+@_register_strategy(ClearanceIssue.NEAR_SELF_INTERSECTION)
+def _strategy_near_self_intersection(
+    geometry: Polygon,
+    min_clearance: float,
+    _: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    return fix_near_self_intersection(
+        geometry,
+        min_clearance,
+        strategy=IntersectionStrategy.SIMPLIFY,
+    )
+
+
+@_register_strategy(ClearanceIssue.PARALLEL_CLOSE_EDGES)
+def _strategy_parallel_edges(
+    geometry: Polygon,
+    min_clearance: float,
+    _: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    return fix_parallel_close_edges(
+        geometry,
+        min_clearance,
+        strategy=IntersectionStrategy.SIMPLIFY,
+    )
+
+
+def _strategy_default(
+    geometry: Polygon,
+    min_clearance: float,
+    _: ClearanceDiagnosis,
+) -> Optional[Polygon]:
+    return fix_narrow_passage(geometry, min_clearance, strategy=PassageStrategy.WIDEN)
+
+
+def _normalize_polygon(candidate: Optional[BaseGeometry]) -> Optional[Polygon]:
+    if candidate is None:
+        return None
+    if candidate.is_empty or not candidate.is_valid:
+        return None
+    polygon = to_single_polygon(candidate)
+    return polygon if polygon.is_valid and not polygon.is_empty else None
+
+
+def _safe_clearance(geometry: Polygon) -> float:
+    try:
+        return float(geometry.minimum_clearance)
+    except Exception:
+        return 0.0
+
+
+def _diagnose_clearance_issue(
+    geometry: Polygon,
+    min_clearance: float
+) -> ClearanceIssue:
+    """Diagnose the type of clearance issue in a polygon.
+
+    Examines the geometry's minimum_clearance_line and surrounding geometry
+    to determine what type of issue is causing low clearance.
+
+    Args:
+        geometry: Input polygon
+        min_clearance: Target minimum clearance
+
+    Returns:
+        A :class:`ClearanceIssue` describing the detected problem.
+    """
+    if _has_close_hole(geometry, min_clearance):
+        return ClearanceIssue.HOLE_TOO_CLOSE
+
+    context = _build_clearance_context(geometry)
+    if context is None:
+        return ClearanceIssue.UNKNOWN
+
+    if "hole" in context.ring_types:
+        return ClearanceIssue.HOLE_TOO_CLOSE
+
+    for heuristic in (
+        _looks_like_protrusion,
+        _looks_like_near_self_intersection,
+        _looks_like_parallel_edges,
+        _default_clearance_issue,
+    ):
+        issue = heuristic(context, min_clearance)
+        if issue is not None:
+            return issue
+    return ClearanceIssue.UNKNOWN
+
+
+def _classify_ring_types(geometry: Polygon, pt1: Tuple[float, float], pt2: Tuple[float, float]) -> Tuple[str, str]:
+    """Return ring type ('exterior' or 'hole') for each endpoint of the clearance line."""
+    def classify(point: Tuple[float, float]) -> Tuple[str, Optional[int]]:
+        p = Point(point)
+        exterior_ring = LinearRing(geometry.exterior.coords)
+        d_exterior = p.distance(exterior_ring)
+
+        min_hole_dist = float("inf")
+        hole_idx = None
+        for idx, hole in enumerate(geometry.interiors):
+            d = p.distance(LinearRing(hole.coords))
+            if d < min_hole_dist:
+                min_hole_dist = d
+                hole_idx = idx
+
+        if min_hole_dist < d_exterior:
+            return "hole", hole_idx
+        return "exterior", None
+
+    t1, _ = classify(pt1)
+    t2, _ = classify(pt2)
+    return t1, t2
+
+
+def _has_close_hole(geometry: Polygon, min_clearance: float) -> bool:
+    if not geometry.interiors:
+        return False
+    exterior_ring = LinearRing(geometry.exterior.coords)
+    for hole in geometry.interiors:
+        hole_ring = LinearRing(hole.coords)
+        if hole_ring.distance(exterior_ring) < min_clearance:
+            return True
+    return False
+
+
+def _build_clearance_context(geometry: Polygon) -> Optional["ClearanceContext"]:
+    try:
+        clearance_line = shapely.minimum_clearance_line(geometry)
+    except Exception:
+        return None
+
+    if clearance_line.is_empty:
+        return None
+
+    coords_2d = np.array(clearance_line.coords)
+    if len(coords_2d) < 2:
+        return None
+
+    pt1, pt2 = coords_2d[:2]
+    exterior_coords = np.array(geometry.exterior.coords)
+    idx1 = _find_nearest_vertex_index(exterior_coords, pt1)
+    idx2 = _find_nearest_vertex_index(exterior_coords, pt2)
+    curvature1 = _calculate_curvature_at_vertex(exterior_coords, idx1)
+    curvature2 = _calculate_curvature_at_vertex(exterior_coords, idx2)
+    n = len(exterior_coords) - 1
+    separation = min(abs(idx2 - idx1), n - abs(idx2 - idx1))
+    ring_types = _classify_ring_types(geometry, pt1, pt2)
+
+    return ClearanceContext(
+        curvature=(curvature1, curvature2),
+        separation=separation,
+        vertex_count=n,
+        ring_types=ring_types,
+    )
+
+
+@dataclass
+class ClearanceContext:
+    curvature: Tuple[float, float]
+    separation: int
+    vertex_count: int
+    ring_types: Tuple[str, str]
+
+
+def _looks_like_protrusion(context: ClearanceContext, _: float) -> Optional[ClearanceIssue]:
+    if "hole" in context.ring_types:
+        return None
+    curvature1, curvature2 = context.curvature
+    sharp_angle_threshold = 135.0
+    if curvature1 > sharp_angle_threshold or curvature2 > sharp_angle_threshold:
+        return ClearanceIssue.NARROW_PROTRUSION
+
+    if context.separation <= 3 and (curvature1 > 90 or curvature2 > 90):
+        return ClearanceIssue.NARROW_PROTRUSION
+    return None
+
+
+def _looks_like_near_self_intersection(context: ClearanceContext, _: float) -> Optional[ClearanceIssue]:
+    if "hole" in context.ring_types:
+        return None
+    if context.separation <= 3:
+        curvature1, curvature2 = context.curvature
+        if curvature1 <= 90 and curvature2 <= 90:
+            return ClearanceIssue.NEAR_SELF_INTERSECTION
+    return None
+
+
+def _looks_like_parallel_edges(context: ClearanceContext, _: float) -> Optional[ClearanceIssue]:
+    if "hole" in context.ring_types:
+        return None
+    if context.vertex_count <= 0:
+        return None
+    if context.separation >= context.vertex_count // 3:
+        return ClearanceIssue.PARALLEL_CLOSE_EDGES
+    return None
+
+
+def _default_clearance_issue(_: ClearanceContext, __: float) -> ClearanceIssue:
+    return ClearanceIssue.NARROW_PASSAGE
+
+
+def diagnose_clearance(
+    geometry: Polygon,
+    min_clearance: float
+) -> ClearanceDiagnosis:
+    """Diagnose clearance issues without fixing them."""
+    if not isinstance(geometry, Polygon):
+        raise TypeError(f"Expected Polygon, got {type(geometry).__name__}")
+
+    current_clearance = geometry.minimum_clearance
+    meets_requirement = current_clearance >= min_clearance
+    ratio = current_clearance / min_clearance if min_clearance > 0 else float("inf")
+
+    try:
+        clearance_line = shapely.minimum_clearance_line(geometry)
+    except Exception:
+        clearance_line = None
+
+    if meets_requirement:
+        return ClearanceDiagnosis(
+            issue=ClearanceIssue.NONE,
+            meets_requirement=True,
+            current_clearance=current_clearance,
+            clearance_ratio=ratio,
+            clearance_line=clearance_line,
+            recommended_fix=RECOMMENDED_FIXES[ClearanceIssue.NONE],
+        )
+
+    issue = _diagnose_clearance_issue(geometry, min_clearance)
+    recommended = RECOMMENDED_FIXES.get(issue, RECOMMENDED_FIXES[ClearanceIssue.UNKNOWN])
+    return ClearanceDiagnosis(
+        issue=issue,
+        meets_requirement=False,
+        current_clearance=current_clearance,
+        clearance_ratio=ratio,
+        clearance_line=clearance_line,
+        recommended_fix=recommended,
+    )
+
+
+__all__ = [
+    'fix_clearance',
+    'diagnose_clearance',
+    'ClearanceIssue',
+    'ClearanceDiagnosis',
+    'ClearanceFixSummary',
+]