feat(pygal): implement contour-basic

[github-actions]

Implementation: contour-basic - python/pygal

Implements the python/pygal version of contour-basic.

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

Parent Issue: #855

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white #FAF8F1 background fills the entire canvas. The title "Mountain Terrain · contour-basic · pygal · anyplot.ai" is centered at the top in dark ink at a large size. The plot area shows a filled contour map using the viridis colormap — two distinct elevation peaks are visible: a large bright-yellow/green peak in the upper-right (highest elevation ~1225m) and a smaller teal/green peak in the lower-left (~880m). Contour lines are drawn in a translucent off-white at both minor (50m interval, thin) and major (200m interval, thicker) levels. The X-axis shows "Distance East (km)" with tick labels 0–10, and the Y-axis shows "Distance North (km)" in rotated text. A viridis gradient colorbar sits on the right with "Elevation (m)" label and values 302–1225. All axis text, tick labels, title, and colorbar labels are clearly readable against the light background using dark ink. No light-on-light issues. Legibility verdict: PASS.

Dark render (plot-dark.png): Near-black #1A1A17 background. The title is rendered in the same position with light-colored text clearly readable against the dark surface. The data colors (viridis colormap) are identical to the light render — the two elevation peaks appear in exactly the same yellow/green/teal hues. Axis labels, tick labels, and colorbar values are rendered in lighter-gray tones (INK_SOFT / INK_MUTED tokens) and are clearly readable against the dark background. No dark-on-dark failure detected. The L-shaped axis frame is appropriately muted. Legibility verdict: PASS.

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

Score: 83/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set (title 64px, labels 44px, ticks 38px). All text readable in both themes.
• VQ-02: No Overlap (6/6) — No overlapping labels or contour elements.
• VQ-03: Element Visibility (6/6) — Filled contour cells and contour lines clearly visible against both backgrounds.
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and CVD-safe; no red-green signal encoding.
• VQ-05: Layout & Canvas (4/4) — 4800×2700 landscape, colorbar well-positioned on right, generous margins.
• VQ-06: Axis Labels & Title (2/2) — "Distance East (km)", "Distance North (km)", "Elevation (m)" all with units.
• VQ-07: Palette Compliance (2/2) — Viridis correctly applied for continuous elevation data. Backgrounds are #FAF8F1/#1A1A17 per theme.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom viridis interpolation, marching squares for contour lines, distinct minor vs. major level styling (opacity + weight), gradient colorbar. Considerable craft for a pygal contour implementation.
• DE-02: Visual Refinement (4/6) — L-shaped frame per style guide, contour lines at two opacity levels (0.30 minor / 0.65 major), no unnecessary chrome. Clean composition.
• DE-03: Data Storytelling (4/6) — Two mountain peaks create clear visual focal points. The viridis color scale naturally guides the eye from valley (purple) to summit (yellow).

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct contour plot with both filled regions and contour lines.
• SC-02: Required Features (3/4) — Viridis colormap ✓, colorbar ✓, filled regions + contour lines ✓, sufficient grid resolution (80×80) ✓. Missing: labeled contour levels on the lines themselves (spec says "label key contour levels when practical").
• SC-03: Data Mapping (3/3) — X/Y as spatial km coordinates, Z as elevation on correct grid.
• SC-04: Title & Legend (3/3) — Title includes spec-id, library, and anyplot.ai. Colorbar serves as the value legend.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Covers filled contours, minor and major contour lines, colorbar. Missing: labeled contour level text.
• DQ-02: Realistic Context (5/5) — Mountain terrain elevation map is realistic, neutral, and domain-appropriate.
• DQ-03: Appropriate Scale (4/4) — Elevation 350–1225m over 10×10 km area; realistic for a mountainous terrain.

Code Quality (9/10)

• CQ-01: KISS Structure (2/3) — Helper functions viridis_at(), lerp(), march() are necessary for the marching squares algorithm. At 343 lines it's verbose but the complexity is justified by the algorithm.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) present (data generation is deterministic anyway).
• CQ-03: Clean Imports (2/2) — cairosvg, numpy, pygal, pygal.style.Style, os, sys — all are used.
• CQ-04: Code Elegance (2/2) — Marching squares correctly implemented; no fake UI elements; SVG injection is cleanly structured.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly.

Library Mastery (3/10)

