Public Member Functions
	__init__ (self, gutter=3, background=0, mode="square")

	reset (self)

	append (self, image, label=None, ctype=None)

	makeMosaic (self, images=None, display="deferToFrame", mode=None, background=None, title="")

	setGutter (self, gutter)

	setBackground (self, background)

	setMode (self, mode)

	getBBox (self, ix, iy=None)

	drawLabels (self, labels=None, display="deferToFrame", frame=None)

	nImage (self)

Public Attributes
	gutter

	background

	xsize

	ysize

	images

	labels

	nImage

	nx

	ny

	mode

Detailed Description

A class to handle mosaics of one or more identically-sized images
(or `~lsst.afw.image.Mask` or `~lsst.afw.image.MaskedImage`)

Notes
-----
Note that this mosaic is a patchwork of the input images;  if you want to
make a mosaic of a set images of the sky, you probably want to use the coadd code

Examples
--------

.. code-block:: py

   m = Mosaic()
   m.setGutter(5)
   m.setBackground(10)
   m.setMode("square")                     # the default; other options are "x" or "y"

   mosaic = m.makeMosaic(im1, im2, im3)    # build the mosaic
   display = afwDisplay.getDisplay()
   display.mtv(mosaic)                         # display it
   m.drawLabels(["Label 1", "Label 2", "Label 3"], display) # label the panels

   # alternative way to build a mosaic
   images = [im1, im2, im3]
   labels = ["Label 1", "Label 2", "Label 3"]

   mosaic = m.makeMosaic(images)
   display.mtv(mosaic)
   m.drawLabels(labels, display)

   # Yet another way to build a mosaic (no need to build the images/labels lists)
   for i in range(len(images)):
       m.append(images[i], labels[i])
   # You may optionally include a colour, e.g. afwDisplay.YELLOW, as a third argument

   mosaic = m.makeMosaic()
   display.mtv(mosaic)
   m.drawLabels(display=display)

Or simply:

.. code-block:: py

   mosaic = m.makeMosaic(display=display)

You can return the (ix, iy)th (or nth) bounding box (in pixels) with `getBBox()`

Definition at line 70 of file utils.py.

Constructor & Destructor Documentation

◆ init()

lsst.afw.display.utils.Mosaic.__init__	(	self,
		gutter = 3,
		background = 0,
		mode = "square" )

Definition at line 120 of file utils.py.

    def __init__(self, gutter=3, background=0, mode="square"):
        self.gutter = gutter            # number of pixels between panels in a mosaic
        self.background = background    # value in gutters
        self.setMode(mode)              # mosaicing mode
        self.xsize = 0                  # column size of panels
        self.ysize = 0                  # row size of panels
 
        self.reset()
 

Member Function Documentation

◆ append()

lsst.afw.display.utils.Mosaic.append	(	self,
		image,
		label = None,
		ctype = None )

Add an image to the list of images to be mosaiced

Returns
-------
index
    the index of this image (may be passed to `getBBox()`)

Notes
-----
Set may be cleared with ``Mosaic.reset()``

Definition at line 134 of file utils.py.

    def append(self, image, label=None, ctype=None):
        """Add an image to the list of images to be mosaiced
 
        Returns
        -------
        index
            the index of this image (may be passed to `getBBox()`)
 
        Notes
        -----
        Set may be cleared with ``Mosaic.reset()``
        """
        if not self.xsize:
            self.xsize = image.getWidth()
            self.ysize = image.getHeight()
 
        self.images.append(image)
        self.labels.append((label, ctype))
 
        return len(self.images)
 

◆ drawLabels()

lsst.afw.display.utils.Mosaic.drawLabels	(	self,
		labels = None,
		display = "deferToFrame",
		frame = None )

Draw the list labels at the corners of each panel.

Notes
-----
If labels is None, use the ones specified by ``Mosaic.append()``

