Source Cutouts

A module that provides tools for creating and mapping image cutouts.

Author:Mihai Cara (for help, contact HST Help Desk) License:LICENSE

class subpixal.cutout.Cutout(data, wcs, blc=(0, 0), trc=None, dq=None, weight=None, src_id=0, data_units='rate', exptime=1, mode='strict', fillval=nan)

This is a class designed to facilitate work with image cutouts. It holds both information about the cutout (location in the image) as well as information about the image and source: source ID, exposure time, image units, WCS, etc.

This class also provides convinience tools for creating cutouts, saving them to or loading from files, and for converting pixel coordinates to world coordinates (and vice versa) using cutout’s pixel grid while preserving all distortion corrections from image’s WCS.

Parameters:

data: numpy.ndarray

Image data from which the cutout will be extracted.

wcs: astropy.wcs.WCS

World Coordinate System object describing coordinate transformations from image’s pixel coordinates to world coordinates.

blc: tuple of two int

Bottom-Left Corner coordinates (x, y) in the data of the cutout to be extracted.

trc: tuple of two int, None, optional

Top-Right Corner coordinates (x, y) in the data of the cutout to be extracted. Pixel with the coordinates trc is included. When trc is set to None, trc is set to the shape of the data image: (nx, ny).

dq: numpy.ndarray

Data quality array associated with image data. If provided, this array will be cropped the same way as image data and stored within the Cutout object.

weight: numpy.ndarray

Weight array associated with image data. If provided, this array will be cropped the same way as image data and stored within the Cutout object.

src_id : any type, None

Anything that can be used to associate the source being extracted with a record in a catalog. This value is simply stored within the Catalog object.

data_units: {‘counts’, ‘rate’}, optional

Indicates the type of data units: count-like or rate-like (counts per unit of time). This provides the information necessary for unit conversion when needed.

exptime: float, optional

Exposure time of image imdata.

mode: {‘strict’, ‘fill’}

Allowed overlap between extraction rectangle for the cutout and the input image. When mode is 'strict' then a PartialOverlapError error will be raised if the extraction rectangle is not completely within the boundaries of input image. When mode is 'fill', then parts of the cutout that are outside the boundaries of the input image will be filled with the value specified by the fillval parameter.

fillval: scalar

All elements of the cutout that are outside the input image will be assigned this value. This parameter is ignored when mode is set to 'strict'.

Raises:

`NoOverlapError`

When cutout is completely outside of the input image.

`PartialOverlapError`

When cutout only partially overlaps input image and mode is set to 'strict'.

DEFAULT_ACCURACY = 1e-05

DEFAULT_MAXITER = 50

DEFAULT_QUIET = True

blc

Set/Get coordinate of the bottom-left corner.

data

Get image data.

data_units

Get/Set image data units. Possible values are: ‘rate’ or ‘counts’.

dq

Set/Get cutout’s data quality.

dx

Set/Get displacement of the image grid along the X-axis in pixels.

dy

Set/Get displacement of the image grid along the Y-axis in pixels.

exptime

Get/Set exposure time.

extraction_slice

Get slice object that shows the slice in the input data array used to extract the cutout.

get_bbox(wrt='orig')

Get a numpy.ndarray of pixel coordinates of vertices of the bounding box. The returned array has the shape (4, 2) and contains the coordinates of the outer corners of pixels (centers of pixels are considered to have integer coordinates).

Parameters:

wrt : {‘orig’, ‘blc’, ‘world’}, optional

height

Get width of the cutout.

insertion_slice

Get slice object that shows the slice in the cutout data array into which image data were placed. This slice coincides with the entire cutout data array when mode is 'strict' but can point to a smaller region when mode is 'fill'.

mask

Set/Get cutout’s mask.

naxis

Get FITS NAXIS property of the cutout.

pix2world(*args, origin=0)

Convert _cutout_’s pixel coordinates to world coordinates.

pscale

Get pixel scale in the tangent plane at the reference point.

src_id

Set/Get source ID.

trc

Set/Get coordinate of the top-right corner.

wcs

Get image’s WCS from which the cutout was extracted.

weight

Set/Get cutout’s pixel weight.

width

Get width of the cutout.

world2pix(*args, origin=0)

Convert world coordinates to _cutout_’s pixel coordinates.

subpixal.cutout.create_primary_cutouts(catalog, segmentation_image, imdata, imwcs, imdq=None, imweight=None, data_units='counts', exptime=1, pad=1)

