animated_wallpaper/README.md

Animated Background

An animated desktop background that runs in a browser. Features:

• Time-of-day simulation with realistic color gradients driven by the actual sun position (computed from latitude/longitude via SunCalc).
• WebGL flight scene (vendor/clouds3d.js): raymarched cloud deck, 3D terrain from Copernicus DEM, real star sky (Yale BSC + Milky Way), moon with phases, animated highway car lights and settlement lights from OpenStreetMap/Overpass at night.
• Night brightness coupled to the moon phase (new moon = minimum, full moon = maximum), with a configurable minimum so the night is never pitch-black.
• Live weather widget (Open-Meteo) showing current conditions and a 4-day forecast (morning, evening, full) at every timestamp.
• Configurable units (metric °C+km/h or imperial °F+mph).
• Configurable language (with English as the base; translations for German, Italian, Spanish, French, and Russian).
• Configurable color theme (Ash, Gruvbox, Nord) - drop a new *.css file in the same directory and add an entry to window.THEMES to add a new theme.
• Customisable location: set CONFIG.location.lat/lon, or let the browser's geolocation API pick one up automatically (falls back to the built-in default Passau).
• Optional custom location label (CONFIG.location.label) that overrides the OpenStreetMap reverse-geocoding lookup.
• Configurable digital clock format string using ISO-8601-ish tokens (YYYY, MM, DD, HH, mm, ss, DDD, DDDD, MMM, MMMM, a, A, sss, T, escape sequences \n \t \, and full weekday/month names via the i18n dict).
• Configurable debug panel (toggle collapse/expand with theme, units, and language dropdowns that apply at runtime).

Run with Docker

docker compose up --build

Then open http://localhost:58881/.

Run locally

The app is a single HTML page. With any static file server:

python3 -m http.server 58881

Open http://localhost:58881/.

Configuration

Edit config.js and reload the page:

window.CONFIG = {
    debug: 0,                          // 0 = hide debug panel, 1 = show
    theme: 'ash',                      // 'ash' | 'gruvbox' | 'nord'
    units: 'metric',                   // 'metric' | 'imperial'
    language: 'de',                    // 'en' | 'de' | 'it' | 'es' | 'fr' | 'ru'
    timeFormat: 'DD. MMMM, YYYY \u2012 HH:mm:SS',
    location: {
        lat: 48.5667,                  // latitude,  -90 to +90, north positive
        lon: 13.4319,                  // longitude, -180 to +180, east positive
        label: ''                       // optional custom place name;
                                       // if set, skips reverse-geocoding
    },
    orbit: {                           // omit/null = straight-line flight
        radiusKm: 15,                  // circular flight around location;
                                       // clamped to ~50 km at zoom 11
        clockwise: true                // turn direction
    }
};

Adding a new language

Edit i18n.js and add entries for each existing key under your new language code, e.g.:

window.TRANSLATIONS['Sunrise']['xx'] = 'MyTranslation';

Adding a new theme

Drop a new *.css file next to the others and add an entry to window.THEMES:

window.THEMES['mytheme'] = 'mytheme.css';

Time format tokens

YYYY   4-digit year          (2026)
MM     month 01-12          (10)
DD     day 01-31            (07)
HH     hour 00-23 (24h)     (14)
mm     minute 00-59        (35)   lowercase!
ss     second 00-59        (22)   lowercase!
sss    millisecond 000-999 (456)
a      am/pm (lowercase)   (pm)
A      AM/PM (uppercase)   (PM)
T      literal 'T'

MMM    month short name     (Oct, Okt, Ott, ...)
MMMM   month full name      (October, Oktober, ...)
DDD    weekday short name   (Mon, Mo, Lu, ...)
DDDD   weekday full name    (Monday, Montag, ...)

\n     newline
\t     tab
\\     literal backslash

Files

.
├── background.html         the page (formerly index.html)
├── config.js                user-facing configuration
├── i18n.js                  translation strings (en/de/it/es/fr/ru)
├── ash.css                  default color theme
├── gruvbox.css              alternative color theme
├── nord.css                 alternative color theme
├── vendor/                  vendored third-party files (no network needed)
│   ├── clouds3d.js          WebGL scene: raymarched clouds, 3D terrain,
│   │                        real sun/moon/stars, car + city lights
│   ├── suncalc.js           ISC (SunCalc by mourner)
│   ├── stars.json           Yale Bright Star Catalogue subset
│   └── LICENSE              per-library license attributions
├── default.conf             nginx server config (port 58881, tile CORS proxies)
├── Dockerfile               builds nginx:alpine image
└── docker-compose.yml          one-service Compose file

Licenses

• Background application code: MIT
• SunCalc (vendored): ISC - https://github.com/mourner/suncalc
• Open-Meteo (weather API): CC BY 4.0 - https://open-meteo.com/
• OpenStreetMap (basemap tiles, Overpass road/place data): ODbL - https://www.openstreetmap.org/copyright
• Copernicus DEM (terrain via terrarium tiles): open data
• NASA GIBS VIIRS (optional night-lights overlay): public domain
• OpenStreetMap Nominatim (reverse geocoding): ODbL - https://nominatim.org/release/