Treemap Area Encoding Gate and Relative Measurement Verification in Diagram Design

The Diagram Design repository enforces treemap accuracy through a strict verification gate that validates area-share fidelity within an 8% relative tolerance and confirms all labels and markers fit inside their assigned cells.

Every treemap in the cathrynlavery/diagram-design repository must satisfy strict geometric contracts before merging. The treemap area encoding gate guarantees that visual area accurately encodes quantitative values while preventing label attribution errors through automated relative measurement verification.

Core Verification Invariants

The verification script scripts/verify-treemap.py enforces two non-negotiable invariants that protect the integrity of treemap visualizations.

Area Fidelity Check

The primary invariant ensures that area encodes value truthfully. Each <rect> element carrying a data-share attribute must have a geometric area proportional to its declared percentage of the whole.

The script parses every cell, calculates its drawn area, normalizes declared shares, and computes relative error:

area_share = cell.area / drawn_total * 100
declared   = cell.share / share_total * 100
relative   = (area_share - declared) / declared * 100

If abs(relative) > AREA_TOLERANCE (8%), the gate emits a detailed finding (e.g., cell 120×80 draws 12.34% but declares 9.80%) and exits with status 1.

Label and Marker Fit Verification

Text labels and information-marker circles must remain strictly inside their host cells to prevent silent misattribution to neighboring regions.

The script extracts <text> and <circle> elements, estimates bounding boxes using calibrated font-advance constants (MONO_ADVANCE, SANS_ADVANCE, WIDE_ADVANCE), and verifies anchor points lie within the smallest containing cell. Overflow beyond EPSILON (1px for labels, 0.01px for circles) generates findings like label "42 %" overflows its 120×80 cell by 3.2 px left.

How the Verification Works

The verify-treemap.py script processes diagrams through a seven-step pipeline that operates without browser rendering.

Parsing and Cell Detection

The parse_cells() function deduplicates the two-rect pair (mask + body) for each treemap cell, extracts the data-share value, and validates its numeric range (0 < share ≤ 100).

Label Geometry Estimation

The label_box() function calculates text dimensions using estimated_advance() with text-length-dependent metrics and the element's font-size. The box accounts for text-anchor attributes and optional rotation to determine precise anchor coordinates.

Smart Label Assignment

For each label, the script identifies the smallest cell whose geometric rectangle contains the label's anchor point. This prevents labels attached to small sliver cells from being mistakenly attributed to larger neighbors.

Relative Error Calculation

After filtering cells with valid data-share attributes, the script totals geometric area (drawn_total) and declared share (share_total). The relative measurement verification tolerates rounding artifacts while catching pathological sizing errors, such as "4-pixel-grid residue" that under-represents small values.

Running the Treemap Verification Gate

Local Verification of Single Files

Validate individual treemap diagrams during development:

python3 scripts/verify-treemap.py skills/diagram-design/assets/example-treemap.html

Successful validation returns:

OK treemap: 1 file(s), area matches labels and every label/marker fits its cell

Batch Verification and CI Integration

Verify all shipped treemap examples or integrate into automated pipelines:

python3 scripts/verify-treemap.py --all

The repository's CI workflow (.github/workflows/ci.yml) executes this command on every pull request:

- name: Verify treemaps
  run: |
    python3 scripts/verify-treemap.py --all

Exit Code Reference

Exit code	Meaning
0	All treemaps passed area fidelity and fit checks
1	One or more findings reported (validation failure)
2	Incorrect usage (e.g., missing file path)

Why Relative Error Matters

Using relative error rather than absolute pixel tolerance accommodates treemaps with high dynamic range. A cell with CELL_MIN_AREA = 400 square pixels (representing 0.5%) and a 60% cell cannot share the same absolute error budget. An absolute error of 1px would be meaningless for the small cell yet too strict for the large one. The 8% relative tolerance catches under-sized sliver cells while permitting normal rounding artifacts from integer coordinate systems.

Integration with Other Verification Gates

The treemap area encoding gate operates as part of a defense-in-depth strategy across 39 diagram types:

• verify-geometry.py validates label-mask overlap for generic diagrams but misses treemap-specific area-share consistency
• lint-skin.py checks color, font, and accessibility compliance but cannot verify spatial positioning
• self_check.py allows runtime validation by agents on generated diagrams, reusing the same logic for immediate feedback

This layered approach ensures that treemaps remain faithful to their quantitative contracts while maintaining visual accessibility standards.

Summary

• The treemap area encoding gate in scripts/verify-treemap.py enforces that drawn area matches declared data-share values within an 8% relative tolerance.
• Label fit verification ensures text and marker elements remain inside their host cells using 1px and 0.01px epsilon margins respectively.
• The script calculates relative error using normalized geometric area versus normalized declared share to handle cells ranging from 400px² to full-canvas size.
• CI integration via .github/workflows/ci.yml automatically blocks merges that violate area fidelity or label containment.
• The verification operates without a browser, using pure Python geometry for deterministic cross-platform results.

Frequently Asked Questions

How does the treemap verification handle font rendering differences across operating systems?

The script uses calibrated font-advance constants (MONO_ADVANCE, SANS_ADVANCE, WIDE_ADVANCE) combined with the declared font-size to estimate bounding boxes mathematically rather than relying on system font metrics. This ensures consistent relative measurement verification across Linux, macOS, and Windows CI runners without requiring browser-based rendering.

What causes the "4-pixel-grid residue" error in treemap area verification?

This occurs when layout algorithms snap rectangles to integer pixel coordinates, causing small cells (near the 400px² minimum) to deviate significantly from their proportional share. The 8% relative tolerance accommodates minor rounding, but residue that pushes error beyond this threshold indicates the cell needs enlargement or consolidation into an "Other" category.

Can I run the treemap gate on SVG files generated outside the Diagram Design repository?

Yes, provided the SVG follows the expected structure: cells must use <rect> elements with data-share attributes, and labels must use <text> elements. Invoke python3 scripts/verify-treemap.py path/to/your/file.svg to validate external treemaps against the same area encoding gate standards.

Why does the verification require the smallest containing cell for label assignment?

Treemap layouts often place small sliver cells adjacent to large parent regions. By selecting the smallest cell containing the label's anchor point, the script prevents attribution errors where a small cell's label is incorrectly associated with a neighboring large cell that also geometrically contains the point.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}