Guide chapters

Scene files

Save a complete composition in JSON or YAML, including geometry, maps, text and boundary styling. Use these files as reproducible starting points.

Run a saved scene

graph-ics render --config docs/scenes/area-fill.json --output examples/output/area-fill.png

JSON and YAML describe the same scene schema. Paths to boundary files resolve relative to the scene file. Unknown keys are rejected so misspelled options are not silently ignored.

Text Hug

Glyph exclusion: branches can enter spaces between letters and sufficiently large letter holes.

650 nodes of 650 requested. Stop: target_reached. 227/240 occupied tiles; 97.9% of tile area has a node. This is a coarse coverage measure, not solid ink coverage.

JSON scene · YAML scene · SVG

Settings and command

graph-ics render --config docs/scenes/text-hug.yaml --output examples/output/text-hug.png

{
  "version": 1,
  "palette": "porcelain",
  "width": 600,
  "height": 360,
  "nodes": 650,
  "seed": 7,
  "growth": {
    "total_attempts": 35000,
    "refill_passes": 2,
    "coverage": {
      "tile_size": 30,
      "reseed_attempts": 1200
    }
  },
  "texts": [
    {
      "content": "graph_ics",
      "x": 300,
      "y": 210,
      "size": 95,
      "align": "center",
      "bold": true,
      "padding": 2,
      "color": "#a64152",
      "exclusion_mode": "glyph"
    }
  ]
}

Colour Gradient

A continuous colour field, sampled at node centres and edge midpoints. It does not alter geometry.

650 nodes of 650 requested. Stop: target_reached. 240/240 occupied tiles; 100.0% of tile area has a node. This is a coarse coverage measure, not solid ink coverage.

JSON scene · YAML scene · SVG

Settings and command

graph-ics render --config docs/scenes/colour-gradient.yaml --output examples/output/colour-gradient.png

{
  "version": 1,
  "palette": "porcelain",
  "width": 600,
  "height": 360,
  "nodes": 650,
  "seed": 7,
  "growth": {
    "total_attempts": 35000,
    "refill_passes": 2,
    "coverage": {
      "tile_size": 30,
      "reseed_attempts": 1200
    }
  },
  "color_map": {
    "field": {
      "kind": "gradient",
      "axis": "x"
    },
    "colors": [
      "#246b87",
      "#e7b96d",
      "#a64152"
    ]
  }
}

Area Fill

Area fill searches beyond the requested local tile populations; the node count is a safety cap. Compare stop reason and tile coverage, not just count.

816 nodes of 2200 requested. Stop: attempt_budget_exhausted. 346/360 occupied tiles; 98.4% of tile area has a node. This is a coarse coverage measure, not solid ink coverage.

JSON scene · YAML scene · SVG

Settings and command

graph-ics render --config docs/scenes/area-fill.yaml --output examples/output/area-fill.png

{
  "version": 1,
  "palette": "porcelain",
  "width": 600,
  "height": 360,
  "nodes": 2200,
  "seed": 7,
  "growth": {
    "fill_area": true,
    "total_attempts": 100000,
    "refill_passes": 1,
    "refill_attempts": 10000,
    "coverage": {
      "tile_size": 25,
      "reseed_attempts": 3000
    }
  }
}

Complete scene schema and field definitions