Treemap Geometric Verification: How Diagram-Design Ensures Area Accuracy

The cathrynlavery/diagram-design repository validates treemap geometry through a dedicated Python verifier that enforces area-to-value consistency using relative error calculations and guarantees label containment via glyph-width budgeting.

Every treemap in the Diagram-Design repository must faithfully encode quantitative data as visual area. The scripts/verify-treemap.py module automates this validation, ensuring that rendered rectangles match their intended proportions and that text labels remain strictly inside cell boundaries.

Parsing SVG Cell Geometry

The verification process begins by parsing the generated SVG and constructing geometric representations of each data cell. The parse_cells() function at line 150 extracts every <rect> element belonging to the treemap and instantiates a Box object for each one ☑️【verify‑treemap.py #L150】.

Each Box stores:

• Corner coordinates and dimensions (width and height)
• The data-share attribute containing the intended fractional area

This extraction step creates a computational geometry layer that mirrors the visual output, enabling precise numerical comparison between the rendered graphic and the underlying data values.

Computing Area Accuracy with Relative Error

Once cells are parsed, the verifier calculates physical area using the Box.area() property at line 115, which returns self.width * self.height ☑️【verify‑treemap.py #L115】. The script compares this drawn area against the expected value from the data-share attribute (or as a fallback, from the label text).

The comparison uses relative error to maintain accuracy across varying cell sizes:

relative_error = abs(drawn - expected) / expected

Relative error is critical because small cells would otherwise pass silently under an absolute threshold, while large cells might trigger false positives ☑️【README.md #L518】. The implementation accepts minor deviations caused by the 4 px grid overlay, tolerating up to approximately 2.7 % relative error in worst-case scenarios ☑️【type‑treemap.md #L12】.

Label Width Verification and Glyph Budgeting

Beyond area accuracy, the verifier ensures textual labels fit entirely within their cells. The estimated_advance() function at line 133 calculates text width by applying a strict budget of 1 em per full-width CJK glyph while treating combining marks as zero-width, matching the specifications in the style guide ☑️【verify‑treemap.py #L133】【style‑guide.md #L99】.

The verification sequence proceeds as follows:

1. label_box() (line 237) creates a bounding box for the text based on calculated dimensions ☑️【verify‑treemap.py #L237】
2. Box.contains_point() (line 118) checks that all corners of the label box lie inside the parent cell rectangle ☑️【verify‑treemap.py #L118】

If a label exceeds the cell boundaries, the verifier reports a failure, forcing authors to reduce label length or adjust cell dimensions.

Handling Edge Cases: Slivers and Grid Distortion

The verifier accommodates extreme aspect ratios and tiny cells through specialized logic. Slivers—cells smaller than 12 × 12 pixels—receive fixed-size disc markers instead of text labels. The script validates that these discs remain fully inside the cell boundaries, as documented in the treemap type specification ☑️【type‑treemap.md #L19】.

The 4 px grid overlay induces systematic area distortion across all cells. Rather than attempting pixel-perfect precision, the verifier measures relative error to ensure grid-induced deviations remain within acceptable bounds, preserving the visual integrity of proportional comparisons.

Running the Verification Suite

The command-line interface in main() (line 489) supports both single-file validation and batch processing ☑️【verify‑treemap.py #L489】.

Verify a single asset:

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

Validate all treemaps in the repository (used in CI):

python3 scripts/verify-treemap.py --all

The script returns exit code 0 on success and prints detailed error messages for any geometric mismatch. Developers can also import the verification logic programmatically:

from pathlib import Path
from scripts.verify_treemap import check

errors = check(Path("skills/diagram-design/assets/example-treemap.html"))
if errors:
    for err in errors:
        print(err)
else:
    print("Treemap geometry OK")

Summary

• Area-to-value consistency is enforced through relative error calculations in scripts/verify-treemap.py, comparing rendered pixel areas against data-share attributes.
• Label containment is verified using CJK-aware glyph budgeting (estimated_advance()) and geometric intersection tests (Box.contains_point()).
• Edge cases like slivers (< 12 × 12 px) switch to disc markers, while grid overlays tolerate ~2.7 % relative error.
• CI integration supports both single-file checks and repository-wide validation via the --all flag, returning exit code 0 only when all geometric constraints pass.

Frequently Asked Questions

Why does the verifier use relative error instead of absolute error?

Absolute error tolerance would allow tiny cells to pass with significant proportional inaccuracies while flagging large cells for minor pixel deviations. Relative error ensures that a 5 % area mistake fails regardless of whether the cell represents 1 % or 50 % of the total value, maintaining consistent data fidelity across the entire treemap.

How does the script handle text in CJK (Chinese, Japanese, Korean) scripts?

The estimated_advance() function applies a budget of 1 em per full-width CJK glyph and treats combining marks as zero-width, aligning with the style-guide specification at line 99. This approach accurately predicts text width for mixed-script labels without requiring font rendering libraries.

What happens when a treemap cell is too small for a text label?

Cells smaller than 12 × 12 pixels are classified as slivers and receive fixed-size disc markers instead of text. The verifier checks that these discs remain fully inside the cell bounds, ensuring visual presence without compromising readability or geometry constraints.

How is the verifier integrated into the continuous integration pipeline?

The repository uses the --all flag to walk the entire skills/diagram-design/assets/ directory during CI builds. The script returns exit code 0 only when all treemaps pass geometric verification, blocking merges that contain area mismatches or label overflows.

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