skygrad 1.0.0__tar.gz

skygrad-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      # Full supported range (requires-python >=3.11). Goldens are compared
+      # byte-exact on every leg: on one ubuntu image the four CPythons share a
+      # libm, so identical pixels across versions is the determinism contract
+      # holding, and a divergence is a real signal, not flake. mypy runs under
+      # each interpreter, so it type-checks against each version too.
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest -q

skygrad-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC): no stored API token. PyPI verifies this repo +
+# workflow via a short-lived OIDC token and issues a short-lived upload
+# credential; PEP 740 attestations are generated automatically. Triggered by
+# publishing a GitHub Release — that human action is the deliberate gate.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/skygrad
+    permissions:
+      id-token: write          # REQUIRED: lets the job mint the OIDC token
+      contents: read           # checkout
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - run: uv build                                   # sdist + wheel into dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1    # uploads dist/, no token

skygrad-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[oc]
+.venv/
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+dist/
+# Design scaffolding and generated review reports: kept local, not shipped.
+docs/
+.DS_Store
+*.egg-info
+!uv.lock

skygrad-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

skygrad-1.0.0/ARCHITECTURE.md

@@ -0,0 +1,64 @@
+# skygrad architecture
+
+A pure, one-way pipeline that turns *(lat, lon, datetime)* into a PNG of the
+sky. The single most important fact about its shape: **output is deterministic
+to the decoded pixel for a fixed `MODEL_VERSION`, with no RNG anywhere** —
+nearly every rule below exists to protect that.
+
+## Component map
+
+Dependency arrows point strictly downward: a module may import those above it
+in this table, never below. `__init__` imports from all.
+
+| Component | Responsibility | Entry points |
+|---|---|---|
+| `color.py` | sRGB ↔ linear ↔ Oklab conversions + interpolation (stdlib only) | `hex_to_oklab`, `oklab_to_srgb`, `lerp3`, `Triple` |
+| `astronomy.py` | `(lat, lon, when_utc)` → solar `(elevation, azimuth)`; the only place naive datetimes are interpreted (stdlib only) | `to_utc`, `solar_position`, `solar_elevation` |
+| `palette.py` | The art console: `ANCHORS` (per-elevation stops) + `GLOW` tables + `MODEL_VERSION` (imports `color`) | `ANCHORS`, `GLOW`, `U_OFFSETS`, `MODEL_VERSION` |
+| `gradient.py` | `Sky`, the validation boundary, elevation→Oklab blending, row/pixel evaluation (imports all) | `Sky`, `Sky.at`, `render`, `write_png` |
+| `png.py` | Bayer dithering + minimal deterministic PNG encoder, flat + leveled (stdlib only) | `encode_rows`, `encode_leveled_rows` |
+| `__init__.py` | Public surface | `render`, `write_png`, `Sky`, `MODEL_VERSION`, `__version__` |
+
+## Invariants
+
+- **Dependency arrows point strictly downward.** Breaks: an upward import (e.g. `palette` importing `gradient`) couples the art console to the validation boundary and defeats isolation/testability.
+- **All input validation lives at the `gradient.py` public boundary; internals are total over clean inputs.** Breaks: an unvalidated value (NaN, out-of-range, `bool` as a dimension) reaches the math and yields garbage or an opaque error instead of a precise `ValueError`/`TypeError`.
+- **No RNG anywhere; dithering is positional (Bayer).** Breaks: any randomness makes output non-reproducible and silently breaks every consumer pinning goldens.
+- **`ANCHORS` are strictly ascending in elevation, each with exactly one stop per `U_OFFSETS` entry; `GLOW` has one entry per anchor elevation.** Breaks: equal adjacent elevations → `ZeroDivisionError` in bracket blending; mismatched stop counts → `zip(strict=True)` raises.
+- **Glow strength is exactly `0.0` at the −18° floor.** Breaks: the `strength == 0.0` short-circuit in `_png_facing` stops firing, and night renders are no longer byte-identical to the `facing=None` path.
+- **`facing=None` (and any facing at night) is byte-identical to the v1 vertical path; `encode_leveled_rows` at level 0 everywhere reproduces `encode_rows`.** Breaks: existing v1 goldens diverge and `MODEL_VERSION` must bump.
+- **Any change that alters a rendered color bumps `MODEL_VERSION`.** Breaks: consumers' pinned goldens diverge silently instead of failing deliberately.
+- **Compare decoded pixels, never compressed bytes.** Breaks: DEFLATE output varies across zlib builds, so byte comparison gives false negatives across environments.
+
+## Landmines
+
+- **`strength == 0.0` in `_png_facing` is a deliberate exact float compare**, not a smell — it is the night byte-identity short-circuit. Do not replace it with an epsilon comparison.
+- **The facing path is per-pixel and capped at `_FACING_MAX_PIXELS` (2048², ~4M px)** *on top of* the `[1, 16384]` per-dimension limit; the vertical path is per-row and keeps the full limit. Raising the cap raises a real worst case (~270M iterations / ~800 MB at 16384²), not just a validation number.
+- **Naive datetimes are local mean solar time (`UTC = naive − lon/15 h`), resolved only in `astronomy.to_utc`.** `solar_position` then re-applies longitude as `+4·lon` min; the two cancel for naive input — it is *not* a double-count.
+- **`to_utc` never raises**: out-of-range shifts clamp to `datetime.min`/`max`. Rendering produces a sky for any valid position/datetime; only the public boundary rejects.
+- **`solar_azimuth` is ill-conditioned near zenith passage** (elevation ≈ 90°). Fine for the glow (insensitive to azimuth there); unreliable for any other use at high sun.
+- **Solar position holds ±0.3° roughly 1800–2200**, degrades gracefully outside, never raises. No refraction correction (shifts apparent sunset ~3 min, invisible in a gradient).
+- **The Oklab→sRGB gamut clip is a per-channel clamp** (can shift hue, not preserve it). Harmless for the in-gamut palette; a wildly out-of-gamut tint would clip oddly.
+- **Determinism is pinned to one platform + interpreter per golden comparison.** Cross-platform last-ulp libm divergence is treated as a bug, not absorbed. Committed goldens were recorded on ubuntu/CPython 3.13; CI compares them byte-exact across CPython 3.11–3.14.
+
+## Flow
+
+`render(lat, lon, when)` → `Sky.at` (validate · resolve naive→UTC in `to_utc` · `solar_position` · clamp elevation to [−18°, +90°] · blend the two bracketing anchors per-stop **in Oklab**) → `Sky.png`:
+
+- **No `facing`:** each row's color at `u = (i + 0.5)/H`, Oklab → linear → gamma-encoded sRGB → `png.encode_rows` (8×8 Bayer dither) → bytes.
+- **With `facing`:** per-pixel separable great-circle weight `cosΔ(x,y) = P(y) + Q(y)·R(x)` → cosine-domain smoothstep → 64 levels → `png.encode_leveled_rows` (lerps base↔glow endpoints per row).
+
+The byte stream is exactly `IHDR` (8-bit, color type 2 RGB, no interlace) · `sRGB` (perceptual) · `IDAT` (zlib level 9) · `IEND` — no timestamps, no metadata. A caller never touches the math except through `Sky`.
+
+## Where to change X
+
+- **Re-art-direct a sky / add an anchor:** edit hex in `palette.py` `ANCHORS`/`GLOW` (keep the anchor invariants above), then regenerate goldens and bump `MODEL_VERSION`. Full ritual: THEORY.md §Making common changes; commands: README.md §Development.
+- **Solar math:** `astronomy.py`, validated against reference angles in `tests/test_astronomy.py` (±0.5°).
+- **Add a render parameter:** validate at the `gradient.py` boundary (follow the `_validate_*` helpers; reject `bool` and non-finite). If it changes output for existing inputs → `MODEL_VERSION` bump; if opt-in like `facing`, prove default-path byte-compat with a test.
+- **Add a Python version:** the matrix in `.github/workflows/ci.yml` (and `requires-python` in `pyproject.toml` if it is a new floor).
+
+---
+
+For *why* any of this is the way it is — the palette-over-physics choice, Oklab
+blending, the v1→v1.1 azimuthal-glow reversal, the determinism design — see
+THEORY.md. For install, build, test, and usage, see README.md.

