add_ds9_contours

Context: contrib

Synopsis

Add the contours from a ds9 *.con file to a ChIPS plot (with optional coordinate conversion).

Syntax

add_ds9_contours(filename [, color="green", thickness=1, style="solid",
depth=100, stem="ds9con", coords=None, fromsys=None, tosys=None])

This routine draws on the contours from the DS9 *.con file onto the current plot as a curve with the given parameters (which correspond to the line options of a curve; symbol.style is set to "none"). If the coords, fromsys and tosys arguments are given then they are used to convert the values to a different coordinate system (e.g. if the values were written out in WCS but you wish to use the sky system). The coords argument on its own can be used to plot up the contours using a tangent-plane projection if one does not already exist.

Loading the routine

The routine can be loaded into a ChIPS or Sherpa session by saying:

from chips_contrib.utils import *

Coordinate conversion

To convert the coordinate values form the file then coords should be either the name of an image file or a crate containing an image and the fromsys and tosys arguments determine what systems to use:

The fromsys and tosys arguments

Value	Description
"world" or "eqpos"	The WCS coordinate systems supported by CIAO
"physical" or "sky"	The physical coordinate system
"logical" or "image"	The logical coordinate system

Example 1

chips> clear()
chips> add_window(8, 8, "inches")
chips> add_image("img.fits")
chips> add_ds9_contours("ds9.con")

The contours from ds9.con are drawn on top of the image img.fits. The contour coordinates are assumed to be in the same system as used to display the image. The output of the info() command after the above looks like:

chips> info()
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.15)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [ds9con1]

Since the contour is drawn using a ChIPS curve, we can use the set_curve() command to change its properties: e.g.

chips> set_curve(["line.color", "orange"])

Example 2

chips> add_ds9_contours("radio.con", color="orange", depth=110)

Here we add the contours from the file radio.con to the plot, using the arguments in the command to change the color and depth of the curve (see 'ahelp depthcontrol' for more information on how ChIPS uses the depth attribute to order the display of objects).

Example 3

chips> clear()
chips> add_window(8, 8, "inches")
chips> add_image("img.fits", ["wcs", "physical"])
chips> add_ds9_contours("ds9.con", coords="img.fits", fromsys="world",
tosys="sky")

Here we display the image in physical (i.e. SKY) coordinates and so we need to convert the DS9 coordinates (which we assume were written out in equatorial coordinates).

Example 4

chips> clear()
chips> add_window(8, 8, "inches")
chips> add_ds9_contours("ds9.con")
chips> set_plot_title("Linear")
chips> add_window(8, 8, "inches")
chips> add_ds9_contours("ds9.con", coords="img.fits")
chips> set_plot_title("World")
chips> current_window("all")
chips> set_axis(["majorgrid.visible", True])
chips> zoom(0.1)

Here we create two plots consisting of just the contours; the difference is whether they use linear axes (first window) or a tangent-plane projection (second window). Grid lines are added and both plots zoomed out to try and show a difference (if the axis scale is large enough or the tangent-point of img.fits is near enough the pole then you should see the major grid lines curve in the second plot).

In the second window, the add_ds9_contours() call had to create axes and so it used the tangent-plane projection information from the coords argument. This is only needed if add_image() or add_contour() has not already been used to set up a plot with the required projection. For example, after

chips> from crates_contrib.utils import scale_image_crate
chips> cr = read_file("img.fits")
chips> scale_image_crate(cr, "log10")

then either

chips> clear()
chips> add_image(cr)
chips> add_ds9_contours("ds9.con")

chips> clear()
chips> add_ds9_contours("ds9.con", coords=cr)
chips> add_image(cr)

will work but the following fails

chips> clear()
chips> add_ds9_contours("ds9.con")
chips> add_image(cr)
chips ERROR: Cannot add object because axes, ax1 and ay1, are not a
valid type and already have data associated with them.

because the axes created by the add_ds9_contour() call do not contain the necessary WCS projection information needed to display the image data.