drizzle 1.15.2__cp311-cp311-win32.whl → 2.0.0__cp311-cp311-win32.whl

drizzle/tests/test_utils.py

@@ -0,0 +1,193 @@
+import os
+
+import numpy as np
+import pytest
+from numpy.testing import assert_almost_equal, assert_equal
+
+from astropy import wcs
+from astropy.io import fits
+from drizzle.utils import (
+    _estimate_pixel_scale,
+    calc_pixmap,
+    decode_context,
+    estimate_pixel_scale_ratio,
+)
+
+TEST_DIR = os.path.abspath(os.path.dirname(__file__))
+DATA_DIR = os.path.join(TEST_DIR, 'data')
+
+
+def test_map_rectangular():
+    """
+    Make sure the initial index array has correct values
+    """
+    naxis1 = 1000
+    naxis2 = 10
+
+    pixmap = np.indices((naxis1, naxis2), dtype='float32')
+    pixmap = pixmap.transpose()
+
+    assert_equal(pixmap[5, 500], (500, 5))
+
+
+def test_map_to_self():
+    """
+    Map a pixel array to itself. Should return the same array.
+    """
+    input_file = os.path.join(DATA_DIR, 'input1.fits')
+    input_hdu = fits.open(input_file)
+
+    input_wcs = wcs.WCS(input_hdu[1].header)
+    naxis1, naxis2 = input_wcs.pixel_shape
+    input_hdu.close()
+
+    ok_pixmap = np.indices((naxis1, naxis2), dtype='float32')
+    ok_pixmap = ok_pixmap.transpose()
+
+    pixmap = calc_pixmap(input_wcs, input_wcs)
+
+    # Got x-y transpose right
+    assert_equal(pixmap.shape, ok_pixmap.shape)
+
+    # Mapping an array to itself
+    assert_almost_equal(pixmap, ok_pixmap, decimal=5)
+
+    # user-provided shape
+    pixmap = calc_pixmap(input_wcs, input_wcs, (12, 34))
+    assert_equal(pixmap.shape, (12, 34, 2))
+
+    # Check that an exception is raised for WCS without pixel_shape or
+    # bounding_box:
+    input_wcs.pixel_shape = None
+    with pytest.raises(ValueError):
+        calc_pixmap(input_wcs, input_wcs)
+
+    # user-provided shape when array_shape is not set:
+    pixmap = calc_pixmap(input_wcs, input_wcs, (12, 34))
+    assert_equal(pixmap.shape, (12, 34, 2))
+
+    # from bounding box:
+    input_wcs.bounding_box = ((5.3, 33.5), (2.8, 11.5))
+    pixmap = calc_pixmap(input_wcs, input_wcs)
+    assert_equal(pixmap.shape, (12, 34, 2))
+
+    # from bounding box and pixel_shape (the later takes precedence):
+    input_wcs.pixel_shape = (naxis1, naxis2)
+    pixmap = calc_pixmap(input_wcs, input_wcs)
+    assert_equal(pixmap.shape, ok_pixmap.shape)
+
+
+def test_translated_map():
+    """
+    Map a pixel array to  at translated array.
+    """
+    first_file = os.path.join(DATA_DIR, 'input1.fits')
+    first_hdu = fits.open(first_file)
+    first_header = first_hdu[1].header
+
+    first_wcs = wcs.WCS(first_header)
+    naxis1, naxis2 = first_wcs.pixel_shape
+    first_hdu.close()
+
+    second_file = os.path.join(DATA_DIR, 'input3.fits')
+    second_hdu = fits.open(second_file)
+    second_header = second_hdu[1].header
+
+    second_wcs = wcs.WCS(second_header)
+    second_hdu.close()
+
+    ok_pixmap = np.indices((naxis1, naxis2), dtype='float32') - 2.0
+    ok_pixmap = ok_pixmap.transpose()
+
+    pixmap = calc_pixmap(first_wcs, second_wcs)
+
+    # Got x-y transpose right
+    assert_equal(pixmap.shape, ok_pixmap.shape)
+    # Mapping an array to a translated array
+    assert_almost_equal(pixmap, ok_pixmap, decimal=5)
+
+
+def test_estimate_pixel_scale_ratio():
+    input_file = os.path.join(DATA_DIR, 'j8bt06nyq_flt.fits')
+
+    with fits.open(input_file) as h:
+        w = wcs.WCS(h[1].header)
+
+    pscale = estimate_pixel_scale_ratio(w, w, w.wcs.crpix, (0, 0))
+
+    assert abs(pscale - 0.9999999916964737) < 1.0e-9
+
+
+def test_estimate_pixel_scale_no_refpix():
+    # create a WCS without higher order (polynomial) distortions:
+    fits_file = os.path.join(DATA_DIR, 'input1.fits')
+    with fits.open(fits_file) as h:
+        w = wcs.WCS(h[1].header, h)
+        w.sip = None
+        w.det2im1 = None
+        w.det2im2 = None
+        w.cpdis1 = None
+        w.cpdis2 = None
+        pixel_shape = w.pixel_shape[:]
+
+    ref_pscale = _estimate_pixel_scale(w, w.wcs.crpix)
+
+    if hasattr(w, 'bounding_box'):
+        del w.bounding_box
+    pscale1 = _estimate_pixel_scale(w, None)
+    assert np.allclose(ref_pscale, pscale1, atol=0.0, rtol=1.0e-8)
+
+    w.bounding_box = None
+    w.pixel_shape = None
+    pscale2 = _estimate_pixel_scale(w, None)
+    assert np.allclose(pscale1, pscale2, atol=0.0, rtol=1.0e-8)
+
+    w.pixel_shape = pixel_shape
+    pscale3 = _estimate_pixel_scale(w, None)
+    assert np.allclose(pscale1, pscale3, atol=0.0, rtol=1.0e-14)
+
+    w.bounding_box = ((-0.5, pixel_shape[0] - 0.5), (-0.5, pixel_shape[1] - 0.5))
+    pscale4 = _estimate_pixel_scale(w, None)
+    assert np.allclose(pscale3, pscale4, atol=0.0, rtol=1.0e-8)
+
+
+def test_decode_context():
+    ctx = np.array(
+        [[[0, 0, 0, 0, 0, 0],
+          [0, 0, 0, 36196864, 0, 0],
+          [0, 0, 0, 0, 0, 0],
+          [0, 0, 0, 0, 0, 0],
+          [0, 0, 537920000, 0, 0, 0]],
+         [[0, 0, 0, 0, 0, 0,],
+          [0, 0, 0, 67125536, 0, 0],
+          [0, 0, 0, 0, 0, 0],
+          [0, 0, 0, 0, 0, 0],
+          [0, 0, 163856, 0, 0, 0]],
+         [[0, 0, 0, 0, 0, 0],
+          [0, 0, 0, 8203, 0, 0],
+          [0, 0, 0, 0, 0, 0],
+          [0, 0, 0, 0, 0, 0],
+          [0, 0, 32865, 0, 0, 0]]],
+        dtype=np.int32
+    )
+
+    idx1, idx2 = decode_context(ctx, [3, 2], [1, 4])
+
+    assert sorted(idx1) == [9, 12, 14, 19, 21, 25, 37, 40, 46, 58, 64, 65, 67, 77]
+    assert sorted(idx2) == [9, 20, 29, 36, 47, 49, 64, 69, 70, 79]
+
+    # context array must be 3D:
+    with pytest.raises(ValueError):
+        decode_context(ctx[0], [3, 2], [1, 4])
+
+    # pixel coordinates must be integer:
+    with pytest.raises(ValueError):
+        decode_context(ctx, [3.0, 2], [1, 4])
+
+    # coordinate lists must be equal in length:
+    with pytest.raises(ValueError):
+        decode_context(ctx, [3, 2], [1, 4, 5])
+
+    # coordinate lists must be 1D:
+    with pytest.raises(ValueError):
+        decode_context(ctx, [[3, 2]], [[1, 4]])