skygrad-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christophe Pettus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skygrad-1.0.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: skygrad
+Version: 1.0.0
+Summary: Realistic sky gradient PNGs from latitude, longitude, and time
+Project-URL: Homepage, https://github.com/Xof/skygrad
+Project-URL: Source, https://github.com/Xof/skygrad
+Project-URL: Issues, https://github.com/Xof/skygrad/issues
+Author-email: Christophe Pettus <christophe.pettus@pgexperts.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astronomy,color,gradient,oklab,png,sky,solar
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# skygrad
+
+Realistic sky gradient PNGs from latitude, longitude, and time. Zenith at
+the top, horizon at the bottom — one color per row, or the sun's glow
+lobe across the frame when you pass `facing`. The sun's position
+drives every color in the image; the sun itself is never drawn — no disc,
+no moon, no stars, no clouds. Zero runtime dependencies.
+
+![24 hours over Los Angeles](assets/contact-sheet.png)
+
+## Usage
+
+```python
+from datetime import datetime
+import skygrad
+
+# One-shot PNG bytes
+png = skygrad.render(lat=34.05, lon=-118.24,
+                     when=datetime(1994, 6, 21, 19, 30),
+                     width=512, height=1024)
+
+# Or write straight to a file
+skygrad.write_png("dusk.png", lat=34.05, lon=-118.24,
+                  when=datetime(1994, 6, 21, 19, 30))
+
+# Layered access: colors without pixels
+sky = skygrad.Sky.at(lat=34.05, lon=-118.24, when=datetime(1994, 6, 21, 19, 30))
+sky.solar_elevation          # degrees; e.g. streetlights on below -4
+sky.color(0.0)               # (r, g, b) at the zenith; 1.0 is the horizon
+sky.stops()                  # [(u, (r, g, b)), ...] — build a CSS gradient
+```
+
+## Facing (azimuthal glow)
+
+Pass a compass direction and the image gains the sun's glow lobe —
+brightest toward the sun, fading with angular distance, gone when you
+face away. Without `facing`, output is byte-identical to skygrad 0.1.
+
+```python
+sky = skygrad.Sky.at(lat=34.05, lon=-118.24, when=datetime(1994, 6, 21, 19, 40))
+sky.solar_azimuth                      # ≈ 303° at this dusk — west-northwest
+toward = sky.png(facing=sky.solar_azimuth)            # sunset glow, centered
+away = sky.png(facing=(sky.solar_azimuth + 180) % 360)  # plain dusk gradient
+wide = sky.png(facing=0.0, fov=360.0, width=2048)     # full panorama strip
+```
+
+`facing` is degrees clockwise from true north (any finite value,
+normalized mod 360; radians callers use `math.degrees()`). `fov` is the
+horizontal span in degrees, default 90, valid (0, 360] — and requires
+`facing`.
+
+A facing render is computed per pixel, so it's capped at ~4 million pixels
+(`width × height ≤ 2048×2048`); go larger and it raises `ValueError`. Tile,
+shrink, or drop `facing` (the plain vertical gradient is per-row and has no
+such cap). Requires Python 3.11+.
+
+![24 hours facing the sunset](assets/contact-sheet-facing.png)
+
+## Time semantics (read this)
+
+`when` is a full datetime — the **date matters** (June and December at the
+same hour give completely different skies).
+
+- **Timezone-aware** datetimes are honored exactly.
+- **Naive** datetimes mean **local mean solar time** at the given
+  longitude: sundial time, where 12:00 puts the sun on the meridian.
+  This is deliberate — it makes "local" meaningful for fictional places —
+  but it can differ from civil wall-clock time by an hour or more. If you
+  want wall-clock local time, attach a tzinfo.
+
+## Determinism
+
+Same inputs → same decoded pixels for a given `skygrad.MODEL_VERSION`
+(and byte-identical PNGs within one zlib build). `MODEL_VERSION` bumps
+whenever any input would render different colors, so golden tests in
+consumers break deliberately, never silently. Compare decoded pixels,
+not compressed bytes.
+
+## Development
+
+    uv sync
+    uv run ruff check . && uv run ruff format --check .
+    uv run mypy
+    uv run pytest -q
+
+Golden skies are pinned under `tests/golden/`; regenerate deliberately
+with `uv run pytest --regen-golden` and bump `MODEL_VERSION` if colors
+changed. Regeneration rewrites all ten goldens, but on one zlib build the
+untouched ones are byte-identical rewrites — so a deliberate single-color
+change surfaces as exactly the goldens it should. The module map and
+invariants live in `ARCHITECTURE.md`, and the design
+rationale (theory of operation) in `THEORY.md`.

