dcel-map-generator 0.2.2__py3-none-any.whl

dcel_builder/__init__.py

@@ -0,0 +1,130 @@
+"""Tree-first recursive DCEL generation from a hierarchical zone tree."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from dcel_builder.frontend_bundle import build_frontend_bundle
+from dcel_builder.hierarchy import build_leaf_dcel_from_tree
+from dcel_builder.tree_loader import load_tree_inputs
+
+
+def _package_version() -> str:
+    try:
+        return version("dcel-map-generator")
+    except PackageNotFoundError:
+        return "0.2.2"
+
+
+__version__ = _package_version()
+
+
+def generate_map_artifacts(
+    zone_edges_path: str | Path,
+    tree_stats_path: str | Path,
+    zone_index_path: str | Path,
+    seed: int | None = None,
+    resolution: int = 512,
+    land_fraction: float = 0.40,
+    noise_exponent: float = 2.3,
+    warp_strength: float = 0.10,
+    quiet: bool = False,
+    blob_radius: float = 0.5,
+    disk_radius: int | None = None,
+    area_floor: float = 0.5,
+) -> tuple:
+    """Build the core map artifacts from a rooted zone tree."""
+    del blob_radius
+    del disk_radius
+    del area_floor
+
+    tree, tree_stats, zone_index = load_tree_inputs(
+        zone_edges_path,
+        tree_stats_path,
+        zone_index_path,
+    )
+    result = build_leaf_dcel_from_tree(
+        tree=tree,
+        seed=seed,
+        resolution=resolution,
+        land_fraction=land_fraction,
+        noise_exponent=noise_exponent,
+        warp_strength=warp_strength,
+    )
+    dcel, report = result.dcel, result.report
+    report["tree_stats_loaded"] = bool(tree_stats)
+    report["zone_index_loaded"] = bool(zone_index)
+
+    if not quiet:
+        interior = sum(1 for face in dcel.faces if not face.is_outer)
+        print(
+            f"Built recursive tree-first DCEL with {interior} leaf faces and "
+            f"{len(dcel.halfedges)} halfedges."
+        )
+
+    return dcel, report, tree, zone_index
+
+
+def generate_dcel(
+    zone_edges_path: str | Path,
+    tree_stats_path: str | Path,
+    zone_index_path: str | Path,
+    seed: int | None = None,
+    resolution: int = 512,
+    land_fraction: float = 0.40,
+    noise_exponent: float = 2.3,
+    warp_strength: float = 0.10,
+    quiet: bool = False,
+    blob_radius: float = 0.5,
+    disk_radius: int | None = None,
+    area_floor: float = 0.5,
+) -> tuple:
+    """Build a leaf-level DCEL from a rooted zone tree."""
+    dcel, report, _, _ = generate_map_artifacts(
+        zone_edges_path=zone_edges_path,
+        tree_stats_path=tree_stats_path,
+        zone_index_path=zone_index_path,
+        seed=seed,
+        resolution=resolution,
+        land_fraction=land_fraction,
+        noise_exponent=noise_exponent,
+        warp_strength=warp_strength,
+        quiet=quiet,
+        blob_radius=blob_radius,
+        disk_radius=disk_radius,
+        area_floor=area_floor,
+    )
+    return dcel, report
+
+
+def generate_frontend_bundle(
+    zone_edges_path: str | Path,
+    tree_stats_path: str | Path,
+    zone_index_path: str | Path,
+    seed: int | None = None,
+    resolution: int = 512,
+    land_fraction: float = 0.40,
+    noise_exponent: float = 2.3,
+    warp_strength: float = 0.10,
+    quiet: bool = False,
+    blob_radius: float = 0.5,
+    disk_radius: int | None = None,
+    area_floor: float = 0.5,
+) -> tuple[dict, dict]:
+    """Build a frontend-ready hierarchy bundle from a rooted zone tree."""
+    dcel, report, tree, zone_index = generate_map_artifacts(
+        zone_edges_path=zone_edges_path,
+        tree_stats_path=tree_stats_path,
+        zone_index_path=zone_index_path,
+        seed=seed,
+        resolution=resolution,
+        land_fraction=land_fraction,
+        noise_exponent=noise_exponent,
+        warp_strength=warp_strength,
+        quiet=quiet,
+        blob_radius=blob_radius,
+        disk_radius=disk_radius,
+        area_floor=area_floor,
+    )
+    return build_frontend_bundle(dcel, tree, zone_index), report

dcel_builder/__main__.py

@@ -0,0 +1,212 @@
+"""CLI entry point for dcel_builder."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate a DCEL map from a zone tree.")
+    parser.add_argument(
+        "--zone-edges",
+        default="examples/atlantis/zone_edges.json",
+        help="Path to zone tree edge-list JSON",
+    )
+    parser.add_argument(
+        "--leaf-graph",
+        default=None,
+        help="Deprecated compatibility alias for --zone-edges",
+    )
+    parser.add_argument(
+        "--tree-stats",
+        default="examples/atlantis/zone_tree_stats.json",
+        help="Path to zone tree stats JSON",
+    )
+    parser.add_argument(
+        "--zone-index",
+        default="examples/atlantis/zone_index.json",
+        help="Path to zone index JSON",
+    )
+    parser.add_argument(
+        "--output",
+        default="dcel_map.json",
+        help="Path for the output DCEL JSON",
+    )
+    parser.add_argument(
+        "--frontend-bundle",
+        default=None,
+        help="Optional path for a frontend-ready hierarchy JSON bundle",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=None,
+        help="RNG seed for reproducible generation (random if omitted)",
+    )
+    parser.add_argument(
+        "--resolution",
+        type=int,
+        default=512,
+        help="Raster grid size H×H (default: 512)",
+    )
+    parser.add_argument(
+        "--land-fraction",
+        type=float,
+        default=0.40,
+        help="Target fraction of raster pixels that are land (default: 0.40)",
+    )
+    parser.add_argument(
+        "--noise-exponent",
+        type=float,
+        default=2.3,
+        help="Power-law exponent for spectral noise (default: 2.3)",
+    )
+    parser.add_argument(
+        "--warp-strength",
+        type=float,
+        default=0.10,
+        help="Domain-warp amplitude as fraction of resolution (default: 0.10)",
+    )
+    parser.add_argument(
+        "--canvas-size",
+        type=float,
+        default=1.0,
+        help="(Retained for compatibility; has no effect on raster resolution)",
+    )
+    parser.add_argument(
+        "--blob-radius",
+        type=float,
+        default=0.5,
+        help="Gaussian blob radius for continent shape (default: 0.5)",
+    )
+    parser.add_argument(
+        "--disk-radius",
+        type=int,
+        default=None,
+        help="Reserved disk radius in pixels; auto-computed if omitted",
+    )
+    parser.add_argument(
+        "--area-floor",
+        type=float,
+        default=0.5,
+        help="Minimum fraction of target area a zone can be reduced to (default: 0.5)",
+    )
+    parser.add_argument(
+        "--validate",
+        action="store_true",
+        help="Run structural invariant checks on output before writing",
+    )
+    parser.add_argument(
+        "--render",
+        action="store_true",
+        help="Render the generated DCEL to a PNG image",
+    )
+    parser.add_argument(
+        "--render-output",
+        default="dcel_map.png",
+        help="Path for the rendered PNG when --render is used",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress progress output",
+    )
+
+    args = parser.parse_args()
+
+    # Validate new parameters
+    if args.blob_radius <= 0:
+        parser.error("--blob-radius must be > 0")
+    if args.disk_radius is not None and args.disk_radius < 1:
+        parser.error("--disk-radius must be >= 1")
+    if not (0 < args.area_floor <= 1):
+        parser.error("--area-floor must be in (0, 1]")
+
+    zone_edges_arg = args.leaf_graph or args.zone_edges
+    zone_edges_path = Path(zone_edges_arg)
+    if not zone_edges_path.exists():
+        print(f"ERROR: Input file not found: {zone_edges_path}", file=sys.stderr)
+        sys.exit(1)
+
+    from dcel_builder import generate_map_artifacts
+    from dcel_builder.frontend_bundle import build_frontend_bundle
+    from dcel_builder.serializer import to_json, validate_invariants
+
+    try:
+        if not args.quiet:
+            ignored = [
+                "--canvas-size",
+                "--blob-radius",
+                "--disk-radius",
+                "--area-floor",
+            ]
+            print(
+                "Tree-first recursive pipeline active; compatibility flags are accepted but "
+                "ignored: "
+                + ", ".join(ignored)
+            )
+        dcel, report, tree, zone_index = generate_map_artifacts(
+            zone_edges_arg,
+            args.tree_stats,
+            args.zone_index,
+            seed=args.seed,
+            resolution=args.resolution,
+            land_fraction=args.land_fraction,
+            noise_exponent=args.noise_exponent,
+            warp_strength=args.warp_strength,
+            quiet=args.quiet,
+            blob_radius=args.blob_radius,
+            disk_radius=args.disk_radius,
+            area_floor=args.area_floor,
+        )
+    except ValueError as e:
+        msg = str(e)
+        if "no valid seed" in msg.lower():
+            print(f"ERROR: Insufficient land pixels. {msg}", file=sys.stderr)
+            sys.exit(3)
+        print(f"ERROR: Invalid input. {msg}", file=sys.stderr)
+        sys.exit(2)
+
+    if args.validate:
+        if not validate_invariants(dcel):
+            print("ERROR: DCEL structural validation failed.", file=sys.stderr)
+            sys.exit(4)
+
+    data = to_json(dcel, {})
+    output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(data, indent=2))
+
+    frontend_bundle_path = None
+    if args.frontend_bundle is not None:
+        frontend_bundle = build_frontend_bundle(dcel, tree, zone_index)
+        frontend_bundle_path = Path(args.frontend_bundle)
+        frontend_bundle_path.parent.mkdir(parents=True, exist_ok=True)
+        frontend_bundle_path.write_text(json.dumps(frontend_bundle, indent=2))
+
+    render_path = None
+    if args.render:
+        from dcel_builder.render import render_dcel
+
+        render_path = Path(args.render_output)
+        render_path.parent.mkdir(parents=True, exist_ok=True)
+        render_dcel(dcel, render_path)
+
+    if not args.quiet:
+        interior = sum(1 for f in dcel.faces if not f.is_outer)
+        message = (
+            f"DCEL map written to {output_path} "
+            f"({interior} leaf faces, root {report['root_id']}, max depth {report['max_depth']})"
+        )
+        if frontend_bundle_path is not None:
+            message += f"; frontend bundle written to {frontend_bundle_path}"
+        if render_path is not None:
+            message += f"; render written to {render_path}"
+        print(message)
+
+
+if __name__ == "__main__":
+    main()

