Source Cutouts¶
A module that provides tools for creating and mapping image cutouts.
- Author
Mihai Cara (for help, contact HST Help Desk)
- 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)[source]¶ 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 thedata
of the cutout to be extracted.- trc: tuple of two int, None, optional
Top-Right Corner coordinates
(x, y)
in thedata
of the cutout to be extracted. Pixel with the coordinatestrc
is included. Whentrc
is set toNone
,trc
is set to the shape of thedata
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. Ifsrc_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 aPartialOverlapError
error will be raised if the extraction rectangle is not completely within the boundaries of input image. Whenmode
is'fill'
, then parts of the cutout that are outside the boundaries of the input image will be filled with the value specified by thefillval
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')[source]¶ 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 whenmode
is'fill'
.
-
property
mask
¶ Set/Get cutout’s mask.
-
property
naxis
¶ Get FITS
NAXIS
property of the cutout.
-
pix2world
(self, *args, origin=0)[source]¶ 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.
-
subpixal.cutout.
create_primary_cutouts
(catalog, segmentation_image, imdata, imwcs, imdq=None, dqbitmask=0, imweight=None, data_units='counts', exptime=1, pad=1)[source]¶ 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 thesegmentation_image
. Ifcatalog
is anastropy.table.Table
, then it’smeta
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, thendqbitmask
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
and4+8
are equivalent to settingdqbitmask
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 themask
property of the returned cutouts.In order to reverse the meaning of thedqbitmask
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 setdqbitmask
to~4+8
, or~4,8
. To obtain the same effect with anint
input value (except for 0), enter-(4+8+1)=-9
. Following this convention, adqbitmask
string value of'~0'
would be equivalent to settingdqbitmask=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)[source]¶ 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 foundimcutouts
cutouts and finds/extracts equivalent cutouts in the “drz” (usually distortion-corrected) image. Fundamentally, this function first callscreate_input_image_cutouts
to createimcutouts
and then it callsdrz_from_input_cutouts
to createdrz_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 ofbad
(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, seecreate_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, seecreate_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 theflt_data
. These cutouts are large enough to enclose cutouts from the inputprimary_cutouts
whenpad=1
(to make sure even partial pixels are included).- drz_cutoutslist of Cutout
A list of extracted
Cutout
s from thedrz_data
. These cutouts are large enough to enclose cutouts from theflt_cutouts
whenpad=1
(to make sure even partial pixels are included).