skygrad-1.0.0/README.md

@@ -0,0 +1,92 @@
+# skygrad
+
+Realistic sky gradient PNGs from latitude, longitude, and time. Zenith at
+the top, horizon at the bottom — one color per row, or the sun's glow
+lobe across the frame when you pass `facing`. The sun's position
+drives every color in the image; the sun itself is never drawn — no disc,
+no moon, no stars, no clouds. Zero runtime dependencies.
+
+![24 hours over Los Angeles](assets/contact-sheet.png)
+
+## Usage
+
+```python
+from datetime import datetime
+import skygrad
+
+# One-shot PNG bytes
+png = skygrad.render(lat=34.05, lon=-118.24,
+                     when=datetime(1994, 6, 21, 19, 30),
+                     width=512, height=1024)
+
+# Or write straight to a file
+skygrad.write_png("dusk.png", lat=34.05, lon=-118.24,
+                  when=datetime(1994, 6, 21, 19, 30))
+
+# Layered access: colors without pixels
+sky = skygrad.Sky.at(lat=34.05, lon=-118.24, when=datetime(1994, 6, 21, 19, 30))
+sky.solar_elevation          # degrees; e.g. streetlights on below -4
+sky.color(0.0)               # (r, g, b) at the zenith; 1.0 is the horizon
+sky.stops()                  # [(u, (r, g, b)), ...] — build a CSS gradient
+```
+
+## Facing (azimuthal glow)
+
+Pass a compass direction and the image gains the sun's glow lobe —
+brightest toward the sun, fading with angular distance, gone when you
+face away. Without `facing`, output is byte-identical to skygrad 0.1.
+
+```python
+sky = skygrad.Sky.at(lat=34.05, lon=-118.24, when=datetime(1994, 6, 21, 19, 40))
+sky.solar_azimuth                      # ≈ 303° at this dusk — west-northwest
+toward = sky.png(facing=sky.solar_azimuth)            # sunset glow, centered
+away = sky.png(facing=(sky.solar_azimuth + 180) % 360)  # plain dusk gradient
+wide = sky.png(facing=0.0, fov=360.0, width=2048)     # full panorama strip
+```
+
+`facing` is degrees clockwise from true north (any finite value,
+normalized mod 360; radians callers use `math.degrees()`). `fov` is the
+horizontal span in degrees, default 90, valid (0, 360] — and requires
+`facing`.
+
+A facing render is computed per pixel, so it's capped at ~4 million pixels
+(`width × height ≤ 2048×2048`); go larger and it raises `ValueError`. Tile,
+shrink, or drop `facing` (the plain vertical gradient is per-row and has no
+such cap). Requires Python 3.11+.
+
+![24 hours facing the sunset](assets/contact-sheet-facing.png)
+
+## Time semantics (read this)
+
+`when` is a full datetime — the **date matters** (June and December at the
+same hour give completely different skies).
+
+- **Timezone-aware** datetimes are honored exactly.
+- **Naive** datetimes mean **local mean solar time** at the given
+  longitude: sundial time, where 12:00 puts the sun on the meridian.
+  This is deliberate — it makes "local" meaningful for fictional places —
+  but it can differ from civil wall-clock time by an hour or more. If you
+  want wall-clock local time, attach a tzinfo.
+
+## Determinism
+
+Same inputs → same decoded pixels for a given `skygrad.MODEL_VERSION`
+(and byte-identical PNGs within one zlib build). `MODEL_VERSION` bumps
+whenever any input would render different colors, so golden tests in
+consumers break deliberately, never silently. Compare decoded pixels,
+not compressed bytes.
+
+## Development
+
+    uv sync
+    uv run ruff check . && uv run ruff format --check .
+    uv run mypy
+    uv run pytest -q
+
+Golden skies are pinned under `tests/golden/`; regenerate deliberately
+with `uv run pytest --regen-golden` and bump `MODEL_VERSION` if colors
+changed. Regeneration rewrites all ten goldens, but on one zlib build the
+untouched ones are byte-identical rewrites — so a deliberate single-color
+change surfaces as exactly the goldens it should. The module map and
+invariants live in `ARCHITECTURE.md`, and the design
+rationale (theory of operation) in `THEORY.md`.