FITSCutout

class astrocut.FITSCutout(input_files: List[str | Path | S3Path], coordinates: SkyCoord | str, cutout_size: int | ndarray | Quantity | List[int] | Tuple[int] = 25, fill_value: int | float = nan, limit_rounding_method: str = 'round', extension: int | List[int] | Literal['all'] | None = None, single_outfile: bool = True, verbose: bool = False, *, fsspec_kwargs: dict | None = None)

Bases: ImageCutout

Class for creating cutouts from FITS files.

Parameters:

input_fileslist

List of input image files.

coordinatesstr | SkyCoord

Coordinates of the center of the cutout.

cutout_sizeint | array | list | tuple | Quantity

Size of the cutout array.

fill_valueint | float

Value to fill the cutout with if the cutout is outside the image.

limit_rounding_methodstr

Method to use for rounding the cutout limits. Options are ‘round’, ‘ceil’, and ‘floor’.

extensionint | list | ‘all’

Optional, default None. The extension(s) to cutout from. If None, the first extension with data is used.

single_outfilebool

Optional, default True. If True, all cutouts are written to a single file or HDUList.

verbosebool

If True, log messages are printed to the console.

fsspec_kwargsdict

Optional, default None. Keyword arguments to pass through to s3fs for cloud-hosted files.

Attributes:

cutouts_by_filedict

The cutouts as a list of FITSCutout.CutoutInstance objects stored by input filename.

fits_cutoutslist

Return the cutouts as a list astropy.io.fits.HDUList objects.

hdu_cutouts_by_filedict

The cutouts as astropy.io.fits.ImageHDU objects stored by input filename.

Methods

cutout()	Generate cutouts from a list of input images.
write_as_fits(output_dir, cutout_prefix)	Write the cutouts to files in FITS format.

Attributes Summary

fits_cutouts	Return the cutouts as a list astropy.io.fits.HDUList objects.
image_cutouts	Return the cutouts as a list of PIL.Image objects.

Methods Summary

cutout()	Generate cutouts from a list of input images.
get_image_cutouts([stretch, minmax_percent, ...])	Get the cutouts as Image objects given certain normalization parameters.
normalize_img(img_arr[, stretch, ...])	Apply given stretch and scaling to an image array.
parse_size_input(cutout_size, *[, allow_zero])	Makes the given cutout size into a length 2 array.
write_as_fits([output_dir, cutout_prefix])	Write the cutouts to memory or to a file in FITS format.
write_as_img([stretch, minmax_percent, ...])	Write the cutout to memory or to a file in an image format.
write_as_zip([output_dir, filename])	Package the FITS cutouts into a zip archive without writing intermediate files.

Attributes Documentation

fits_cutouts

Return the cutouts as a list astropy.io.fits.HDUList objects.

image_cutouts

Return the cutouts as a list of PIL.Image objects.

If the image objects have not been generated yet, they will be generated with default normalization parameters.

Methods Documentation

cutout() → str | List[str] | List[HDUList]

Generate cutouts from a list of input images.

Returns:

cutout_pathPath | list

Cutouts as memory objects or path(s) to the written cutout files.

Raises:

InvalidQueryError

If no cutouts contain data.

get_image_cutouts(stretch: str | None = 'asinh', minmax_percent: List[int] | None = None, minmax_value: List[int] | None = None, invert: bool | None = False, colorize: bool | None = False, flip_orientation: bool | None = True) → List[Image]

Get the cutouts as Image objects given certain normalization parameters. This method also sets the image_cutouts attribute.

Parameters:

stretchstr

Optional, default ‘asinh’. The stretch to apply to the image array. Valid values are: asinh, sinh, sqrt, log, linear

minmax_percentarray

Optional. Interval based on a keeping a specified fraction of pixels (can be asymmetric) when scaling the image. The format is [lower percentile, upper percentile], where pixel values below the lower percentile and above the upper percentile are clipped. Only one of minmax_percent and minmax_value should be specified.

minmax_valuearray

Optional. Interval based on user-specified pixel values when scaling the image. The format is [min value, max value], where pixel values below the min value and above the max value are clipped. Only one of minmax_percent and minmax_value should be specified.

invertbool

Optional, default False. If True the image is inverted (light pixels become dark and vice versa).

colorizebool

Optional, default False. If True, the first three cutouts will be combined into a single RGB image.

flip_orientationbool

Optional, default True. If True, the cutout images are flipped vertically to match the orientation of the input images.

Returns:

image_cutoutslist

