Collage plugin

Plugin to create an image mosaic via the collage method.

Plugin Type: Local

Collage is a local plugin, which means it is associated with a channel. An instance can be opened for each channel.


This plugin is used to automatically create a mosaic collage in the channel viewer using images provided by the user. The position of an image on the collage is determined by its WCS without distortion correction. This is meant as a quick-look tool, not a replacement for image drizzling that takes account of image distortion, etc.

The collage only exists as a plot on the Ginga canvas. No new single image is actually built (if you want that, see the “Mosaic” plugin). Some plugins that expect to operate on single images may not work correctly with a collage.

To create a new collage, click the “New Collage” button and drag files onto the display window (e.g. files can be dragged from the FBrowser plugin). Images must have a working WCS. The first image processed will be loaded and its WCS will be used to orient the other tiles. You can add new images to an existing collage simply by dragging addtional files.


The “Method” control is used to choose a method for mosaicing the images in the collage. It has two values: ‘simple’ and ‘warp’:

  • ‘simple’ will attempt to rotate and flip the images according to the WCS. It is a fast method, at the expense of accuracy. It will not handle distortions near the edge of the field that should skew the image.

  • ‘warp’ will use the WCS to completely move each pixel in the image according to the reference image’s WCS. This may leave empty pixels in the image that are filled in by sampling from surrounding pixels. This will be slower than the simple method, and the time increases linearly with the size of the images.

Check the “Collage HDUs” button to have Collage attempt to plot all the image HDUs in a dragged file instead of just the first found one.

Check “Label Images” to have the plugin draw the name of each image over each plotted tile.

If “Match bg” is checked, the background of each tile is adjusted relative to the median of the first tile plotted (a kind of rough smoothing).

The “Num Threads” box assigns how many threads will be used from the thread pool to load the data. Using several threads will usually speed up loading of many files.

Difference from `Mosaic` plugin

  • Doesn’t allocate a large array to hold all the mosaic contents

  • No need to specify output FOV or worry about it

  • Can be quicker to show result (depends a bit on constituent images)

  • Some plugins will not work correctly with a collage, or will be slower

  • Cannot save the collage as a data file (although you can use “ScreenShot”)

It is customizable using ~/.ginga/plugin_Collage.cfg, where ~ is your HOME directory:

# Collage plugin preferences file
# Place this in file under ~/.ginga with the name "plugin_Collage.cfg"

# Set to True when you want to collage image HDUs in a file
collage_hdus = False

# annotate images with their names
annotate_images = False

# Try to match backgrounds
match_bg = False

# Number of threads to devote to opening images
num_threads = 4