Metadata-Version: 2.5
Name: asteria-roman
Version: 0.1.3
Summary: Lightweight astronomical deep learning inference engine and instance deblender powered by boundary-aware UNet++
Project-URL: Homepage, https://github.com/PabloMSanAla/asteria
Project-URL: Documentation, https://asteria.readthedocs.io
Project-URL: Repository, https://github.com/PabloMSanAla/asteria.git
Project-URL: Issues, https://github.com/PabloMSanAla/asteria/issues
Author-email: "Pablo M. Sanchez-Alarcon" <pablo.sanchezalarcon@nasa.gov>
License-Expression: MIT
License-File: LICENSE
Keywords: asdf,astronomy,astrophysics,deblending,deep-learning,fits,roman-space-telescope,segmentation,unetplusplus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.11
Requires-Dist: astropy>=5.0.0
Requires-Dist: boto3>=1.26.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: numpy>=1.22.0
Requires-Dist: pixel-clarity>=0.9.0
Requires-Dist: requests>=2.28.0
Requires-Dist: roman-datamodels>=1.0.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: torch>=2.0.0
Requires-Dist: tqdm>=4.65.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'docs'
Requires-Dist: sphinx>=7.0.0; extra == 'docs'
Description-Content-Type: text/markdown

# Asteria 🌌

[![PyPI version](https://img.shields.io/pypi/v/asteria-roman.svg?color=blue)](https://pypi.org/project/asteria-roman/)
[![Python Versions](https://img.shields.io/pypi/pyversions/asteria-roman.svg)](https://pypi.org/project/asteria-roman/)
[![CI Status](https://github.com/PabloMSanAla/asteria/actions/workflows/ci.yml/badge.svg)](https://github.com/PabloMSanAla/asteria/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/asteria/badge/?version=latest)](https://asteria.readthedocs.io/en/latest/?badge=latest)



<p><strong>Asteria</strong> is a lightweight, high-performance deep learning inference engine and instance deblender for stars in astronomical imaging, powered by boundary-aware <strong>UNet++ (Nested U-Net)</strong>.</p>

<p>Designed for the <strong>Nancy Grace Roman Space Telescope</strong>, Asteria provides promptless, end-to-end star detection in a single neural forward pass.</p>

<p align="center">
  <img width="40%" src="https://raw.githubusercontent.com/PabloMSanAla/asteria/prepare-production/docs/_static/images/example_blinking.gif" alt="Asteria segmentation example">
  <sub><br> Example of <strong>Asteria</strong> star detection on a simulated Roman WFI exposure.</sub>
</p>


---

## Key Features

- **Lightweight & Self-Contained**: Pure PyTorch UNet++ architecture without bulky dependencies or heavyweight vision foundation models.
- **Hardware Acceleration with Automatic Fallback**: Auto-detects and optimizes execution across **NVIDIA CUDA** (with TF32 and AMP), **Apple Silicon MPS** (Metal Performance Shaders on macOS), and universal **CPU**.
- **Physical Boundary-Aware Deblending**: Trained with 3-class supervision:
  - `0`: Sky Background
  - `1`: Source Interior / Core
  - `2`: Deblending Boundary / Contact Interface
- **Seamless Tiled Dense Inference (`predict_dense`)**: Sliding-window 2D Hann/cosine window blending to process arbitrary image sizes (from local cutouts up to full $4088 \times 4088$ Roman WFI exposures) with bounded memory ($< 350$ MB VRAM).
- **Photometric LeakySB Stretch**: Non-linear surface brightness transformation that preserves stellar point-spread functions (PSFs) while lifting faint, diffuse galactic wings.
- **Unified Astronomical I/O & Cloud Storage**: Direct support for 2D astronomical **FITS** (`.fits`, `.fits.gz`), Roman **ASDF** (`.asdf` Level 2 calibrated exposures and Level 3 mosaics via `roman_datamodels`), raw **NumPy** arrays, and **Amazon Web Services (AWS) S3** URLs (`s3://bucket/key...` or HTTPS S3 URLs). Automatically converts Level 2 exposures to surface brightness units ($\text{MJy/sr}$) using calibrated photometry and enables $\text{ZP}=20.472$.

---

## Installation

### From PyPI
```bash
pip install asteria-roman
```

### From Source
```bash
git clone https://github.com/PabloMSanAla/asteria.git
cd asteria
pip install -e .
```

---

## Quickstart

### 1. Python API

```python
import asteria

# 1. Load pre-trained model (auto-downloads weights on first run, auto-selects device)
segmentor = asteria.load_model("latest")

# 2. Run dense 3-class segmentation inference on a local file or AWS S3 URL
pred_mask, probs, stretched = segmentor.predict_dense(
    "s3://my-roman-bucket/exposures/r0000101_wfi.asdf",  # or local "scene_0001_F106.fits"
    tile_size=512,
    overlap=64,
)

# 3. Render publication-ready side-by-side 2-panel figure
fig = asteria.plot_two_panel(
    stretched=stretched,
    pred_mask=pred_mask,
    save_path="prediction.png",
)
```

### 2. Command-Line Interface (CLI)

Asteria includes the `asteria` (and `asteria-predict`) CLI command:

```bash
# Pre-download official weights for offline/cloud deployment
asteria --download

# Basic prediction and display (local file or S3 URI)
asteria s3://my-roman-bucket/exposures/r0000101_wfi.asdf

# Full-field tiled inference with saving and FITS export
asteria scene.fits \
    --tile_size 512 \
    --overlap 64 \
    --output results.png \
    --export_fits segmap.fits \
    --no_display
```

---

## Model Architecture & Weights History

| Weight Version | Backbone | Resolution | Training Set | Epochs | Interior IoU | Edge IoU (tol=1px) | Macro IoU | Training cutouts | Hardware |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **`v0.1.0`** (latest) | UNet++ (32-512) | $512 \times 512$ | Roman WFI Synthetic | 80 | **0.754** | **0.513** | **0.6335** | 2800 | NASA NAS GH200 |

For comprehensive architectural details and benchmark comparisons, see the [Asteria Documentation](https://asteria.readthedocs.io).

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
