download-astronomical-images

name	download-astronomical-images
description	This skill should be used when the user asks to "download astronomical images", "get survey images", "download galaxy images", "fetch Legacy Survey images", "PanSTARRS data", "SDSS images", "DSS2 images", mentions "Simbad lookup", "Simbad name resolution", "astro image downloader", or discusses downloading optical/infrared survey data from Legacy Survey, PanSTARRS, SDSS, or DSS2. Also use when user needs images of astronomical objects by name (M87, Ark120, NGC1365, etc.) or coordinates, or wants to download multiple targets from IPAC format tables.
version	1.0.0

Astro Image Downloader

Description: Download astronomical survey images from multiple sources (Legacy Survey, PanSTARRS, SDSS, DSS2) with automatic fallback, Simbad name resolution, and image labeling.

Author: Claude Code Version: 1.0.0 Package Location: /Users/shangguan/Softwares/my_modules/astro_image_downloader/

---

When to Use This Skill

Use this skill when you need to:

• Download optical/infrared survey images of astronomical objects
• Get images by target name (e.g., "M87", "Ark120", "NGC1365")
• Get images by coordinates (RA/Dec in degrees)
• Download multiple targets from an IPAC format table
• Access multiple surveys with automatic fallback priority
• Add labeled images with target name and source information

Supported Surveys (in priority order):

