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, src_pos=None, src_weight=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).

src_pos: tuple of two int, None, optional

Image coordinates (x, y) in the input ``data`` image of the source contained in this cutout. If src_pos is set to the default value (None), then it will be set to the center of the cutout.

Warning

TODO: The algorithm for src_pos computation most likely will need to be revised to obtain better estimates for the position of the source in the cutout.

src_weightfloat, None, optional

The weight of the source in the cutout to be used in alignment when fitting geometric transformations.

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_idany 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

property blc

Set/Get coordinate of the bottom-left corner.

property cutout_src_pos

Get/set source position in the cutout’s image coordinates.

property data

Get image data.

property data_units

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

property dq

Set/Get cutout’s data quality.

property dx

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

property dy

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

property exptime

Get/Set exposure time.

property extraction_slice

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

get_bbox(self, 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

property height

Get width of the cutout.

property 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'.

property mask

Set/Get cutout’s mask.

property naxis

Get FITS NAXIS property of the cutout.

pix2world(self, *args, origin=0)

Convert _cutout_’s pixel coordinates to world coordinates.

property pscale

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

property src_id

Set/Get source ID.

property src_pos

Get/set source position in the cutout’s image.

property src_weight

Get/set source’s weight for fitting geometric transformations.

property trc

Set/Get coordinate of the top-right corner.

property wcs

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

property weight

Set/Get cutout’s pixel weight.

property width

Get width of the cutout.

world2pix(self, *args, origin=0)

Convert world coordinates to _cutout_’s pixel coordinates.

subpixal.cutout.create_primary_cutouts(catalog, segmentation_image, imdata, imwcs, imdq=None, dqbitmask=0, 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

catalogImageCatalog, 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. If catalog is an astropy.table.Table, then it’s meta attribute may contain an optional 'weight_colname' item indicating which column in the table shows source weight. If not provided, unweighted fitting will be performed.

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 (DQ) array corresponding to imdata.

dqbitmaskint, str, None, optional

Integer sum of all the DQ bit values from the input imdq DQ array that should be considered “good” when building masks for cutouts. For example, if pixels in the DQ array can be combinations of 1, 2, 4, and 8 flags and one wants to consider DQ “defects” having flags 2 and 4 as being acceptable, then dqbitmask should be set to 2+4=6. Then a DQ pixel having values 2,4, or 6 will be considered a good pixel, while a DQ pixel with a value, e.g., 1+2=3, 4+8=12, etc. will be flagged as a “bad” pixel.

Alternatively, one can enter a comma- or ‘+’-separated list of integer bit flags that should be added to obtain the final “good” bits. For example, both 4,8 and 4+8 are equivalent to setting dqbitmask to 12.

Default value (0) will make all non-zero pixels in the DQ mask to be considered “bad” pixels, and the corresponding image pixels will be flagged in the mask property of the returned cutouts.

Set dqbitmask to None to not consider DQ array when computing cutout’s mask.

In order to reverse the meaning of the dqbitmask parameter from indicating values of the “good” DQ flags to indicating the “bad” DQ flags, prepend ‘~’ to the string value. For example, in order to mask only pixels that have corresponding DQ flags 4 and 8 and to consider as “good” all other pixels set dqbitmask to ~4+8, or ~4,8. To obtain the same effect with an int input value (except for 0), enter -(4+8+1)=-9. Following this convention, a dqbitmask string value of '~0' would be equivalent to setting dqbitmask=None.

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

segmentslist 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_dqbitmask=0, drz_weight=None, drz_data_units='rate', drz_exptime=1, flt_dq=None, flt_dqbitmask=0, flt_weight=None, flt_data_units='counts', flt_exptime=1, pad=2, combine_seg_mask=True)

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_cutoutslist 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_dqbitmaskint, str, None, optional

Integer sum of all the DQ bit values from the input drz_dq DQ array that should be considered “good” when building masks for cutouts. For more details, see create_primary_cutouts.

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_dqbitmaskint, str, None, optional

Integer sum of all the DQ bit values from the input flt_dq DQ array that should be considered “good” when building masks for cutouts. For more details, see create_primary_cutouts.

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).

combine_seg_mask: bool, optional

Indicates whether to combine segmanetation mask with cutout’s mask. When True, segmentation image is used to create a mask that indicates “good” pixels in the image. This mask is combined with cutout’s mask.

Returns

flt_cutoutslist 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_cutoutslist 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.