Topography
Cartographic living art that turns repositories and activity into terrain, routes, and survey chrome.
Module
scripts/art/topography.py — cartographic living-art renderer backed by scripts/art/shared.py.
Generator mapping
Topography treats the profile as a survey map rather than a literal project list. The generator starts from normalized metrics, derives a shared World State, and then maps repository structure onto terrain and map furniture.
| Signal | Topography mapping |
|---|---|
repos[] | Each repository becomes a terrain feature, landmark, or named route anchor. |
stars and per-repo stars | Raise summit prominence, label importance, and flagship peak selection. |
age_months and repo chronology | Control ridge softness, erosion width, and reveal ordering for animated timelines. |
languages | Partition biome palette, terrain texture, and survey ornament. |
contributions_monthly | Feed route intensity, timeline density, and expedition-style overlays. |
followers, forks, network_count | Add contour density, tributaries, crossings, and collaborative chrome. |
topic_clusters | Produce named peaks, valleys, corridors, and annotation clusters. |
commit_hour_distribution, issue_stats, star_velocity | Influence hillshade angle, weather overlays, and atmosphere. |
Entry point
from scripts.art.topography import generate
svg = generate(metrics, seed="portfolio-map", maturity=0.9, timeline=True)| Parameter | Type | Notes |
|---|---|---|
metrics | dict | Normalized metrics snapshot with repo and contribution data |
seed | str | None | Optional deterministic seed override |
maturity | float | None | Controls how fully the terrain and chrome resolve |
chrome_maturity | float | None | Lets labels and decorative cartography lag or lead terrain growth |
timeline | bool | When True, injects CSS reveal timing into the SVG |
loop_duration | float | Full loop length for timeline mode |
reveal_fraction | float | Share of the loop reserved for staged reveals |
Timeline versus static export
Topography has a stricter split between authored animation and export-safe output than the animated pair:
timeline=Trueenables CSS-driven reveal choreography and treats the terrain as fully mature while the map animates into view.timeline=Falseproduces a static composition with no timeline CSS injected. This is the mode used for frame rendering inscripts/art/animate.pyand for contexts that flatten animation.
That behavior is visible in the implementation through timeline_enabled = bool(timeline and loop_duration > 0). When the timeline is disabled, the generator keeps the requested maturity instead of forcing the map to full growth for animation staging.
Why static export matters here
Topography carries dense labels, contour lines, and route overlays. Flattened viewers can make animated timing unreadable, so the generator supports a clean static composition instead of assuming every consumer can replay the timeline.
World-state influence
Topography reads WorldState to keep its atmosphere aligned with the other living-art systems:
time_of_daysteers hillshade angle and color temperatureweatherdrives fog, haze, and warning-style overlaysseasonnudges biome palette selectionenergyandvitalityinfluence accent intensity and route presence
Outputs in the living-art lane
| File | Meaning |
|---|---|
.github/assets/img/living-topo.gif | Canonical Topography timelapse GIF published by the current CLI/workflow contract |
.github/assets/img/living-art-manifest.json | Manifest regenerated from discovered living-*.gif files |
.github/assets/img/living-art-preview.html | Preview gallery regenerated from the same timelapse files |
Legacy topo-growth* assets may still be checked in as showcase collateral, but they are not the current generated contract.