drizzle/util.py

@@ -1,138 +1,15 @@
-import numpy as np
+"""
+Module ``util`` has been deprecated.
+"""
+import warnings
 
-
-def find_keyword_extn(fimg, keyword, value=None):
-    """
-    This function will return the index of the extension in a multi-extension
-    FITS file which contains the desired keyword with the given value.
-
-    Parameters
-    ----------
-
-    fimg : hdulist
-        A list of header data units
-
-    keyword : str
-        The keyword to search for
-
-    value : str or number, optional
-        If set, the value the keyword must have to match
-
-    Returns
-    -------
-
-    The index of the extension
-    """
-
-    i = 0
-    extnum = -1
-    # Search through all the extensions in the FITS object
-    for chip in fimg:
-        hdr = chip.header
-        # Check to make sure the extension has the given keyword
-        if keyword in hdr:
-            if value is not None:
-                # If it does, then does the value match the desired value
-                # MUST use 'str.strip' to match against any input string!
-                if hdr[keyword].strip() == value:
-                    extnum = i
-                    break
-            else:
-                extnum = i
-                break
-        i += 1
-    # Return the index of the extension which contained the
-    # desired EXTNAME value.
-    return extnum
-
-
-def get_extn(fimg, extn=''):
-    """
-    Returns the FITS extension corresponding to extension specified in
-    filename. Defaults to returning the first extension with data or the
-    primary extension, if none have data.
-
-    Parameters
-    ----------
-
-    fimg : hdulist
-        A list of header data units
-
-    extn : str
-        The extension name and version to match
-
-    Returns
-    -------
-
-    The matching header data unit
-    """
-
-    if extn:
-        try:
-            _extn = parse_extn(extn)
-            if _extn[0]:
-                _e = fimg.index_of(_extn)
-            else:
-                _e = _extn[1]
-
-        except KeyError:
-            _e = None
-
-        if _e is None:
-            _extn = None
-        else:
-            _extn = fimg[_e]
-
-    else:
-        # If no extension is provided, search for first extension
-        # in FITS file with data associated with it.
-
-        # Set up default to point to PRIMARY extension.
-        _extn = fimg[0]
-        # then look for first extension with data.
-        for _e in fimg:
-            if _e.data is not None:
-                _extn = _e
-                break
-
-    return _extn
-
-
-def get_keyword(fimg, keyword, default=None):
-    """
-    Return a keyword value from the header of an image,
-    or the default if the keyword is not found.
-
-    Parameters
-    ----------
-
-    fimg : hdulist
-        A list of header data units
-
-    keyword : hdulist
-        The keyword value to search for
-
-    default : str or number, optional
-        The default value if not found
-
-    Returns
-    -------
-
-    The value if found or default if not
-    """
-
-    value = None
-    if keyword:
-        _nextn = find_keyword_extn(fimg, keyword)
-        try:
-            value = fimg[_nextn].header[keyword]
-        except KeyError:
-            value = None
-
-    if value is None and default is not None:
-        value = default
-
-    return value
+warnings.warn(
+    "Module 'drizzle.util' has been deprecated since version 2.0.0 "
+    "and it will be removed in a future release. "
+    "Please replace calls to 'util.is_blank()' with alternative "
+    "implementation.",
+    DeprecationWarning
+)
 
 
 def is_blank(value):