dcel_builder/dcel.py

@@ -0,0 +1,174 @@
+"""T006: DCEL data structure — Vertex, HalfEdge, Face, and DCEL container."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Vertex:
+    """A 2-D point in the DCEL map."""
+
+    x: float
+    y: float
+    incident_edge: int  # index of one outgoing half-edge
+
+
+@dataclass
+class HalfEdge:
+    """A directed half-edge in the DCEL."""
+
+    origin: int  # index of origin Vertex
+    twin: int  # index of the opposite half-edge
+    next: int  # index of next half-edge in CCW face cycle
+    prev: int  # index of previous half-edge in same cycle
+    incident_face: int  # index of face to the left of this half-edge
+
+
+@dataclass
+class Face:
+    """A polygon face in the DCEL (or the unbounded outer face)."""
+
+    outer_component: Optional[int]  # index of one bounding half-edge; None for outer
+    is_outer: bool
+    zone_id: Optional[int]  # node ID from zone_leaf_graph; None for outer
+    area: float = field(default=0.0)
+    target_area: float = field(default=0.0)
+
+
+class DCEL:
+    """Doubly-Connected Edge List container.
+
+    Holds flat lists of Vertex, HalfEdge, and Face objects.
+    Array position = implicit index for all cross-references.
+    """
+
+    def __init__(
+        self,
+        vertices: list[Vertex],
+        halfedges: list[HalfEdge],
+        faces: list[Face],
+    ) -> None:
+        self.vertices = vertices
+        self.halfedges = halfedges
+        self.faces = faces
+
+    # ------------------------------------------------------------------
+    # Structural validation
+    # ------------------------------------------------------------------
+
+    def validate(self) -> None:
+        """Check all four DCEL structural invariants.
+
+        Raises
+        ------
+        ValueError
+            Lists every violated invariant found.
+        """
+        violations: list[str] = []
+        he = self.halfedges
+
+        for i, h in enumerate(he):
+            # 1. twin.twin == self
+            if he[h.twin].twin != i:
+                violations.append(
+                    f"twin invariant violated at he[{i}]: "
+                    f"he[{h.twin}].twin = {he[h.twin].twin}, expected {i}"
+                )
+
+            # 2. next.prev == self
+            if he[h.next].prev != i:
+                violations.append(
+                    f"next.prev invariant violated at he[{i}]: "
+                    f"he[{h.next}].prev = {he[h.next].prev}, expected {i}"
+                )
+
+            # 3. twin faces differ
+            if he[h.twin].incident_face == h.incident_face:
+                violations.append(
+                    f"twin face invariant violated at he[{i}]: "
+                    f"he[{i}].incident_face == he[{h.twin}].incident_face == "
+                    f"{h.incident_face}"
+                )
+
+        # 4. Outer face must have outer_component == None
+        for j, f in enumerate(self.faces):
+            if f.is_outer and f.outer_component is not None:
+                violations.append(
+                    f"outer face invariant violated at face[{j}]: "
+                    f"outer_component should be None, got {f.outer_component}"
+                )
+
+        if violations:
+            raise ValueError("DCEL structural validation failed:\n" + "\n".join(violations))
+
+    # ------------------------------------------------------------------
+    # Geometry helpers (added in US2 / T021)
+    # ------------------------------------------------------------------
+
+    def compute_face_areas(
+        self,
+        pos: dict[int, tuple[float, float]],
+        target_map: Optional[dict[int, float]] = None,
+    ) -> None:
+        """Compute and store the polygon area for every interior face.
+
+        Uses the shoelace formula.  Results are stored in ``face.area``.
+        If *target_map* is provided (zone_id → target_area), also sets
+        ``face.target_area``.
+
+        Parameters
+        ----------
+        pos:
+            Mapping from graph node IDs to (x, y) coordinates.
+        target_map:
+            Optional mapping from zone_id to target area.
+        """
+        # Store vertex positions keyed by vertex index for quick lookup.
+        vert_pos = {i: (v.x, v.y) for i, v in enumerate(self.vertices)}
+
+        # Build a coordinate → vertex_index map
+        coord_to_vidx = {(v.x, v.y): i for i, v in enumerate(self.vertices)}
+
+        # Build vertex_index → node_id map using pos
+        vidx_to_node: dict[int, int] = {}
+        for node_id, (x, y) in pos.items():
+            key = (x, y)
+            if key in coord_to_vidx:
+                vidx_to_node[coord_to_vidx[key]] = node_id
+
+        for face_idx, face in enumerate(self.faces):
+            if face.is_outer:
+                continue
+            if face.outer_component is None:
+                continue
+
+            # Walk the half-edge boundary cycle to collect vertex coords
+            start = face.outer_component
+            coords: list[tuple[float, float]] = []
+            cur = start
+            while True:
+                v_idx = self.halfedges[cur].origin
+                coords.append(vert_pos[v_idx])
+                cur = self.halfedges[cur].next
+                if cur == start:
+                    break
+
+            # Shoelace formula
+            area = _shoelace_area(coords)
+            face.area = abs(area)
+
+            if target_map is not None and face.zone_id is not None:
+                face.target_area = target_map.get(face.zone_id, 0.0)
+
+
+def _shoelace_area(coords: list[tuple[float, float]]) -> float:
+    """Return signed area via the shoelace formula (positive = CCW)."""
+    n = len(coords)
+    s = 0.0
+    for i in range(n):
+        x0, y0 = coords[i]
+        x1, y1 = coords[(i + 1) % n]
+        s += x0 * y1 - x1 * y0
+    return s / 2.0

dcel_builder/frontend_bundle.py

@@ -0,0 +1,184 @@
+"""Build a frontend-oriented hierarchy bundle from the generated DCEL."""
+
+from __future__ import annotations
+
+from itertools import combinations
+from functools import lru_cache
+
+from shapely.geometry import GeometryCollection, LineString, MultiLineString, MultiPolygon, Polygon
+from shapely.geometry.polygon import orient
+from shapely.ops import unary_union
+
+from dcel_builder.dcel import DCEL
+from dcel_builder.geometry import face_polygon_coords
+from dcel_builder.tree_loader import ZoneTree
+
+
+def build_frontend_bundle(dcel: DCEL, tree: ZoneTree, zone_index: dict[int, str]) -> dict:
+    """Return a frontend-ready hierarchy bundle with geometry for every zone."""
+    leaf_polygons = _leaf_polygons(dcel)
+
+    @lru_cache(maxsize=None)
+    def zone_geometry(zone_id: int):
+        children = tree.children[zone_id]
+        if not children:
+            return leaf_polygons[zone_id]
+        return _normalize_geometry(unary_union([zone_geometry(child) for child in children]))
+
+    zone_geometries = {zone_id: zone_geometry(zone_id) for zone_id in sorted(tree.nodes)}
+    zones: dict[str, dict] = {}
+    for zone_id in sorted(tree.nodes):
+        geometry = zone_geometries[zone_id]
+        min_x, min_y, max_x, max_y = geometry.bounds
+        children = list(tree.children[zone_id])
+        depth = tree.depth[zone_id]
+        zones[str(zone_id)] = {
+            "id": zone_id,
+            "name": zone_index.get(zone_id, str(zone_id)),
+            "parent_id": tree.parent[zone_id],
+            "depth": depth,
+            "child_ids": children,
+            "is_leaf": not children,
+            "bbox": [min_x, min_y, max_x, max_y],
+            "area": geometry.area,
+            "path": _svg_path(geometry),
+            "children_reveal_depth": depth + 1 if children else None,
+        }
+
+    borders = _shared_borders(zone_geometries, tree)
+    levels = {
+        str(depth): [zone_id for zone_id in sorted(tree.nodes) if tree.depth[zone_id] == depth]
+        for depth in range(tree.max_depth + 1)
+    }
+    return {
+        "root_id": tree.root,
+        "max_depth": tree.max_depth,
+        "world_bbox": [0.0, 0.0, 1.0, 1.0],
+        "zoom_depth_thresholds": {
+            str(depth): float(2**depth)
+            for depth in range(tree.max_depth + 1)
+        },
+        "levels": levels,
+        "borders": borders,
+        "zones": zones,
+    }
+
+
+def _leaf_polygons(dcel: DCEL) -> dict[int, Polygon]:
+    polygons: dict[int, Polygon] = {}
+    for face in dcel.faces:
+        if face.is_outer or face.zone_id is None or face.outer_component is None:
+            continue
+        coords = face_polygon_coords(dcel, face.outer_component)
+        if len(coords) < 3:
+            raise ValueError(f"Face for zone {face.zone_id} is degenerate.")
+        polygons[face.zone_id] = orient(Polygon(coords), sign=1.0)
+    return polygons
+
+
+def _normalize_geometry(geometry):
+    if isinstance(geometry, Polygon):
+        return orient(geometry, sign=1.0)
+    if isinstance(geometry, MultiPolygon):
+        return MultiPolygon([orient(polygon, sign=1.0) for polygon in geometry.geoms])
+    raise ValueError(f"Expected polygon geometry, got {geometry.geom_type}")
+
+
+def _svg_path(geometry) -> str:
+    if isinstance(geometry, Polygon):
+        return _polygon_path(geometry)
+    if isinstance(geometry, MultiPolygon):
+        return " ".join(_polygon_path(polygon) for polygon in geometry.geoms)
+    raise ValueError(f"Expected polygon geometry, got {geometry.geom_type}")
+
+
+def _polygon_path(polygon: Polygon) -> str:
+    segments = [_ring_path(list(polygon.exterior.coords))]
+    segments.extend(_ring_path(list(interior.coords)) for interior in polygon.interiors)
+    return " ".join(segments)
+
+
+def _ring_path(coords: list[tuple[float, float]]) -> str:
+    commands = [f"M{_fmt(coords[0][0])},{_fmt(coords[0][1])}"]
+    commands.extend(f"L{_fmt(x)},{_fmt(y)}" for x, y in coords[1:])
+    commands.append("Z")
+    return " ".join(commands)
+
+
+def _fmt(value: float) -> str:
+    text = f"{value:.6f}"
+    return text.rstrip("0").rstrip(".") if "." in text else text
+
+
+def _shared_borders(zone_geometries: dict[int, Polygon | MultiPolygon], tree: ZoneTree) -> list[dict]:
+    borders: list[dict] = []
+    for left_zone, right_zone in combinations(sorted(zone_geometries), 2):
+        if _related_by_ancestry(tree, left_zone, right_zone):
+            continue
+        left_geometry = zone_geometries[left_zone]
+        right_geometry = zone_geometries[right_zone]
+        if not _bounds_intersect(left_geometry.bounds, right_geometry.bounds):
+            continue
+        shared = left_geometry.boundary.intersection(right_geometry.boundary)
+        shared_lines = _as_multiline(shared)
+        if shared_lines is None or shared_lines.length <= 1e-9:
+            continue
+        borders.append(
+            {
+                "id": f"{left_zone}:{right_zone}",
+                "zone_ids": [left_zone, right_zone],
+                "path": _line_path(shared_lines),
+            }
+        )
+    return borders
+
+
+def _related_by_ancestry(tree: ZoneTree, left_zone: int, right_zone: int) -> bool:
+    current = tree.parent[left_zone]
+    while current is not None:
+        if current == right_zone:
+            return True
+        current = tree.parent[current]
+
+    current = tree.parent[right_zone]
+    while current is not None:
+        if current == left_zone:
+            return True
+        current = tree.parent[current]
+    return False
+
+
+def _as_multiline(geometry) -> MultiLineString | None:
+    if geometry.is_empty:
+        return None
+    if isinstance(geometry, LineString):
+        return MultiLineString([geometry])
+    if isinstance(geometry, MultiLineString):
+        return geometry
+    if isinstance(geometry, GeometryCollection):
+        lines = [geom for geom in geometry.geoms if isinstance(geom, LineString) and geom.length > 0]
+        return MultiLineString(lines) if lines else None
+    return None
+
+
+def _line_path(geometry: MultiLineString) -> str:
+    commands: list[str] = []
+    for line in geometry.geoms:
+        coords = list(line.coords)
+        if len(coords) < 2:
+            continue
+        commands.append(f"M{_fmt(coords[0][0])},{_fmt(coords[0][1])}")
+        commands.extend(f"L{_fmt(x)},{_fmt(y)}" for x, y in coords[1:])
+    return " ".join(commands)
+
+
+def _bounds_intersect(
+    left_bounds: tuple[float, float, float, float],
+    right_bounds: tuple[float, float, float, float],
+) -> bool:
+    return not (
+        left_bounds[2] < right_bounds[0]
+        or right_bounds[2] < left_bounds[0]
+        or left_bounds[3] < right_bounds[1]
+        or right_bounds[3] < left_bounds[1]
+    )