drizzle 1.15.3__cp310-cp310-macosx_11_0_arm64.whl → 2.0.0__cp310-cp310-macosx_11_0_arm64.whl

drizzle/resample.py

@@ -0,0 +1,702 @@
+"""
+The `drizzle` module defines the `Drizzle` class, for combining input
+images into a single output image using the drizzle algorithm.
+"""
+import numpy as np
+
+from drizzle import cdrizzle
+
+__all__ = ["blot_image", "Drizzle"]
+
+SUPPORTED_DRIZZLE_KERNELS = [
+    "square",
+    "gaussian",
+    "point",
+    "turbo",
+    "lanczos2",
+    "lanczos3",
+]
+
+CTX_PLANE_BITS = 32
+
+
+class Drizzle:
+    """
+    A class for managing resampling and co-adding of multiple images onto a
+    common output grid. The main method of this class is :py:meth:`add_image`.
+    The main functionality of this class is to resample and co-add multiple
+    images onto one output image using the "drizzle" algorithm described in
+    `Fruchter and Hook, PASP 2002 <https://doi.org/10.1086/338393>`_.
+    In the simplest terms, it redistributes flux
+    from input pixels to one or more output pixels based on the chosen kernel,
+    supplied weights, and input-to-output coordinate transformations as defined
+    by the ``pixmap`` argument. For more details, see :ref:`main-user-doc`.
+
+    This class keeps track of the total exposure time of all co-added images
+    and also of which input images have contributed to an output (resampled)
+    pixel. This is accomplished via *context image*.
+
+    Main outputs of :py:meth:`add_image` can be accessed as class properties
+    ``out_img``, ``out_wht``, ``out_ctx``, and ``exptime``.
+
+    .. warning::
+        Output arrays (``out_img``, ``out_wht``, and ``out_ctx``) can be
+        pre-allocated by the caller and be passed to the initializer or the
+        class initializer can allocate these arrays based on other input
+        parameters such as ``output_shape``. If caller-supplied output arrays
+        have the correct type (`numpy.float32` for ``out_img`` and ``out_wht``
+        and `numpy.int32` for the ``out_ctx`` array) and if ``out_ctx`` is
+        large enough not to need to be resized, these arrays will be used as is
+        and may be modified by the :py:meth:`add_image` method. If not,
+        a copy of these arrays will be made when converting to the expected
+        type (or expanding the context array).
+
+    Output Science Image
+    --------------------
+
+    Output science image is obtained by adding input pixel fluxes according to
+    equations (4) and (5) in
+    `Fruchter and Hook, PASP 2002 <https://doi.org/10.1086/338393>`_.
+    The weights and coefficients in those equations will depend on the chosen
+    kernel, input image weights, and pixel overlaps computed from ``pixmap``.
+
+    Output Weight Image
+    -------------------
+
+    Output weight image stores the total weight of output science pixels
+    according to equation (4) in
+    `Fruchter and Hook, PASP 2002 <https://doi.org/10.1086/338393>`_.
+    It depends on the chosen kernel, input image weights, and pixel overlaps
+    computed from ``pixmap``.
+
+    Output Context Image
+    --------------------
+
+    Each pixel in the context image is a bit field that encodes
+    information about which input image has contributed to the corresponding
+    pixel in the resampled data array. Context image uses 32 bit integers to
+    encode this information and hence it can keep track of only 32 input images.
+    First bit corresponds to the first input image, second bit corrsponds to the
+    second input image, and so on. We call this (0-indexed) order "context ID"
+    which is represented by the ``ctx_id`` parameter/property. If the number of
+    input images exceeds 32, then it is necessary to have multiple context
+    images ("planes") to hold information about all input images with the first
+    plane encoding which of the first 32 images contributed to the output data
+    pixel, second plane representing next 32 input images (number 33-64), etc.
+    For this reason, context array is either a 2D array (if the total number
+    of resampled images is less than 33) of the type `numpy.int32` and shape
+    ``(ny, nx)`` or a a 3D array of shape ``(np, ny, nx)`` where ``nx`` and
+    ``ny`` are dimensions of image's data. ``np`` is the number of "planes"
+    equal to ``(number of input images - 1) // 32 + 1``. If a bit at position
+    ``k`` in a pixel with coordinates ``(p, y, x)`` is 0 then input image number
+    ``32 * p + k`` (0-indexed) did not contribute to the output data pixel
+    with array coordinates ``(y, x)`` and if that bit is 1 then input image
+    number ``32 * p + k`` did contribute to the pixel ``(y, x)`` in the
+    resampled image.
+
+    As an example, let's assume we have 8 input images. Then, when ``out_ctx``
+    pixel values are displayed using binary representation (and decimal in
+    parenthesis), one could see values like this::
+
+        00000001 (1) - only first input image contributed to this output pixel;
+        00000010 (2) - 2nd input image contributed;
+        00000100 (4) - 3rd input image contributed;
+        10000000 (128) - 8th input image contributed;
+        10000100 (132=128+4) - 3rd and 8th input images contributed;
+        11001101 (205=1+4+8+64+128) - input images 1, 3, 4, 7, 8 have contributed
+        to this output pixel.
+
+    In order to test if a specific input image contributed to an output pixel,
+    one needs to use bitwise operations. Using the example above, to test
+    whether input images number 4 and 5 have contributed to the output pixel
+    whose corresponding ``out_ctx`` value is 205 (11001101 in binary form) we
+    can do the following:
+
+    >>> bool(205 & (1 << (5 - 1)))  # (205 & 16) = 0 (== 0 => False): did NOT contribute
+    False
+    >>> bool(205 & (1 << (4 - 1)))  # (205 & 8) = 8 (!= 0 => True): did contribute
+    True
+
+    In general, to get a list of all input images that have contributed to an
+    output resampled pixel with image coordinates ``(x, y)``, and given a
+    context array ``ctx``, one can do something like this:
+
+    .. doctest-skip::
+
+        >>> import numpy as np
+        >>> np.flatnonzero([v & (1 << k) for v in ctx[:, y, x] for k in range(32)])
+
+    For convenience, this functionality was implemented in the
+    :py:func:`~drizzle.utils.decode_context` function.
+
+    References
+    ----------
+    A full description of the drizzling algorithm can be found in
+    `Fruchter and Hook, PASP 2002 <https://doi.org/10.1086/338393>`_.
+
+    Examples
+    --------
+    .. highlight:: python
+    .. code-block:: python
+
+        # wcs1 - WCS of the input image usually with distortions (to be resampled)
+        # wcs2 - WCS of the output image without distortions
+
+        import numpy as np
+        from drizzle.resample import Drizzle
+        from drizzle.utils import calc_pixmap
+
+        # simulate some data and a pixel map:
+        data = np.ones((240, 570))
+        pixmap = calc_pixmap(wcs1, wcs2)
+        # or simulate a mapping from input image to output image frame:
+        # y, x = np.indices((240, 570), dtype=np.float64)
+        # pixmap = np.dstack([x, y])
+
+        # initialize Drizzle object
+        d = Drizzle(out_shape=(240, 570))
+        d.add_image(data, exptime=15, pixmap=pixmap)
+
+        # access outputs:
+        d.out_img
+        d.out_ctx
+        d.out_wht
+
+    """
+
+    def __init__(self, kernel="square", fillval=None, out_shape=None,
+                 out_img=None, out_wht=None, out_ctx=None, exptime=0.0,
+                 begin_ctx_id=0, max_ctx_id=None, disable_ctx=False):
+        """
+        kernel: str, optional
+            The name of the kernel used to combine the input. The choice of
+            kernel controls the distribution of flux over the kernel. The kernel
+            names are: "square", "gaussian", "point", "turbo",
+            "lanczos2", and "lanczos3". The square kernel is the default.
+
+            .. warning::
+               The "gaussian" and "lanczos2/3" kernels **DO NOT**
+               conserve flux.
+
+        out_shape : tuple, None, optional
+            Shape (`numpy` order ``(Ny, Nx)``) of the output images (context
+            image will have a third dimension of size proportional to the number
+            of input images). This parameter is helpful when neither
+            ``out_img``, ``out_wht``, nor ``out_ctx`` images are provided.
+
+        fillval: float, None, str, optional
+            The value of output pixels that did not have contributions from
+            input images' pixels. When ``fillval`` is either `None` or
+            ``"INDEF"`` and ``out_img`` is provided, the values of ``out_img``
+            will not be modified. When ``fillval`` is either `None` or
+            ``"INDEF"`` and ``out_img`` is **not provided**, the values of
+            ``out_img`` will be initialized to `numpy.nan`. If ``fillval``
+            is a string that can be converted to a number, then the output
+            pixels with no contributions from input images will be set to this
+            ``fillval`` value.
+
+        out_img : 2D array of float32, None, optional
+            A 2D numpy array containing the output image produced by
+            drizzling. On the first call the array values should be set to zero.
+            Subsequent calls it will hold the intermediate results.
+
+        out_wht : 2D array of float32, None, optional
+            A 2D numpy array containing the output counts. On the first
+            call it should be set to zero. On subsequent calls it will
+            hold the intermediate results.
+
+        out_ctx : 2D or 3D array of int32, None, optional
+            A 2D or 3D numpy array holding a bitmap of which image was an input
+            for each output pixel. Should be integer zero on first call.
+            Subsequent calls hold intermediate results. This parameter is
+            ignored when ``disable_ctx`` is `True`.
+
+        exptime : float, optional
+            Exposure time of previously resampled images when provided via
+            parameters ``out_img``, ``out_wht``, ``out_ctx``.
+
+        begin_ctx_id : int, optional
+            The context ID number (0-based) of the first image that will be
+            resampled (using `add_image`). Subsequent images will be asigned
+            consecutively increasing ID numbers. This parameter is ignored
+            when ``disable_ctx`` is `True`.
+
+        max_ctx_id : int, None, optional
+            The largest integer context ID that is *expected* to be used for
+            an input image. When it is a non-negative number and ``out_ctx`` is
+            `None`, it allows to pre-allocate the necessary array for the output
+            context image. If the actual number of input images that will be
+            resampled will exceed initial allocation for the context image,
+            additional context planes will be added as needed (context array
+            will "grow" in the third dimention as new input images are added.)
+            The default value of `None` is equivalent to setting ``max_ctx_id``
+            equal to ``begin_ctx_id``. This parameter is ignored either when
+            ``out_ctx`` is provided or when ``disable_ctx`` is `True`.
+
+        disable_ctx : bool, optional
+            Indicates to not create a context image. If ``disable_ctx`` is set
+            to `True`, parameters ``out_ctx``, ``begin_ctx_id``, and
+            ``max_ctx_id`` will be ignored.
+
+        """
+        self._disable_ctx = disable_ctx
+
+        if disable_ctx:
+            self._ctx_id = None
+            self._max_ctx_id = None
+        else:
+            if begin_ctx_id < 0:
+                raise ValueError("Invalid context image ID")
+            self._ctx_id = begin_ctx_id  # the ID of the *last* image to be resampled
+            if max_ctx_id is None:
+                max_ctx_id = begin_ctx_id
+            elif max_ctx_id < begin_ctx_id:
+                raise ValueError("'max_ctx_id' cannot be smaller than 'begin_ctx_id'.")
+            self._max_ctx_id = max_ctx_id
+
+        if exptime < 0.0:
+            raise ValueError("Exposure time must be non-negative.")
+
+        if (exptime > 0.0 and out_img is None and out_ctx is None and out_wht is None):
+            raise ValueError(
+                "Exposure time must be 0.0 for the first resampling "
+                "(when no ouput resampled images have been provided)."
+            )
+
+        if (
+            exptime == 0.0 and
+                (
+                    (out_ctx is not None and np.sum(out_ctx) > 0) or
+                    (out_wht is not None and np.sum(out_wht) > 0)
+                )
+        ):
+            raise ValueError(
+                "Inconsistent exposure time and context and/or weight images: "
+                "Exposure time cannot be 0 when context and/or weight arrays "
+                "are non-zero."
+            )
+
+        self._texptime = exptime
+
+        if kernel.lower() not in SUPPORTED_DRIZZLE_KERNELS:
+            raise ValueError(f"Kernel '{kernel}' is not supported.")
+        self._kernel = kernel
+
+        if fillval is None:
+            fillval = "INDEF"
+
+        elif isinstance(fillval, str):
+            fillval = fillval.strip()
+            if fillval.upper() in ["", "INDEF"]:
+                fillval = "INDEF"
+            else:
+                float(fillval)
+                fillval = str(fillval)
+
+        else:
+            fillval = str(fillval)
+
+        if out_img is None and fillval == "INDEF":
+            fillval = "NaN"
+
+        self._fillval = fillval
+
+        # shapes will collect user specified 'out_shape' and shapes of
+        # out_* arrays (if provided) in order to check all shapes are the same.
+        shapes = set()
+
+        if out_img is not None:
+            out_img = np.asarray(out_img, dtype=np.float32)
+            shapes.add(out_img.shape)
+
+        if out_wht is not None:
+            out_wht = np.asarray(out_wht, dtype=np.float32)
+            shapes.add(out_wht.shape)
+
+        if out_ctx is not None:
+            out_ctx = np.asarray(out_ctx, dtype=np.int32)
+            if out_ctx.ndim == 2:
+                out_ctx = out_ctx[None, :, :]
+            elif out_ctx.ndim != 3:
+                raise ValueError("'out_ctx' must be either a 2D or 3D array.")
+            shapes.add(out_ctx.shape[1:])
+
+        if out_shape is not None:
+            shapes.add(tuple(out_shape))
+
+        if len(shapes) == 1:
+            self._out_shape = shapes.pop()
+            self._alloc_output_arrays(
+                out_shape=self._out_shape,
+                max_ctx_id=max_ctx_id,
+                out_img=out_img,
+                out_wht=out_wht,
+                out_ctx=out_ctx,
+            )
+        elif len(shapes) > 1:
+            raise ValueError(
+                "Inconsistent data shapes specified: 'out_shape' and/or "
+                "out_img, out_wht, out_ctx have different shapes."
+            )
+        else:
+            self._out_shape = None
+            self._out_img = None
+            self._out_wht = None
+            self._out_ctx = None
+
+    @property
+    def fillval(self):
+        """Fill value for output pixels without contributions from input images."""
+        return self._fillval
+
+    @property
+    def kernel(self):
+        """Resampling kernel."""
+        return self._kernel
+
+    @property
+    def ctx_id(self):
+        """Context image "ID" (0-based ) of the next image to be resampled."""
+        return self._ctx_id
+
+    @property
+    def out_img(self):
+        """Output resampled image."""
+        return self._out_img
+
+    @property
+    def out_wht(self):
+        """Output weight image."""
+        return self._out_wht
+
+    @property
+    def out_ctx(self):
+        """Output "context" image."""
+        return self._out_ctx
+
+    @property
+    def total_exptime(self):
+        """Total exposure time of all resampled images."""
+        return self._texptime
+
+    def _alloc_output_arrays(self, out_shape, max_ctx_id, out_img, out_wht,
+                             out_ctx):
+        # allocate arrays as needed:
+        if out_wht is None:
+            self._out_wht = np.zeros(out_shape, dtype=np.float32)
+        else:
+            self._out_wht = out_wht
+
+        if self._disable_ctx:
+            self._out_ctx = None
+        else:
+            if out_ctx is None:
+                n_ctx_planes = max_ctx_id // CTX_PLANE_BITS + 1
+                ctx_shape = (n_ctx_planes, ) + out_shape
+                self._out_ctx = np.zeros(ctx_shape, dtype=np.int32)
+            else:
+                self._out_ctx = out_ctx
+
+            if not (out_wht is None and out_ctx is None):
+                # check that input data make sense: weight of pixels with
+                # non-zero context values must be different from zero:
+                if np.any(
+                    np.bitwise_xor(
+                        self._out_wht > 0.0,
+                        np.sum(self._out_ctx, axis=0) > 0
+                    )
+                ):
+                    raise ValueError(
+                        "Inconsistent values of supplied 'out_wht' and "
+                        "'out_ctx' arrays. Pixels with non-zero context "
+                        "values must have positive weights and vice-versa."
+                    )
+
+        if out_img is None:
+            self._out_img = np.zeros(out_shape, dtype=np.float32)
+        else:
+            self._out_img = out_img
+
+    def _increment_ctx_id(self):
+        """
+        Returns a pair of the *current* plane number and bit number in that
+        plane and increments context image ID
+        (after computing the return value).
+        """
+        if self._disable_ctx:
+            return None, 0
+
+        self._plane_no = self._ctx_id // CTX_PLANE_BITS
+        depth = self._out_ctx.shape[0]
+
+        if self._plane_no >= depth:
+            # Add a new plane to the context image if planeid overflows
+            plane = np.zeros((1, ) + self._out_shape, np.int32)
+            self._out_ctx = np.append(self._out_ctx, plane, axis=0)
+
+        plane_info = (self._plane_no, self._ctx_id % CTX_PLANE_BITS)
+        # increment ID for the *next* image to be added:
+        self._ctx_id += 1
+
+        return plane_info
+
+    def add_image(self, data, exptime, pixmap, scale=1.0,
+                  weight_map=None, wht_scale=1.0, pixfrac=1.0, in_units='cps',
+                  xmin=None, xmax=None, ymin=None, ymax=None):
+        """
+        Resample and add an image to the cumulative output image. Also, update
+        output total weight image and context images.
+
+        Parameters
+        ----------
+        data : 2D numpy.ndarray
+            A 2D numpy array containing the input image to be drizzled.
+
+        exptime : float
+            The exposure time of the input image, a positive number. The
+            exposure time is used to scale the image if the units are counts.
+
+        pixmap : 3D array
+            A mapping from input image (``data``) coordinates to resampled
+            (``out_img``) coordinates. ``pixmap`` must be an array of shape
+            ``(Ny, Nx, 2)`` where ``(Ny, Nx)`` is the shape of the input image.
+            ``pixmap[..., 0]`` forms a 2D array of X-coordinates of input
+            pixels in the ouput frame and ``pixmap[..., 1]`` forms a 2D array of
+            Y-coordinates of input pixels in the ouput coordinate frame.
+
+        scale : float, optional
+            The pixel scale of the input image. Conceptually, this is the
+            linear dimension of a side of a pixel in the input image, but it
+            is not limited to this and can be set to change how the drizzling
+            algorithm operates.
+
+        weight_map : 2D array, None, optional
+            A 2D numpy array containing the pixel by pixel weighting.
+            Must have the same dimensions as ``data``.
+
+            When ``weight_map`` is `None`, the weight of input data pixels will
+            be assumed to be 1.
+
+        wht_scale : float
+            A scaling factor applied to the pixel by pixel weighting.
+
+        pixfrac : float, optional
+            The fraction of a pixel that the pixel flux is confined to. The
+            default value of 1 has the pixel flux evenly spread across the image.
+            A value of 0.5 confines it to half a pixel in the linear dimension,
+            so the flux is confined to a quarter of the pixel area when the square
+            kernel is used.
+
+        in_units : str
+            The units of the input image. The units can either be "counts"
+            or "cps" (counts per second.)
+
+        xmin : float, optional
+            This and the following three parameters set a bounding rectangle
+            on the input image. Only pixels on the input image inside this
+            rectangle will have their flux added to the output image. Xmin
+            sets the minimum value of the x dimension. The x dimension is the
+            dimension that varies quickest on the image. If the value is zero,
+            no minimum will be set in the x dimension. All four parameters are
+            zero based, counting starts at zero.
+
+        xmax : float, optional
+            Sets the maximum value of the x dimension on the bounding box
+            of the input image. If the value is zero, no maximum will
+            be set in the x dimension, the full x dimension of the output
+            image is the bounding box.
+
+        ymin : float, optional
+            Sets the minimum value in the y dimension on the bounding box. The
+            y dimension varies less rapidly than the x and represents the line
+            index on the input image. If the value is zero, no minimum  will be
+            set in the y dimension.
+
+        ymax : float, optional
+            Sets the maximum value in the y dimension. If the value is zero, no
+            maximum will be set in the y dimension,  the full x dimension
+            of the output image is the bounding box.
+
+        Returns
+        -------
+        nskip : float
+            The number of lines from the box defined by
+            ``((xmin, xmax), (ymin, ymax))`` in the input image that were
+            ignored and did not contribute to the output image.
+
+        nmiss : float
+            The number of pixels from the box defined by
+            ``((xmin, xmax), (ymin, ymax))`` in the input image that were
+            ignored and did not contribute to the output image.
+
+        """
+        # this enables initializer to not need output image shape at all and
+        # set output image shape based on output coordinates from the pixmap.
+        #
+        if self._out_shape is None:
+            pmap_xmin = int(np.floor(np.nanmin(pixmap[:, :, 0])))
+            pmap_xmax = int(np.ceil(np.nanmax(pixmap[:, :, 0])))
+            pmap_ymin = int(np.floor(np.nanmin(pixmap[:, :, 1])))
+            pmap_ymax = int(np.ceil(np.nanmax(pixmap[:, :, 1])))
+            pixmap = pixmap.copy()
+            pixmap[:, :, 0] -= pmap_xmin
+            pixmap[:, :, 1] -= pmap_ymin
+            self._out_shape = (
+                pmap_xmax - pmap_xmin + 1,
+                pmap_ymax - pmap_ymin + 1
+            )
+
+            self._alloc_output_arrays(
+                out_shape=self._out_shape,
+                max_ctx_id=max(self._max_ctx_id, self._ctx_id),
+                out_img=None,
+                out_wht=None,
+                out_ctx=None,
+            )
+
+        plane_no, id_in_plane = self._increment_ctx_id()
+
+        if exptime <= 0.0:
+            raise ValueError("'exptime' *must* be a strictly positive number.")
+
+        # Ensure that the fillval parameter gets properly interpreted
+        # for use with tdriz
+        if in_units == 'cps':
+            expscale = 1.0
+        else:
+            expscale = exptime
+
+        self._texptime += exptime
+
+        data = np.asarray(data, dtype=np.float32)
+        pixmap = np.asarray(pixmap, dtype=np.float64)
+        in_ymax, in_xmax = data.shape
+
+        if pixmap.shape[:2] != data.shape:
+            raise ValueError(
+                "'pixmap' shape is not consistent with 'data' shape."
+            )
+
+        if xmin is None or xmin < 0:
+            xmin = 0
+
+        if ymin is None or ymin < 0:
+            ymin = 0
+
+        if xmax is None or xmax > in_xmax - 1:
+            xmax = in_xmax - 1
+
+        if ymax is None or ymax > in_ymax - 1:
+            ymax = in_ymax - 1
+
+        if weight_map is not None:
+            weight_map = np.asarray(weight_map, dtype=np.float32)
+        else:  # TODO: this should not be needed after C code modifications
+            weight_map = np.ones_like(data)
+
+        pixmap = np.asarray(pixmap, dtype=np.float64)
+
+        if self._disable_ctx:
+            ctx_plane = None
+        else:
+            if self._out_ctx.ndim == 2:
+                raise AssertionError("Context image is expected to be 3D")
+            ctx_plane = self._out_ctx[plane_no]
+
+        # TODO: probably tdriz should be modified to not return version.
+        #       we should not have git, Python, C, ... versions
+
+        # TODO: While drizzle code in cdrizzlebox.c supports weight_map=None,
+        #       cdrizzleapi.c does not. It should be modified to support this
+        #       for performance reasons.
+
+        _vers, nmiss, nskip = cdrizzle.tdriz(
+            input=data,
+            weights=weight_map,
+            pixmap=pixmap,
+            output=self._out_img,
+            counts=self._out_wht,
+            context=ctx_plane,
+            uniqid=id_in_plane + 1,
+            xmin=xmin,
+            xmax=xmax,
+            ymin=ymin,
+            ymax=ymax,
+            scale=scale,  # scales image intensity. usually equal to pixel scale
+            pixfrac=pixfrac,
+            kernel=self._kernel,
+            in_units=in_units,
+            expscale=expscale,
+            wtscale=wht_scale,
+            fillstr=self._fillval,
+        )
+        self._cversion = _vers  # TODO: probably not needed
+
+        return nmiss, nskip
+
+
+def blot_image(data, pixmap, pix_ratio, exptime, output_pixel_shape,
+               interp='poly5', sinscl=1.0):
+    """
+    Resample the ``data`` input image onto an output grid defined by
+    the ``pixmap`` array. ``blot_image`` performs resampling using one of
+    the several interpolation algorithms and, unlike the "drizzle" algorithm
+    with 'square', 'turbo', and 'point' kernels, this resampling is not
+    flux-conserving.
+
+    This method works best for with well sampled images and thus it is
+    typically used to resample the output of :py:class:`Drizzle` back to the
+    coordinate grids of input images of :py:meth:`Drizzle.add_image`.
+    The output of :py:class:`Drizzle` are usually well sampled images especially
+    if it was created from a set of dithered images.
+
+    Parameters
+    ----------
+    data : 2D array
+        Input numpy array of the source image in units of 'cps'.
+
+    pixmap : 3D array
+        A mapping from input image (``data``) coordinates to resampled
+        (``out_img``) coordinates. ``pixmap`` must be an array of shape
+        ``(Ny, Nx, 2)`` where ``(Ny, Nx)`` is the shape of the input image.
+        ``pixmap[..., 0]`` forms a 2D array of X-coordinates of input
+        pixels in the ouput frame and ``pixmap[..., 1]`` forms a 2D array of
+        Y-coordinates of input pixels in the ouput coordinate frame.
+
+    output_pixel_shape : tuple of int
+        A tuple of two integer numbers indicating the dimensions of the output
+        image ``(Nx, Ny)``.
+
+    pix_ratio : float
+        Ratio of the input image pixel scale to the ouput image pixel scale.
+
+    exptime : float
+        The exposure time of the input image.
+
+    interp : str, optional
+        The type of interpolation used in the resampling. The
+        possible values are:
+
+            - "nearest" (nearest neighbor interpolation);
+            - "linear" (bilinear interpolation);
+            - "poly3" (cubic polynomial interpolation);
+            - "poly5" (quintic polynomial interpolation);
+            - "sinc" (sinc interpolation);
+            - "lan3" (3rd order Lanczos interpolation); and
+            - "lan5" (5th order Lanczos interpolation).
+
+    sincscl : float, optional
+        The scaling factor for "sinc" interpolation.
+
+    Returns
+    -------
+    out_img : 2D numpy.ndarray
+        A 2D numpy array containing the resampled image data.
+
+    """
+    out_img = np.zeros(output_pixel_shape[::-1], dtype=np.float32)
+
+    cdrizzle.tblot(data, pixmap, out_img, scale=pix_ratio, kscale=1.0,
+                   interp=interp, exptime=exptime, misval=0.0, sinscl=sinscl)
+
+    return out_img