lsst.meas.algorithms.stamps Namespace Reference

Classes
class	AbstractStamp
class	Stamp
class	StampsBase
class	Stamps

Functions
def	writeFits (filename, stamp_ims, metadata, type_name, write_mask, write_variance)
def	readFitsWithOptions (filename, stamp_factory, options)

Function Documentation

readFitsWithOptions()

def lsst.meas.algorithms.stamps.readFitsWithOptions	(		filename,
			stamp_factory,
			options
	)

Read stamps from FITS file, allowing for only a
subregion of the stamps to be read.

Parameters
----------
filename : `str`
    A string indicating the file to read
stamp_factory : classmethod
    A factory function defined on a dataclass for constructing
    stamp objects a la `lsst.meas.alrogithm.Stamp`
options : `PropertyList` or `dict`
    A collection of parameters. If it contains a bounding box
    (``bbox`` key), or if certain other keys (``llcX``, ``llcY``,
    ``width``, ``height``) are available for one to be  constructed,
    the bounding box is passed to the ``FitsReader`` in order to
    return a sub-image.

Returns
-------
stamps : `list` of dataclass objects like `Stamp`, PropertyList
    A tuple of a list of `Stamp`-like objects
metadata : `PropertyList`
    The metadata

Definition at line 88 of file stamps.py.

def readFitsWithOptions(filename, stamp_factory, options):
    """Read stamps from FITS file, allowing for only a
    subregion of the stamps to be read.
 
    Parameters
    ----------
    filename : `str`
        A string indicating the file to read
    stamp_factory : classmethod
        A factory function defined on a dataclass for constructing
        stamp objects a la `lsst.meas.alrogithm.Stamp`
    options : `PropertyList` or `dict`
        A collection of parameters. If it contains a bounding box
        (``bbox`` key), or if certain other keys (``llcX``, ``llcY``,
        ``width``, ``height``) are available for one to be  constructed,
        the bounding box is passed to the ``FitsReader`` in order to
        return a sub-image.
 
    Returns
    -------
    stamps : `list` of dataclass objects like `Stamp`, PropertyList
        A tuple of a list of `Stamp`-like objects
    metadata : `PropertyList`
        The metadata
    """
    # extract necessary info from metadata
    metadata = afwFits.readMetadata(filename, hdu=0)
    f = afwFits.Fits(filename, 'r')
    nExtensions = f.countHdus()
    nStamps = metadata["N_STAMPS"]
    # check if a bbox was provided
    kwargs = {}
    if options:
        # gen3 API
        if "bbox" in options.keys():
            kwargs["bbox"] = options["bbox"]
        # gen2 API
        elif "llcX" in options.keys():
            llcX = options["llcX"]
            llcY = options["llcY"]
            width = options["width"]
            height = options["height"]
            bbox = Box2I(Point2I(llcX, llcY), Extent2I(width, height))
            kwargs["bbox"] = bbox
    stamp_parts = {}
    # We need to be careful because nExtensions includes the primary
    # header data unit
    for idx in range(nExtensions-1):
        md = afwFits.readMetadata(filename, hdu=idx+1)
        if md['EXTNAME'] in ('IMAGE', 'VARIANCE'):
            reader = afwImage.ImageFitsReader(filename, hdu=idx+1)
        elif md['EXTNAME'] == 'MASK':
            reader = afwImage.MaskFitsReader(filename, hdu=idx+1)
        else:
            raise ValueError(f"Unknown extension type: {md['EXTNAME']}")
        stamp_parts.setdefault(md['EXTVER'], {})[md['EXTNAME'].lower()] = reader.read(**kwargs)
    if len(stamp_parts) != nStamps:
        raise ValueError(f'Number of stamps read ({len(stamp_parts)}) does not agree with the '
                         f'number of stamps recorded in the metadata ({nStamps}).')
    # construct stamps themselves
    stamps = []
    for k in range(nStamps):
        # Need to increment by one since EXTVER starts at 1
        maskedImage = afwImage.MaskedImageF(**stamp_parts[k+1])
        stamps.append(stamp_factory(maskedImage, metadata, k))
 
    return stamps, metadata
 
 
@dataclass

writeFits()

def lsst.meas.algorithms.stamps.writeFits	(		filename,
			stamp_ims,
			metadata,
			type_name,
			write_mask,
			write_variance
	)

Write a single FITS file containing all stamps.

Parameters
----------
filename : `str`
    A string indicating the output filename
stamps_ims : iterable of `lsst.afw.image.MaskedImageF`
    An iterable of masked images
metadata : `PropertyList`
    A collection of key, value metadata pairs to be
    written to the primary header
type_name : `str`
    Python type name of the StampsBase subclass to use
write_mask : `bool`
    Write the mask data to the output file?
write_variance : `bool`
    Write the variance data to the output file?

Definition at line 40 of file stamps.py.

def writeFits(filename, stamp_ims, metadata, type_name, write_mask, write_variance):
    """Write a single FITS file containing all stamps.
 
    Parameters
    ----------
    filename : `str`
        A string indicating the output filename
    stamps_ims : iterable of `lsst.afw.image.MaskedImageF`
        An iterable of masked images
    metadata : `PropertyList`
        A collection of key, value metadata pairs to be
        written to the primary header
    type_name : `str`
        Python type name of the StampsBase subclass to use
    write_mask : `bool`
        Write the mask data to the output file?
    write_variance : `bool`
        Write the variance data to the output file?
    """
    metadata['HAS_MASK'] = write_mask
    metadata['HAS_VARIANCE'] = write_variance
    metadata['N_STAMPS'] = len(stamp_ims)
    metadata['STAMPCLS'] = type_name
    # Record version number in case of future code changes
    metadata['VERSION'] = 1
    # create primary HDU with global metadata
    fitsPrimary = afwFits.Fits(filename, "w")
    fitsPrimary.createEmpty()
    fitsPrimary.writeMetadata(metadata)
    fitsPrimary.closeFile()
 
    # add all pixel data optionally writing mask and variance information
    for i, stamp in enumerate(stamp_ims):
        metadata = PropertyList()
        # EXTVER should be 1-based, the index from enumerate is 0-based
        metadata.update({'EXTVER': i+1, 'EXTNAME': 'IMAGE'})
        stamp.getImage().writeFits(filename, metadata=metadata, mode='a')
        if write_mask:
            metadata = PropertyList()
            metadata.update({'EXTVER': i+1, 'EXTNAME': 'MASK'})
            stamp.getMask().writeFits(filename, metadata=metadata, mode='a')
        if write_variance:
            metadata = PropertyList()
            metadata.update({'EXTVER': i+1, 'EXTNAME': 'VARIANCE'})
            stamp.getVariance().writeFits(filename, metadata=metadata, mode='a')
    return None