dwarf3🔭•🪐•☄️

👤 Author

🌌 Features

📂 Folder Conventions

project/
├── rawData/ # IMMUTABLE — never modified
│ └── DWARF_RAW_TELE_*/ # One folder per acquisition session
│ ├── *.fits # Raw light frames
│ ├── failed_*.fits # Device-flagged failures (excluded)
│ └── shotsInfo.json # Session metadata
│
├── processedData/ # ALL outputs go here
│ └── <session_id>/
│ ├── stacked/
│ │ ├── master_linear.fits
│ │ ├── master_quicklook.png
│ │ └── master_quicklook.tif
│ ├── run_manifest.json # Complete processing record
│ ├── report.json # Summary statistics
│ └── report.md # Human-readable report

⬇️ Installation

🛠️ Using conda (recommended)

# Create and activate the environment
conda env create -f environment.yaml
conda activate dwarf-astro
# Install dwarf3 in development mode
cd /path/to/dwarf3
pip install -e .

🔧 Using pip (in existing environment)

# Install dependencies
pip install -r requirements.txt
# Install dwarf3 in development mode
cd /path/to/dwarf3
pip install -e .

⚙️ Verifying installation

# Check version
dwarf3 --version
# Show help
dwarf3 --help
dwarf3 stack --help

🚀 Quickstart

>_ Command Line

# Basic stacking with defaults
dwarf3 stack rawData/DWARF_RAW_TELE_M31_EXP_15_GAIN_60_2025年12月27日-18-26-56-449
# With custom parameters
dwarf3 stack rawData/DWARF_RAW_TELE_M31_* \
 --keep 0.92 \
 --sigma 3.0 \
 --out processedData/
# Dry run (score frames, generate report, no stacking)
dwarf3 stack rawData/DWARF_RAW_TELE_M31_* --dry-run

🐍 Python API

from dwarf3 import stack_session, StackConfig
# Configure the pipeline
config = StackConfig(
 keep_fraction=0.92, # Keep top 92% of frames by quality
 sigma=3.0, # Sigma-clipping threshold
 maxiters=5, # Max clipping iterations
 reference="best", # Use best-quality frame as reference
)
# Run the pipeline
result = stack_session(
 "rawData/DWARF_RAW_TELE_M31_EXP_15_GAIN_60_2025年12月27日-18-26-56-449",
 output_root="processedData",
 config=config,
)
# Access results
print(f"Stacked {len(result.kept)} frames")
print(f"Output: {result.outputs['master_linear']}")
print(f"SNR proxy: {result.stats['snr_proxy']:.2f}")

🆑 CLI Options

☰ Stack Command

dwarf3 stack <session_path> [options]
Options:
 --out PATH Output root directory (default: processedData)
 --keep FLOAT Fraction of frames to keep (default: 0.92)
 --sigma FLOAT Sigma for sigma-clipped mean (default: 3.0)
 --maxiters INT Max iterations for sigma clipping (default: 5)
 --reference METHOD Reference frame selection: best|first (default: best)
 --debayer MODE Debayer mode: none|rgb|superpixel|bayer-first (default: none)
 --align-mode MODE Alignment: integer|rgb_affine|auto (default: auto)
 --workers N Parallel workers for scoring (default: auto)
 --dry-run Score and report only, no stacking
 --no-quicklook Skip PNG/TIFF preview generation
 --use-gpu Use GPU acceleration if available
 -v, --verbose Enable verbose output
 -q, --quiet Suppress colored output