A function for creating first-order cutouts from a (drizzle-)combined image given a source catalog and a segmentation image.

Parameters:

catalog : SourceCatalog, astropy.table.Table

A table of sources which need to be extracted. catalog must contain a column named 'id' which contains IDs of segments from the segmentation_image.

segmentation_image: numpy.ndarray

A 2D segmentation image identifying sources from the catalog in imdata.

imdata: numpy.ndarray

Image data array.

imwcs: astropy.wcs.WCS

World coordinate system of image imdata.

imdq: numpy.ndarray, None, optional

Data quality array corresponding to imdata.

imweight: numpy.ndarray, None, optional

Pixel weight array corresponding to imdata.

data_units: {‘counts’, ‘rate’}, optional

Indicates the type of data units: count-like or rate-like (counts per unit of time). This provides the information necessary for unit conversion when needed.

exptime: float, optional

Exposure time of image imdata.

pad: int, optional

Number of pixels to pad around the minimal rectangle enclosing a source segmentation.

Returns:

segments : list of Cutout

A list of extracted Cutout s.

subpixal.cutout.create_cutouts(primary_cutouts, segmentation_image, drz_data, drz_wcs, flt_data, flt_wcs, drz_dq=None, drz_weight=None, drz_data_units='rate', drz_exptime=1, flt_dq=None, flt_weight=None, flt_data_units='counts', flt_exptime=1, pad=2)

A function for mapping “primary cutouts” (cutouts formed form a drizzle-combined image) to “input images” (generally speaking, distorted images) and some other “drizzle-combined” image. This “other” drizzle-combined image may be the same image used to create primary cutouts.

This function performs the following mapping/cutout extractions:

> primary_cutouts -> imcutouts -> drz_cutouts

That is, this function takes as input primary_cutouts and finds equivalent cutouts in the “input” (distorted) “flt” image. Then it takes the newly found imcutouts cutouts and finds/extracts equivalent cutouts in the “drz” (usually distortion-corrected) image. Fundamentally, this function first calls create_input_image_cutouts to create imcutouts and then it calls drz_from_input_cutouts to create drz_cutouts .

Parameters:

primary_cutouts : list of Cutout

A list of Cutout s that need to be mapped to another image.

segmentation_image: numpy.ndarray

A 2D segmentation image identifying sources from the catalog in imdata. This is used for creating boolean mask of bad (not within a segmentation region) pixels.

drz_data: numpy.ndarray

Image data array of “drizzle-combined” image.

drz_wcs: astropy.wcs.WCS

World coordinate system of “drizzle-combined” image.

flt_data: numpy.ndarray

Image data array of “distorted” image (input to the drizzle).

flt_wcs: astropy.wcs.WCS

World coordinate system of “distorted” image.

drz_dq: numpy.ndarray, None, optional

Data quality array corresponding to drz_data.

drz_weight: numpy.ndarray, None, optional

Pixel weight array corresponding to drz_data.

drz_data_units: {‘counts’, ‘rate’}, optional

Indicates the type of data units for the drz_data : count-like or rate-like (counts per unit of time). This provides the information necessary for unit conversion when needed.

drz_exptime: float, optional

Exposure time of image drz_data.

flt_dq: numpy.ndarray, None, optional

Data quality array corresponding to flt_data.

flt_weight: numpy.ndarray, None, optional

Pixel weight array corresponding to flt_data.

flt_data_units: {‘counts’, ‘rate’}, optional

Indicates the type of data units for the flt_data: count-like or rate-like (counts per unit of time). This provides the information necessary for unit conversion when needed.

flt_exptime: float, optional

Exposure time of image flt_data.

pad: int, optional

Number of pixels to pad around the minimal rectangle enclosing a mapped cutout (a cutout to be extracted).

Returns:

flt_cutouts : list of Cutout

A list of Cutout s extracted from the flt_data. These cutouts are large enough to enclose cutouts from the input primary_cutouts when pad=1 (to make sure even partial pixels are included).

drz_cutouts : list of Cutout

A list of extracted Cutout s from the drz_data. These cutouts are large enough to enclose cutouts from the flt_cutouts when pad=1 (to make sure even partial pixels are included).

exception subpixal.cutout.NoOverlapError

Raised when cutout does not intersect the extraction image.

exception subpixal.cutout.PartialOverlapError

Raised when cutout only partially overlaps the extraction image.