How to display images

How to %display images

• How to build a mosaic image
• All supported ds9 commands
• How to use ds9 through a firewall

Using DS9 in the LSST framework

At present (July 2009) we are using ds9 (http://hea-www.harvard.edu/RD/ds9) to display Images, Masks, and MaskedImages. This has a number of drawbacks (slow; slightly unstable API; awkward to use with firewalls) as well as a number of advantages: Supported by the CfA; ubiquitous in astronomy; support for WCS; support for multiple frames).

The basic functionality is in lsst.afw.display.ds9, and the workhorse routine is mtv. The simplest use is simply to setup afw and ds9, start ds9 and python, and type:

import lsst.afw.display.ds9 as ds9
import lsst.afw.image as afwImage

im = afwImage.ImageF("myFile.fits")
ds9.mtv(im)

You can display images in multiple frames, either by explicitly specifying the frame, or by setting the default with ds9.setDefaultFrame(). If there's a strong desire for multiple instances of ds9 this could be supported (by choosing different tcp ports); file a ticket if this is really important for you.

The mtv command handles all of the LSST image types:

Image

The pixels are displayed on ds9. Images don't have a Wcs, so no astronomical WCS information is available, but we do support WCSA and WCSB; the former is 0-indexed pixel coordinates allowing for the Image's XY0; the latter is 0-indexed pixel coordinates relative to the bottom left pixel being (0, 0).

mtv accepts an optional wcs argument, which allows you to provide an astronomical Wcs (but if you have an DecoratedImage or Exposure this is done for you)

DecoratedImage

Displayed like Image, but with the default WCS set from the DecoratedImage's Wcs

Mask

Overlay the current display with the Mask. A bug in ds9 prevents you from displaying a pure Mask, but you can use the isMask argument to force the Mask to be treated as a 16-bit image.

The Mask display isn't as fast as you might like, as ds9's current API requires us to send each mask plane as a separate 16-bit image (I have asked Bill Joy at CfA to change this). Each bitplane may be given a separate colour; you can inspect the current mapping with getMaskPlaneColor or set it with setMaskPlaneColor. If a mask plane has no defined colour, one will be chosen for you.

Recent versions of ds9 allow you to vary the mask's transparency, either via the GUI or with e.g. setMaskTransparency(50).

MaskedImage

The image-plane pixels are displayed, overlaid with the mask. If you want to look at the variance too, you'll need to say something like:

mi = afwImage.MaskedImageF("mi.fits")
ds9.mtv(mi, frame=0)
ds9.mtv(mi.getVariance(), frame=1)
ds9.mtv(mi.getMask(), frame=1)

Exposure

Displayed like MaskedImage, but with the default WCS set from the MaskedImage's Wcs

How to build a mosaic image

There are facilities to build mosaics of images in lsst.afw.display.utils

The basic class is Mosaic:

m = Mosaic()
m.setGutter(5)
m.setBackground(10)
m.setMode("square")                   # the default

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

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

mosaic = m.makeMosaic(images)
ds9.mtv(mosaic)
m.drawLabels(labels)

# 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])

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

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

• The Mosaic class API

  __init__() [self, gutter=3, background=0, mode='square']

  append() [self, image, label=None]

  Add an image to the list of images to be mosaiced Set may be cleared with Mosaic.reset()

  drawLabels() [self, labels=None, frame=0]

  Draw the list labels at the corners of each panel. If labels is None, use the ones specified by Mosaic.append()

  drawLabels() [self, labels, frame=0]

  Draw the list labels at the corners of each panel

  getBBox() [self, ix, iy=None]

  Get the bounding box for the nth or (ix, iy)the panel

  makeMosaic() [self, images, frame=None, mode=None]

  Return a mosaic of all the images provided; if none are specified, use the list accumulated with Mosaic.append()

  If frame is specified, display it

  setBackground() [self, background]

  Set the value in the gutters

  setGutter() [self, gutter]

  Set the number of pixels between panels in a mosaic

  setMode() [self, mode]

  Set mosaicing mode. Valid options:

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

All supported ds9 commands

• Image commands

  It turns out that writing symbols to ds9 is very slow. Whenever you're writing more than a few glyphs we strongly recommend that you turn on buffering. The simplest way to do this is by using python's with statement:

  with ds9.Buffering():
      for source in sourceList:
          if display:
              ds9.dot("o", source.getXAstrom(), source.getYAstrom())

  (note that ds9.Buffering() is safe even if no ds9 display is available). You can explicitly flush the buffer at anytime with ds9.flush()

  erase() [frame=-1]

  Erase the specified DS9 frame

  flush() []

  Draw all pending glyphs; you shouldn't usually need to use this.

  mtv() [data, frame=-1, init=True, wcs=None, isMask=False, lowOrderBits=False, title=None]

  Display an Image or Mask on a DS9 display

  If lowOrderBits is True, give low-order-bits priority in display (i.e. overlay them last)

  Historical note: the name "mtv" comes from Jim Gunn's forth imageprocessing system, Mirella (named after Mirella Freni); The "m" stands for Mirella.

  pan() [colc=None, rowc=None, frame=-1]

  Pan to (rowc, colc); see also zoom

  setDefaultFrame() [frame]

  Set the default frame for ds9

  setMaskColor() [color=GREEN]

  Set the ds9 mask colour to; eg. ds9.setMaskColor(ds9.RED)

  setMaskPlaneColor() [name, color=None]

  Request that mask plane name be displayed as color; name may be a dictionary (in which case color should be omitted

  setMaskPlaneVisibility() [name, show=True]

  Specify the visibility of a given mask plane; name may be a dictionary (in which case show w ill be ignored)

  setMaskTransparency() [transparency=None]

  Specify ds9's mask transparency (percent); or None to not set it when loading masks

  show() [frame=-1]

  Uniconify and Raise ds9. N.b. throws an exception if frame doesn't exit

  zoom() [zoomfac=None, colc=None, rowc=None, frame=-1]

  Zoom frame by specified amount, optionally panning also

• Graphics commands

  dot() [symb, c, r, frame=-1, size=2, ctype=GREEN]

  Draw a symbol onto the specified DS9 frame at (col,row) = (c,r) [0-based coordinates] Possible values are:

  +	Draw a +
  x	Draw an x
  o	Draw a circle
  @:Mxx,Mxy,Myy	Draw an ellipse with moments (Mxx, Mxy, Myy) (size is ignored)

  Any other value is interpreted as a string to be drawn

  line() [points, frame=-1, symbs=False, ctype=GREEN]

  Draw a set of symbols or connect the points, a list of (col,row) If symbs is True, draw points at the specified points using the desired symbol, otherwise connect the dots. Ctype is the name of a colour (e.g. ds9.RED)

• Internal commands that you shouldn't need to know

  Ds9Error

  Exception thrown if there's some problem talking to ds9

  ds9Cmd() [cmd, trap=True]

  Issue a ds9 command, raising errors as appropriate

  getDefaultFrame()

  Get the default frame for ds9

  getMaskPlaneColor() [name]

  Return the colour associated with the specified mask plane name

  getMaskPlaneVisibility() [name]

  Should we display the specified mask plane name?

  getMaskTransparency()

  Return ds9's mask transparency

  getXpaAccessPoint()

  Parse XPA_PORT and send return an identifier to send ds9 commands there, instead of "ds9" If you don't have XPA_PORT set, the usual xpans tricks will be played when we return "ds9".

  initDS9() [execDs9=True]

Colours may be specified as any X11-compliant string (e.g. "orchid"), or by one of the following constants defined in ds9; the advantage of the latter approach is that the python interpreter can detect typos: BLACK, WHITE, RED, BLUE, GREEN, CYAN, MAGENTA, YELLOW.

How to use ds9 through a firewall

On your home machine, type

export XPA_PORT="DS9:ds9 22345 22346"
#                        ^^^^^ ^^^^^
#                        Choose any 2 consecutive numbers over 4095
ssh -N -f lsstXXX.ncsa.uiuc.edu -R 22345:localhost:22345 -R 22346:localhost:22346 > /dev/null 2>&1
ds9 &

(setenv XPA_PORT "DS9:ds9 22345 22346" for csh users, of course)

On lsstXXX.ncsa.uiuc.edu, set XPA_PORT to the same value, start python, import lsst.afw.display.ds9 and proceed:

export XPA_PORT="DS9:ds9 22345 22346"
python
>>> import lsst.afw.display.ds9 as ds9
>>> ds9.erase()

xpa afficianados will note that I'm bypassing the xpa name server; it needs another set of 2 or 3 ports tunnelled, and setting up ACLs.

Here's a script (in afw/examples) to run on your home machine that should simplify setting up/tearing down the ssh tunnels. It's not great, so improvements would/will be welcomed.