graph-graphics 0.0.1__py3-none-any.whl

graph_graphics-0.0.1.dist-info/licenses/LICENSING.md

@@ -0,0 +1,30 @@
+# Licensing and commercial permissions
+
+Required Notice: Copyright (c) 2022-2026 Johannes Pippidis Lorentzen (https://pippidis.no), for project-owned code.
+
+## Code: PolyForm Noncommercial 1.0.0
+
+Project-owned Python code, scripts and website implementation are licensed under [PolyForm Noncommercial 1.0.0](LICENSE). This permits use, modification and redistribution for the purposes described in that licence, with its notice requirements. The unchanged [official text](https://polyformproject.org/licenses/noncommercial/1.0.0) governs.
+
+Permitted purposes include non-commercial use, the specified personal uses, and use by the charitable, educational, public research, public safety/health, environmental and government organisations identified in the licence. Those organisational permissions apply regardless of their funding. This is source-available software, not an unrestricted open-source licence.
+
+## Artwork and documentation: CC BY-NC 4.0
+
+Project-owned supplied artwork, scene illustrations and written documentation are licensed under [Creative Commons Attribution-NonCommercial 4.0 International](LICENSE-ARTWORK). Sharing and adaptation are permitted for non-commercial purposes, subject to attribution and the other licence terms. Credit Johannes Pippidis Lorentzen and graph_ics, link the licence, and indicate changes when required. The [official legal code](https://creativecommons.org/licenses/by-nc/4.0/legalcode) governs.
+
+The artwork licence does not replace the PolyForm licence on code appearing in examples or used to generate the artwork. The two licences apply to different material; they are not alternatives from which users may choose for the same code.
+
+## Commercial permissions
+
+For commercial use not permitted by the applicable licence, contact [Johannes Pippidis Lorentzen](https://pippidis.no) to discuss a separate paid commercial licence. Payment alone does not grant permission; a separate agreement is required.
+
+The copyright holder retains ownership and may use their own material commercially or license it under other terms. This does not waive other contributors' or data providers' rights. Neither licence should be described as a blanket prohibition on all uses by companies; the actual permitted-purpose clauses control.
+
+## Third-party material and generated output
+
+- Bundled WorldPop data remains CC BY 4.0, and Natural Earth boundaries remain public domain. Preserve the existing [source and attribution notices](src/data/README.md).
+- Dependencies and third-party assets retain their own licences. This notice does not relicense them or claim ownership of user-supplied inputs.
+- Running the generator does not automatically place every user-created output under the artwork licence. Rights in an output depend on the copyrighted artwork, data and other material it incorporates. The software licence governs permitted use of the generator itself.
+- These terms apply to the current version insofar as the copyright holder has the rights to license it. They do not withdraw permissions already granted for earlier GPL-distributed versions. Third-party contributions require compatible rights or permission before relicensing.
+
+Package metadata lists both licences because the distribution contains code and documentation; this scope statement explains which applies to each.

graph_graphics-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+graph_ics

graph_ics/__init__.py

@@ -0,0 +1,46 @@
+from .logo import make_logo, make_icon
+from .scene import SceneConfig
+from .color_fields import ColorField, ColorRamp
+from .samples import Example, build_example, describe_example, example_names
+from .validation import ValidationReport, validate_graph
+from .replay import EventLog, EventRecorder, Playback, ReplayState
+from .animation import ReplayRenderer, LiveGrowth
+from .text import Text, MeasuredText
+from .styles import GraphStyle
+from .colonies import Colony, Interaction, ColonySettings, ColonyPopulation, ColonyReport
+from .quality import AngleSettings, QualityReport
+from .obj import Obj
+from .vector import Vector
+from .node import Node, NodeShape, NODE_SHAPES
+from .edge import Edge, EdgeStyle, EDGE_STYLES
+from .graph import Graph
+from .rendering import export_graph
+from .growth import GrowthGenerator, GrowthSettings, GrowthStatus, GrowthPolicy, RandomFrontier, NewestTip, Addition, Completion, StepResult, Join
+from .fields import ScalarField, ConstantField, CallableField, ImageField, SpatialFields
+
+from .contours import RegionSpec, Readability, ContourSettings, ContourReport, DistanceField, LocalWidth
+
+from .coverage import CoverageSettings, CoverageReport
+
+__all__ = ['Obj', 'Vector', 'Node', 'Edge', 'Graph', 'export_graph']
+__all__ += ['GrowthGenerator', 'GrowthSettings', 'GrowthStatus', 'GrowthPolicy', 'RandomFrontier', 'NewestTip', 'Addition', 'Completion', 'StepResult']
+__all__ += ["ScalarField", "ConstantField", "CallableField", "ImageField", "SpatialFields"]
+
+__all__ += ["RegionSpec", "Readability", "ContourSettings", "ContourReport", "DistanceField", "LocalWidth"]
+
+__all__ += ["CoverageSettings", "CoverageReport"]
+
+__all__ += ["AngleSettings", "QualityReport"]
+
+__all__ += ["Colony", "Interaction", "ColonySettings", "ColonyPopulation", "ColonyReport", "Join"]
+
+__all__ += ["Text", "MeasuredText", "GraphStyle"]
+
+__all__ += ["EventLog", "EventRecorder", "Playback", "ReplayState", "ReplayRenderer", "LiveGrowth"]
+
+__all__ += ["Example", "build_example", "describe_example", "example_names", "ValidationReport", "validate_graph"]
+
+
+__all__ += ["NodeShape", "NODE_SHAPES", "EdgeStyle", "EDGE_STYLES"]
+
+__all__ += ['make_icon', 'make_logo', 'SceneConfig', 'ColorField', 'ColorRamp']

graph_ics/__main__.py

@@ -0,0 +1,4 @@
+"""Support python -m graph_ics."""
+from .cli import main
+
+raise SystemExit(main())

graph_ics/animation.py

@@ -0,0 +1,232 @@
+"""Cached replay rendering, PNG sequences, and bounded live generation."""
+from __future__ import annotations
+from math import ceil, isfinite
+from pathlib import Path
+from time import perf_counter
+from typing import TYPE_CHECKING, Literal
+from shapely.geometry import Polygon, MultiPolygon, shape
+from .colors import rgb_normalized
+from .rendering import draw_node, draw_edge
+from .replay import EventLog, EventRecorder, Playback, ReplayState
+from .growth import StepResult
+if TYPE_CHECKING:
+    import cairo
+    from .graph import Graph
+
+
+class ReplayRenderer:
+    """Cache completed edge/node paths separately, preserving static draw order."""
+    def __init__(self, playback: Playback, *, margin: float = 5, scale: float = 1, background: str | None = None,
+                 frame: Literal['region', 'artwork'] = 'region') -> None:
+        try:
+            import cairo
+        except ImportError as error:
+            raise ImportError('Install graph-ics[render] to render animation') from error
+        if not isfinite(margin) or margin < 0 or not isfinite(scale) or scale <= 0: raise ValueError('Require finite margin >= 0 and scale > 0')
+        if frame not in ('region', 'artwork'): raise ValueError('Unknown animation frame')
+        if scale < playback.log.scene.minimum_scale: raise ValueError('Animation scale is below the contour readability scale')
+        if background is not None: rgb_normalized(background)
+        self.playback, self.margin, self.scale, self.background, self.frame = playback, margin, scale, background, frame
+        region = shape(playback.log.scene.region)
+        if not isinstance(region, (Polygon, MultiPolygon)): raise ValueError('Replay region must be polygonal')
+        self.region: Polygon | MultiPolygon = region
+        final = playback.log.validate()
+        bounds = [node.bounds for node in final.nodes.values()]+[edge.footprint.bounds for edge in final.edges]+[text.bounds for text in playback.log.scene.texts]
+        if frame == 'region': bounds.append(self.region.bounds)
+        if playback.log.scene.border: bounds.append(self.region.buffer(float(playback.log.scene.configuration.get('border_width', 0.5))/2).bounds)
+        if not bounds: raise ValueError('Cannot frame empty artwork')
+        self.bounds = min(b[0] for b in bounds), min(b[1] for b in bounds), max(b[2] for b in bounds), max(b[3] for b in bounds)
+        self.width = max(1, ceil((self.bounds[2]-self.bounds[0]+2*margin)*scale))
+        self.height = max(1, ceil((self.bounds[3]-self.bounds[1]+2*margin)*scale))
+        self.cached_events = 0
+        self.cache_rebuilds = 0
+        self._reset_cache()
+        self.overlay = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, None)
+        context = cairo.Context(self.overlay)
+        self._draw_overlay(context)
+
+    def _draw_overlay(self, context: cairo.Context[cairo.RecordingSurface] | cairo.Context[cairo.ImageSurface]) -> None:
+        import cairo
+        if self.playback.log.scene.border:
+            context.set_source_rgba(*rgb_normalized(self.playback.log.scene.configuration.get('border_color', '#a6a6a6')), 1)
+            context.set_line_width(self.playback.log.scene.configuration.get('border_width', 0.5))
+            context.set_line_join(cairo.LINE_JOIN_ROUND)
+            polygons = [self.region] if isinstance(self.region, Polygon) else self.region.geoms
+            for polygon in polygons:
+                for ring in [polygon.exterior, *polygon.interiors]:
+                    for i, (x, y) in enumerate(ring.coords):
+                        if i == 0: context.move_to(x, y)
+                        else: context.line_to(x, y)
+                    context.close_path()
+            context.stroke()
+        for text in self.playback.log.scene.texts:
+            context.new_path()
+            for kind, points in text.path:
+                if kind == 0: context.move_to(*points)
+                elif kind == 1: context.line_to(*points)
+                elif kind == 2: context.curve_to(*points)
+                elif kind == 3: context.close_path()
+                else: raise ValueError('Unknown text path command')
+            context.set_source_rgba(*rgb_normalized(text.color), text.opacity)
+            context.fill()
+
+    def _reset_cache(self) -> None:
+        import cairo
+        self.state = ReplayState()
+        self.edge_cache = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, None)
+        self.node_cache = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, None)
+        self.cached_events = 0
+        self.cache_rebuilds += 1
+
+    def update(self, log: EventLog) -> None:
+        """Append a live recording without changing its clock or fixed viewport."""
+        if self.frame != 'region': raise ValueError('Live updates require a fixed region frame')
+        old = self.playback.log
+        if log.scene != old.scene or log.events[:len(old.events)] != old.events: raise ValueError('Live replay updates must extend the same log')
+        replacement = Playback(log, seconds_per_event=self.playback.seconds_per_event, speed=self.playback.speed)
+        replacement.seek(self.playback.position)
+        replacement.paused = self.playback.paused
+        self.playback = replacement
+
+    def _sync(self, index: int) -> None:
+        import cairo
+        if index < self.cached_events: self._reset_cache()
+        for event in self.playback.events[self.cached_events:index]:
+            self.state.apply(event)
+            if event.kind in ('branch', 'loop', 'join'): draw_edge(self.state.edges[-1], cairo.Context(self.edge_cache))
+            if event.node is not None: draw_node(self.state.nodes[event.node.id], cairo.Context(self.node_cache))
+            if event.kind == 'remove':
+                self.node_cache = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, None)
+                context = cairo.Context(self.node_cache)
+                for node in self.state.nodes.values(): draw_node(node, context)
+        self.cached_events = index
+
+    def render(self, seconds: float | None = None) -> cairo.ImageSurface:
+        import cairo
+        if seconds is not None: self.playback.seek(seconds)
+        index, progress = self.playback.cursor()
+        self._sync(index)
+        surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, self.width, self.height)
+        context = cairo.Context(surface)
+        if self.background is not None:
+            context.set_source_rgb(*rgb_normalized(self.background))
+            context.paint()
+        context.scale(self.scale, self.scale)
+        context.translate(self.margin-self.bounds[0], self.margin-self.bounds[1])
+        if index == len(self.playback.events):
+            # Render the completed scene directly to avoid extra compositing-rounding in the caches.
+            for edge in self.state.edges: draw_edge(edge, context)
+            for node in self.state.nodes.values(): draw_node(node, context)
+            self._draw_overlay(context)
+            surface.flush()
+            return surface
+        context.set_source_surface(self.edge_cache)
+        context.paint()
+        event = self.playback.events[index] if index < len(self.playback.events) else None
+        if event is not None and event.edge is not None and progress > 0:
+            nodes = dict(self.state.nodes)
+            if event.node is not None: nodes[event.node.id] = event.node.restore()
+            edge = event.edge.restore(nodes)
+            fraction = min(1, progress/0.75) if event.kind == 'branch' else progress
+            # Reveal the actual styled edge through a growing rectangular clip.
+            # Drawing a temporary solid segment would lose dash/dot/double styling.
+            context.save()
+            x, y = edge.start_point.x, edge.start_point.y
+            dx, dy = -edge.nx, -edge.ny
+            end_x, end_y = x+dx*edge.length*fraction, y+dy*edge.length*fraction
+            half = edge.thickness/2+1
+            context.new_path()
+            context.move_to(x-dy*half, y+dx*half)
+            context.line_to(end_x-dy*half, end_y+dx*half)
+            context.line_to(end_x+dy*half, end_y-dx*half)
+            context.line_to(x+dy*half, y-dx*half)
+            context.close_path()
+            context.clip()
+            draw_edge(edge, context)
+            context.restore()
+        context.set_source_surface(self.node_cache)
+        context.paint()
+        if event is not None and event.node is not None:
+            opacity = max(0, (progress-0.75)/0.25) if event.kind == 'branch' else progress
+            if opacity > 0:
+                node = event.node.restore()
+                node.opacity *= opacity
+                draw_node(node, context)
+        context.set_source_surface(self.overlay)
+        context.paint()
+        surface.flush()
+        return surface
+
+    def export_gif(self, path: str | Path, *, fps: float = 20, max_frames: int = 500, max_pixels: int = 100_000_000) -> Path:
+        """Export an opaque looping GIF; reject excessive frame storage before rendering."""
+        from io import BytesIO
+        from PIL import Image
+        if not isfinite(fps) or not 0 < fps <= 100 or type(max_frames) is not int or max_frames < 1: raise ValueError('GIF requires 0 < fps <= 100 and a positive frame cap')
+        count = ceil(self.playback.duration*fps)+1
+        if count > max_frames or count*self.width*self.height > max_pixels: raise ValueError('GIF exceeds frame/pixel budget; reduce scale, fps or event duration')
+        destination = Path(path)
+        if destination.suffix.lower() != '.gif': raise ValueError('GIF output must end in .gif')
+        if destination.exists(): raise FileExistsError(destination)
+        if self.background is None: raise ValueError('GIF requires an opaque background; use PNG frames for alpha')
+        frames: list[Image.Image] = []
+        position = self.playback.position
+        try:
+            for index in range(count):
+                stream = BytesIO()
+                self.render(min(index/fps, self.playback.duration)).write_to_png(stream)
+                stream.seek(0)
+                with Image.open(stream) as image: frames.append(image.convert('RGB'))
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            frames[0].save(destination, save_all=True, append_images=frames[1:], duration=[max(10, round(100/fps)*10)]*(count-1)+[1500], loop=0)
+        finally:
+            self.playback.seek(position)
+            for frame in frames: frame.close()
+        return destination
+
+    def export_sequence(self, directory: str | Path, *, fps: float = 24, max_frames: int = 10000) -> tuple[Path, ...]:
+        if not isfinite(fps) or fps <= 0 or type(max_frames) is not int or max_frames < 1: raise ValueError('Require positive fps and frame limit')
+        count = ceil(self.playback.duration*fps)+1
+        if count > max_frames: raise ValueError('Sequence exceeds frame limit; reduce fps or event duration')
+        output = Path(directory)
+        paths = tuple(output/f'frame_{index:06d}.png' for index in range(count))
+        if any(path.exists() for path in paths): raise FileExistsError('Frame sequence destination already contains output frames')
+        output.mkdir(parents=True, exist_ok=True)
+        position = self.playback.position
+        try:
+            for index, path in enumerate(paths): self.render(min(index/fps, self.playback.duration)).write_to_png(str(path))
+        finally:
+            self.playback.seek(position)
+        return paths
+
+
+class LiveGrowth:
+    """Pause/resume generation in this process; optional recording is independent."""
+    def __init__(self, graph: Graph, *, record: bool = True, path: str | Path | None = None, retain: bool = True) -> None:
+        if not record and path is not None: raise ValueError('A recording destination requires recording')
+        self.graph = graph
+        self.generator = graph.growth()
+        self.recorder = EventRecorder(graph, path=path, retain=retain) if record else None
+        self.paused = False
+
+    def pause(self) -> None:
+        self.paused = True
+
+    def resume(self) -> None:
+        self.paused = False
+
+    def tick(self, max_attempts: int = 100, *, time_budget_ms: float | None = None) -> tuple[StepResult, ...]:
+        if type(max_attempts) is not int or max_attempts <= 0: raise ValueError('Attempt budget must be a positive integer')
+        if time_budget_ms is not None and (not isfinite(time_budget_ms) or time_budget_ms < 0): raise ValueError('Time budget must be finite and nonnegative')
+        if self.paused or self.generator.done: return ()
+        if time_budget_ms is None: return (self.generator.step(max_attempts),)
+        deadline = perf_counter()+time_budget_ms/1000
+        results: list[StepResult] = []
+        used = 0
+        while not self.generator.done and used < max_attempts and perf_counter() < deadline:
+            result = self.generator.step(1)
+            results.append(result)
+            used += result.attempts
+        return tuple(results)
+
+    def close(self) -> None:
+        if self.recorder is not None: self.recorder.close()

