Metadata-Version: 2.4
Name: STCI
Version: 0.1.5
Summary: SpaceTelescopeColorImage tools for astronomy cutouts.
Author: Tian Li
License-Expression: MIT
Project-URL: Homepage, https://github.com/astroskylee/STCI
Project-URL: Repository, https://github.com/astroskylee/STCI
Keywords: astronomy,euclid,fits,image-processing,color-image
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy
Requires-Dist: astroquery
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: photutils>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: tifffile
Dynamic: license-file

# STCI

STCI stands for **SpaceTelescopeColorImage**.

STCI is a small astronomy image-composition tool for making display-ready
color JPEGs or 16-bit TIFFs from space telescope cutouts and other aligned mono images.

## Installation

```bash
pip install STCI
```

The installed Python import module is `STCI`.

## Example usage

`mk_colorimg` creates one color image from either a 3-channel RGB array or three mono images in `(R, G, B)` order. For Euclid-style color images, the default mapping is `NIR_J`, `NIR_Y`, `VIS`.

```python
from STCI import mk_colorimg

mk_colorimg(
    [
        "cutout_H.fits",    # R channel
        "cutout_VIS.fits",  # G channel
        "cutout_Y.fits",    # B channel
    ],
    output_jpg="target_mtf_vis_y_h.jpg",
    input_mode="raw",
    ReplaceL=False,
    reference_ROI=200,
)
```

For a NumPy RGB cube:

```python
from STCI import mk_colorimg

mk_colorimg(rgb_array, output_jpg="target_color.jpg", input_mode="normalized")
```

Use a `.tif` or `.tiff` output filename to write a 16-bit TIFF instead of an 8-bit JPEG:

```python
mk_colorimg(rgb_array, output_jpg="target_color.tiff", input_mode="normalized")
```

Set `ReplaceL=False` to skip replacing the CIELab L* channel with the stretched blue luminosity channel. By default, `mk_colorimg` keeps the original replacement behavior.

Set `reference_ROI=200` to estimate the raw normalization, color calibration, and STF/HT stretch from the centered `200 x 200` pixel region, then apply those settings to the full image. By default, `reference_ROI=None` estimates from the full image.

For raw three-channel inputs, STCI uses one shared linear scale derived from
the largest channel 99th percentile. This preserves relative RGB amplitudes
while preventing a small number of saturated stars from making the target
galaxy too dark or excessively warm.

## Single-Band MTF Image

`mk_monoimg` creates one grayscale image from a single mono image. It uses the same MTF-style stretch as `mk_colorimg`, but omits RGB-only steps such as color calibration, Lab luminance replacement, SCNR, and saturation.

```python
from STCI import mk_monoimg

mk_monoimg(
    "cutout_VIS.fits",
    output_jpg="target_vis_mtf.jpg",
    input_mode="raw",
)
```

For a NumPy mono image:

```python
from STCI import mk_monoimg

mk_monoimg(mono_array, output_jpg="target_mono.jpg", input_mode="normalized")
```

## Download a Euclid Color Image

`Euclidimg` downloads Euclid DR1 `VIS`, `NIR_Y`, `NIR_J`, and `NIR_H` FITS cutouts, then renders one color image using the `NIR_J / NIR_Y / VIS` channel order.

```python
from STCI import Euclidimg

result = Euclidimg(
    ra=50.7163333,
    dec=-39.7693889,
    size=5.0,
    path="euclid_color",
    cred="Euclid/cred.txt",
    output_jpg="EUCLJ032251.92-394609.8.jpg",
    ReplaceL=True,
    RGB="auto",
    reference_ROI=None,
    style="Euclid",
)

print(result["jpg"])
print(result["fits"])
print(result["rgb_bands"])
```

Arguments:

- `ra`, `dec`: target coordinates in degrees.
- `size`: cutout radius in arcsec. For example, `size=5.0` makes a `10" x 10"` image.
- `path`: output directory for the FITS files and rendered image.
- `cred`: Euclid credentials file passed to `astroquery.esa.euclid`.
- `output_jpg`: optional output filename written inside `path`; use `.tif` or `.tiff` for 16-bit TIFF.
- `ReplaceL`: if `False`, skip replacing the CIELab L* channel with the stretched blue luminosity channel.
- `RGB`: Euclid bands in `(R, G, B)` order. Use `"auto"` for the default available-band choice, or pass bands such as `("NIR_H", "NIR_Y", "VIS")` or `("H", "Y", "VIS")`.
- `reference_ROI`: optional centered square ROI size, in pixels, used to estimate the display scaling before applying it to the full image.
- `style`: rendering workflow. `"Euclid"` is the unchanged original STCI workflow. `"Euclid Epic"` uses the H/Y/VIS workflow described below.

The returned dictionary contains the selected FITS paths and the final rendered image path. If the first overlapping mosaic tile for a band is empty or all zero, the downloader tries the next matching tile.

### Euclid Epic style

`style="Euclid Epic"` selects `NIR_H / NIR_Y / VIS` and applies the display workflow validated on the Euclid--SGA image set:

- linked-STF `target_background=0.125`
- fixed rank-0032 H/Y/VIS color-calibration gains
- ChannelCombination `R=H`, `G=Y`, `B=VIS`; this is the default Epic mapping.
  The earlier equal mix remains available by explicitly setting
  `EuclidEpicSettings(green_vis_weight=0.5)`
- a `VIS-H > 1.25 mag` red-source mask with VIS-only point-source protection;
  H and Y are never used to classify point sources, and the Euclid VIS point
  spread function is treated as having a typical FWHM of 1.6 pixels. The
  existing compact-peak detector is augmented with DAOStarFinder detections
  whose native VIS peak is above the sigma-clipped background by 5 sigma and
  whose mean positive brightness within 3 pixels is at least 10 times the mean
  in the 3--6 pixel annulus; DAO and existing detections are merged within a
  2-pixel matching radius
- a bright-VIS host veto, validated on rank 1539, that measures VIS light on a
  12-pixel scale and rejects red-mask ellipses inside connected host regions
  brighter than 5 times the native-pixel VIS noise and at least 500 pixels in
  area; this prevents dust in luminous galaxies from receiving the red-source
  Screen enhancement
- one equivalent feathered ellipse per accepted red source
- a post-STF H-to-VIS Screen luminance blend with strength `0.58`
- the original STCI post-HT, SCNR, and saturation chain, followed by the Euclid--SGA final SCNR pass

```python
from STCI import Euclidimg

result = Euclidimg(
    ra=39.446736,
    dec=-33.822218,
    size=52.965,
    path="PGC671065_epic",
    cred="Euclid/cred.txt",
    output_jpg="PGC671065_EuclidEpic.tiff",
    style="Euclid Epic",
)
```

The Epic style is a display composite and must not be interpreted photometrically. The style changes rendering only; `Euclidimg` retains the existing Euclid FITS downloader. To render already restored `BGSUB+BGMOD` inputs, call `mk_euclid_epicimg([H_fits, Y_fits, VIS_fits], output_jpg=...)` directly.

## Download Euclid FITS Only

```python
from Download_Euclid import EUC_download

fits_paths = EUC_download(
    ra=50.7163333,
    dec=-39.7693889,
    size=5.0,
    path="euclid_fits",
    cred="Euclid/cred.txt",
)
```
