Fornax Cutouts

Pluggable backend for async FITS image cutouts with FastAPI + Celery + Astrocut using the IVOA UWS standard.

Welcome

This repository is the codebase for a generalized astronomical image cutout service. The goal is to make it easier for archives and mission teams to stand up their own cutout services for their holdings without reimplementing async job handling, worker dispatch, and a standards-based REST API. You add mission-specific data sources and deploy to your own infrastructure. The framework supplies the cutout pipeline, UWS-based API and job metadata management. The library is meant to be used by archives and other teams to deploy and extend it for their own data. For example, MAST's cutouts service is one such deployment. Collaboration happens on GitHub: use issues to report problems or discuss changes that benefit others, and open pull requests to contribute improvements upstream. See Contributing to get started.

Overview

Fornax Cutouts provides a framework for building astronomical image cutout services. Define mission-specific data sources, register them with the cutout registry, and the framework handles job queuing, worker dispatch, result storage, and REST API exposure automatically.

Requirements

• Python 3.12+
• Redis 6.x or newer — used as the Celery broker/backend and for UWS job state.

Configure the broker/backend with the following CUTOUTS__REDIS__* settings for local development:

The API and workers must use the same Redis instance (and compatible TLS/cluster settings). See the configuration reference for the full list of settings.

Documentation

Full documentation is available at nasa-fornax.github.io/fornax-cutouts.

• Getting Started
• Configuration
• CLI Reference
• API Reference
• Building a Source
• Auth Providers Overview
• Building an Auth Provider
• Contributing

Use as a library

Install this package in your own service and point CUTOUTS__SOURCE_PATH at a directory of mission modules that register sources with cutout_registry.

With uv, you can add an editable path dependency if developing this project side by side with your mission sources:

[tool.uv.sources]
fornax-cutouts = { path = "../fornax-cutouts", editable = true }  # Only include if developing with fornax-cutouts source code

[project]
dependencies = [
    "fornax-cutouts",
]

Then run uv sync. Implement mission sources as described in Building a Source.

Quick Start

# Install
git clone https://github.com/nasa-fornax/fornax-cutouts
cd fornax-cutouts
uv sync

# Configure (minimum required)
export CUTOUTS__SOURCE_PATH=/path/to/your/sources
export CUTOUTS__REDIS__HOST=localhost

# Start Redis
docker run -d -p 6379:6379 valkey/valkey-bundle:9.1

# Start API
fornax-cutouts api

# Start worker (separate terminal)
fornax-cutouts worker

Visit http://localhost:8000/docs for the interactive API.

Contributing

Pre-commit is configured to lint and format all code:

uv sync
pre-commit install
pre-commit run --all-files

Use Conventional Commits in pull request titles (squash merges). That drives Semantic Versioning and the changelog via semantic-release. See the Contributing guide for types, scopes, and best practices.

Architecture

Cloud Infrastructure

architecture-beta
    service internet(internet)[Internet]

    group cloud(cloud)[Cloud IaC]
    group fornax(server)[Fornax Cutouts] in cloud

    service gateway(internet)[Gateway] in cloud
    service load_balancer(server)[Load Balancer] in cloud

    service api(server)[REST API] in fornax
    service worker(server)[Celery Workers] in fornax

    service redis(database)[Redis] in cloud
    service s3(disk)[Storage] in cloud

    internet:R -- L:gateway
    gateway:R -- L:load_balancer
    load_balancer:B -- T:api
    api:B -- T:worker

    junction j1 in cloud
    redis:B -- T:j1

    redis:R -- L:api
    j1:R -- L:worker

    s3:L -- R:worker

User sequence

sequenceDiagram
    actor U as User
    participant R as REST API
    participant C as Cutouts
    participant RD as Redis

    U->>+R: Request cutout
    R->>RD: Add request to queue
    R->>-U: Request Ack + Job ID

    par For each cutout
        RD->>+C: Perform cutout
        C->>-RD: Write results
    end

    loop Poll job status for complete
        U->>+R: Request job status
        RD->>R: .
        R->>-U: .
    end

    U->>+R: Get cutout results
    R->>-U: .

Issues

Report bugs and request features on GitHub Issues.

License

This project is licensed under the terms of the BSD 3-Clause license.