Ahelp: ds9 - CIAO 3.4

Description

The ds9 package provides a set of S-Lang functions for interacting with ds9 which are based on the XPA module (see "ahelp xpa").

The functions can be loaded using either of the following statements:

  require ("ds9");
  () = evalfile ("ds9");

Functions provided by the module

The following functions are provided by the pckage; use "ahelp <function>" to get a detailed description of a function:

ds9_launch
ds9_view
ds9_quit
ds9_clear
ds9_center
ds9_get_cmap and ds9_set_cmap
ds9_get_coords
ds9_get_crosshair and ds9_put_crosshair
ds9_get_array and ds9_put_array
ds9_get_file and ds9_put_file
ds9_get_regions and ds9_put_regions
ds9_get_scale and ds9_put_scale
ds9_put_wcs, ds9_put_wcs_keys, and ds9_put_wcs_struct
ds9_pan
ds9_get_zoom and ds9_set_zoom

Example 1

chips> require ("ds9")
chips> ds9_view ("acisf03662N001_evt2.fits")

Here we load in the ds9 package and then use it to start up a ds9 - if one is not running - and get it to view a file. The ds9_put_file() command can be used to change the file being displayed:

chips> ds9_put_file ("expmap.fits")

Example 2

chips> () = ds9_launch
chips> ds9_put_array ([1:512*512])

Here we use the package to send an array (the numbers 1 to 512*512) to ds9 for display. We can also read the data from ds9, which provides the possibility for manipulating the ds9 display:

chips> img = ds9_get_array
chips> img
Integer_Type[512,512]
chips> ds9_put_array (sqrt (img))

The routines default to treating images as arrays of raw pixel values. It is also possible to attach coordinate systems to these arrays to define the mapping between pixel number and the desired physical coordinate system.

From a text file

If the text file image.wcs contains

CRPIX1  256
CRVAL1  512
CDELT1  2
CTYPE1  X
CRPIX2  256
CRVAL2  512
CDELT2  2
CTYPE2  y

then it can be used by saying

chips> ds9_view ([1:512*512])
chips> ds9_put_wcs_keys ("image.wcs")

As a string array

The numeric values for the transform can also be supplied as an eight-element string-array. For example:

chips> wcs = String_Type [8]
chips> wcs[[0:3]] = ["CRPIX1 256","CRVAL1 512","CDELT1 2","CTYPE1 X"]
chips> wcs[[4:7]] = ["CRPIX2 256","CRVAL2 512","CDELT2 2","CTYPE2 Y"]
chips> ds9_put_wcs_keys ("image.wcs")

Numeric arrays

The WCS values can also be set using numeric arrays:

chips> crpix = [256,256]
chips> crval = [512,512]
chips> cdelt =[2,2]
chips> ds9_put_wcs (crpix, crval, cdelt)

As a structure

The WCS values can also be specified using a S-Lang struct:

chips> s = struct { crpix, crval, cdelt, ctype, cunit }
chisp> s.crval = [256,256]
chips> s.crval = [512,512]
chips> s.cdelt =[2,2]
chips> ds9_put_wcs_struct (s)

Removing the WCS

The coordinate transformation can be cleared by saying:

chips> ds9_put_wcs_keys ("")

Synopsis