unisky 0.2.0__tar.gz

unisky-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build*/
+node_modules/
+frontend/.vite/
+.e2e-build/
+.DS_Store
+.venv/
+tests/fixtures/rxcj2211_mini/
+frontend/test-results/
+frontend/playwright-report/
+# page snapshots the Playwright MCP server drops beside the cwd
+.playwright-mcp/
+.history
+
+# wrangler caches the Cloudflare account it authenticated as; never publishable
+.wrangler/
+# agent worktrees: a whole second copy of the tree, never publishable
+.claude/worktrees/

unisky-0.2.0/CHANGELOG.md

@@ -0,0 +1,386 @@
+# Changelog
+
+All notable changes to UniSky are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.2.0] - 2026-08-23
+
+### Changed
+
+- **The project is now called UniSky.** It was AnyMap; that name is taken on
+  PyPI. The rename is complete rather than aliased — there is no compatibility
+  shim anywhere — so an existing checkout, cache and built site each need one
+  action:
+
+  | was | is |
+  |---|---|
+  | `pip install anymap`, `import anymap` | `pip install unisky`, `import unisky` |
+  | `anymap build` / `serve` / `add` | `unisky build` / `serve` / `add` |
+  | `$ANYMAP_CACHE`, `$ANYMAP_OFFLINE`, `$ANYMAP_SCRATCH` | `$UNISKY_CACHE`, `$UNISKY_OFFLINE`, `$UNISKY_SCRATCH` |
+  | `manifest.json` key `anymap_version` | `unisky_version` |
+  | catalog overlay marker `"AnyMapCatalog"` | `"UniSkyCatalog"` |
+  | `localStorage` keys `anymap.*` | `unisky.*` |
+
+  - **Reinstall the console script.** The old `anymap` entry point belongs to
+    the old distribution: `pip uninstall -y anymap && pip install -e ".[dev]"`.
+    Without `-y`, `pip uninstall` stops to ask, and outside an interactive
+    terminal it dies on the prompt and the `&&` never runs.
+  - **MERGE the download cache — do not let it be re-fetched, and do not
+    `mv` it.** It holds real archive downloads (DESI cutouts, HiPS tiles, TAP
+    answers), and the code does not look at the old path:
+
+    ```bash
+    # keeps whichever copy of a file is newer, and says what it moved;
+    # correct whether or not ~/.cache/unisky already exists
+    rsync -a --update --itemize-changes ~/.cache/anymap/ ~/.cache/unisky/
+    ```
+
+    `mv ~/.cache/anymap ~/.cache/unisky` — which earlier drafts of this entry
+    and of the README recommended — is correct only while the destination
+    does not exist. Once it does, and it does from the first `unisky build`
+    onwards, `mv` nests the old cache at `~/.cache/unisky/anymap/`, where
+    `cache_root()` never looks: it strands exactly the data it was meant to
+    save, and exits 0. Both trailing slashes above are load-bearing.
+
+    Nothing inside it changes; the cache key is the canonical request URL.
+    See [docs/remote-data.md](docs/remote-data.md).
+  - **Rebuild built sites.** `manifest.json` carries `unisky_version` and
+    nothing reads the old key, so `unisky serve` and `unisky add` refuse a
+    pre-rename site with a message that names the rebuild, and so does the
+    viewer. Rebuild with `unisky build <config.yaml> -o <site>`; configs
+    themselves are unchanged apart from any `$ANYMAP_*` they mention.
+  - Saved viewer state in the browser (theme, window positions) lives under
+    renamed `localStorage` keys and starts from the defaults once.
+
+- **A broken config is now a message for a person, not a traceback.** A YAML
+  syntax error is reported with the line, the column, the offending source
+  line and a caret under it. A config that parses but does not validate is
+  refused with **every** problem at once, each carrying the line it is on, the
+  field path, the layer's `id`, and the nearest known name when there is one:
+
+  ```
+  Error: config.yaml is not a valid UniSky config; 2 problems.
+
+  the config file:
+    /home/you/fields/config.yaml
+
+  what to do:
+    - line 31, layers[3].channels.g (layer 'rgb'): term 'half*f200w' has
+      no numeric weight: 'half' is not a number. Write it as
+      '<weight>*<layer id>', for example '0.5*f322w2'
+    - line 32, layers[3].lupton.q (layer 'rgb'): unknown key 'q' - did you
+      mean 'Q'?
+  ```
+
+  A file the config names but that cannot be read is caught the same way, in
+  one pre-flight pass before any work starts — every missing path at once,
+  resolved and printed in full, with nothing built and nothing written.
+  `--traceback` still prints the Python one underneath, and a failure that
+  looks like a bug in UniSky prints one anyway.
+
+- **Config errors, unreadable files and archive failures are all laid out the
+  same way**: what happened, then the file, URL or directory it happened to,
+  then what to do about it — hard-wrapped to a fixed 72 columns (not
+  `$COLUMNS`, so the text reads the same wherever it lands), except that a
+  path, URL or command is left on its own line however long it is, because
+  wrapping one breaks copy-paste. It replaces the 1096-character single line
+  one of them used to be. A test reads every refusal in the package out of the
+  source and holds it to that layout, so one written tomorrow is covered the
+  moment it is written.
+
+### Added
+
+- **`unisky add` and `unisky remove`: one more layer into a site that is
+  already built, and one back out.** A full-field build is minutes and
+  gigabytes, and a region file that turns up afterwards should not cost that
+  twice.
+
+  ```bash
+  unisky add config.yaml -o build/ lrd_msa   # build ONE more layer in place
+  unisky remove -o build/ lrd_msa            # ...and take it back out
+  ```
+
+  `add` builds only the layers you name, splices them into `manifest.json` in
+  **config order**, and leaves every other layer's tiles byte for byte as they
+  were. `remove` is the inverse and takes **no config at all**: what a layer
+  owns, and which composites are rendered from it, are read from the site's
+  own manifest — so a layer can leave the site before, after, or instead of
+  leaving the config. Both refuse rather than corrupt a site (a config that no
+  longer describes its display grid; a layer that misses the grid; a channel
+  whose composite would be left showing pixels it no longer has; the last
+  image layer), and `--dry-run` runs every check without writing a byte.
+
+  **The display grid never moves.** It is derived once, when the site is
+  built, from the union of every image layer's footprint, and every tile on
+  disk is addressed by it — so `add` reads the grid out of `manifest.json` and
+  reuses it exactly rather than re-derive it, and `remove` leaves it as wide
+  as it was even when the widest layer goes. Only `unisky build` derives a
+  grid. Remove a layer, add it straight back, and the site is the same bytes.
+  See [docs/incremental.md](docs/incremental.md).
+
+- **A site now says what its DEPLOYMENT can offer, so one build can feed two.**
+  `manifest.json` grows `serve.cutout` and `serve.lensing`, and `unisky build`
+  grows three flags that set them without the config being edited between the
+  full internal site and the copy going somewhere poorer:
+
+  ```bash
+  unisky build config.yaml -o site/                # both on: the full server
+  unisky build config.yaml -o site/ --no-cutout    # has the folder, not the data
+  unisky build config.yaml -o site/ --static       # --no-cutout --no-lensing
+  ```
+
+  **Two switches and not one**, because the two server-side features do not
+  need the same machine. A cutout re-opens the ORIGINAL FITS at request time,
+  by the absolute path in the layer's `native` block, so it needs the dataset
+  on the serving host — often terabytes that were never in the build folder.
+  The lensing endpoints read only the `.npy` grids the build already wrote
+  *inside* the folder, so they need a Python process and nothing else. A small
+  server holding the build and none of the data behind it can therefore do one
+  and not the other, and one switch could not have said that. Both default to
+  **true**, and a manifest carrying neither key — every site built before this
+  round — keeps meaning "everything, as before".
+
+  The flags are **negative only**: the config's `serve:` block is the ceiling,
+  and a build of it may be poorer, never richer.
+
+- **`unisky capabilities <site>`: the two booleans, on a site already built.**
+
+  ```bash
+  unisky capabilities site/            # with no flags: what does it offer?
+  unisky capabilities site/ --static   # about to be uploaded to object storage
+  unisky capabilities site/ --lensing  # ...and back up again, a month later
+  ```
+
+  No config, no rebuild, and not one tile read or written: `manifest.json` is
+  republished by the same same-directory temp plus atomic rename that `add` and
+  `remove` use, so this is as cheap on a 300 GB site as on an empty one and an
+  interrupted run leaves the site exactly as it was. A new subcommand rather
+  than a flag, because every existing command needs something this does not (a
+  config, forty minutes, artifacts to delete, a process that outlives nothing),
+  and a **noun** because with no flags it changes nothing and reports what the
+  site offers — the question anyone asks before pushing a folder somewhere.
+
+  Here, and only here, a capability may go back **up**: this is the site's
+  declaration being written rather than read, and the way back from a flag
+  typed at the wrong directory must not be a second forty-minute build. Putting
+  cutouts back checks that the FITS this site names are readable here and
+  **warns rather than refuses** — a deployment folder is usually prepared
+  somewhere other than where it will be served.
+
+  A `--static` build still ships `lens/**` on purpose: it is what lets
+  `--lensing` turn lensing back on later without rebuilding, and it makes a
+  flipped site **byte-identical** to one rebuilt with the same shape, manifest
+  included.
+
+- **Everything else agrees with the manifest, and only ever downward.**
+  `unisky serve` mounts each API router only when its flag is true; what takes
+  a router's place is a short **404** naming the flag — 404 and not 501 or 503,
+  because the object-storage copy of the same folder answers 404 and nothing
+  can change that, so one status means one thing and a client needs one code
+  path instead of two. `unisky serve --no-cutout` / `--no-lensing` / `--static`
+  lower a full build for one process and cannot raise one — there is no
+  `--cutout` to type — and a lowered process serves a lowered `manifest.json`
+  too, since the viewer decides what to offer from that document. `unisky add`
+  re-derives the block from the config like everything else and then **floors
+  it** with what the site already declares, saying so when the floor bites: a
+  rebuilt layer is not a reason for the FITS to have arrived on the server.
+
+- **In the viewer, a feature the deployment cannot serve is ABSENT, not greyed
+  out.** `src/capabilities.ts` is the one place the two booleans are read, and
+  only a literal `false` takes a feature away — a missing block, a null, a
+  string left by a hand-edit all read as "available", because that is what they
+  have always meant. What goes with it is every way to ask: no panel, no dock
+  button, no remembered "was open last visit" (all three come from one
+  `registerWindow` that is never called), no menu item, and no accelerator in
+  the key map — *unbound* rather than bound to a no-op, so the letter does
+  nothing rather than quietly doing nothing. `api.ts` refuses on its own too,
+  before a request is built, because unreachable has to be a property of the
+  module and not of one wiring. The Tools menu drops the separators that had
+  been holding the removed items' places rather than opening on a rule with
+  nothing above it.
+
+  The keys describe the **machine, not the science**: `lensing: false` does not
+  mean the field has no lens model. Its kappa and mu tiles are ordinary picture
+  tiles and keep being drawn, the layer census still counts the model, and the
+  About window says the same words on every site. What goes is every way to ask
+  a question this deployment cannot answer.
+
+  Both deployment stories — a collaboration server, and Cloudflare with the
+  tiles in R2 and `/api/*` on one hostname through a Tunnel — are now in
+  [docs/deploy.md](docs/deploy.md), which has been run end to end.
+
+- **`unisky build` builds several layers at once.** Layers are independent, so
+  images, catalogs, contours, regions and lens models run in parallel
+  processes, and whatever the layers cannot use goes to threads *inside* a
+  layer, parallelizing the reprojection bands and the tile encoding. `-j N` is
+  a total core budget (`-j 1` strictly serial, `-j 0` every core); the default
+  is the smaller of 75% of the cores and as many concurrent layers as fit in
+  half of RAM, so it stays sane on a 64-core box and on a laptop alike.
+  **The output does not depend on `-j`** — every choice writes byte-identical
+  tiles and the same manifest, whose layers stay in config order however the
+  build finishes, and the test suite builds the committed real-data fixture
+  serially and in parallel and compares every file's hash.
+
+- **A build shows what it is doing while it does it**: one in-place bar, plus
+  one line per layer *in flight* with its id, its stage, its progress within
+  that stage and how long it has been running; finished layers scroll off as
+  ordinary log lines, so the scrollback is still a build log. Progress is
+  **work-weighted**, not layer-counted — a full-resolution JWST layer writes
+  ~1000 tiles where a native-scale-capped IRAC layer writes ~80, so each
+  layer's cost is estimated up front from the decimated grid it will actually
+  tile — and the ETA is **withheld** until a tenth of that weighted work has
+  been measured, because dividing by a tiny fraction multiplies its error by
+  `(1-f)/f`. It degrades to one plain line per layer whenever stdout is not a
+  terminal or `TERM=dumb`; `--no-progress` forces that on a terminal too, and
+  `NO_COLOR` is honoured separately (the live display stays, the colour goes).
+  A Ctrl-C or a failing layer erases the frame and restores the cursor without
+  swallowing the error, and a build with the display on writes byte-identical
+  files to one with it off.
+
+- **Composite recipes in YAML gained the two things the viewer's RGB panel
+  already had.** A channel may be a **weighted sum** of image layers, and the
+  three channels may be combined by **Lupton**'s rule instead of one at a
+  time:
+
+  ```yaml
+  channels: {r: f322w2, g: 0.5*f322w2 + 0.5*f150w2, b: f150w2}
+  lupton: {stretch: 5, Q: 8}
+  ```
+
+  The sum is the two-filter trick — with only two wide bands there is no
+  middle filter for green, so green is synthesized — and weights are
+  relative, divided by their sum before mixing, so `1*a + 1*b + 1*c` is the
+  average of the three rather than three times the brightness. Lupton scales
+  all three channels by one common asinh factor derived from their mean, so a
+  bright core keeps the colour of its spectrum instead of saturating to white;
+  `lupton: {}` takes astropy's own defaults. Both are written exactly as the
+  RGB panel writes them, so a composite designed in the browser can be pasted
+  into a config and built — and `tests/test_composite.py` runs the viewer's
+  **own** TypeScript against the builder, whole pipeline, holding the two to
+  one display level. `examples/rxcj2211.yaml` carries a weighted composite for
+  the NIRCam wide pair. See [docs/composites.md](docs/composites.md).
+
+- **A stale viewer bundle can no longer be committed unnoticed.**
+  `src/unisky/static/` is a build product that lives in git — it is what
+  `unisky build` copies into every site and what the wheel ships — so a
+  frontend change that was not rebuilt reached every user as the old viewer.
+  That had happened three times, and each time a human noticed the wrong thing
+  on screen. `just build-fe` now writes `bundle-source.json` beside the
+  bundle, recording the SHA-256 of every file vite read and every file it
+  wrote; `just check-fe-fresh` — and the ordinary `pytest` run — recompute
+  both offline in well under a second and fail naming the files that moved and
+  the one command that fixes it. `vite build` empties the directory on its way
+  through, so a build that skips the stamping step leaves no stamp at all, and
+  no stamp fails loudly rather than passing quietly. See
+  [docs/frontend-bundle.md](docs/frontend-bundle.md).
+
+- Gravitational **time delays**: a lens model may now carry the lensing
+  potential (`maps.psi`, arcsec², glafic's `_pot` dump). With it,
+  `/api/lens/findimg` reports `delay_days` for every predicted counter-image
+  — the arrival time relative to the first image of that source — and the
+  lensing panel labels each image with it. `LensModel` grows
+  `fermat_potential()`, `time_delay_distance()` and `delay_days()`;
+  `/api/lens/models` and the manifest report `has_potential`.
+- The RGB window can now **build a weighted channel**: "+ band" adds a term
+  to a channel, each term gets a weight, and the channel becomes the weighted
+  sum the compositor already supported (previously reachable only by editing
+  the permalink by hand).
+
+### Fixed
+
+- **`docs/deploy.md` opened by naming two answers to a question that now has
+  three.** "The cutout API needs the original FITS files, so either build on
+  the server or mount the dataset at the same absolute path" was the whole
+  section, written before there was a third answer — publish the site without
+  cutouts and let the deployment say so. The section now names all three, and
+  the document goes on to the deployment the third one exists for. Nothing in
+  `docs/` or the README had mentioned `--no-cutout`, `--static`,
+  `serve.cutout`, `serve.lensing` or `unisky capabilities` at all.
+- **The README's figure for what an `mv` of the cache would strand was one
+  count too loose.** It said "68 MB in 68 files"; on the machine it describes
+  the number is 66 files, and the line now carries the one-line `diff` that
+  produces it, so the next person measures rather than trusts it.
+- **The README told you to destroy the cache it told you to keep.** Its
+  upgrade step was `mv ~/.cache/anymap ~/.cache/unisky`, which is right only
+  while the destination does not exist — and it exists from the first
+  `unisky build` onwards, after which `mv` nests the old cache at
+  `~/.cache/unisky/anymap/`, where `cache_root()` never looks. The command
+  stranded exactly the downloads it existed to preserve, and exited 0. It is
+  now an `rsync -a --update` merge that keeps whichever copy of a file is
+  newer, works whether or not the destination exists, prints what it moved,
+  and is followed by a `diff` that names anything left behind. Corrected in
+  the README, in this entry above, and in `docs/remote-data.md`.
+- **Three more things the README claimed that a real machine refuted.**
+  `python3 -m venv .venv` picks up Python 3.9 on stock macOS, below the
+  `>=3.10` two lines above it, and the failure that follows is pip 21.2.4
+  blaming `setup.py` — so the interpreter is now named and checked, and pip
+  upgraded, before anything is installed. `UNISKY_RXCJ2211=… just test` was
+  described as running the whole real-data set, which it cannot promise: it
+  says where the dataset is, and each test decides by opening a file. And a
+  grid-clash refusal was quoted verbatim from a version that no longer
+  existed; the quote is replaced by the `--dry-run` that prints the current
+  one. Running the rest of the file end to end from a fresh clone also turned
+  up `just e2e` needing `npx playwright install chromium`, which `just setup`
+  does not do, and `pip uninstall anymap` needing `-y` to survive a
+  non-interactive shell.
+
+- **The viewer's refusal of a pre-rename site expired after 60 seconds**,
+  leaving a blank black page with nothing in the console either. The three
+  toasts raised when `boot()` gives up — `manifest.json` unreachable, refused
+  for a missing `unisky_version`, or a throw on the way up — are not notices
+  on top of a working map; they are the whole page, so they now wait to be
+  dismissed instead of timing out. Ordinary toasts still fade after 5 s.
+- Restoring the lensing panel from its dock button drew no critical curve —
+  only the menu-bar route refreshed it. `WindowSpec` grows an `onShow` hook
+  that fires for every route back on screen.
+- **Coverage footprints drew as near-opaque slabs**, hiding the image they
+  are meant to be read against. The opacity slider's generic vector path
+  stamped `fillOpacity: opacity * 0.8` on every child of every overlay, so a
+  footprint's deliberately faint 0.07 fill (and a region's 0.6) was replaced
+  rather than scaled the moment the layer was enabled. It now scales each
+  overlay's OWN fill, remembered once so repeated slider ticks cannot
+  compound. Catalogs were already immune — they override `setOpacity` to
+  defend against exactly this — which is why it surfaced only with the new
+  `footprint` layers.
+- **Popups rounded coordinates to 4 significant digits**, so a source at
+  RA 332.952929 was shown as `333` — 169 arcsec out — and Dec −3.830160 as
+  `-3.83`. Coordinate columns are now printed to a fixed 6 decimals (3.6 mas)
+  with trailing zeros dropped; every other column keeps the 4-significant-
+  digit rule. Affects built-in and uploaded catalogues alike.
+- **A 64-bit catalogue id read `48420000000000000` for every source.** Two
+  independent bugs produced that one number. The popup printed an integer
+  verbatim only below 1e7 and sent everything above through a 4-significant-
+  digit rounding, so a DESI `ls_id` near 4.84e16 kept four digits and gained
+  sixteen zeros — and its neighbours, sharing those four digits, became the
+  same id. An identifier is a name that happens to be spelled in digits, so an
+  integer is now printed in full at any magnitude. Fixing the formatter alone
+  was not enough: 4.8e16 is five times past 2^53, so an id written as a JSON
+  *number* is already rounded by the time `JSON.parse` returns. The builder now
+  writes an integer outside JavaScript's safe range as a JSON **string** and
+  the viewer renders it as one; ordinary small integers stay numbers, so a
+  short id still sorts and compares numerically. Catalogues dropped onto the
+  map in the browser follow the same rule.
+
+## [0.1.0] - 2026-08-20
+
+First release.
+
+### Added
+
+- `unisky build`: config-driven builder producing a self-contained static
+  site — quantized 16-bit PNG data tiles with client-side stretch, composite
+  RGB tiles, catalog/contour/region GeoJSON overlays, and lens-model grids.
+- `unisky serve`: FastAPI server for the built site plus the science API:
+  native-grid FITS cutouts (`/api/cutout`) and strong-lensing endpoints
+  (`/api/lens/critcurve`, `/api/lens/mu`, `/api/lens/findimg`,
+  `/api/lens/models`); optional basic auth and CORS.
+- Leaflet + WebGL frontend with grouped layers, stretch/colormap panel,
+  catalog popups, coordinate readout and goto box, cutout tool, lensing
+  panel with z_s slider, and URL-hash permalinks.
+- RXCJ2211-0350 production example config (`examples/rxcj2211.yaml`) covering
+  JWST NIRCam, HST RELICS, ALMA continuum + contours, Spitzer IRAC, merged
+  photometry with EAZY photo-z join, DS9 regions, and the glafic v0.91 lens
+  model.
+- Real-data fixture subsampler (`scripts/make_test_field.py`), a committed
+  sub-3 MB tiny field, and a six-spec Playwright E2E suite.
+- Deployment guide (systemd + nginx + basic auth) and `just` dev targets.

unisky-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Mingyu Li
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.