What is a cell?
Imagine a transparent grid wrapped around the celestial sphere. A cell says “this patch is included.” A MOC stores the included cells, not the pixels of your science data.
Astro Survey Atlas / scientific core
Turn local sky evidence
into a map computers can compare.
MOC-Core-SDK turns reviewed local inputs into a standard map of sky coverage. It speaks ICRS, NESTED HEALPix, and IVOA FITS MOC so different projects can exchange the same spatial evidence.
You do not need to begin with the mathematics. Think of the sky as a globe covered by equal-area tiles: the Core decides which tiles are supported by your images, catalog, regions, or existing MOC, then writes the result in a deterministic form.
Reviewed local input
FITS / table / region / MOC
MOC-Core-SDK
validate / rasterize / canonicalize
IVOA FITS MOC
ICRS / NESTED / NUNIQ
Assets / Workspace / Warehouse
one shared spatial language
offlineafter snapshot lock
ICRSone celestial frame
NESTEDone cell ordering
FITSone authoritative artifact
01 / The beginner version
A MOC is a list of sky tiles
A Multi-Order Coverage map does not copy an image or catalog into a new service. It records which parts of the sky are covered, using a hierarchy of equal-area HEALPix cells.
order
The detail level. Every step splits one parent into four children.
nside = 2order
ipix
The pixel number inside one order. Together, order and ipix identify one nested cell.
0 ... 12 × 4order − 1
Offline calculator
How fine is one order?
The Core accepts orders 0–29. The calculator stops at 10 so the cell count remains easy to read.
02 / The contract
One core, several useful artifacts
The Core keeps one authoritative spatial result and derives the convenient views from it. That makes a preview easy to load without letting a preview pretend to be more precise than the source.
CoverageSpec
A validated recipe: layer identity, input mode, coverage meaning, source tier, maximum order, and the locked snapshot reference.
normalize_spec()
BuildResult
Canonical cells, an IVOA FITS MOC, fixed-order JSON projections, statistics, and redacted provenance.
build_layer()
Resource Package v3
A deterministic ZIP for releasing one or more MOCs with footprint metadata, provenance, and a human-readable README.
package build
01Validate firstReject a bad plan before source enumeration or credentialed I/O.
02Read locallyParse a locked snapshot or normalized input using one declared mode.
03NormalizeDeduplicate, remove covered descendants, and collapse complete sibling groups.
04PublishWrite stable FITS, projections, statistics, and redacted evidence.
The public Python surface
The package root keeps the normal path small. Lower-level helpers exist for conformance and package tooling, but callers can start with a recipe and a build.
Python / public API
from astro_survey_moc_core import (
CoverageSpec,
build_layer,
canonical_cells,
normalize_spec,
validate_moc_fits,
)
spec = normalize_spec(recipe)
result = build_layer(recipe, "build/", base_dir="snapshots")
validate_moc_fits(result.moc_path)
print(result.sha256, len(result.cells))A deliberate boundary: Core accepts local files or already parsed normalized inputs. Source connectors, authentication, remote byte ranges, release review, and online queries belong to the surrounding project.
03 / Input adapters
Choose the evidence you already have
Each mode turns one kind of local evidence into the same canonical cell language. The Core does not silently guess a different mode or invent a footprint when the evidence is missing.
fits-wcs
Image footprint from WCS
Reads a celestial 2D WCS from FITS or parsed JSON/JSONL headers. It samples the rectangle boundary, converts it to ICRS, and rasterizes it with mocpy.
Important: the rectangle is the model; masks and bad pixels are not inspected. Finite edge sampling is an approximation.
catalog-radec
Object positions from a catalog
Reads RA and Dec from FITS tables, JSON, JSONL, or CSV. RA wraps modulo 360; invalid or non-finite coordinates fail, while rows without coordinates are skipped.
Important: a non-positive radius marks point cells; a positive radius asks mocpy for cone coverage.
nested-healpix
Cells you already trust
Accepts a validated FITS/NUNIQ MOC or JSON/CSV cells. Every cell carries an explicit order and pixel, or scalar values are explicitly declared as uniq.
Important: the current nside conversion does not enforce that nside is a power of two.
regions
Shapes from a region file
Reads a DS9-style regions file or a safe ZIP containing flat .reg entries. Geometry conversion is delegated to regions and mocpy.
Important: the repository’s strongest tested path is ICRS DS9 regions; other frames depend on the upstream libraries.
tile-table
Pointings filtered by exposure
Uses table-like RA/Dec inputs with an optional NEXP threshold. It is useful when a survey inventory contains tile pointings and only sufficiently exposed tiles should contribute.
Important: the threshold filters rows; it does not turn a pointing table into a measured instrument footprint.
| Mode | Reads | Makes cells by | Boundary to remember |
|---|---|---|---|
fits-wcs | 2D celestial WCS | sampled polygon → mocpy | whole WCS rectangle |
catalog-radec | RA / Dec rows | HEALPix point or cone | occupancy, not object index |
nested-healpix | NUNIQ or cells | validate and normalize | ordering must be NESTED |
regions | DS9 / ZIP regions | upstream geometry → MOC | frame semantics are delegated |
tile-table | pointings + NEXP | filtered point or cone | threshold is not footprint truth |
04 / The algorithm lab
Three small rules make the result reproducible
These demos use the same integer rules as the Python implementation. They are intentionally small: the point is to see what the Core promises, not to replace scientific validation.
01 / canonical cells
Many descriptions, one answer
A parent covers all of its descendants. Four complete children can become their parent. The result is sorted, deduplicated, and independent of shard order.
Try removing 7/25 to see four order-8 siblings collapse into it.
02 / NUNIQ
Give a cell one integer ID
FITS stores one UNIQ value. The order is encoded in the size band; the pixel is the offset inside that band.
Decode a UNIQ
03 / fixed-order projection
Compare at one resolution
A finer cell maps to its containing coarse cell. A coarse cell expands to all descendants when a finer index is requested. That expansion adds candidates, not measurement detail.
Why not just use decimal coordinates?
Coordinates are excellent input, but cells give a shared, bounded vocabulary for intersection and indexing. The Core keeps the frame, ordering, and actual order explicit so a consumer never has to guess what a number means.
05 / From snapshot to release
Build once, inspect every artifact
The network step is explicit. After refresh locks a source snapshot and its SHA-256, the build path is offline and repeatable.
CLI / deterministic lifecycle
# The only network-enabled step
astro-survey-moc-core refresh \
--spec recipe.json --snapshot-dir snapshots --lock recipe.lock.json
# Everything after the lock reads local files
SOURCE_DATE_EPOCH=1787184000 astro-survey-moc-core rebuild \
--spec recipe.lock.json --base-dir snapshots --output build
astro-survey-moc-core project \
--moc build/layer.moc.fits --order 8 --output query-order8.json
astro-survey-moc-core package build \
--spec package.json --output release.zip<layer>.moc.fits
Authoritative IVOA FITS MOC: Primary HDU plus a MOC table with 64-bit NUNIQ cells.
query-order8.json
Fixed-order NESTED pixels for fast lookup. The default query order is 8.
preview-order4.json
A smaller overview projection. Upsampling it later cannot recover detail.
statistics.json + provenance.json
Counts, area, source identity, and redacted build context for investigation.
Repository fixture / CSST W1
simulation evidenceA real, bounded example
The conformance fixture records a reviewed union of simulated image inputs. Warehouse matched 178,056 image basenames; 178,055 were included after one pathological WCS input was excluded.
6,763order-8 cells
46order-4 preview cells
354.7589°²measured area
This is simulation evidence, not a formal CSST survey footprint. The project label “1000 square degrees” is not a measurement claim.
Read the frozen fixture notes ↗Resource Package v3
The release envelope is closed, deterministic, and inspectable without a service.
resource-package.json
mocs/<layer-id>.moc.fits
footprints/survey-footprints.json
provenance.json
README.mdThe validator checks traversal, symlinks, encryption, duplicates, undeclared files, MOC headers, sizes, and SHA-256 values. It also enforces 10,000 entries, a 512 MiB entry limit, and a 2 GiB total limit.
06 / Read the fine print
Useful evidence has honest boundaries
The Core is intentionally narrow. These limits are part of the product contract, not footnotes to hide after a result is published.
Canonical spatial coverage
ICRS spatial MOCs, NESTED cells, deterministic union/canonicalization, fixed-order projections, FITS I/O, statistics, provenance, and Resource Package v3 validation.
A cell is not a boundary proof
WCS uses finite boundary samples and models a rectangle. A cell intersection is a candidate relation, not a continuous geometry error guarantee.
No online astronomy service
There is no online search endpoint, visualization service, scientific reduction, time/frequency MOC, RING conversion, or intersection/difference query algebra here.
FITS validation is focused
validate_moc_fits() checks the important ICRS/NUNIQ/MOC headers and decodable cells. It is not a complete external IVOA conformance validator.
Check the exact wheel
The repository currently contains a version split: package metadata is 1.1.0 while CORE_VERSION, README, CLI, and task contract still say 1.0.0. Record the exact commit and wheel SHA-256.
Credentials stay outside
Refresh rejects URL credentials and provenance redacts userinfo, query fragments, and secret-like keys. Do not put credential values in recipes, evidence, logs, indices, or responses.
A preview never becomes a measurement. Order 4 is a compact view and order 8 is a common query projection. Neither can manufacture detail that was absent from the authoritative input.