# Treemap Area Encoding Gate and Relative Measurement Verification in Diagram Design

> Ensure treemap accuracy with Diagram Design's verification gate. Validate area-share fidelity within 8% tolerance and confirm label/marker fit. Discover robust treemap area encoding and relative measurement verification.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-09

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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**:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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:

```bash
python3 scripts/verify-treemap.py --all

```

The repository's CI workflow ([`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml)) executes this command on every pull request:

```yaml
- 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`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py)** validates label-mask overlap for generic diagrams but misses treemap-specific area-share consistency
- **[`lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py)** checks color, font, and accessibility compliance but cannot verify spatial positioning
- **[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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.