# 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

```sh
docker compose up --build
```

Then open <http://localhost:58881/>.

## Run locally

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

```sh
python3 -m http.server 58881
```

Open <http://localhost:58881/>.

## Configuration

Edit `config.js` and reload the page:

```javascript
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.:

```javascript
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`:

```javascript
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/>