Return to the DS9 Users Manual


Contours are curves along which the pixels have a constant value. ds9 can create and display contours as an overlay on a data image. The contours can be copied between frames in the current session or saved to file for future use with ds9.

If you encounter any problems, please email ds9help @


Creating Contours on a Dataset

This thread uses Chandra data from an observation of the galaxy cluster Abell 2142 (ObsID 5005).

After loading the data into ds9 and setting the desired scale, click on the "Contours" item in the "Analysis" menu to turn on contour display. Open the "Contour Parameters" window from "Analysis → Contours Parameters". There are two sliding scales which are used to set the number and smoothness of the contours and fields for setting the range of values to use.

Typically, you will want to generate between 1 and 10 contours; larger numbers will take longer to generate and display. A smoothness level of 1 will evaluate the contour at each image pixel, while a level of 2 will evaluate the contour at every other pixel, and so on. A larger smoothing will generate contours more quickly, but less detail will be available.

By default, the range of the data scale is filled in as the limits. Under the "Method" menu, there are two choices:

  1. block (the default) - blocks down the image by the smoothness factor before contours are calculated. The larger the smoothness, the faster the result.
  2. smooth - smooths the image before calculating contours. The larger the smoothness, the slower the result.

In this example, the number of levels is set to 6 and the smoothing is set to 5. The contours will be generated over the limit 1 to 100. The default method (block) is used.

After clicking the "Generate" button, the list of contours is calculated and displayed in the "Levels" portion of the window. Click "Apply" and the ds9 display is updated with the new contour levels, as shown in Figure 2.

The contour parameters can be adjusted until the desired result is achieved. Be sure to click "Generate" whenever an adjustment is made so that the levels are recalculated.

Copying the Contours to Another Frame

In this section, we take the X-ray contours just generated and display them on an optional image from the Digital Sky Survey (DSS).

From the "Analysis → Image Servers" menu, select one of the DSS server options (e.g. "SAO-DSS"). The server dialog box allows you to retrieve an optical image of the field of your observation and load it into a new frame. The default retrieval image size and (RA,Dec) is equal to the size and center of the field currently displayed. Here the width and height have been set to 40, but the (RA,Dec) determined by ds9 are used.

Click on "Retrieve" and the data is loaded into a new ds9 frame.

To copy the x-ray contours:

  1. Select the frame with the X-ray data in it.

  2. Use "Frame → Match Frames → WCS" to align the two images.

  3. To copy the contours, open the "Contour Parameters" dialog again and select "Copy Contours" from the "File" menu. Leave the window open, as it is needed in a future step.

  4. Select the frame with the optical data in it.

  5. Using the "File" menu of the "Contour Parameters" dialog, select "Paste Contours".

  6. Adjust the parameters (if desired) in the small dialog box that is displayed, then click "OK".

The optical image now has the x-ray contours overlaid. Since the WCS is the same, correlation between x-ray and optical features may be seen.

To delete contours which have been pasted into a frame, select "Clear" from the "File" menu of the "Contour Parameters" dialog.

Saving the Contours

To save the contours to a text file, choose "Save Contours" from the "File" menu of the "Contour Parameters" dialog. The contours are saved in a text file which can be loaded back into ds9 with the "Load Contours" menu item.

The contours generated in this thread have been saved as ds9.con.

Converting to Polygons and Saving

The contours can be converted to ds9 polygon regions for use in filtering data. Converting to polygons also allows you to select and/or delete specific contours.

Note that the contours cannot be saved in ds9 format after converting. If you wish to save the contours, do so before continuing.

To convert the contours, select "Convert to Polygons" from the "File" menu of the "Contour Parameters" dialog. The contours are now defined as ds9 polygons, e.g.


The polygon-shaped contours can be saved as a ds9 region file from the "Region Save → Regions" menu. The region file for these contours has been saved as a2142.reg.


24 Jun 2009 Original version

Return to the DS9 Users Manual