UniSky

Tiles that carry data, not pictures.

Turn heterogeneous astronomical survey data into an interactive, WCS-aware web map.

unisky.cc · Documentation · Technical report · Source · Changelog

Abell 2744. Critical curves and caustics from the UNCOVER lens model at z_s = 3, over a JWST/NIRCam colour image with the observed multiple images marked.

UniSky puts FITS images on any WCS, colour composites, catalogues, contours, DS9 regions, footprints and strong-lensing models on one map, in the spirit of the DESI Legacy Survey viewer and as a more capable replacement for FitsMap. A build is a folder of static files; serve it from one machine or from object storage.

Install

Python 3.11 or newer.

pip install unisky

Quickstart

No local data and no checkout are needed. Save this as abell2744.yaml: three DESI Legacy Survey DR11 bands and the Tractor catalogue for Abell 2744, downloaded on the first build (about 16 MB, about half a minute) and cached afterwards.

field:
  name: Abell 2744
  grid: {ra0: 3.5862, dec0: -30.4003, scale_arcsec: 0.262, width: 1100, height: 1100}

layers:
  - id: g
    type: image
    title: DESI-LS g
    source: {survey: legacy, release: dr11, band: g, ra: 3.5862, dec: -30.4003, width_arcmin: 5}
  - id: r
    type: image
    title: DESI-LS r
    source: {survey: legacy, release: dr11, band: r, ra: 3.5862, dec: -30.4003, width_arcmin: 5}
  - id: z
    type: image
    title: DESI-LS z
    source: {survey: legacy, release: dr11, band: z, ra: 3.5862, dec: -30.4003, width_arcmin: 5}
  - id: grz
    type: composite
    title: grz
    channels: {r: z, g: r, b: g}
    visible: true
  - id: tractor
    type: catalog
    title: Tractor sources
    source: {survey: legacy, release: dr11, ra: 3.5862, dec: -30.4003, width_arcmin: 5, columns: [mag_r]}
    popup: [ra, dec, mag_r]

unisky build abell2744.yaml -o site/ && unisky serve site/

Then open http://127.0.0.1:8000/. Eight layer types, each one entry in the config: image, composite, catalog, contour, region, prerendered, footprint and lensmodel. The configuration reference has the rest.

Commands

unisky build config.yaml -o site/     # ingest data, write a self-contained site
unisky serve site/                    # static files + the science API
unisky add config.yaml -o site/ ID    # build one more layer into a built site
unisky remove -o site/ ID             # take one back out
unisky capabilities site/             # show or set what a deployment offers (--no-cutout, --static)
unisky refresh site/                  # new viewer + content versions; no tile rebuilt

Each is described in the command-line reference.

What it does

• Data tiles. Image tiles are quantised 16-bit data, not pictures: black and white point, stretch function (linear, sqrt, log, asinh, power) and colormap change instantly in the browser, with no refetch and no server. The Stretch window draws a histogram of the decoded tiles, with draggable black and white marks.
• Any WCS in, one map out. Images on TAN, SIN, CAR and other grids are reprojected onto one gnomonic display grid, for display only; science operations use the native pixels.
• Native-grid cutouts. The cutout API returns FITS whose pixels are bit-identical to the source, with a correctly shifted WCS.
• Catalogues. Configurable popups, a joined second table, markers coloured by any column and hover highlight. search: columns make sources findable from the go-to box, and the Sources window (T) filters, sorts and steps through the catalogue with the arrow keys, with a preview stamp on hover.
• Vector overlays. Contours with sigma-scaled levels traced in the native pixel grid, DS9 region files and footprints.
• Strong lensing, live. Critical curves and caustics with a source-redshift slider, magnification at the cursor, counter-image prediction with time delays when the model carries a potential, and κ and μ as map layers (glafic-convention models).
• Composite RGB. Each channel is one band or a weighted sum, combined per channel or by Lupton's rule, in the same grammar the viewer's RGB panel reads and prints: a composite designed in the browser pastes into the config.
• Remote data. Legacy Survey cutouts, HiPS and TAP catalogues are downloaded and cached, so a config can name no local file at all.
• Incremental builds. Add or remove layers of a built site without touching the rest; the display grid is reused exactly, and a conflicting config is refused with the fix spelled out.
• Deployment. One machine with uvicorn and nginx, or static object storage (Cloudflare R2) with /api through a tunnel. A site declares which of cutout and lensing it offers and the viewer hides what a deployment cannot serve. Tile and overlay URLs are keyed by content, so a rebuilt layer reaches browsers that cached the old one.
• In the browser. Permalinks in the URL hash, so a view is a link; coordinate readout; a go-to box that takes decimal or sexagesimal; uploads of your own regions and catalogues; optional basic auth; and a phone layout at 720 px and narrower in which every panel is a bottom sheet.

Documentation

• Reference: install · quickstart · how it works · configuration · layer types · the viewer · command line · HTTP API · permalinks · the data tile · the display grid · lensing engine · remote data · add and remove · deployment · troubleshooting
• Notes in the repository: parallel builds and progress · deployment · incremental builds · reprojection · remote data · composites · prerendered images · alignment · lens-model normalisation · uploads · development and testing · the viewer bundle · upgrading from AnyMap
• Technical report: the tile format and its error characteristics, the display grid, the lensing engine and the incremental build model.
• Changelog.

License

BSD-3-Clause, see LICENSE. Written by Mingyu Li.