pypeit.core.mosaic module

Provide basic mosaicing functions.

pypeit.core.mosaic.build_image_mosaic(imgs, tforms, ivar=None, bpm=None, mosaic_shape=None, cval=0.0, order=0, overlap='combine')[source]

Use the provided images and transformation matrices to construct an image mosaic.

Warning

Beware when using order > 0!

Bad-pixel masks are always mapped to the mosaic image using order=0 (i.e., without interpolation). However, masked pixels are not excluded from the input images during the transformation. For higher order interpolations (order > 0), this means that the masked pixels can contribute to the interpolation for any given output pixel. Users should appropriately consider how these pixels will affect the mosaic pixels before calling this function.

Similarly, error propagation from the input image to the mosaic image is only approximate when order > 0. Error propagaion is performed simply by applying the coordinate transform to each variance image with the same order as used for the input image, and then combining those variances as necessary in overlap regions.

Tests show that this approach is also not invertable. I.e., iteratively transforming the image back and forth between the native and mosaic frames lead to image drifts.

Parameters:

  • imgs (list of numpy.ndarray) – List of numpy.ndarray images to include in the mosaic. If arrays do not contain floating-point values, they will be cast as np.float64 before passing them to scipy.ndimage.affine_transform. The shape of all the input images must be identical if mosaic_shape is None.

  • tforms (list of numpy.ndarray) – List of numpy.ndarray objects with the transformation matrices necessary to convert between image and mosaic coordinates. See pypeit.core.mosaic.build_image_mosaic_transform(). The number of transforms must match the number of images. If mosaic_shape is None, the transforms are considered in a relative sense. That is, the shape of the output mosaic is determined by applying these transforms to the bounding boxes of each image and then determining the shape needed to retain all pixels in the input images. The transforms are then adjusted appropriately to map to this shape; see prepare_mosaic(). If mosaic_shape is not None, these transforms are expected to map directly to the output mosaic coordinates.

  • ivar (list of numpy.ndarray, optional) – List of numpy.ndarray images with the inverse variance of the image data. The number of inverse-variance images must match the number of images in the mosaic. If None, inverse variance is returned as None.

  • bpm (list of numpy.ndarray, optional) – List of boolean numpy.ndarray objects with the bad-pixel mask for each image in the mosaic. The number of bad-pixel masks must match the number of images in the mosaic. If None, all input pixels are considered valid.

  • mosaic_shape (tuple, optional) – Shape for the output image. If None, the shape is determined by pypeit.core.mosaic.prepare_mosaic() and the shape of all the input images must be identical.

  • cval (float, optional) – The value used to fill empty pixels in the mosaic.

  • order (int, optional) – The order of the spline interpolation of each input image onto the mosaic grid. This is passed directly to scipy.ndimage.affine_transform. The order has to be in the range 0-5; order=0 is nearest-grid-point interpolations, order=1 is linear.

  • overlap (str, optional) –

    Keyword that indicates how to handle pixels in the regions where multiple images overlap in the mosaic. Options are:

    • 'combine': Average the values of the pixels and, if the inverse variance is provided, propagate the error.

    • 'error': Raise an exception. Largely provided for testing under the expectation that no pixels should overlap in the mosaic.

Returns:

Four objects are returned. The first three are numpy.ndarray objects with the mosaic image, its inverse variance (None if no inverse variance is provided), and an integer array with the number of input pixels in each output pixel. The last contains the detailed transformation matrices applied to each image. If mosaic_shape is provided, these are identical to the input tforms; otherwise, these are the transforms adjusted from the relative frame to the absolute mosaic frame given its determined shape; see prepare_mosaic().

Return type:

tuple

pypeit.core.mosaic.build_image_mosaic_transform(shape, shift, rotation=0.0, binning=(1.0, 1.0))[source]

Build the affine transform matrix for a binned image.

The order of operations is as follows:

  1. Shift the coordinate system to the center of the image, assuming the (0,0) coordinate is at the center of the first pixel.

  2. For binning that is different in each dimension, scale the size of each pixel back to the correct aspect ratio.

  3. Rotate the image.

  4. Undo the dimension scaling to account for the binning aspect ratio.

  5. Undo the shift to the center of the image.

  6. Apply the requested shift, accounting for the binning.

Steps 1-5 are only performed if the image is rotated. Steps 2 and 4 are only done if the binning is not square. All steps are compiled into a single transformation matrix using affine_transform_series().

The coordinate reference frame adopts numpy/matplotlib conventions; see Detector Mosaics. That is, if you plot the image using matplotlib.pyplot.imshow, the first axis is along the ordinate (Cartesian \(y\)) and the second axis is along the abscissa (Cartesian \(x\)). Shifts and rotation are with respect to this coordinate system; see descriptions of shift and rotation.

Parameters:

  • shape (tuple) – A two-tuple with the shape of the binned image. In terms of the coordinate system, this provides the number of pixels along Cartesian \(y\) then along Cartesian \(x\); i.e., (ny, nx). See description above.

  • shift (tuple) – A two-tuple with the nominal shift in Cartesian coordinates of the unbinned image in the mosaic in each dimension. For example, setting shift=(1,10) means the image is shifted \(+1\) pixel in \(x\) and \(+10\) pixels in \(y\).

  • rotation (float, optional) – The counter-clockwise rotation in degrees of the unbinned image in the mosaic. The rotation assumes the coordinate frame described above.

  • binning (tuple, optional) – The number of pixels binned in each dimension. The order should match the provided image shape. That is, the order is the number of binned pixels in \(y\), then the number in \(x\). This only has an effect on the results when the binning is not the same in both dimensions.

Returns:

The single coordinate transformation matrix that applies all transformations. See pypeit.core.transform.affine_transform_series().

Return type:

numpy.ndarray

pypeit.core.mosaic.prepare_mosaic(shape, tforms, buffer=0, inplace=False)[source]

Prepare to mosaic images by determining the shape of the mosaic image and adjusting the transformation coordinates to the mosaic pixel coordinates.

Parameters:

  • shape (tuple) – A two-tuple with the shape of the images to mosaic. The shape is assumed to be the same for all images.

  • tforms (list) – A list of \(3\times3\) numpy.ndarray objects with the transformations to apply to each image. These are adjusted as necessary to perform the transformations within the coordinate system of the mosaic image.

  • buffer (int, optional) – An added buffer in each dimension that frames the mosaic image and should not have any image data. Buffer must be non-negative.

  • inplace (bool, optional) – If True, alter the provided tforms in-place. Otherwise, the returned transforms are new arrays.

Returns:

Returns the shape for the mosaic image as a two-tuple and the new transformation matrices as a list of numpy.ndarray objects.

Return type:

tuple