• LM-01: Idiomatic Usage (2/5) — Pygal is used only as an SVG skeleton container: a pygal.XY chart is created with a single dummy data point [(0, 0)], and all actual rendering is done via raw SVG injection. The Style object is used correctly for theming, but the native pygal chart API is barely engaged.
• LM-02: Distinctive Features (1/5) — Pygal's defining feature — interactive JavaScript charts — is explicitly disabled with js=[]. The HTML output is a static SVG embedded in HTML rather than a pygal interactive chart. No pygal-native chart type is meaningfully used.

Score Caps Applied

• None

Strengths

• Creative SVG injection approach overcomes pygal's lack of native contour support while maintaining correct theme tokens throughout
• Viridis colormap correctly chosen and manually interpolated for continuous elevation data, matching style guide requirements
• Marching squares implementation produces accurate contour lines at both minor (50m) and major (200m) intervals with intentional visual differentiation
• Both light and dark themes fully implemented with identical data colors and distinct chrome — no dark-on-dark or light-on-light failures

Weaknesses

• Library mastery is critically low: pygal's native charting API is only used for its SVG wrapper (dummy data point), and JS interactivity is explicitly disabled — the implementation is essentially a custom SVG renderer wearing pygal's theme system
• Contour level labels (elevation values printed directly on contour lines) are absent; the spec recommends labeling key levels when practical

Issues Found

1. LM-01 LOW: Pygal used only as SVG container — real chart drawn via raw SVG injection with [(0, 0)] dummy data. Not idiomatic pygal usage.
   • Fix: Consider using pygal's XY or Line chart type for at least the axis/grid layer, or structure the SVG injection to leverage more of pygal's native rendering
2. LM-02 LOW: Pygal's interactive JS disabled (js=[]); HTML output is static SVG in HTML rather than a living pygal interactive chart.
   • Fix: Remove js=[] to preserve pygal's hover/tooltip interactivity in the HTML output; only the PNG needs to be static
3. SC-02 PARTIAL: No labeled contour levels on the lines themselves.
   • Fix: Add elevation value text at key contour intervals (e.g., every 200m major contour) using SVG <text> elements along the line paths

AI Feedback for Next Attempt

The visual output is strong but library mastery is the critical weakness. Re-enable pygal's JavaScript by removing js=[] so the HTML output is a true interactive pygal chart. Consider whether any axis or grid elements can be delegated to pygal's native rendering rather than full SVG injection. Add contour level labels at major contour intervals using SVG text positioned along contour segments.

Verdict: APPROVED

[github-actions]

