feat(altair): implement contour-basic

[github-actions]

Implementation: contour-basic - python/altair

Implements the python/altair version of contour-basic.

File: plots/contour-basic/implementations/python/altair.py

Parent Issue: #855

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot shows a topographic elevation map on a warm off-white (#FAF8F1) background. A viridis colormap fills the 2D grid (purple for low elevations ~350m, transitioning through blue-green to yellow at the highest point ~1250m). Two mountain peaks are clearly visible: a larger one in the upper-right (~850m base) and a smaller one in the lower-left (~550m base), with a slight low-elevation corridor between them. White contour lines overlay the fill — thin semi-transparent minor lines at every 100m and thicker, near-opaque major lines at every 200m. The colorbar "Elevation (m)" sits on the right with a gradient legend. The title "Mountain Terrain · contour-basic · altair · anyplot.ai" appears in dark ink at top-center. Axis labels "Distance East (km)" and "Distance North (km)" with decimal tick labels (0.00–9.60) are clearly legible against the light background. All text is readable — PASS.

Dark render (plot-dark.png): The same plot on a near-black (#1A1A17) warm background. The viridis colormap colors are identical to the light render (same purple-to-yellow gradient) — data colors unchanged, only chrome flips. The title and axis labels appear in light ink (#F0EFE8 / #B8B7B0), clearly readable against the dark background. Colorbar labels and title are light-colored and legible. The white contour lines remain visible against the dark-themed background. No dark-on-dark text failures observed. Legibility verdict: PASS.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 86/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	13	20
Spec Compliance	14	15
Data Quality	15	15
Code Quality	9	10
Library Mastery	6	10
Total	86	100

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — Title 28px, axis labels 22px, tick labels 18px, legend title 22px/labels 18px — all explicitly set and readable in both themes
• VQ-02: No Overlap (6/6) — Tick labels are dense on x-axis (13 values) but no actual overlap observed at rendered size
• VQ-03: Element Visibility (6/6) — Filled viridis contours and both minor/major white contour lines are clearly distinguishable
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and colorblind-safe; white contour lines provide high contrast
• VQ-05: Layout & Canvas (3/4) — Canvas 1420×785 → 4260×2355 px output, below the 4800×2700 standard; guide specifies width=1600, height=900
• VQ-06: Axis Labels & Title (2/2) — "Distance East (km)", "Distance North (km)", colorbar "Elevation (m)" — all descriptive with units
• VQ-07: Palette Compliance (2/2) — Viridis correctly applied for sequential continuous elevation data; #FAF8F1 / #1A1A17 backgrounds correct; theme-adaptive chrome (INK, INK_SOFT, ELEVATED_BG) correctly implemented in both renders

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Thoughtful design: viridis fill + major/minor contour line distinction (100m thin 35% opacity vs. 200m thick 95% opacity) creates intentional visual hierarchy above a basic default; overall look is competent scientific visualization but not publication-ready
• DE-02: Visual Refinement (4/6) — stroke=None removes view border, grid opacity 0.10 (very subtle), theme-adaptive tick/label/domain colors; fill contour naturally reduces reliance on grid
• DE-03: Data Storytelling (4/6) — Two peaks of different heights are immediately apparent via viridis progression; major/minor contour distinction guides the viewer's reading of elevation bands; no annotations needed, visual hierarchy does the work

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct: filled contour background (mark_rect + viridis) layered with isoline segments (mark_rule) matches spec description of "isolines of a 2D scalar field"
• SC-02: Required Features (3/4) — Spec says "label key contour levels when practical" — not implemented; colorbar present ✓, both contour lines and filled regions ✓, 80×80 grid ✓
• SC-03: Data Mapping (3/3) — x=Distance East (km), y=Distance North (km), z=Elevation (m) — all correctly mapped; axes show full 0–10 km range
• SC-04: Title & Legend (3/3) — "Mountain Terrain · contour-basic · altair · anyplot.ai" follows {name} · {spec-id} · {library} · anyplot.ai; colorbar titled "Elevation (m)" correct

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Two distinct peaks at different elevations, a saddle/valley between them, and a linear slope; demonstrates all core contour features (peaks, ridges, valleys, gradients)
• DQ-02: Realistic Context (5/5) — Topographic elevation map of a 10km×10km mountain region; neutral scientific scenario, no sensitive content
• DQ-03: Appropriate Scale (4/4) — Elevation 350–1250m (realistic mountain range), 80×80 grid (within spec's 20×20 to 100×100), contour intervals at 100m (standard topographic practice)

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) — Imports → theme tokens → data generation → marching squares → plot composition → save; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic: mathematical functions of x,y with no random elements
• CQ-03: Clean Imports (2/2) — All three imported modules (alt, np, pd) plus os/sys are used; importlib pattern is justified by path isolation comment
• CQ-04: Code Elegance (1/2) — Marching squares implementation is 45+ lines of nested loops with bit manipulation; acceptable given Altair's lack of native contour support, but verbose and hard to follow
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (scale_factor=3.0) and plot-{THEME}.html correctly

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5) — Correctly uses layer composition (+ operator), declarative aggregation (mean(elevation):Q in encode), alt.Bin(maxbins=80), mark_rule with x2/y2 encoding for segments, and full .configure_*() chain — idiomatic Altair patterns
• LM-02: Distinctive Features (2/5) — Layer composition and declarative aggregation+binning are Altair-specific, but the core contour extraction (marching squares) is pure Python outside Altair's capabilities; no use of Altair's distinctive interactivity (tooltips, zoom/pan) despite generating HTML output

Score Caps Applied

• None — all criteria above threshold for cap triggers

Strengths

• Viridis colormap correctly chosen for sequential continuous elevation data — perceptually uniform and colorblind-safe
• Major/minor contour line distinction (100m thin 35% vs. 200m thick 95%) is a deliberate design choice that adds genuine visual hierarchy
• Full theme-adaptive chrome correctly implemented with all five tokens (PAGE_BG, ELEVATED_BG, INK, INK_SOFT) — both renders pass readability checks
• Realistic topographic scenario with plausible elevation values and two peaks of different heights demonstrates all core contour features
• Declarative aggregation (mean(elevation):Q with alt.Bin) to create the filled contour effect is a clever Altair-idiomatic approach

Weaknesses

• Canvas undersize: width=1420, height=785 produces 4260×2355 px; altair.md guide specifies width=1600, height=900 → 4800×2700 px
• No contour level labels despite spec recommending them "when practical"
• Altair's distinctive interactive features not utilized: HTML output is generated but neither .interactive() nor tooltip encoding is added
• Marching squares implementation adds 45+ lines of dense bit-manipulation code

Issues Found

1. VQ-05 LOW: Canvas dimensions off-spec — use width=1600, height=900 (per altair.md guide) with scale_factor=3.0 to hit 4800×2700 standard
   • Fix: Change .properties(width=1420, height=785, ...) → .properties(width=1600, height=900, ...)
2. LM-02 LOW: Altair's distinctive interactivity unused despite HTML export
   • Fix: Add .interactive() to the layer chart and tooltip=[alt.Tooltip('x:Q', title='East (km)'), alt.Tooltip('y:Q', title='North (km)'), alt.Tooltip('mean(elevation):Q', title='Elevation (m)', format='.0f')] to the filled layer encoding
3. SC-02 MINOR: Contour level labels absent — if practical, add alt.Chart(df_major_pts).mark_text() annotations at major-level midpoints
4. CQ-04: Consider refactoring the marching squares loop or using a helper comment block to explain the algorithm for readability

AI Feedback for Next Attempt

Fix canvas size to width=1600, height=900 (scale_factor=3.0 = 4800×2700px). Add .interactive() to enable zoom/pan (Altair's key differentiator) and add tooltip encoding to the filled layer showing x, y, and elevation values — this leverages Altair's declarative interactive capabilities that justify the HTML output. These two changes together will lift LM-02 from 2→4 and bring the canvas into compliance.

Verdict: REJECTED