ASDFCutout

Bases: ImageCutout

Class for creating cutouts from ASDF 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. Default is np.nan. If the input data array has an integer data type, the fill value will be converted to an integer (e.g., a fill value of 1.0 will be converted to 1). If the conversion fails, it will default to 0.
keystr: Optional, default None. Access key ID for S3 file system.
secretstr: Optional, default None. Secret access key for S3 file system.
tokenstr: Optional, default None. Security token for S3 file system.
litebool: Optional, default True. If True, the cutout will be created in “lite” mode, which means that it will only contain the data and an updated world coordinate system. If False, cutouts will be made from all arrays in the input file (e.g., data, error, uncertainty, variance, etc.) where the last two dimensions match the shape of the science data array. It also preserves all of the metadata from the input file.
verbosebool: If True, log messages are printed to the console.

Attributes:

cutoutslist: The cutouts as a list of astropy.nddata.Cutout2D objects.
cutouts_by_filedict: The cutouts as astropy.nddata.Cutout2D objects stored by input filename.
fits_cutoutslist: Return the cutouts as a list astropy.io.fits.HDUList objects.
asdf_cutoutslist: Return the cutouts as a list of asdf.AsdfFile objects.
image_cutoutslist: Return the cutouts as a list of PIL.Image objects.

Methods

cutout()	Generate cutouts from a list of input images.
write_as_fits(output_dir)	Write the cutouts to disk or memory in FITS format.
write_as_asdf(output_dir)	Write the cutouts to disk or memory in ASDF format.

Attributes Summary

`asdf_cutouts`	Return the cutouts as a list of `asdf.AsdfFile` objects.
`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_asdf`([output_dir, validate_output])	Write the cutouts to disk or memory in ASDF format.
`write_as_fits`([output_dir])	Write the cutouts to disk or memory 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 ASDF or FITS cutouts into a zip archive without writing intermediates.

Attributes Documentation

asdf_cutouts: Return the cutouts as a list of asdf.AsdfFile objects.

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][source]

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 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_asdf(output_dir: str | Path = '.', validate_output: bool = True) → List[str][source]

Write the cutouts to disk or memory in ASDF format.

Parameters:

output_dirstr | Path: The output directory to write the cutouts to. Defaults to the current directory.
validate_outputbool: Whether to validate the output ASDF file. Defaults to True. Setting to False can speed up writing for large numbers of cutouts, but should only be used if you trust the output is valid.

Returns:

list: A list of paths to the cutout ASDF files.

write_as_fits(output_dir: str | Path = '.') → List[str][source]

Write the cutouts to disk or memory in FITS format.

Parameters:

output_dirstr | Path: The output directory to write the cutouts to. Defaults to the current directory.

Returns:

list: A list of paths to the cutout FITS files.

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, *, output_format: str = '.asdf') → str[source]

Package the ASDF or FITS cutouts into a zip archive without writing intermediates.

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.
output_formatstr, optional: Either ‘.asdf’ (default) or ‘.fits’. Determines which in-memory representation is zipped.

Returns:

str: Path to the created zip file.