BoundingBox

BoundingBox(ixmin, ixmax, iymin, iymax)

Pixel-index bounding box with exclusive upper bounds.

Parameters

ixmin : int: Inclusive lower and exclusive upper x pixel indices.
ixmax : int: Inclusive lower and exclusive upper x pixel indices.
iymin : int: Inclusive lower and exclusive upper y pixel indices.
iymax : int: Inclusive lower and exclusive upper y pixel indices.

Notes

Bounding boxes may extend outside an image. Use :meth:overlap_slices to obtain matching image and bbox-tight mask slices.

Attributes

Name	Description
shape	Mask-array shape as `(ny, nx)`.

Methods

Name	Description
apsum	Return aperture sum, and npix by default, for raw aperture weights.
npix	Return the in-frame sum of raw aperture weights for `shape`.
overlap_slices	Return image and mask slices for the overlap with `shape`.
to_fits_section	Return this box as a FITS image section string.
to_image	Embed bbox-tight mask weights in a full image array.
weighted_cutout	Return a bbox-tight weighted cutout for raw aperture weights.
weighted_values	Return weighted values for positive raw aperture weights.

apsum

BoundingBox.apsum(weights, image, mask=None, *, return_npix=True, validate=True)

Return aperture sum, and npix by default, for raw aperture weights.

Parameters

weights : array_like: Bbox-tight aperture weights with shape self.shape.
image : array_like: Two-dimensional image to sample.
mask : array_like of bool = None: Boolean image mask with the same shape as image. True pixels contribute zero weight.
return_npix : bool = True: If True, return (apsum, npix). If False, return only apsum.
validate : bool = True: If False, trust that weights, image, and mask are already valid and aligned.

Returns

apsum : float: Sum of image * weight over the overlapping, unmasked footprint. Accumulation uses float64, even when both the image and stored weights are float32.
npix : float: Sum of the contributing aperture weights. This can be smaller than the analytic aperture area when the aperture is clipped by the image edge or by mask. Accumulation uses float64. Returned only when return_npix=True.

npix

BoundingBox.npix(weights, shape, mask=None, *, validate=True)

Return the in-frame sum of raw aperture weights for shape.

Parameters

weights : array_like: Bbox-tight aperture weights with shape self.shape.
shape : tuple[int, int]: Full image shape as (ny, nx). This controls image-edge clipping.
mask : array_like of bool = None: Boolean image mask with shape shape. True pixels are excluded from the returned effective pixel count.
validate : bool = True: If False, trust that weights, shape, and mask are already valid and aligned.

Returns

npix : float: Sum of in-frame, unmasked aperture weights. Accumulation uses float64, even when the stored weights are float32.

overlap_slices

BoundingBox.overlap_slices(shape)

Return image and mask slices for the overlap with shape.

Parameters

shape : tuple[int, int]: Full image shape as (ny, nx).

Returns

: tuple of tuple of slice, or None: (data_slices, mask_slices) when the bounding box overlaps the image. data_slices select the in-frame pixels from the full image; mask_slices select the matching region from the bbox-tight mask. Returns None when the bounding box is fully outside the image.

to_fits_section

BoundingBox.to_fits_section(shape=None)

Return this box as a FITS image section string.

Parameters

shape : tuple[int, int] = None: Full image shape as (ny, nx). If supplied, the returned section is clipped to the image overlap. If omitted, the raw bounding box must already be valid in FITS coordinates.

Returns

: str: FITS-standard image section in 1-indexed, x,y order, with inclusive upper bounds.

Raises

: ValueError: If the raw bounding box has nonpositive extent, if an unclipped box would start before FITS pixel 1, or if the box does not overlap shape.

to_image

BoundingBox.to_image(weights, shape, fill_value=0.0, *, validate=True)

Embed bbox-tight mask weights in a full image array.

Parameters

weights : array_like: Bbox-tight aperture weights with shape self.shape.
shape : tuple[int, int]: Output image shape as (ny, nx).
fill_value : float = 0.0: Value assigned to pixels outside the aperture mask footprint.
validate : bool = True: If False, trust that weights and shape are already valid.

Returns

: ndarray: Floating image with shape shape. If this bounding box is partly outside the image, only the overlapping weights are copied. If it is fully outside, the returned image contains only fill_value.

weighted_cutout

BoundingBox.weighted_cutout(
    weights,
    image,
    mask=None,
    fill_value=np.nan,
    *,
    validate=True,
)

Return a bbox-tight weighted cutout for raw aperture weights.

Parameters

weights : array_like: Bbox-tight aperture weights with shape self.shape.
image : array_like: Two-dimensional image to sample.
mask : array_like of bool = None: Boolean image mask with the same shape as image. True pixels are set to fill_value in the returned cutout.
fill_value : float = np.nan: Value used in returned cutout pixels that do not overlap image.
validate : bool = True: If False, trust that weights, image, and mask are already valid and aligned.

Returns

: ndarray: Floating cutout with shape self.shape. Unmasked overlapping pixels contain image * weight; masked and non-overlapping pixels contain fill_value.

weighted_values

BoundingBox.weighted_values(weights, image, mask=None, *, validate=True)

Return weighted values for positive raw aperture weights.

Parameters

weights : array_like: Bbox-tight aperture weights with shape self.shape.
image : array_like: Two-dimensional image to sample.
mask : array_like of bool = None: Boolean image mask with the same shape as image. True pixels are omitted from the returned vector.
validate : bool = True: If False, trust that weights, image, and mask are already valid and aligned.

Returns

: ndarray: One-dimensional floating array containing image * weight for in-frame pixels with positive aperture weight. Masked pixels and off-image pixels are omitted.