1. Legacy Survey DR10 - Best coverage (94%), high resolution (0.262"/pix)
2. PanSTARRS - Northern sky, good resolution (0.25"/pix)
3. SDSS - Northern sky, moderate resolution (0.396"/pix)
4. DSS2 - All-sky coverage, lower resolution (~1.0"/pix)

---

Quick Reference

Most Common Usage

# Download by target name (with auto-fallback)
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --name M87 \
  --size 120 \
  --output images

# Download by coordinates
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --ra 187.706 \
  --dec 12.391 \
  --size 600 \
  --output images

# Batch download from IPAC table
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --table /path/to/targets.ipac \
  --size 120 \
  --output survey_images

Key Parameters

Parameter	Type	Description	Default
--name	string	Target name (resolves via Simbad)	None
--ra	float	Right ascension (degrees)	None
--dec	float	Declination (degrees)	None
--table	path	IPAC table file	None
--size	float	Image size in arcseconds	120 (2 arcmin)
--output	path	Output directory	survey_images
--no-labels	flag	Disable image labels	False (labels on)
--priority	list	Survey priority order	legacy,panstarrs,sdss,dss2

Image Size Guide

Arcseconds	Arcmin	Description	Pixel Size (Legacy)
30	0.5	Small, compact targets	115×115
60	1.0	Galaxy cores	229×229
120	2.0	Standard size (recommended)	458×458
300	5.0	Extended objects	1145×1145
600	10.0	Large galaxies + environment	2290×2290

---

Individual Survey Scripts

Legacy Survey (DR10)

python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_legacy_survey.py \
  --name M87 --size 120 --output legacy_images

PanSTARRS

python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_panstarrs.py \
  --name M87 --size 120 --output panstarrs_images

SDSS

python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_sdss.py \
  --name M87 --size 120 --output sdss_images

DSS2 (Digitized Sky Survey 2)

python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_dss_survey.py \
  --name M87 --size 120 --output dss2_images

---

IPAC Table Format

The package expects IPAC format tables with at least these columns:

|     target     |      ra      |     dec     |
|    varchar     |    double    |    double   |
|M87            | 12:30:49.42  | +12:23:28.04 |
|Ark120          | 05:16:11.41  | -00:08:59.38 |
|NGC1365         | 03:33:36.36  | -36:08:25.42 |

Required columns:

• target - Target name (will be used for filename and label)
• ra - Right ascension (sexagesimal format: HH:MM:SS)
• dec - Declination (sexagesimal format: DD:MM:SS)

---

Common Workflows

Workflow 1: Single Target by Name

# Automatically resolves via Simbad and tries all surveys
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --name "Ark120" \
  --size 120 \
  --output galaxy_images

Workflow 2: Single Target by Coordinates

# Use when you have precise coordinates
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --ra 79.0475 \
  --dec -0.1498 \
  --size 600 \
  --output galaxy_images

Workflow 3: Batch Download with Custom Priority

# Try PanSTARRS first, then SDSS, then DSS2 (skip Legacy Survey)
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --table targets.ipac \
  --size 120 \
  --output survey_images \
  --priority panstarrs sdss dss2

Workflow 4: High-Resolution Images (Extended Objects)

# 10 arcmin cutouts for large galaxies
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --table targets.ipac \
  --size 600 \
  --output survey_images_10arcmin

Workflow 5: Images Without Labels

# Clean images without text overlays
python /Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/download_survey_auto.py \
  --table targets.ipac \
  --size 120 \
  --output survey_images \
  --no-labels

---

Image Labeling

Default (labels enabled):

• Upper left: Target name
• Upper right: Image source (e.g., "Legacy Survey DR10", "DSS2 Color")
• White text with black outline for visibility
• Font size scales with image dimensions

To disable labels: Add the --no-labels flag to any command.

---

Return Values and Status

The scripts provide detailed status output:

Successful download:

[1/17] Ark120 (RA=79.0475°, Dec=-0.1498°)
  ✓ Legacy Survey ls-dr10
  Path: survey_images/Ark120.jpg
  Size: (458, 458)

Auto-fallback in action:

[10/17] MCG-5-23-16 (RA=146.9172°, Dec=-30.9489°)
  Trying legacy... ✗
  Trying panstarrs... ✗
  Trying sdss... ✗
  Trying dss2... ✓ DSS2 Color
  Path: survey_images/MCG-5-23-16.jpg
  Size: (530, 530)

Summary:

============================================================
Summary: 17/17 images downloaded successfully

---

Troubleshooting

"Target not found in Simbad"

• Check spelling of target name
• Try alternate names (e.g., "M87" vs "NGC4486")
• Use coordinates instead with --ra and --dec

"All surveys failed"

• Target may be in coverage gap
• Try customizing priority order with --priority
• Check network connectivity
• Verify coordinates are correct

"Image too dark" or "Image uniform"

• Download returned empty/black image
• Auto-fallback will try next survey
• Consider using DSS2 (has all-sky coverage)

DSS2 Size Limitations

• DSS2 returns fixed plate cutouts (~530×530 pixels)
• The --size parameter is informational only for DSS2
• Other surveys (Legacy, PanSTARRS, SDSS) honor custom sizes

---

Python API Usage

You can also import and use as a Python package:

import sys
from pathlib import Path

# Add package to path
sys.path.insert(0, '/Users/shangguan/Softwares/my_modules/astro_image_downloader')

# Import functions
from cli.download_any import download_by_name, download_by_coord, download_batch

# Download by name
result = download_by_name(
    name='M87',
    size_arcsec=120,
    output_dir='images',
    labels=True
)

if result['success']:
    print(f"Downloaded from {result['source']}")
    print(f"Path: {result['path']}")

# Download by coordinates
result = download_by_coord(
    ra=187.706,
    dec=12.391,
    size_arcsec=600,
    output_dir='images',
    labels=True
)

# Batch download
results = download_batch(
    table_path='targets.ipac',
    size_arcsec=120,
    output_dir='survey_images',
    labels=True
)

---

Dependencies

Required Python packages:

pip install astropy astroquery pillow numpy scipy

• astropy: Coordinate handling, FITS processing
• astroquery: Simbad name resolution
• pillow: Image processing and labeling
• numpy: Array operations
• scipy: Image resizing (for DSS2 color composites)

---

Examples from Tests

Test Results (17 galaxy sample)

• Legacy Survey DR10: 16/17 targets (94% success)
• DSS2 fallback: 1/17 targets (MCG-5-23-16, in coverage gap)
• Overall success rate: 100% (17/17) with auto-fallback

Example Targets

# Well-known galaxy with good coverage
--name M87  # Downloads from Legacy Survey

# Southern sky galaxy
--name Ark120  # Downloads from Legacy Survey

# Target in coverage gap (uses DSS2)
--name MCG-5-23-16  # Falls back to DSS2

---

File Locations

Package:

/Users/shangguan/Softwares/my_modules/astro_image_downloader/

Scripts:

/Users/shangguan/Softwares/my_modules/astro_image_downloader/scripts/
├── download_survey_auto.py       # Auto-fallback (USE THIS)
├── download_legacy_survey.py     # Legacy Survey only
├── download_panstarrs.py         # PanSTARRS only
├── download_sdss.py              # SDSS only
└── download_dss_survey.py        # DSS2 only

Documentation:

/Users/shangguan/Softwares/my_modules/astro_image_downloader/README.md

---

Tips for Best Results

1. Use auto-fallback script (download_survey_auto.py) for most cases
2. 2 arcmin (120 arcsec) is a good default size for galaxy cores
3. 10 arcmin (600 arcsec) for large galaxies and environment
4. Simbad resolution works well for common names (M87, NGC1365, etc.)
5. Customize priority if you know which survey covers your targets
6. Keep labels on for documentation purposes
7. Check the summary after batch downloads for failed targets

---

Notes

• All surveys return JPEG format (RGB)
• Legacy Survey provides false-color gri composites
• DSS2 creates composite color from red + blue plates
• Images include FITS header metadata when downloaded from surveys
• The package handles coordinate conversions automatically
• Sexagesimal coordinates in IPAC tables are parsed automatically