Metadata-Version: 2.4
Name: astro-senpai
Version: 2.3.1
Summary: SENPAI is a software package for the analysis of astronomical images.
Project-URL: Homepage, https://github.com/zgazak/senpai
Project-URL: Repository, https://github.com/zgazak/senpai
Project-URL: Issues, https://github.com/zgazak/senpai/issues
Author-email: Zach Gazak <jzg@alum.mit.edu>
Keywords: astrometric calibration,astrometric fitting,astrometry,astronomy,photometry
Requires-Python: <3.14,>=3.11
Requires-Dist: arrow>=1.3.0
Requires-Dist: astroeasy>=1.0.14
Requires-Dist: astropy>=6.1.7
Requires-Dist: astroquery>=0.4.11
Requires-Dist: colorlog>=6.9.0
Requires-Dist: fastapi>=0.115.12
Requires-Dist: imageio>=2.37.0
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: numpy>=2.2.4
Requires-Dist: opencv-python-headless>=4.11.0.86
Requires-Dist: pandas>=2.3.1
Requires-Dist: photutils<3.0,>=2.0.2
Requires-Dist: pydantic>=2.11.1
Requires-Dist: pypng>=0.20220715.0
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rawpy>=0.25.1
Requires-Dist: scikit-learn>=1.7.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: tqdm>=4.67.1
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.25.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-datadir>=1.5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.3.3; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# SENPAI

[![CI](https://github.com/zgazak/senpai/actions/workflows/ci.yml/badge.svg)](https://github.com/zgazak/senpai/actions/workflows/ci.yml) ![Tests](https://raw.githubusercontent.com/zgazak/senpai/main/tests.svg) ![Coverage](https://raw.githubusercontent.com/zgazak/senpai/main/coverage.svg)

A classic star detector and astrometry tool.

<img src="https://raw.githubusercontent.com/zgazak/senpai/main/resources/senpai_logo.png" alt="senpai" width="600"/>

SENPAI is built off of the algorithm descriptions in [Gazak et al. 2026, PASP, 138, 014502](https://iopscience.iop.org/article/10.1088/1538-3873/ae2b35/meta) — see [Citation](#citation) below if you use this software.


Is SENPAI the tool I'm looking for? SENPAI processes FITS imagery from ground-based telescopes and provides:

- ✔️ **Astrometric fitting (WCS)** — from a sidereal image, a list of extracted star positions, a sidereal + rate-track series, or a single or series of rate-track images with no prior WCS
- ✔️ **Point source detection** — stars in sidereal frames, satellites in rate-track frames
- ✔️ **Streak detection** — satellite/debris trail detection and measurement, with multi-frame confirmation
- ✔️ **Photometry** — aperture photometry with star catalog cross-matching (Gaia, SDSS, SSTRC7)
- ✔️ **Batch processing** — process whole directories of imagery via CLI or REST API
- ✔️ **ML dataset export** — export detections as COCO-format datasets for model training

## Dependencies

- [astroeasy](https://github.com/zgazak/astroeasy) - Handles all Astrometry.net considerations (installation, index files). See its README for setup and getting your config right
- Star catalogs - See [senpai/catalog/README.md](senpai/catalog/README.md) for setup and usage


## Install

Install from PyPI (package name `astro-senpai`, imports as `senpai`):

```sh
pip install astro-senpai
```

### Development install

This repo uses [uv](https://docs.astral.sh/uv/) to manage python dependencies.  First, install uv.  Then,

```sh
make sync
```
or 
```sh
uv sync --all-extras
```

then

```sh
source .venv/bin/activate
```

## Run SENPAI

When you run the SENPAI api, it loads a config file, which you can specify on command line (or use default resources/config/local.yaml)


## Run SENPAI CLI

you can always provide your own config.yaml with --config <your_config.yaml> flag.

I want to:

1. fit a single sidereal image:

```sh
python -m senpai.cli.single --image <your_fits_file> --output_dir <your_output_directory> --plot
```





## Run SENPAI API

When you run the SENPAI api, it loads a config file, which you can specify on command line (or use default resources/config/local.yaml)

- the default config is resources/config/local.yaml
- on startup, SENPAI will check for downloaded indices files


### local SENPAI API

```sh
make run
```

or 

```sh
uv run python -m senpai.api.main --config resources/config/local.yaml
```


### containerized SENPAI API

#### Build container

```sh
docker build -t senpai .
```

Or, if you have a custom base image:
```sh
docker build --build-arg BASE_IMAGE=<your-custom-base-image> -t senpai .
```

#### run container

- **config** this container builds with resources/local/containerize.yaml
- **port** runs on 8000 in container

Run like this, noting that **target** is the path to your indices in the container, and must match your config file (containerized.yaml by default).

```sh
docker run -p 8000:8000 --mount type=bind,source=/path/to/indices/5000/5200,target=/home/starman/indices/5000/5200 senpai:latest
```

If you want to use a different config file (to specify different indices or other settings), you can do so like this:

```sh
docker run -p 8000:8000 \
    --mount type=bind,source=/path/to/indices/5000/5200,target=/home/starman/indices/5000/5200 \
    --mount type=bind,source=/path/to/your/config.yaml,target=/app/resources/config/containerized.yaml \
    senpai:latest
```

This will mount your custom config file in place of the default containerize.yaml. Make sure your custom config file follows the same format as the default configuration.

http://localhost:8000/docs

## Citation

SENPAI implements the algorithms described in:

> Gazak, J. Z., Fisher, L., Phelps, M., Swindle, R., Baruela, L., & Fletcher, J. 2026, "SENPAI: Sidereal Enriched Rate-track Astrometry in Deep Imagery of Solar System Bodies", PASP, 138, 014502. [doi:10.1088/1538-3873/ae2b35](https://doi.org/10.1088/1538-3873/ae2b35)

If you use SENPAI in your research, please cite this paper:

```bibtex
@article{Gazak2026SENPAI,
  title   = {SENPAI: Sidereal Enriched Rate-track Astrometry in Deep Imagery of Solar System Bodies},
  author  = {Gazak, J. Zachary and Fisher, Lauren and Phelps, Matthew and Swindle, Ryan and Baruela, Leonard and Fletcher, Justin},
  journal = {Publications of the Astronomical Society of the Pacific},
  volume  = {138},
  number  = {1},
  pages   = {014502},
  year    = {2026},
  doi     = {10.1088/1538-3873/ae2b35}
}
```