asteria-roman 0.1.0__tar.gz

asteria_roman-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }} - Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        python-version: [ "3.11", "3.12" ]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install Package & Test Dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -e ".[dev]"
+
+      - name: Run Test Suite (pytest)
+        run: |
+          pytest -v --cov=asteria --cov-report=xml
+
+      - name: Build Source Distribution & Wheel
+        run: |
+          python -m build
+
+      - name: Verify Package Metadata with Twine
+        run: |
+          twine check dist/*

asteria_roman-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Deploy to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  id-token: write  # Mandatory for PyPI Trusted Publishing (OIDC)
+  contents: read
+
+jobs:
+  test:
+    name: Run Pre-Release Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run Pytest
+        run: |
+          pytest -v
+
+  build-and-publish:
+    name: Build & Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/asteria-roman
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Build Tools
+        run: |
+          python -m pip install --upgrade pip build twine
+
+      - name: Build Distribution Packages
+        run: |
+          python -m build
+
+      - name: Validate Wheel & Sdist with Twine
+        run: |
+          twine check dist/*
+
+      - name: Publish Package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

asteria_roman-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.xml
+
+# Weights & Large Data (Never commit real weights or data files)
+*.pt
+*.pth
+*.onnx
+*.fits
+*.fits.gz
+*.asdf
+*.tar
+*.tar.gz
+data/
+/weights/
+!src/asteria/weights/
+.cache/
+
+# Sphinx docs build
+docs/_build/
+docs/build/
+
+# IDE & OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Untracked developer notes & guidelines
+guidelines.md
+*guidelines*.md
+
+# Agent memory & guidelines (kept locally for next sessions, excluded from git)
+MEMORY.md
+*memory*.md
+AGENTS.md
+*agent*.md
+.agents/
+.agent/
+_agents/
+_agent/
+GEMINI.md
+*gemini*.md

asteria_roman-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo M. Sanchez-Alarcon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asteria_roman-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: asteria-roman
+Version: 0.1.0
+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: 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.svg?color=blue)](https://pypi.org/project/asteria/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/asteria.svg)](https://pypi.org/project/asteria/)
+[![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**: Direct support for 2D astronomical **FITS** (`.fits`, `.fits.gz`), Roman **ASDF** (`.asdf` Level 2 calibrated exposures and Level 3 mosaics via `roman_datamodels`), and raw **NumPy** arrays. Automatically converts Level 2 exposures to surface brightness units ($\text{MJy/sr}$) using calibrated photometry and enables $\text{ZP}=20.472$.
+- **Instant Deblending**: Marker-controlled watershed expansion turning dense neural predictions into discrete celestial catalogs with centroids, bounding boxes, and photometry.
+
+---
+
+## 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 FITS or ASDF exposure
+pred_mask, probs, stretched = segmentor.predict_dense(
+    "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",
+)
+
+# 4. Extract discrete, deblended astronomical sources (marker-controlled watershed)
+catalog = segmentor.segment("scene_0001_F106.fits")
+print(f"Extracted {len(catalog.masks)} distinct celestial objects!")
+for idx, (cx, cy) in enumerate(catalog.centroids[:5]):
+    print(f"Source #{idx + 1}: centroid=({cx:.1f}, {cy:.1f}), area={catalog.areas[idx]} px")
+```
+
+### 2. Command-Line Interface (CLI)
+
+Asteria includes the `asteria-predict` CLI command:
+
+```bash
+# Basic prediction and display
+asteria-predict scene.fits
+
+# Full-field tiled inference with saving and FITS export
+asteria-predict scene.fits \
+    --tile_size 512 \
+    --overlap 64 \
+    --output results.png \
+    --export_fits segmap.fits \
+    --deblend \
+    --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.

asteria_roman-0.1.0/README.md

@@ -0,0 +1,117 @@
+# Asteria 🌌
+
+[![PyPI version](https://img.shields.io/pypi/v/asteria.svg?color=blue)](https://pypi.org/project/asteria/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/asteria.svg)](https://pypi.org/project/asteria/)
+[![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**: Direct support for 2D astronomical **FITS** (`.fits`, `.fits.gz`), Roman **ASDF** (`.asdf` Level 2 calibrated exposures and Level 3 mosaics via `roman_datamodels`), and raw **NumPy** arrays. Automatically converts Level 2 exposures to surface brightness units ($\text{MJy/sr}$) using calibrated photometry and enables $\text{ZP}=20.472$.
+- **Instant Deblending**: Marker-controlled watershed expansion turning dense neural predictions into discrete celestial catalogs with centroids, bounding boxes, and photometry.
+
+---
+
+## 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 FITS or ASDF exposure
+pred_mask, probs, stretched = segmentor.predict_dense(
+    "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",
+)
+
+# 4. Extract discrete, deblended astronomical sources (marker-controlled watershed)
+catalog = segmentor.segment("scene_0001_F106.fits")
+print(f"Extracted {len(catalog.masks)} distinct celestial objects!")
+for idx, (cx, cy) in enumerate(catalog.centroids[:5]):
+    print(f"Source #{idx + 1}: centroid=({cx:.1f}, {cy:.1f}), area={catalog.areas[idx]} px")
+```
+
+### 2. Command-Line Interface (CLI)
+
+Asteria includes the `asteria-predict` CLI command:
+
+```bash
+# Basic prediction and display
+asteria-predict scene.fits
+
+# Full-field tiled inference with saving and FITS export
+asteria-predict scene.fits \
+    --tile_size 512 \
+    --overlap 64 \
+    --output results.png \
+    --export_fits segmap.fits \
+    --deblend \
+    --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.

asteria_roman-0.1.0/docs/Makefile

@@ -0,0 +1,13 @@
+# Minimal makefile for Sphinx documentation
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

asteria_roman-0.1.0/docs/api.rst

@@ -0,0 +1,68 @@
+.. _api:
+
+API Reference
+=============
+
+This section documents the public classes, functions, and modules in Asteria.
+
+Top-Level Functions
+-------------------
+
+.. autofunction:: asteria.load_model
+
+Inference & Deblending
+----------------------
+
+.. autoclass:: asteria.AsteriaSegmentor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: asteria.SegmentationResult
+   :show-inheritance:
+
+.. autofunction:: asteria.get_optimal_device
+
+.. autofunction:: asteria.get_device_info
+
+Neural Network Architecture
+---------------------------
+
+.. autoclass:: asteria.UNetPlusPlus
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Photometric Stretches
+---------------------
+
+.. autofunction:: asteria.leaky_surface_brightness
+
+.. autofunction:: asteria.asinh_stretch
+
+.. autofunction:: asteria.linear_stretch
+
+.. autofunction:: asteria.stretch_image
+
+Astronomical Image I/O
+----------------------
+
+.. autofunction:: asteria.load_image
+
+.. autoclass:: asteria.AstroImage
+   :show-inheritance:
+
+Visualization
+-------------
+
+.. autofunction:: asteria.plot_two_panel
+
+.. autofunction:: asteria.plot_instance_overlay
+
+Model Weights Registry
+----------------------
+
+.. autoclass:: asteria.weights.registry.WeightMetadata
+   :show-inheritance:
+
+.. autofunction:: asteria.weights.registry.get_weight_metadata

asteria_roman-0.1.0/docs/architecture.rst

@@ -0,0 +1,97 @@
+.. _architecture:
+
+Model Architecture
+==================
+
+Asteria is powered by a **Nested U-Net (UNet++)** deep convolutional neural network, engineered specifically for high-contrast astronomical imaging and crowded-field source extraction.
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Why UNet++ for Astronomical Source Detection?
+---------------------------------------------
+
+Traditional astronomical source extraction pipelines (such as SExtractor or standard thresholding) struggle in crowded stellar regions and galaxy clusters where object halos overlap. While standard U-Nets use direct skip connections between encoder and decoder stages, they suffer from a **semantic gap**: low-level encoder features contain rich spatial coordinates but high noise, whereas high-level decoder features contain abstract semantic context at degraded spatial resolution.
+
+UNet++ (Zhou et al., 2018; 2019) overcomes this limitation by bridging the semantic gap through **nested, dense skip pathways**.
+
+Mathematical Formulation
+-------------------------
+
+Let $x^{i,j}$ denote the output of node $X^{i,j}$, where:
+
+* $i \in \{0, 1, 2, 3, 4\}$ indexes the downsampling depth along the encoder backbone.
+* $j \in \{0, 1, 2, 3, 4\}$ indexes the dense convolution layer along the horizontal skip pathway.
+
+The forward accumulation at each intermediate node is computed as:
+
+.. math::
+
+   x^{i,j} = \begin{cases}
+   \mathcal{H}_{\text{enc}}\left( \mathcal{D}(x^{i-1, 0}) \right), & j = 0 \\
+   \mathcal{H}\left( \left[ [x^{i,k}]_{k=0}^{j-1}, \mathcal{U}(x^{i+1, j-1}) \right] \right), & j > 0
+   \end{cases}
+
+where:
+
+* $\mathcal{H}(\cdot)$ denotes a double convolution block (Conv2D $\to$ BatchNorm $\to$ ReLU $\to$ Conv2D $\to$ BatchNorm $\to$ ReLU).
+* $\mathcal{D}(\cdot)$ denotes $2 \times 2$ max pooling with stride 2.
+* $\mathcal{U}(\cdot)$ denotes bilinear upsampling with scale factor 2.
+* $[\cdot]$ denotes channel-wise feature concatenation.
+
+Through these nested skip pathways, feature maps from earlier stages are progressively merged and refined before reaching the decoder nodes, ensuring that fine astronomical boundary structures are preserved with sub-pixel fidelity.
+
+Three-Class Boundary-Aware Target Formulation
+---------------------------------------------
+
+Standard binary segmentation (source vs. background) inevitably merges touching or overlapping astronomical sources into contiguous blobs, requiring heuristic post-processing deblenders.
+
+Asteria formulates source detection as a **3-class boundary-aware semantic segmentation** task:
+
+* **Class 0 (Sky Background)**: Deep space sky noise and intergalactic regions.
+* **Class 1 (Source Interior / Core)**: High surface brightness galactic cores and stellar point spread functions (PSFs).
+* **Class 2 (Deblending Boundary / Edge)**: The outer perimeter of celestial sources and, critically, the contact interface between overlapping or touching objects.
+
+Deblending via Marker-Controlled Watershed
+------------------------------------------
+
+During inference, Asteria leverages the explicit boundary prediction to split touching galaxies:
+
+1. **Topological Seed Markers**: Identified by thresholding the interior probability map ($P_{\text{core}} \ge 0.45$). Connected components generate distinct integer markers for each galaxy core.
+2. **Total Foreground Mask**: Computed from $P_{\text{core}} + P_{\text{edge}} \ge 0.50$ (or $P_{\text{bg}} < 0.50$).
+3. **Watershed Expansion**: Inverted Euclidean distance transforms expand the core markers outward until they collide along the predicted Class 2 boundary line, cleanly separating touching objects into discrete instances without morphological distortion.
+
+Loss Function & Class Weighting
+-------------------------------
+
+Due to the extreme class imbalance in deep astronomical exposures (where the sky background occupies $\sim 85-90\%$ of pixels, source cores $\sim 2-5\%$, and 1-pixel boundaries $\sim 5-10\%$), models trained with standard unweighted Cross-Entropy collapse toward predicting the background.
+
+Asteria was trained using a **Combined Weighted Cross-Entropy and Multi-Class Dice Loss**:
+
+.. math::
+
+   \mathcal{L}_{\text{total}} = \mathcal{L}_{\text{WCE}} + \lambda \mathcal{L}_{\text{Dice}}
+
+with empirically optimized class weights:
+
+.. math::
+
+   \mathbf{w}_{\text{CE}} = [w_{\text{bg}} = 0.5, \; w_{\text{core}} = 2.5, \; w_{\text{edge}} = 8.0]
+
+The high penalty ($8.0$) on boundary errors forces the network to prioritize thin edge continuity, which is the decisive factor for successful instance deblending.
+
+Tiled Dense Sliding-Window Inference (`predict_dense`)
+------------------------------------------------------
+
+To process large scientific exposures (such as the $4088 \times 4088$ detector arrays of the Nancy Grace Roman Space Telescope) without GPU out-of-memory (OOM) failures or artificial boundary seams:
+
+1. The exposure is decomposed into overlapping $512 \times 512$ tiles with a default 64-pixel margin.
+2. Each tile is evaluated in mini-batches through the neural network.
+3. Softmax probability maps are accumulated using a **2D separable Hann / cosine window**:
+
+.. math::
+
+   W(x, y) = \sin\left(\frac{\pi x}{T}\right) \cdot \sin\left(\frac{\pi y}{T}\right)
+
+4. The accumulated probability tensor is normalized by the total weight matrix, completely eliminating edge discontinuity artifacts and bounding memory consumption to $< 350$ MB VRAM.