@@ -141,116 +18,17 @@ def is_blank(value):
 
     Parameters
     ----------
-
     value : str
         The value to check
 
     Returns
     -------
-
     True or False
     """
+    warnings.warn(
+        "'is_blank()' has been deprecated since version 2.0.0 "
+        "and it will be removed in a future release. "
+        "Please replace calls to 'is_blank()' with alternative implementation.",
+        DeprecationWarning
+    )
     return value.strip() == ""
-
-
-def parse_extn(extn=''):
-    """
-    Parse a string representing a qualified fits extension name as in the
-    output of parse_filename and return a tuple (str(extname), int(extver)),
-    which can be passed to pyfits functions using the 'ext' kw.
-    Default return is the first extension in a fits file.
-
-    Examples
-    --------
-        >>> parse_extn('sci,2')
-        ('sci', 2)
-        >>> parse_extn('2')
-        ('', 2)
-        >>> parse_extn('sci')
-        ('sci', 1)
-
-    Parameters
-    ----------
-    extn : str
-        The extension name
-
-    Returns
-    -------
-    A tuple of the extension name and value
-    """
-    if not extn:
-        return ('', 0)
-
-    try:
-        lext = extn.split(',')
-    except Exception:
-        return ('', 1)
-
-    if len(lext) == 1 and lext[0].isdigit():
-        return ("", int(lext[0]))
-    elif len(lext) == 2:
-        return (lext[0], int(lext[1]))
-    else:
-        return (lext[0], 1)
-
-
-def parse_filename(filename):
-    """
-    Parse out filename from any specified extensions.
-    Returns rootname and string version of extension name.
-
-    Parameters
-    ----------
-
-    filename : str
-        The filename to be parsed
-
-    Returns
-    -------
-
-    A tuple with the filename root and extension
-    """
-    # Parse out any extension specified in filename
-    _indx = filename.find('[')
-    if _indx > 0:
-        # Read extension name provided
-        _fname = filename[:_indx]
-        _extn = filename[_indx + 1:-1]
-    else:
-        _fname = filename
-        _extn = ''
-
-    return _fname, _extn
-
-
-def set_pscale(the_wcs):
-    """
-    Calculates the plate scale from cdelt and the pc  matrix and adds
-    it to the WCS. Plate scale is not part of the WCS standard, but is
-    required by the drizzle code
-
-    Parameters
-    ----------
-
-    the_wcs : wcs
-        A WCS object
-    """
-    try:
-        cdelt = the_wcs.wcs.get_cdelt()
-        pc = the_wcs.wcs.get_pc()
-
-    except Exception:
-        try:
-            # for non-celestial axes, get_cdelt doesnt work
-            cdelt = the_wcs.wcs.cd * the_wcs.wcs.cdelt
-        except AttributeError:
-            cdelt = the_wcs.wcs.cdelt
-
-        try:
-            pc = the_wcs.wcs.pc
-        except AttributeError:
-            pc = 1
-
-    pccd = np.array(cdelt * pc)
-    scales = np.sqrt((pccd ** 2).sum(axis=0, dtype=float))
-    the_wcs.pscale = scales[0]

drizzle/utils.py

@@ -0,0 +1,239 @@
+import math
+
+import numpy as np
+
+__all__ = ["calc_pixmap", "decode_context", "estimate_pixel_scale_ratio"]
+
+_DEG2RAD = math.pi / 180.0
+
+
+def calc_pixmap(wcs_from, wcs_to, shape=None):
+    """
+    Calculate a discretized on a grid mapping between the pixels of two images
+    using provided WCS of the original ("from") image and the destination ("to")
+    image.
+
+    .. note::
+       This function assumes that output frames of ``wcs_from`` and ``wcs_to``
+       WCS have the same units.
+
+    Parameters
+    ----------
+    wcs_from : wcs
+        A WCS object representing the coordinate system you are
+        converting from. This object's ``array_shape`` (or ``pixel_shape``)
+        property will be used to define the shape of the pixel map array.
+        If ``shape`` parameter is provided, it will take precedence
+        over this object's ``array_shape`` value.
+
+    wcs_to : wcs
+        A WCS object representing the coordinate system you are
+        converting to.
+
+    shape : tuple, None, optional
+        A tuple of integers indicating the shape of the output array in the
+        ``numpy.ndarray`` order. When provided, it takes precedence over the
+        ``wcs_from.array_shape`` property.
+
+    Returns
+    -------
+    pixmap : numpy.ndarray
+        A three dimensional array representing the transformation between
+        the two. The last dimension is of length two and contains the x and
+        y coordinates of a pixel center, repectively. The other two coordinates
+        correspond to the two coordinates of the image the first WCS is from.
+
+    Raises
+    ------
+    ValueError
+        A `ValueError` is raised when output pixel map shape cannot be
+        determined from provided inputs.
+
+    Notes
+    -----
+    When ``shape`` is not provided and ``wcs_from.array_shape`` is not set
+    (i.e., it is `None`), `calc_pixmap` will attempt to determine pixel map
+    shape from the ``bounding_box`` property of the input ``wcs_from`` object.
+    If ``bounding_box`` is not available, a `ValueError` will be raised.
+
+    """
+    if shape is None:
+        shape = wcs_from.array_shape
+        if shape is None:
+            if (bbox := getattr(wcs_from, "bounding_box", None)) is not None:
+                if (nd := np.ndim(bbox)) == 1:
+                    bbox = (bbox, )
+                if nd > 1:
+                    shape = tuple(
+                        int(math.ceil(lim[1] + 0.5)) for lim in bbox[::-1]
+                    )
+
+    if shape is None:
+        raise ValueError(
+            'The "from" WCS must have pixel_shape property set.'
+        )
+
+    y, x = np.indices(shape, dtype=np.float64)
+    x, y = wcs_to.world_to_pixel_values(*wcs_from.pixel_to_world_values(x, y))
+    pixmap = np.dstack([x, y])
+    return pixmap
+
+
+def estimate_pixel_scale_ratio(wcs_from, wcs_to, refpix_from=None, refpix_to=None):
+    """
+    Compute the ratio of the pixel scale of the "to" WCS at the ``refpix_to``
+    position to the pixel scale of the "from" WCS at the ``refpix_from``
+    position. Pixel scale ratio,
+    when requested, is computed near the centers of the bounding box
+    (a property of the WCS object) or near ``refpix_*`` coordinates
+    if supplied.
+
+    Pixel scale is estimated as the square root of pixel's area, i.e.,
+    pixels are assumed to have a square shape at the reference
+    pixel position. If input reference pixel position for a WCS is `None`,
+    it will be taken as the center of the bounding box
+    if ``wcs_*`` has a bounding box defined, or as the center of the box
+    defined by the ``pixel_shape`` attribute of the input WCS if
+    ``pixel_shape`` is defined (not `None`), or at pixel coordinates
+    ``(0, 0)``.
+
+    Parameters
+    ----------
+    wcs_from : wcs
+        A WCS object representing the coordinate system you are
+        converting from. This object *must* have ``pixel_shape`` property
+        defined.
+
+    wcs_to : wcs
+        A WCS object representing the coordinate system you are
+        converting to.
+
+    refpix_from : numpy.ndarray, tuple, list
+        Image coordinates of the reference pixel near which pixel scale should
+        be computed in the "from" image. In FITS WCS this could be, for example,
+        the value of CRPIX of the ``wcs_from`` WCS.
+
+    refpix_to : numpy.ndarray, tuple, list
+        Image coordinates of the reference pixel near which pixel scale should
+        be computed in the "to" image. In FITS WCS this could be, for example,
+        the value of CRPIX of the ``wcs_to`` WCS.
+
+    Returns
+    -------
+    pixel_scale_ratio : float
+        Estimate the ratio of "to" to "from" WCS pixel scales. This value is
+        returned only when ``estimate_pixel_scale_ratio`` is `True`.
+
+    """
+    pscale_ratio = (_estimate_pixel_scale(wcs_to, refpix_to) /
+                    _estimate_pixel_scale(wcs_from, refpix_from))
+    return pscale_ratio
+
+
+def _estimate_pixel_scale(wcs, refpix):
+    # estimate pixel scale (in rad) using approximate algorithm
+    # from https://trs.jpl.nasa.gov/handle/2014/40409
+    if refpix is None:
+        if hasattr(wcs, 'bounding_box') and wcs.bounding_box is not None:
+            refpix = np.mean(wcs.bounding_box, axis=-1)
+        else:
+            if wcs.pixel_shape:
+                refpix = np.array([(i - 1) // 2 for i in wcs.pixel_shape])
+            else:
+                refpix = np.zeros(wcs.pixel_n_dim)
+
+    else:
+        refpix = np.asarray(refpix)
+
+    l1, phi1 = wcs.pixel_to_world_values(*(refpix - 0.5))
+    l2, phi2 = wcs.pixel_to_world_values(*(refpix + [-0.5, 0.5]))
+    l3, phi3 = wcs.pixel_to_world_values(*(refpix + 0.5))
+    l4, phi4 = wcs.pixel_to_world_values(*(refpix + [0.5, -0.5]))
+    area = _DEG2RAD * abs(
+        0.5 * (
+            (l4 - l2) * (math.sin(_DEG2RAD * phi1) - math.sin(_DEG2RAD * phi3)) +
+            (l1 - l3) * (math.sin(_DEG2RAD * phi2) - math.sin(_DEG2RAD * phi4))
+        )
+    )
+    return math.sqrt(area)
+
+
+def decode_context(context, x, y):
+    """Get 0-based indices of input images that contributed to (resampled)
+    output pixel with coordinates ``x`` and ``y``.
+
+    Parameters
+    ----------
+    context: numpy.ndarray
+        A 3D `~numpy.ndarray` of integral data type.
+
+    x: int, list of integers, numpy.ndarray of integers
+        X-coordinate of pixels to decode (3rd index into the ``context`` array)
+
+    y: int, list of integers, numpy.ndarray of integers
+        Y-coordinate of pixels to decode (2nd index into the ``context`` array)
+
+    Returns
+    -------
+    A list of `numpy.ndarray` objects each containing indices of input images
+    that have contributed to an output pixel with coordinates ``x`` and ``y``.
+    The length of returned list is equal to the number of input coordinate
+    arrays ``x`` and ``y``.
+
+    Examples
+    --------
+    An example context array for an output image of array shape ``(5, 6)``
+    obtained by resampling 80 input images.
+
+    >>> import numpy as np
+    >>> from drizzle.utils import decode_context
+    >>> ctx = np.array(
+    ...     [[[0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 0, 36196864, 0, 0],
+    ...       [0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 537920000, 0, 0, 0]],
+    ...      [[0, 0, 0, 0, 0, 0,],
+    ...       [0, 0, 0, 67125536, 0, 0],
+    ...       [0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 163856, 0, 0, 0]],
+    ...      [[0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 0, 8203, 0, 0],
+    ...       [0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 0, 0, 0, 0],
+    ...       [0, 0, 32865, 0, 0, 0]]],
+    ...     dtype=np.int32
+    ... )
+    >>> decode_context(ctx, [3, 2], [1, 4])
+    [array([ 9, 12, 14, 19, 21, 25, 37, 40, 46, 58, 64, 65, 67, 77]),
+     array([ 9, 20, 29, 36, 47, 49, 64, 69, 70, 79])]
+
+    """
+    if context.ndim != 3:
+        raise ValueError("'context' must be a 3D array.")
+
+    x = np.atleast_1d(x)
+    y = np.atleast_1d(y)
+
+    if x.size != y.size:
+        raise ValueError("Coordinate arrays must have equal length.")
+
+    if x.ndim != 1:
+        raise ValueError("Coordinates must be scalars or 1D arrays.")
+
+    if not (np.issubdtype(x.dtype, np.integer) and
+            np.issubdtype(y.dtype, np.integer)):
+        raise ValueError('Pixel coordinates must be integer values')
+
+    nbits = 8 * context.dtype.itemsize
+    one = np.array(1, context.dtype)
+    flags = np.array([one << i for i in range(nbits)])
+
+    idx = []
+    for xi, yi in zip(x, y):
+        idx.append(
+            np.flatnonzero(np.bitwise_and.outer(context[:, yi, xi], flags))
+        )
+
+    return idx