List of Image objects representing the cutouts.

static normalize_img(img_arr: ndarray, stretch: str = 'asinh', minmax_percent: List[int] | None = None, minmax_value: List[int] | None = None, invert: bool = False) → ndarray

Apply given stretch and scaling to an image array.

Parameters:

img_arrarray

The input image array.

stretchstr

Optional, default ‘asinh’. The stretch to apply to the image array. Valid values are: asinh, sinh, sqrt, log, linear

minmax_percentarray

Optional. Interval based on a keeping a specified fraction of pixels (can be asymmetric) when scaling the image. The format is [lower percentile, upper percentile], where pixel values below the lower percentile and above the upper percentile are clipped. Only one of minmax_percent and minmax_value shoul be specified.

minmax_valuearray

Optional. Interval based on user-specified pixel values when scaling the image. The format is [min value, max value], where pixel values below the min value and above the max value are clipped. Only one of minmax_percent and minmax_value should be specified.

invertbool

Optional, default False. If True the image is inverted (light pixels become dark and vice versa).

Returns:

responsearray

The normalized image array, in the form in an integer arrays with values in the range 0-255.

Raises:

InvalidInputError

If the stretch is not supported.

static parse_size_input(cutout_size, *, allow_zero: bool = False) → ndarray

Makes the given cutout size into a length 2 array.

Parameters:

cutout_sizeint, array-like, Quantity

The size of the cutout array. If cutout_size is a scalar number or a scalar Quantity, then a square cutout of cutout_size will be created. If cutout_size has two elements, they should be in (ny, nx) order. Scalar numbers in cutout_size are assumed to be in units of pixels. Quantity objects must be in pixel or angular units.

allow_zerobool, optional

If True, allows cutout dimensions to be zero. Default is False.

Returns:

responsearray

Length two cutout size array, in the form [ny, nx].

write_as_fits(output_dir: str | Path = '.', cutout_prefix: str = 'cutout') → List[str]

Write the cutouts to memory or to a file in FITS format.

Returns:

cutout_pathslist

A list of paths to the cutout FITS files.

write_as_img(stretch: str | None = 'asinh', minmax_percent: List[int] | None = None, minmax_value: List[int] | None = None, invert: bool | None = False, colorize: bool | None = False, output_format: str = '.jpg', output_dir: str | Path = '.', cutout_prefix: str = 'cutout', flip_orientation: bool | None = True) → str | List[str]

Write the cutout to memory or to a file in an image format. If colorize is set, the first 3 cutouts will be combined into a single RGB image. Otherwise, each cutout will be written to a separate file.

Parameters:

stretchstr

Optional, default ‘asinh’. The stretch to apply to the image array. Valid values are: asinh, sinh, sqrt, log, linear

minmax_percentarray

Optional. Interval based on a keeping a specified fraction of pixels (can be asymmetric) when scaling the image. The format is [lower percentile, upper percentile], where pixel values below the lower percentile and above the upper percentile are clipped. Only one of minmax_percent and minmax_value shoul be specified.

minmax_valuearray

Optional. Interval based on user-specified pixel values when scaling the image. The format is [min value, max value], where pixel values below the min value and above the max value are clipped. Only one of minmax_percent and minmax_value should be specified.

invertbool

Optional, default False. If True the image is inverted (light pixels become dark and vice versa).

colorizebool

Optional, default False. If True, the first three cutouts will be combined into a single RGB image.

flip_orientationbool

Optional, default True. If True, the cutout images are flipped vertically to match the orientation of the input images.

output_formatstr

Optional, default ‘.jpg’. The output format for the cutout image(s).

output_dirstr | Path

Optional, default ‘.’. The directory to write the cutout image(s) to.

cutout_prefixstr

Optional, default ‘cutout’. The prefix to add to the cutout image file name.

Returns:

cutout_pathList[Path]

Path(s) to the written cutout files.

Raises:

InvalidInputError

If less than three inputs were provided for a colorized cutout.

write_as_zip(output_dir: str | Path = '.', filename: str | Path | None = None) → str

Package the FITS cutouts into a zip archive without writing intermediate files.

Parameters:

output_dirstr | Path, optional

Directory where the zip will be created. Default ‘.’.

filenamestr | Path | None, optional

Name (or path) of the output zip file. If not provided, defaults to ‘astrocut_{ra}_{dec}_{size}.zip’. If provided without a ‘.zip’ suffix, the suffix is added automatically.

Returns:

str

Path to the created zip file.