AstroFetch

PyTorch-friendly, ML-ready access to planetary science data, starting with the Moon. Request a bounding box, receive a coregistered multichannel tensor.

AstroFetch is a thin layer over existing archive tooling — the USGS Astrogeology STAC catalog and Cloud Optimized GeoTIFFs — that turns planetary science archives into ML-ready tensors. It wraps existing tools rather than mirroring archives: nothing is rehosted, everything is fetched on demand and cached. It is, roughly, what TorchGeo is for Earth observation, pointed at the Moon (and Mars next).

Status: Phase 1 (STAC sampler). The data path is real: a request fetches the Cloud Optimized GeoTIFFs covering the window from the USGS ARD catalog, reprojects them onto a common grid, and returns physical values. See the roadmap.

Install

uv add astrofetch      # or: pip install astrofetch

Usage

One dataset class per instrument; combine instruments with & to stack their channels over the overlapping region:

import astrofetch as af

bbox = (-26.3, -50.6, -25.5, -49.7)  # west, south, east, north (degrees)

moondata = af.KaguyaTC(products=["dtm"], bbox=bbox, resolution=100) & af.KaguyaTCImagery(
    bbox=bbox, resolution=100
)

for sample in moondata:
    sample["image"]  # torch.Tensor (C, H, W), one channel per layer
    sample["mask"]  # torch.BoolTensor (C, H, W), validity (nodata gaps)
    sample["layers"]  # ["kaguya_tc_dtm", "kaguya_tc_image"], plus bbox/crs/resolution

Each dataset is map-style: index it (moondata[0]), take its len(), and shuffle or split it like any torch dataset. patch_size sets the output size — images are (C, patch_size, patch_size), default 256 — and length sets how many random patches make up one epoch:

moondata = af.KaguyaTC(products=["dtm"], bbox=bbox, patch_size=128, length=500, seed=0)
moondata[0]["image"].shape  # torch.Size([1, 128, 128]); moondata[i] is reproducible

It plugs directly into a PyTorch training loop — samples are plain dicts, so the default collation just works:

from torch.utils.data import DataLoader

loader = DataLoader(moondata, batch_size=16)
for batch in loader:
    batch["image"]  # torch.Tensor (16, C, H, W)

Not sure what data exists? The MOON catalog enumerates probes, instruments, and products, and points at the dataset classes:

from astrofetch.moon import MOON

for probe in MOON.probes.values():
    for instrument in probe.instruments.values():
        print(probe.name, "/", instrument.name, "->", sorted(instrument.products))

MOON.probes["kaguya"].instruments["tc_imagery"].dataset  # KaguyaTCImagery

Design principles

• One dataset class per instrument. KaguyaTC, LROCWAC, … (the TorchGeo pattern); cross-instrument stacks are explicit compositions via & (IntersectionDataset). Probes and bodies are catalog metadata, never dataset boundaries.
• Wrap, do not reimplement. pystac-client queries STAC, rasterio reads and windows COGs. AstroFetch composes these rather than re-deriving archive tooling.
• STAC + COGs are the primary source. Windowed HTTP range reads give real physical values in their existing map projection. Rendered tile services are a visualization convenience only, never the quantitative path.
• Cache is throwaway. On-demand data is reproducible and disposable; nothing fetched is load-bearing or rehosted.
• Body-namespaced from day one. The Moon ships first; adding Mars is a new module, not a redesign.

Roadmap

Phase	Deliverable	Status
0	Scaffolding — package, CI, docs, target API	Done
1	STAC sampler MVP — bbox to coregistered (C, H, W) tensor	In progress
2	Datasets and transforms — grid-tile dataset, spatial splits, transforms, LRO WAC	Planned
3	Release and community — PyPI, planetarypy affiliation, paper	Planned

Development

git clone https://github.com/TechnicToms/AstroFetch.git
cd AstroFetch
uv sync              # create the venv and install everything
uv run pytest        # run the test suite (no network calls)
uv run ruff check    # lint

Contributing

Contributions are welcome, especially new body modules (Mars first) and new dataset classes. Open an issue to discuss substantial changes, keep unit tests network-free by mocking archive calls, and run ruff before pushing.

Contributors

License

Released under the Apache 2.0 license.

Acknowledgements

Built on the planetary open-source community: the USGS Astrogeology Science Center, planetarypy, rasterio, and pystac-client, with a nod to TorchGeo for showing the way on Earth.