Definition at line 303 of file utils.py.

    def drawLabels(self, labels=None, display="deferToFrame", frame=None):
        """Draw the list labels at the corners of each panel.
 
        Notes
        -----
        If labels is None, use the ones specified by ``Mosaic.append()``
        """
 
        if not labels:
            labels = self.labels
 
        if not labels:
            return
 
        if len(labels) != self.nImage:
            raise RuntimeError(f"You provided {len(labels)} labels for {self.nImage} panels")
 
        display = _getDisplayFromDisplayOrFrame(display, frame)
        if not display:
            return
 
        with display.Buffering():
            for i in range(len(labels)):
                if labels[i]:
                    label, ctype = labels[i], None
                    try:
                        label, ctype = label
                    except Exception:
                        pass
 
                    if not label:
                        continue
 
                    display.dot(str(label), self.getBBox(i).getMinX(),
                                self.getBBox(i).getMinY(), ctype=ctype)
 

◆ getBBox()

lsst.afw.display.utils.Mosaic.getBBox	(	self,
		ix,
		iy = None )

Get the BBox for a panel

Parameters
----------
ix : `int`
    If ``iy`` is not `None`, this is the x coordinate of the panel.
    If ``iy`` is `None`, this is the number of the panel.
iy : `int`, optional
    The y coordinate of the panel.

Definition at line 285 of file utils.py.

    def getBBox(self, ix, iy=None):
        """Get the BBox for a panel
 
        Parameters
        ----------
        ix : `int`
            If ``iy`` is not `None`, this is the x coordinate of the panel.
            If ``iy`` is `None`, this is the number of the panel.
        iy : `int`, optional
            The y coordinate of the panel.
        """
 
        if iy is None:
            ix, iy = ix % self.nx, ix//self.nx
 
        return lsst.geom.Box2I(lsst.geom.PointI(ix*(self.xsize + self.gutter), iy*(self.ysize + self.gutter)),
                               lsst.geom.ExtentI(self.xsize, self.ysize))
 

◆ makeMosaic()

lsst.afw.display.utils.Mosaic.makeMosaic	(	self,
		images = None,
		display = "deferToFrame",
		mode = None,
		background = None,
		title = "" )

Return a mosaic of all the images provided.

If none are specified, use the list accumulated with `Mosaic.append()`.

If display is specified, display the mosaic

