Add size-controlled mesh cartograms (non-contiguous, layer-unrolled, focus+context) for per-element scalar fields

[domattioli]

Summary

CHILmesh should provide reusable cartogram plotting so a per-element (or per-vertex) scalar field can be read without large elements visually dominating small ones. A geographic, area-weighted tripcolor of a 98,365-element WNAT mesh devotes most of the canvas to coarse open-ocean elements and shrinks the refined coastline — where the signal concentrated — to sub-pixel threads. Three prototype views (QuADMESH#96 / QuADMESH#97) solved this; they are mesh-generic and belong in CHILmesh.

Motivation

The QuADMESH+ Monte-Carlo layer-pass study measured a per-triangle pass-frequency. On WNAT_Hagen the ever-routed elements are 9.9% of the mesh and the always-routed 4.9%, concentrated in the fine coastal band; the plain map renders them invisible. Equalizing visual weight per element exposed real structure — start-dependent "swing" triangles cluster at specific layer-and-angle locations in the deep small layers (L21–L25). The large-element-dominance problem is general to any scalar on any non-uniform mesh.

Prototype to generalize (QuADMESH experiments/mc_layer_pass/)

• cartogram_noncontig — each element redrawn at equal area about its centroid, geographic position preserved.
• cartogram_unrolled — skeleton layers unrolled into equal-height bands; each element an equal-width cell ordered by angle. Built from CHILmesh layers + paths_on_outer_vertices.
• cartogram_hybrid — focus+context: element extent ∝ |value − reference| + ε, reference ∈ {mean, median, mode, max, min}.

Proposed API

fig, ax = mesh.cartogram(values, kind="unrolled"|"noncontig"|"hybrid", reference="mean", cmap="inferno", ax=None) — per-element or per-vertex array, returns Matplotlib handles.

Iteration backlog (presentation + utility)

• Non-contiguous overlap/gaps: Dorling equal-circle option and/or contiguous Gastner–Newman diffusion cartogram.
• Unrolled band height: equal-per-layer (current) vs count-weighted vs log-count.
• Within-band ordering: true OV-path arc-length vs centroid angle; multi-loop layers + islands.
• Mixed tri/quad element support; diverging colormaps + percentile-clip + colorblind-safe defaults.
• PolyCollection batching/decimation for 10⁶-element meshes; optional hover interactivity; gallery doc + tests.

Acceptance

API + docstrings (MATLAB-help register), gallery page, unit/smoke tests, and reproduction of the QuADMESH pass-frequency cartograms directly from CHILmesh.

References

QuADMESH PR #96 (branch monte-carlo-quality-analysis), issue #97; prototypes cartogram.py, cartogram_hybrid.py. Gastner & Newman (2004); Dorling (1996).

[domattioli]

Scoping note (routine, advance-only) — the substrate is already in-repo; propose shipping noncontig first

Grounded the three proposed views against what chilmesh already exposes on development, to find the smallest slice that's ready without new topology.

• Substrate check — all three views map onto existing primitives

  ▸ noncontig

    ↪ needs only `chilplotting.build_polygons(points, connectivity)` (returns per-element `(k,2)` vertex arrays, already handles tri/quad/mixed) + a per-polygon rescale about its centroid to equal area, then the colormap/`PolyCollection` fill path that `chilplotting.plot_filled(..., values=, cmap=)` already implements. Zero new topology, zero layer dependency.
  

  ▸ unrolled

    ↪ needs `self.layers` (`OE`/`IE`/`OV`/`IV` per peel pass) for the band decomposition and `mesh.paths_on_outer_vertices(layer_idx)` for within-band OV-arc ordering — both already exist, but this view carries the multi-loop-layer + island edge cases the issue body itself flags, so it is materially more work.
  

  ▸ hybrid

    ↪ = `noncontig` extent scaled by `|value − reference| + ε` with `reference ∈ {mean, median, mode, max, min}`; a small addition once `noncontig` lands, not a separate build.
  

• Recommended first slice (toward status: ready)

  I. ship mesh.cartogram(values, kind="noncontig", cmap="inferno", ax=None) — least code, no layer/OV dependency, reuses build_polygons + plot_filled's colormap path verbatim.

  II. acceptance for that slice: API + MATLAB-help-register docstring, a smoke test (per-element array in → Matplotlib handles out, equal drawn area per element), and a gallery figure.

  III. defer unrolled + hybrid to follow-up slices under this same issue (or split off) once noncontig is in — keeps the multi-loop/island and reference-semantics questions out of the first landing.

• What's needed to flip to ready

  ↪ an operator nod on "start with noncontig, defer the other two" (or a different first-slice pick). This is priority: someday and sits in the zoom-out audit: roadmap doc stale + 5 issues parked in decision-limbo (project_plan.md, #201/#223/#197/#219/#155) #261 decision-limbo queue, so no label flip is proposed here — just a concrete first slice for whenever it's picked up. The QuADMESH experiments/mc_layer_pass/ prototypes remain the reference for the visual output to reproduce.

[model: claude-opus-4-8, repo: CHILmesh, session: 018z9MobkyDkCqHasxikpEpi]

---

Generated by Claude Code

[domattioli]

Advanced — research note grounded in the current API (2b850ed, development)

Committed .specify/specs/004-mesh-cartograms/research.md. Advance only (brainstorming entitlement) — no label flip, no implementation.

• What it pins down

  ▸ Composition (not a new render engine)

    ↪ the cartogram is additive — it re-lays-out element geometry, then hands the polygons to the plotting path that already exists: `chilplotting.plot_filled` / `build_polygons` (`src/chilmesh/chilplotting.py:205,100`) for the scalar-colormap fill, `layer_paths.paths_on_outer_vertices(mesh, layer_idx)` (`layer_paths.py:51`) for `unrolled` within-band ordering, and `mesh.layers` OE/IE/OV/IV (`CHILmesh.py:307`) for the bands.
  

  ▸ Per-kind algorithm

    a. `noncontig` — centroid-anchored equal-area glyphs (geographic position kept, area equalized).
  
    b. `unrolled` — skeleton layers as equal-height bands, elements ordered by OV-path arc-length; this is the variant that exposes the deep-small-layer (L21–L25) clustering the issue motivates.
  
    c. `hybrid` — same layout as `noncontig` but element extent ∝ `|value - reference| + eps` (focus+context).
  

  ▸ Scope discipline

    ↪ matplotlib-only v1 (no new extra; orthogonal to the env-blocked GPU track in #167), with Dorling / Gastner–Newman contiguous diffusion, count-weighted band heights, and 10⁶-element batching all tiered to a backlog so v1 stays small.
  

• What would make this status: ready — four one-line operator answers (v1 scope: all three kinds vs noncontig+unrolled first / noncontig glyph: square vs shape-preserving / unrolled band-height default / confirm someday priority or promote). Detail + verified line refs + validation plan in the research.md.

[model: claude-opus-4-8, repo: CHILmesh, session: 013NhKuhHJwC9wmmysELCufc]

---

Generated by Claude Code