Cache Options:
 --no-cache Disable caching (compute fresh, don't save)
 --cache-refresh Clear existing cache before starting
 --frame-list FILE File containing frame names to include (one per line)
Transform Options:
 --save-transforms Save alignment transforms for reuse
 --load-transforms Load cached transforms (skip alignment)

⌞ ⌝ Frames Command

# List all frames
dwarf3 frames rawData/DWARF_RAW_TELE_M31_*
# List with quality scores (from cache or computed)
dwarf3 frames rawData/DWARF_RAW_TELE_M31_* --scored
# Preview which frames would be kept at 90%
dwarf3 frames rawData/DWARF_RAW_TELE_M31_* --keep 0.90
# Save frame list to file for later use
dwarf3 frames rawData/DWARF_RAW_TELE_M31_* --keep 0.92 --save selected_frames.txt
# Use saved frame list for stacking
dwarf3 stack rawData/DWARF_RAW_TELE_M31_* --frame-list selected_frames.txt

🗃️ Cache Command

# Show cache status
dwarf3 cache rawData/DWARF_RAW_TELE_M31_*
# Clear all cache
dwarf3 cache rawData/DWARF_RAW_TELE_M31_* --clear
# Clear only alignment transforms
dwarf3 cache rawData/DWARF_RAW_TELE_M31_* --clear-transforms
# Clear only stacked images
dwarf3 cache rawData/DWARF_RAW_TELE_M31_* --clear-stack

📥 Outputs

🔭 Acquisition Modes

🧭 Alt-Az Mode (Default)

# Alt-Az mode (default)
./scripts/process_M31.sh

𝆺𝅥⃝🌍 EQ Mode (Equatorial)

# EQ mode (--eq-mode flag)
./scripts/process_M43.sh
./scripts/process_M45.sh

🌕 Methods

🌌 M31 Complete Pipeline Example

from pathlib import Path
import numpy as np
from scipy.ndimage import gaussian_filter
from dwarf3 import (
 list_lights,
 read_fits,
 select_frames,
 debayer_rggb,
 align_rgb_debayer_first_parallel,
 sigma_clip_mask_aware_rgb,
 crop_to_coverage,
 apply_bayer_compensation,
 asinh_stretch,
 write_fits,
 StackConfig,
)
# 1. Session path
session = Path("rawData/DWARF_RAW_TELE_M31_EXP_15_GAIN_60_2025年12月27日-18-26-56-449")
# 2. Discover and score frames
frame_paths = list_lights(session)
print(f"Found {len(frame_paths)} light frames")
# 3. Select best 92% by quality
config = StackConfig(keep_fraction=0.92, sigma=3.0)
kept_paths, rejected = select_frames(frame_paths, config=config)
print(f"Keeping {len(kept_paths)}, rejected {len(rejected)}")
# 4. Prepare reference (best frame, debayered)
ref_bayer = read_fits(kept_paths[0])
ref_rgb = debayer_rggb(ref_bayer, mode="bilinear")
# 5. Parallel alignment with explicit validity masks
aligned_frames, results, masks = align_rgb_debayer_first_parallel(
 kept_paths,
 ref_rgb,
 str(kept_paths[0]),
 debayer_mode="bilinear",
 workers=None, # Auto-detect CPU count
)
successes = sum(1 for r in results if r.success)
print(f"Aligned {successes}/{len(kept_paths)} frames")
# 6. Mask-aware sigma-clipped stacking with edge feathering
stacked_rgb, coverage = sigma_clip_mask_aware_rgb(
 aligned_frames,
 masks=masks, # Explicit validity masks from alignment
 sigma=3.0,
 maxiters=5,
 feather_width=10, # Smooth 10-pixel edge transition
)
print(f"Coverage: {coverage.min():.0f}-{coverage.max():.0f} frames per pixel")
# 7. Crop to well-covered region (avoids edge artifacts)
cropped_rgb, bounds = crop_to_coverage(
 stacked_rgb, coverage, min_coverage_fraction=0.8
)
print(f"Cropped to {cropped_rgb.shape[1]}x{cropped_rgb.shape[0]} pixels")
# 8. Auto Bayer compensation
balanced = apply_bayer_compensation(cropped_rgb, auto=True)
# 9. Optional: per-channel smoothing for noise reduction
for c in range(3):
 balanced[:, :, c] = gaussian_filter(balanced[:, :, c], sigma=0.7)
# 10. Asinh stretch for visualization
preview = asinh_stretch(balanced, a=5.0)
# 11. Save outputs
output_dir = Path("processedData") / session.name / "stacked"
output_dir.mkdir(parents=True, exist_ok=True)
write_fits(balanced, output_dir / "master_lrgb_galaxy.fits")
# Save preview (PIL or matplotlib)
from PIL import Image
img = Image.fromarray((np.clip(preview, 0, 1) * 255).astype(np.uint8))
img.save(output_dir / "master_lrgb_galaxy.png")
print(f"Saved to {output_dir}")

📄 DWARF 3 FITS Header Reference

📜 License

✅ Acknowledgments