Definition at line 155 of file utils.py.

                   background=None, title=""):
        """Return a mosaic of all the images provided.
 
        If none are specified, use the list accumulated with `Mosaic.append()`.
 
        If display is specified, display the mosaic
        """
 
        if images:
            if self.images:
                raise RuntimeError(
                    f"You have already appended {len(self.images)} images to this Mosaic")
 
            try:
                len(images)             # check that it quacks like a list
            except TypeError:
                images = [images]
 
            self.images = images
        else:
            images = self.images
 
        if self.nImage == 0:
            raise RuntimeError("You must provide at least one image")
 
        self.xsize, self.ysize = 0, 0
        for im in images:
            w, h = im.getWidth(), im.getHeight()
            if w > self.xsize:
                self.xsize = w
            if h > self.ysize:
                self.ysize = h
 
        if background is None:
            background = self.background
        if mode is None:
            mode = self.mode
 
        if mode == "square":
            nx, ny = 1, self.nImage
            while nx*im.getWidth() < ny*im.getHeight():
                nx += 1
                ny = self.nImage//nx
 
                if nx*ny < self.nImage:
                    ny += 1
                if nx*ny < self.nImage:
                    nx += 1
 
            if nx > self.nImage:
                nx = self.nImage
 
            assert nx*ny >= self.nImage
        elif mode == "x":
            nx, ny = self.nImage, 1
        elif mode == "y":
            nx, ny = 1, self.nImage
        elif isinstance(mode, int):
            nx = mode
            ny = self.nImage//nx
            if nx*ny < self.nImage:
                ny += 1
        else:
            raise RuntimeError(f"Unknown mosaicing mode: {mode}")
 
        self.nx, self.ny = nx, ny
 
        mosaic = images[0].Factory(
            lsst.geom.Extent2I(nx*self.xsize + (nx - 1)*self.gutter,
                               ny*self.ysize + (ny - 1)*self.gutter)
        )
        try:
            mosaic.set(self.background)
        except AttributeError:
            raise RuntimeError(f"Attempt to mosaic images of type {type(mosaic)} which don't support set")
 
        for i in range(len(images)):
            smosaic = mosaic.Factory(
                mosaic, self.getBBox(i%nx, i//nx), afwImage.LOCAL)
            im = images[i]
 
            if smosaic.getDimensions() != im.getDimensions():  # im is smaller than smosaic
                llc = lsst.geom.PointI((smosaic.getWidth() - im.getWidth())//2,
                                       (smosaic.getHeight() - im.getHeight())//2)
                smosaic = smosaic.Factory(smosaic, lsst.geom.Box2I(
                    llc, im.getDimensions()), afwImage.LOCAL)
 
            smosaic[:] = im
 
        display = _getDisplayFromDisplayOrFrame(display)
        if display:
            display.mtv(mosaic, title=title)
 
            if images == self.images:
                self.drawLabels(display=display)
 
        return mosaic
 

◆ nImage()

lsst.afw.display.utils.Mosaic.nImage ( self )

Number of images

Definition at line 340 of file utils.py.

    def nImage(self):
        """Number of images
        """
        return len(self.images)
 
 

◆ reset()

lsst.afw.display.utils.Mosaic.reset ( self )

Reset the list of images to be mosaiced

Definition at line 129 of file utils.py.

    def reset(self):
        """Reset the list of images to be mosaiced"""
        self.images = []                # images to mosaic together
        self.labels = []                # labels for images
 

◆ setBackground()

lsst.afw.display.utils.Mosaic.setBackground	(		self,
			background )

Set the value in the gutters

Definition at line 259 of file utils.py.

    def setBackground(self, background):
        """Set the value in the gutters
        """
        self.background = background
 

◆ setGutter()

lsst.afw.display.utils.Mosaic.setGutter	(		self,
			gutter )

Set the number of pixels between panels in a mosaic

Definition at line 254 of file utils.py.

    def setGutter(self, gutter):
        """Set the number of pixels between panels in a mosaic
        """
        self.gutter = gutter
 

◆ setMode()

lsst.afw.display.utils.Mosaic.setMode	(		self,
			mode )

Set mosaicing mode.

Parameters
----------
mode : {"square", "x", "y"}
    Valid options:

    square
        Make mosaic as square as possible
    x
        Make mosaic one image high
    y
        Make mosaic one image wide

Definition at line 264 of file utils.py.

    def setMode(self, mode):
        """Set mosaicing mode.
 
        Parameters
        ----------
        mode : {"square", "x", "y"}
            Valid options:
 
            square
                Make mosaic as square as possible
            x
                Make mosaic one image high
            y
                Make mosaic one image wide
        """
 
        if mode not in ("square", "x", "y"):
            raise RuntimeError(f"Unknown mosaicing mode: {mode}")
 
        self.mode = mode
 

Member Data Documentation

◆ background

lsst.afw.display.utils.Mosaic.background

Definition at line 122 of file utils.py.

◆ gutter

lsst.afw.display.utils.Mosaic.gutter

Definition at line 121 of file utils.py.

◆ images

lsst.afw.display.utils.Mosaic.images

Definition at line 131 of file utils.py.

◆ labels

lsst.afw.display.utils.Mosaic.labels

Definition at line 132 of file utils.py.

◆ mode

lsst.afw.display.utils.Mosaic.mode

Definition at line 283 of file utils.py.

◆ nImage

lsst.afw.display.utils.Mosaic.nImage

Definition at line 178 of file utils.py.

◆ nx

lsst.afw.display.utils.Mosaic.nx

Definition at line 221 of file utils.py.

◆ ny

lsst.afw.display.utils.Mosaic.ny