🔧 Repair Attempt 1/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (plot-light.png): The plot displays a mountain terrain contour map on a warm off-white (#FAF8F1) background. The filled contour regions use the viridis colormap — deep purple at low elevations (~320 m) transitioning through teal and green to bright yellow at the highest elevations (~1220 m). Two elevation peaks are marked with Okabe-Ito colored dots: orange (#D55E00) for the primary peak (upper-right) and blue (#0072B2) for the secondary peak (lower-left). Minor contour lines appear at 50 m intervals (subtle, low opacity) and major lines at 200 m intervals (more prominent). Major contour levels are labeled (400 m through 1200 m) with white-halo text for legibility. A vertical colorbar on the right shows the elevation scale with numeric labels and a rotated "Elevation (m)" title. Axes show "Distance East (km)" and "Distance North (km)" with 0–10 tick labels. An L-shaped frame (left + bottom) anchors the plot. Title reads "Mountain Terrain · contour-basic · pygal · anyplot.ai" in dark ink. All text is clearly readable against the light background — no light-on-light issues.

Dark render (plot-dark.png): Same plot on a warm near-black (#1A1A17) background. The viridis data colors are identical to the light render — the colormap, contour fills, and peak marker colors (orange and blue) are unchanged between themes. Title, axis labels, tick labels, colorbar labels, and contour level text all render in light-colored ink (#F0EFE8 / #B8B7B0) — clearly readable against the dark background. No dark-on-dark failures detected. The L-shaped frame is rendered in the muted ink tone, maintaining the L-shape. Overall the dark render is fully legible.

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

Score: 82/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	13	20
Spec Compliance	14	15
Data Quality	15	15
Code Quality	7	10
Library Mastery	6	10
Total	82	100

Visual Quality (27/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 64px, axis labels 44px, tick labels 38px, contour labels 40px; perfectly readable in both themes
• VQ-02: No Overlap (4/6) — Minor crowding of contour labels near the primary peak: "1000 m" and "1200 m" labels are close together in the upper-right; main content readable but not fully comfortable
• VQ-03: Element Visibility (6/6) — Filled regions, contour lines, peak markers, and colorbar all clearly visible
• VQ-04: Color Accessibility (2/2) — Viridis is CVD-safe; peak markers use Okabe-Ito orange and blue with good luminance separation from each other and from the viridis background
• VQ-05: Layout & Canvas (3/4) — Good canvas utilization; right margin slightly tight (colorbar + rotated label + numeric labels all compete for the ~520px right margin)
• VQ-06: Axis Labels & Title (2/2) — "Distance East (km)", "Distance North (km)", "Elevation (m)" — all descriptive with units
• VQ-07: Palette Compliance (2/2) — Viridis for continuous data (correct); background #FAF8F1 (light) / #1A1A17 (dark); data colors theme-invariant; text chrome correctly flips between themes

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above defaults: viridis colormap, two-level contours (minor + major at different opacities), halo labels, L-shaped frame, clean peak markers. Not quite publication-ready but clearly thoughtful design.
• DE-02: Visual Refinement (4/6) — No top/right spines, no grid (appropriate for filled contour), two opacity levels for minor vs. major contours, label halos. Some refinement visible; minor and major contour differentiation adds polish.
• DE-03: Data Storytelling (4/6) — The viridis colormap naturally draws the eye to peak elevations; two annotated peaks guide the viewer to the key terrain features; the filled + line combination creates clear visual hierarchy.

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct contour plot type with both filled regions and contour lines
• SC-02: Required Features (4/4) — Sequential viridis colormap ✓, colorbar ✓, filled regions + contour lines ✓, major contour labels ✓, 80×80 grid resolution ✓
• SC-03: Data Mapping (3/3) — X/Y correctly mapped to spatial coordinates; Z encoded via viridis fill and contour lines; all data visible
• SC-04: Title & Legend (2/3) — Title "Mountain Terrain · contour-basic · pygal · anyplot.ai" contains extra "Mountain Terrain ·" prefix; required format is contour-basic · pygal · anyplot.ai. Peak marker labels only visible via HTML tooltips, not in PNG.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows filled isolines, two contour density levels (minor + major), two distinct topographic peaks, valley between them, gradient from low to high — all aspects of contour plots covered
• DQ-02: Realistic Context (5/5) — Mountain terrain with 10×10 km region, elevation in meters; neutral geographic/scientific context
• DQ-03: Appropriate Scale (4/4) — Elevation range ~320–1220 m realistic for a local mountain region; 10 km spatial extent appropriate

Code Quality (7/10)

• CQ-01: KISS Structure (1/3) — Four helper functions defined (viridis_at, lerp, march, label_anchors); KISS principle requires no functions/classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) present
• CQ-03: Clean Imports (2/2) — All imports used (os, re, sys, cairosvg, numpy, pygal, Style)
• CQ-04: Code Elegance (1/2) — The marching squares + SVG injection approach is technically impressive but adds substantial complexity (~250 lines of custom SVG generation); slightly over-engineered for the task
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html with correct filenames; current pygal API

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Uses pygal's XY chart and Style system correctly; main visualization is custom SVG (not pygal API) since pygal lacks native contour support — correct but unconventional
• LM-02: Distinctive Features (3/5) — Leverages pygal's interactive HTML export and JS hover tooltips for peak markers; SVG injection creatively exploits pygal's SVG output format

Score Caps Applied

• None

Strengths

• Viridis colormap correctly applied to continuous elevation data — spec-compliant and perceptually appropriate
• Two-level contour system (minor 50 m / major 200 m at different opacities) creates genuine visual hierarchy
• Flawless theme adaptation in both renders — backgrounds, ink colors, and text all correct
• Realistic, neutral mountain terrain data with appropriate scales (km distances, meter elevations)
• Colorbar with units and numeric labels meets spec requirement exactly

Weaknesses

• SC-04: Title format incorrect — prefix "Mountain Terrain ·" should be removed; correct format is contour-basic · pygal · anyplot.ai
• CQ-01: Four helper functions (viridis_at, lerp, march, label_anchors) violate KISS structure — inline the simple ones; reorganize march algorithm inline if possible
• VQ-02: Contour level labels crowd near the primary peak — reduce max_labels to 1 per level, or spread label placement to avoid clustering in the peak area
• VQ-05: Right margin tight — reduce colorbar label size or shift colorbar left to give the rotated "Elevation (m)" text more space

Issues Found

1. SC-04 TITLE FORMAT: Title starts with descriptive text before the spec-id
   • Fix: Change title to exactly contour-basic · pygal · anyplot.ai
2. CQ-01 FUNCTIONS: viridis_at, lerp, march, label_anchors defined as module-level functions
   • Fix: Inline viridis_at and lerp; restructure march and label_anchors as inline code blocks
3. VQ-02 LABEL CROWDING: Multiple contour labels cluster near primary peak
   • Fix: Reduce max_labels=1 per major contour level, or filter label positions that fall within 100px of an existing label
4. VQ-05 MARGIN: Right margin crowded with colorbar + labels + title
   • Fix: Increase MARGIN_R to 620 or shift cb_x closer to plot

AI Feedback for Next Attempt

Fix the title to exactly contour-basic · pygal · anyplot.ai (remove "Mountain Terrain ·" prefix). Reduce max_labels to 1 per contour level to eliminate label crowding near the primary peak — the labels already form a visual story without doubling up. Inline the helper functions (viridis_at and lerp are short enough; march can be restructured as inline code). Increase MARGIN_R to ~620 to give the colorbar label comfortable breathing room.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 2/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 3/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white #FAF8F1 background. It shows a filled contour elevation map of a 10 km × 10 km mountain region using the viridis colormap (deep purple at low elevations through cyan to bright yellow at peaks). Two mountain peaks are visible: a dominant primary peak in the upper-right quadrant and a secondary peak in the lower-left. Major contour lines (every 200 m) are drawn in white/light at ~65% opacity; minor lines (every 50 m) are subtle at ~30% opacity. Contour level labels (400, 600, 800, 1000, 1200 m) appear with a background halo for legibility. An orange dot marks the primary peak and a blue dot marks the secondary peak. A custom colorbar on the right shows the elevation scale from ~350 m to ~1371 m with tick labels, and the colorbar is titled "Elevation (m)". The title "contour-basic · pygal · anyplot.ai" appears at the top in dark ink. Axis labels read "Distance East (km)" and "Distance North (km)". All text is clearly readable against the light background — no light-on-light failures detected.

Dark render (plot-dark.png): The same layout renders on a warm near-black #1A1A17 background. The viridis colormap data colors are identical to the light render — only the chrome flips. The title, axis labels, tick labels, colorbar labels, and contour-level annotations all appear in light-colored text (#F0EFE8 / #B8B7B0 tones) against the dark background. The L-shaped frame uses the lighter INK_SOFT token, and contour labels use INK (light) fill with a PAGE_BG (dark) halo. No dark-on-dark failures detected — all text is readable. The orange and blue peak markers retain the same Okabe-Ito hues. The colorbar gradient is identical to the light render.

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

Score: 89/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	14	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	89	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set in SVG (title 64px, axis labels 44px, ticks 38px, colorbar labels 34px, contour labels 40px); all readable in both themes. Minor deduction: colorbar labels (34px) slightly below the 38px minimum tick-label guideline.
• VQ-02: No Overlap (5/6) — Halo-backed contour labels are legible; minor crowding of the 1200 m label near the primary peak marker, though still readable.
• VQ-03: Element Visibility (6/6) — Viridis gradient fill, major/minor contour lines, peak markers, colorbar segments all perfectly visible.
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and CVD-safe; peak markers use Okabe-Ito orange (#D55E00) and blue (#0072B2) for clear distinction.
• VQ-05: Layout & Canvas (4/4) — Plot fills well over 50% of 4800×2700 canvas; margins are generous and balanced; colorbar fits cleanly in the right margin.
• VQ-06: Axis Labels & Title (2/2) — "Distance East (km)", "Distance North (km)", "Elevation (m)" — all descriptive with units.
• VQ-07: Palette Compliance (2/2) — Viridis sequential colormap correct for continuous elevation data; light background #FAF8F1, dark background #1A1A17; chrome tokens flip correctly between themes; viridis data colors identical across renders.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: viridis gradient fill produces a beautiful, professional contour visualization; smart label placement algorithm fans labels away from peaks; peak markers use contrasting Okabe-Ito colors for instant legibility. Clearly above defaults.
• DE-02: Visual Refinement (4/6) — L-shaped frame (top/right spines removed), no grid lines, layered contour line opacities (0.30 minor / 0.65 major), generous whitespace. Solid refinement.
• DE-03: Data Storytelling (4/6) — Visual hierarchy is clear: the bright yellow primary peak immediately draws the eye; labeled contours and annotated peak elevations tell a topographic story. Viewer immediately sees the two-mountain landscape.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: filled contour regions + isoline overlay.
• SC-02: Required Features (4/4) — Sequential viridis colormap ✓; colorbar ✓; filled regions + contour lines ✓; labeled major contour levels ✓; 80×80 grid resolution ✓.
• SC-03: Data Mapping (3/3) — X = Distance East (km), Y = Distance North (km), Z = Elevation (m) mapped via viridis; all axes span 0–10 km correctly.
• SC-04: Title & Legend (3/3) — Title "contour-basic · pygal · anyplot.ai" ✓; colorbar serves as the legend with "Elevation (m)" ✓.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows full range of contour features: high/low elevation regions, multiple peaks with different heights, saddle between them, minor and major isolines.
• DQ-02: Realistic Context (5/5) — Topographic elevation map of a 10 km × 10 km mountain region; neutral, comprehensible real-world scenario.
• DQ-03: Appropriate Scale (4/4) — Elevation range ~350–1371 m is realistic for a mountainous 10 km region; contour intervals (50 m minor, 200 m major) are standard for topographic maps.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat script: no functions or classes; follows Imports → Data → Plot → Save pattern.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used: os, re, sys, cairosvg, numpy, pygal, pygal.style.Style.
• CQ-04: Code Elegance (2/2) — Inline marching squares and vectorized viridis interpolation are complex but genuinely required for contour plotting in pygal; SVG injection is appropriate and well-commented. No fake UI elements.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png + plot-{THEME}.html correctly.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Uses pygal.XY for interactive peak markers with native hover tooltips, pygal.Style for theme tokens, pygal.render() for SVG, cairosvg for PNG export. SVG injection is non-standard but is the correct approach given pygal's lack of native contour support.
• LM-02: Distinctive Features (3/5) — Distinctive pygal technique: reverse-engineers peak marker pixel positions from SVG regex parsing to perfectly align the custom contour overlay with pygal's coordinate system; native JS hover interactivity retained in HTML output; HTML export leverages pygal's interactive rendering pipeline.

Score Caps Applied

• None — no cap conditions triggered.

Strengths

• Correct viridis colormap for continuous elevation data; both light and dark themes fully theme-correct with no chrome failures
• Smart contour label placement algorithm (maximize-distance from placed anchors) prevents label–marker collisions
• Inline marching squares + vectorized viridis interpolation is a technically accomplished, elegant solution to a hard problem (contour plots in pygal)
• All five required spec features present; axis labels and colorbar title include units
• Perfect data quality: realistic topographic scenario with appropriate scale and good feature coverage

Weaknesses

• Colorbar tick labels at 34px are slightly below the 38px minimum for pixel-based tick labels; raising to 38px would improve consistency
• Minor label crowding near the 1200 m / primary peak area — the halo keeps labels readable but the placement could fan labels slightly further from peak markers
• DE-01 could approach 8 with more typographic polish (e.g., a slightly refined font weight hierarchy between the title and axis labels)

Issues Found

1. VQ-01 minor: Colorbar labels set at 34px; the style guide recommends 38px for pixel-based tick labels.
   • Fix: Change colorbar label font size from 34px to 38px for consistency.
2. DE-01 gap: Design is strong but the typography hierarchy between title (64px) and axis labels (44px) is functional rather than refined.
   • Fix: Consider slightly adjusting weight/spacing for a more polished typographic rhythm.

AI Feedback for Next Attempt

Scores are high. Remaining deductions: (1) raise colorbar label size from 34 to 38px for VQ-01 consistency; (2) address the 1200 m label crowding near the primary peak by widening the separation in the placement algorithm; (3) refine typography weight hierarchy (title slightly bolder relative to axis labels) to close the DE-01 gap toward 8.

Verdict: APPROVED