graph_ics/cli.py

@@ -0,0 +1,121 @@
+"""Command-line entry points using the same documented Python example factories."""
+from __future__ import annotations
+import argparse
+from dataclasses import asdict
+from pathlib import Path
+import json
+import sys
+from math import isfinite
+from .samples import EXAMPLES, build_example, describe_example, example_names, explain_option
+from .styles import GraphStyle
+from .rendering import export_graph
+from .replay import EventRecorder, EventLog, Playback
+from .animation import ReplayRenderer
+from .gallery import generate_gallery
+from .validation import validate_graph
+from .node import NODE_SHAPES
+from .edge import EDGE_STYLES
+from .quality import AngleSettings
+from .scene import SceneConfig
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog='graph-ics', description='Generate sprawling graph artwork, explained examples, and replay frames.')
+    commands = root.add_subparsers(dest='command', required=True)
+    commands.add_parser('list', help='List examples and palettes')
+    describe = commands.add_parser('describe', help='Explain an example and the controls it demonstrates')
+    describe.add_argument('example', choices=example_names())
+    for name in ('render', 'frames'):
+        command = commands.add_parser(name, help='Export SVG/PNG' if name == 'render' else 'Export replay PNG sequence', formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        command.add_argument('--fill-area', action='store_true', help='Keep searching underfilled space; --nodes is a safety cap, not a completion claim')
+        command.add_argument('--config', type=Path, help='Load a complete JSON/YAML scene; geometry comes from this file')
+        for option in ('node-inner-radius','node-outer-radius','node-buffer','edge-thickness','edge-node-distance','edge-length-min','edge-length-max'):
+            command.add_argument('--'+option, type=float, help='Override '+option.replace('-', ' ')+' in world units; see the visual dimensions guide')
+        command.add_argument('--example', choices=example_names(), default='typography', help='Recipe to build; describe NAME explains its settings')
+        command.add_argument('--palette', choices=GraphStyle.palette_names(), default='arctic', help='Named colour scheme for nodes, lines, text and background')
+        command.add_argument('--seed', type=int, default=7, help='Random seed; repeat it to reproduce geometry')
+        command.add_argument('--nodes', type=int, help='Requested total nodes, including seeds; packing can stop below this target')
+        command.add_argument('--output', type=Path, required=True, help='PNG/SVG file for render, or a new directory for frames')
+        command.add_argument('--scale', type=float, default=1, help='Output units per world unit; changes resolution, not growth')
+        command.add_argument('--margin', type=float, default=16, help='Empty margin around the region in world units')
+        command.add_argument('--transparent', action='store_true', help='Omit the palette background; preserve alpha')
+        command.add_argument('--node-shape', choices=NODE_SHAPES, help='Hollow shape inside the reserved node radius')
+        command.add_argument('--edge-style', choices=EDGE_STYLES, help='Stroke pattern inside the reserved connection corridor')
+        command.add_argument('--minimum-angle', type=float, help='Hard minimum between incident edges, in degrees (0 to 180)')
+        command.add_argument('--preferred-angle', type=float, help='Preferred junction angle in degrees; enables a soft target')
+        command.add_argument('--angle-penalty', type=float, help='Rejection strength below the preferred angle (0 to 1)')
+        if name == 'render':
+            command.add_argument('--record', type=Path, help='Also save replay JSONL')
+            command.add_argument('--force', action='store_true', help='Replace an existing output/recording')
+        else:
+            command.add_argument('--gif', action='store_true', help='Export one looping GIF instead of PNG frames; requires an opaque background')
+            command.add_argument('--log', type=Path, help='Replay a saved log instead of building an example')
+            command.add_argument('--fps', type=float, default=24, help='Frames per second; higher values sample the same replay more often')
+            command.add_argument('--seconds-per-event', type=float, default=0.04, help='Seconds allocated to each recorded event; larger values slow growth')
+            command.add_argument('--max-frames', type=int, default=10000, help='Safety limit: reject an export requiring more frames')
+    gallery = commands.add_parser('gallery', help='Generate the explained visual sample library', formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    gallery.add_argument('--output', type=Path, default=Path('docs'), help='Gallery directory; index.html sits above figures/ and controls.html')
+    selection = gallery.add_mutually_exclusive_group()
+    selection.add_argument('--all-palettes', action='store_true', help='Expand every regular recipe across all ten palettes')
+    selection.add_argument('--quick', action='store_true', help='Six small scenes for a smoke check')
+    return root
+
+
+def main(argv: list[str] | None = None) -> int:
+    tokens = sys.argv[1:] if argv is None else argv
+    args = parser().parse_args(tokens)
+    try:
+        if args.command == 'list':
+            print('Palettes: '+', '.join(GraphStyle.palette_names()))
+            for example in EXAMPLES: print(f'{example.name}: {example.title} ({example.target_nodes} target nodes)')
+            return 0
+        if args.command == 'describe':
+            print(json.dumps(dict(asdict(describe_example(args.example)), option_notes={option: explain_option(option) for option in describe_example(args.example).options}), indent=2))
+            return 0
+        if args.command == 'gallery':
+            path = generate_gallery(args.output, quick=args.quick, all_palettes=args.all_palettes).resolve()
+            print('Gallery: '+str(path))
+            print('Open: '+path.as_uri())
+            return 0
+        if not isfinite(args.scale) or args.scale <= 0 or not isfinite(args.margin) or args.margin < 0: raise ValueError('Require finite positive scale and nonnegative margin')
+        if args.command == 'frames' and (not isfinite(args.fps) or args.fps <= 0 or not isfinite(args.seconds_per_event) or args.seconds_per_event <= 0 or args.max_frames <= 0): raise ValueError('Frame rate, event duration, and frame cap must be positive')
+        overrides = {name: getattr(args,name) for name in ('node_inner_radius','node_outer_radius','node_buffer','edge_thickness','edge_node_distance','edge_length_min','edge_length_max') if getattr(args,name) is not None}
+        if args.config and any(token.split('=',1)[0] in ('--example','--palette','--seed') for token in tokens): raise ValueError('Put example-independent colours and seed in the scene when using --config')
+        scene = SceneConfig.load(args.config) if args.config else None
+        if scene and (args.fill_area or overrides or any(value is not None for value in (args.node_shape,args.edge_style,args.minimum_angle,args.preferred_angle,args.angle_penalty,args.nodes))): raise ValueError('Put geometry overrides inside the scene when using --config')
+        background = None if args.transparent else scene.background if scene else GraphStyle.named(args.palette).background
+        if args.command == 'frames' and args.log is not None:
+            if args.config or overrides or args.fill_area: raise ValueError('Cannot rebuild a saved log with config or dimension overrides')
+            if any(value is not None for value in (args.node_shape, args.edge_style, args.minimum_angle, args.preferred_angle, args.angle_penalty)):
+                raise ValueError('Saved logs preserve shapes, lines and angles; omit geometry overrides with --log')
+            log = EventLog.load(args.log)
+        else:
+            if args.command == 'render':
+                if args.output.suffix.lower() not in ('.png', '.svg'): raise ValueError('Output must end in .png or .svg')
+                if args.record is not None and args.record.resolve() == args.output.resolve(): raise ValueError('Artwork and replay log need distinct paths')
+                for path in (args.output, args.record):
+                    if path is not None and path.exists() and not args.force: raise FileExistsError(f'{path} exists; use --force to replace')
+            graph = scene.graph if scene else build_example(args.example, fill_area=args.fill_area, style_overrides=overrides, palette=args.palette, seed=args.seed, nodes=args.nodes, node_shape=args.node_shape, edge_style=args.edge_style)
+            if any(value is not None for value in (args.minimum_angle, args.preferred_angle, args.angle_penalty)):
+                graph.angles = AngleSettings(args.minimum_angle if args.minimum_angle is not None else graph.angles.minimum,
+                                            args.preferred_angle if args.preferred_angle is not None else graph.angles.preferred,
+                                            args.angle_penalty if args.angle_penalty is not None else graph.angles.penalty)
+            if args.command == 'frames' or args.record is not None:
+                with EventRecorder(graph, path=args.record if args.command == 'render' else None) as recorder: graph.build()
+                log = recorder.snapshot()
+            else: graph.build()
+            validate_graph(graph)
+            if args.command == 'render':
+                dimensions = export_graph(graph, args.output, scale=args.scale, margin=args.margin, frame='region', background=background)
+                print(json.dumps(dict(output=str(args.output), dimensions=dimensions, nodes=len(graph.nodes), attempts=graph.growth().attempts, status=graph.growth().status.value, coverage=asdict(graph.growth().coverage_report()) if graph.growth().coverage else None)))
+                return 0
+        renderer = ReplayRenderer(Playback(log, seconds_per_event=args.seconds_per_event), scale=args.scale, margin=args.margin, background=background)
+        if args.gif:
+            print(renderer.export_gif(args.output, fps=args.fps, max_frames=args.max_frames))
+            return 0
+        paths = renderer.export_sequence(args.output, fps=args.fps, max_frames=args.max_frames)
+        print(f'{len(paths)} frames: {args.output}')
+        return 0
+    except (ValueError, OSError, ImportError) as error:
+        print(f'graph-ics: {error}', file=sys.stderr)
+        return 2

graph_ics/colonies.py

@@ -0,0 +1,145 @@
+"""Explicit colony ownership, symmetric interactions, and spatial diagnostics."""
+from __future__ import annotations
+from dataclasses import dataclass
+from math import atan2, cos, sin, isfinite
+from typing import TYPE_CHECKING
+import networkx as nx
+from shapely.geometry import Point
+from .colors import hex2rgb
+from .node import Node
+from .edge import Edge
+if TYPE_CHECKING:
+    from .graph import Graph
+
+
+@dataclass(frozen=True)
+class Colony:
+    id: str
+    seeds: tuple[tuple[float, float], ...]
+    weight: float = 1
+    color: str = '#a6b7c8'
+
+    def __post_init__(self) -> None:
+        if not self.id or not self.seeds: raise ValueError('Colony needs an ID and at least one seed')
+        if not isfinite(self.weight) or self.weight <= 0: raise ValueError('Weight must be finite and positive')
+        if not all(isfinite(x) and isfinite(y) for x, y in self.seeds): raise ValueError('Seed positions must be finite')
+        hex2rgb(self.color)
+
+
+@dataclass(frozen=True)
+class Interaction:
+    first: str
+    second: str
+    attraction: float = 0  # [-1, 1]: avoidance through attraction; independent of joining.
+    allow_join: bool = False
+    clearance: float = 0  # Minimum distance between visible rival geometry.
+
+    def __post_init__(self) -> None:
+        if not self.first or not self.second or self.first == self.second: raise ValueError('Interactions require two distinct colony IDs')
+        if not isfinite(self.attraction) or not -1 <= self.attraction <= 1: raise ValueError('Attraction must be between -1 and 1')
+        if type(self.allow_join) is not bool: raise ValueError('Join permission must be boolean')
+        if not isfinite(self.clearance) or self.clearance < 0: raise ValueError('Clearance must be finite and nonnegative')
+        if self.allow_join and self.clearance: raise ValueError('Joining and rival exclusion are mutually exclusive for a pair')
+
+
+@dataclass(frozen=True)
+class ColonySettings:
+    colonies: tuple[Colony, ...]
+    interactions: tuple[Interaction, ...] = ()
+    influence_distance: float = 100
+    target_bridges: int = 0
+    bridge_attempts: int = 1000
+    bridge_distance: float = 40
+
+    def __post_init__(self) -> None:
+        ids = [colony.id for colony in self.colonies]
+        if not ids or len(ids) != len(set(ids)): raise ValueError('Colony IDs must be nonempty and unique')
+        if not isfinite(sum(colony.weight for colony in self.colonies)): raise ValueError('Total colony weight must be finite')
+        pairs: set[frozenset[str]] = set()
+        for rule in self.interactions:
+            pair = frozenset((rule.first, rule.second))
+            if not pair.issubset(ids) or pair in pairs: raise ValueError('Unknown or duplicate interaction pair')
+            pairs.add(pair)
+        for value in (self.influence_distance, self.bridge_distance):
+            if not isfinite(value) or value <= 0: raise ValueError('Interaction distances must be finite and positive')
+        for value in (self.target_bridges, self.bridge_attempts):
+            if type(value) is not int or value < 0: raise ValueError('Bridge limits must be nonnegative integers')
+
+    def rule(self, first: str | None, second: str | None) -> Interaction | None:
+        return next((rule for rule in self.interactions if {rule.first, rule.second} == {first, second}), None)
+
+    def bias(self, graph: Graph, parent: Node, angle: float) -> float:
+        radius = self.influence_distance
+        x, y = parent.center.x, parent.center.y
+        nearby = [graph._objects[key] for key in graph._index.query((x-radius, y-radius, x+radius, y+radius))]
+        candidates = [n for n in nearby if isinstance(n, Node) and n.colony_id != parent.colony_id and n.distance_to(parent) <= radius
+                      and (rule := self.rule(parent.colony_id, n.colony_id)) is not None and rule.attraction != 0]
+        if not candidates: return angle
+        target = min(candidates, key=lambda n: (n.distance_to(parent), n.id))
+        rule = self.rule(parent.colony_id, target.colony_id)
+        assert rule is not None
+        direction = atan2(target.center.y-y, target.center.x-x)
+        strength = abs(rule.attraction)
+        dx, dy = (1-strength)*cos(angle)+rule.attraction*cos(direction), (1-strength)*sin(angle)+rule.attraction*sin(direction)
+        return atan2(dy, dx) if abs(dx)+abs(dy) > 1e-12 else angle
+
+
+def owners(obj: Node | Edge) -> set[str]:
+    ids = (obj.colony_id,) if isinstance(obj, Node) else (obj.start_node.colony_id, obj.end_node.colony_id)
+    return {key for key in ids if key is not None}
+
+
+def visible_distance(first: Node | Edge, second: Node | Edge) -> float:
+    if isinstance(first, Node) and isinstance(second, Node): return first.distance_to(second)-first.outer_radius-second.outer_radius
+    if isinstance(first, Node):
+        assert isinstance(second, Edge)
+        return float(second.footprint.distance(first.center))-first.outer_radius
+    if isinstance(second, Node): return float(first.footprint.distance(second.center))-second.outer_radius
+    return float(first.footprint.distance(second.footprint))
+
+
+def rival_clearance(settings: ColonySettings, first: Node | Edge, second: Node | Edge) -> float:
+    return max((rule.clearance for a in owners(first) for b in owners(second) if a != b and (rule := settings.rule(a, b)) is not None), default=0)
+
+
+@dataclass(frozen=True)
+class ColonyPopulation:
+    colony_id: str
+    nodes: int
+    attempts: int
+    accepted: int
+    rejected: int
+    components: int
+    territory_fraction: float
+
+
+@dataclass(frozen=True)
+class ColonyReport:
+    populations: tuple[ColonyPopulation, ...]
+    components: int
+    bridges: int
+    bridge_attempts: int
+    bridge_shortfall: int
+    clearance_rejections: int
+    territory_samples: int
+
+
+def territory_counts(graph: Graph, resolution: int) -> tuple[dict[str, int], int]:
+    """Nearest-center allocation of a deterministic grid of usable region samples."""
+    if type(resolution) is not int or not 1 <= resolution <= 200: raise ValueError('Territory resolution must be 1..200')
+    counts: dict[str, int] = {}
+    samples = 0
+    if not graph.nodes: return counts, samples
+    x0, y0, x1, y1 = graph.outline_polygon.bounds
+    for row in range(resolution):
+        for column in range(resolution):
+            point = Point(x0+(column+0.5)*(x1-x0)/resolution, y0+(row+0.5)*(y1-y0)/resolution)
+            if not graph.outline_polygon.covers(point) or any(area.covers(point) for area in graph._illegal_areas): continue
+            nearest = min(graph.nodes, key=lambda n: (n.center.distance(point), n.id))
+            if nearest.colony_id is not None: counts[nearest.colony_id] = counts.get(nearest.colony_id, 0)+1
+            samples += 1
+    return counts, samples
+
+
+def component_ids(graph: Graph) -> dict[str, str]:
+    return {key: min(component) for component in nx.connected_components(graph.to_networkx()) for key in component}

graph_ics/color_fields.py

@@ -0,0 +1,29 @@
+"""Spatial colour ramps sampled independently of geometry density."""
+from dataclasses import dataclass
+from typing import Protocol
+from math import isfinite
+from .fields import ScalarField
+from .colors import hex2rgb
+
+
+class ColorField(Protocol):
+    def sample(self, x: float, y: float) -> str: ...
+
+
+@dataclass(frozen=True)
+class ColorRamp:
+    field: ScalarField
+    colors: tuple[str, ...] = ('#284d68', '#eead64', '#a64152')
+
+    def __post_init__(self) -> None:
+        if len(self.colors) < 2: raise ValueError('Colour ramps need at least two stops')
+        for color in self.colors: hex2rgb(color)
+
+    def sample(self, x: float, y: float) -> str:
+        value = self.field.sample(x, y)
+        if not isfinite(value): raise ValueError('Colour field must return finite values')
+        position = min(1, max(0, value))*(len(self.colors)-1)
+        index = min(len(self.colors)-2, int(position))
+        fraction = position-index
+        left, right = hex2rgb(self.colors[index]), hex2rgb(self.colors[index+1])
+        return '#'+''.join(f'{round(a+(b-a)*fraction):02x}' for a,b in zip(left,right))

graph_ics/colors.py

@@ -0,0 +1,17 @@
+"""Minimal color parsing without importing a plotting library."""
+
+
+def hex2rgb(color: str) -> tuple[int, int, int]:
+    """Parse six hexadecimal digits, optionally prefixed by '#', into byte channels.
+
+    Raises ValueError for malformed input. Use rgb_normalized for drawing.
+    """
+    digits = color.removeprefix('#')
+    if len(digits) != 6: raise ValueError('Expected a six-digit hexadecimal color')
+    return int(digits[:2], 16), int(digits[2:4], 16), int(digits[4:], 16)
+
+
+def rgb_normalized(color: str) -> tuple[float, float, float]:
+    """Return Cairo-compatible channels in the closed interval [0, 1]."""
+    red, green, blue = hex2rgb(color)
+    return red/255, green/255, blue/255