Next Previous Contents

7. DS9 Function Reference

7.1 ds9_launch

Synopsis

Establish connection to a DS9 process

Usage

Struct_Type = ds9_launch( [xpa_id="ds9", ds9_cl_arg1, ds9_cl_arg2, ... [ ; timeout=num_seconds, verbosity=integer])

Description

Returns a handle to an instance of SAOds9 running with the specified XPA template identifier. If such a process is not already running then one will be launched, with the optionally command line arguments. To optimize communication with SAOds9 the returned handle should be passed to subsequent calls. The timeout= qualifier can be used to adjust how long the routine will wait to contact DS9 before giving up (the default is 30 seconds). The verbose= qualifier can be used to alter the amount of information printed to the screen while interacting with DS9.

Notes

When launched with no arguments this routine looks for/launches a default SAOds9 process, running on the local machine and identified as "ds9". Likewise, if the returned handle is omitted from subsequent calls then the respective function will contact the default process.

See Also

ds9_quit

7.2 ds9_connect

Synopsis

Establish connection to a DS9 process

Usage

Struct_Type = ds9_connect( [xpa_id="ds9", ds9_cl_arg1, ds9_cl_arg2, ... ])

Description

Synonym for ds9_launch; more contextually relevant for attaching to a running DS9 process, as opposed to launching an entirely new DS9 process. See ds9_launch for call sequence and more details.

Notes
See Also

ds9_launch, ds9_quit

7.3 ds9_quit

Synopsis

Terminate a DS9 process

Usage

ds9_quit ( [handle] )

Description

Terminates the DS9 process associated with the given handle.

Notes

When handle is omitted the routine will terminate the default process, as described above.

See Also

ds9_launch

7.4 ds9_clear

Synopsis

Erase DS9 frame

Usage

ds9_clear( [frame_number | "all"][, handle] )

Description

Erase the contents of the specified DS9 frame, which by default is the current frame.

See Also

7.5 ds9_center

Synopsis

Center image at position

Usage

ds9_center( X, Y, [system="physical" , handle])

Description

Shift image so that (X,Y) is positioned at the center of the frame, using the same coordinate system constraints as those described for ds9_get_coords.

Notes
See Also

ds9_pan, ds9_put_crosshair

7.6 ds9_get_cmap

Synopsis

Retrieve colormap

Usage

(name, inverted) = ds9_get_cmap( [handle] )

Description

Retrieve the name of the colormap applied to the current image frame, and an integer value indicating whether it is inverted.

Notes
See Also

ds9_set_cmap

7.7 ds9_set_cmap

Synopsis

Change colormap

Usage

ds9_set_cmap( "grey|red|..." [, inverted, handle])

Description

Redraw the image within the current frame, using the specified colormap. By default the colormap will not be inverted, but that may be controlled by specfying inverted=[0/"no" | 1 / "yes"].

Notes

Unsupported colormap parameters will be ignored.

See Also

ds9_get_cmap

7.8 ds9_get_coords

Synopsis

Retrieve position of next mouseclick within any frame

Usage

 (x,y) = ds9_get_coords( [coord_sys="physical" , handle])

Description

Changes cursor to an annulus and pauses DS9 until the next mouseclick within any frame, after which the mouse coordinates are returned. By default these values will be of Double_Type in the physical coordinate system, or (-1, -1) upon error. Image pixel and WCS coordinate values may be obtained by passing in a coord_sys of "image" or "wcs," respectively. Note that the return values may be of String_Type if coord_sys contains additional qualifiers, such as "wcs fk5 sexagesimal".

Notes

Requires DS9 version 3.0b9 or later.

See Also

ds9_get_crosshair

7.9 ds9_get_crosshair

Synopsis

Retrieve position of crosshair cursor

Usage

(x, y) = ds9_get_crosshair( [coord_sys="physical" , handle])

Description

Return the position of the crosshair cursor, under the same coordinate system and return values constraints as those described for ds9_get_coords. (0,0) will be returned when the current frame is not displaying an image. (-1,-1) will be returned upon error (e.g. when no frames exist).

Notes

When an image is loaded into a frame the crosshair cursor will be positioned at its center, even if the crosshair is invisible.

See Also

ds9_put_crosshair, ds9_get_coords

7.10 ds9_put_crosshair

Synopsis

Set position of crosshair cursor

Usage

ds9_put_crosshair( x, y, [system="physical" , handle])

Description

Set the position of the crosshair cursor, using the same coordinate system constraints as those described for ds9_get_coords.

Notes
See Also

ds9_get_crosshair, ds9_pan

7.11 ds9_get_version

Synopsis

Retrieve DS9 version information

Usage

String = ds9_get_version([handle])

Description

Returns a string containing the software version of the DS9 process in use.

Notes

When the DS9 version is obtained directly from a command prompt, say via

linux% xpaget ds9 version

ds9 3.0b9

the application name is included in the version. This function removes that redundancy, so in this instance would return only "3.0b9".

7.12 ds9_get_array

Synopsis

Retrieve displayed image

Usage

 Array_Type = ds9_get_array( [handle] ) 

Description

Returns the image being displayed in the current DS9 frame, as a 2D S-Lang array of pixel values. The array will be of dimension [Y=NAXIS2, X=NAXIS1] and type reflecting the BITPIX value.

Notes

By default DS9 returns pixel arrays in FITS (big-endian) format. This routine will transparently byteswap its return value, when necessary, to match the the calling platform.

See Also

ds9_put_array

7.13 ds9_put_array

Synopsis

Visualize an image pixel array

Usage

ds9_put_array(image_pixel_array [, handle] )

Description

Transmits an S-Lang array of image pixel values to DS9 for visualization in the current frame. If no frames exist then one will be created first. The array may be either 1D or 2D, and will automatically be tagged with the correct FITS BITPIX and image dimension values.

Notes

A 1D pixel array must contain N^2 elements, and will transmitted to DS9 as an NxN image. DS9 will byteswap all pixel arrays, if necessary, on input.

See Also

ds9_get_array

7.14 ds9_get_file

Synopsis

Retrieve name of file being displayed

Usage

String_Type ds9_get_file ( [handle] )

Description

Returns the name of file being displayed within the current DS9 frame, which may include a directory path if such was specified to DS9 on input.

Notes

An empty string will be returned if DS9 is not running, has no current frame, or is not displaying a file in the current frame.

See Also

ds9_put_file

7.15 ds9_put_file

Synopsis

Load FITS file

Usage

ds9_put_file (FITS_file_name [, handle]) 

Description

Transmits the name of a FITS file to DS9, which it will open and visualize within the current frame. If no frames exist then one will be created first

Notes

The file name may need to include a relative or absolute directory path, if it's located in a directory other than the one from which DS9 was launched.

See Also

ds9_get_file

7.16 ds9_view

Synopsis

Launch DS9 with file or image pixel array

Usage

ds9_view( filename | image_pixel_array [, ds9_arg1, ...])

Description

A convenience function, which issues a ds9_launch() command followed by ds9_put_file() or ds9_put_array() as appropriate.

Notes

All parameters after the first will be interpreted as DS9 command line arguments.

See Also

ds9_launch, ds9_put_file, ds9_put_array

7.17 ds9_get_regions

Synopsis

Retrieve descriptions of regions applied to displayed image

Usage

String_Type[] = ds9_get_regions( [file_name | NULL, handle; coord_sys=String ; format=fmt])

Description

Returns a possibly empty string array describing the regions that have been applied to the current image frame. Results will be given in the current region file format and coordinate system. The latter defaults to the current region coordinate system in use by DS9, but may be changed changed manually within the Region menu of the GUI or by specifying the named coord_sys qualifier, e.g.

ds9_get_regions( "/tmp/my.reg" ; coord_sys="physical")

Note that a semicolon separates named qualifiers from positional parameters.

A string passed in as the first argument will be interpreted as the name of a file to which the region descriptions should be written, and will be echoed back to the caller as the only element within the result array.

Seee the DS9 reference manual for the full range of supported coordinate systems and region file formats.

Notes

Some region formats will prepend one or more comment lines (begining with '#') prior to the actual regions, unless the 'strip' option has been selected within the GUI. Finally, note that the function may be called with no arguments.

See Also

ds9_put_regions

7.18 ds9_put_regions

Synopsis

Request that region descriptions be applied to displayed image

Usage

ds9_put_regions( from_file_name | string_array | NULL [, handle ]

Description

Transmits a set of region descriptions, from the specified file or string array, to DS9 for application on the current image frame. Pass in NULL to erase all regions.

Notes

File names may need to include a relative or absolute directory path, if the referenced file is located in a directory other than the one from which DS9 was launched.

See Also

ds9_get_regions

7.19 ds9_get_scale

Synopsis

Retrieve image scale

Usage

String_Type  ds9_get_scale ( [handle] )

Description

Retreive the scale setting of the current image frame, as a string.

Notes
See Also

ds9_set_scale

7.20 ds9_set_scale

Synopsis

Change image scale

Usage

ds9_set_scale( "linear|log|sqrt ..." [, handle])

Description

Redraw the image within the current frame, using the specified scale.

Notes

Unsupported scale parameters will be ignored.

See Also

ds9_get_scale

7.21 ds9_put_wcs

Synopsis

Apply WCS to displayed image, using raw numeric/string values

Usage

ds9_put_wcs(crpix, crval, cdelt [, ctype, cunit, alt_wcs_char, handle])

Description

Generate a set of FITS world coordinate system header keywords from the given inputs, and transmit them to DS9 for application to the current image frame, replacing any previous WCS keywords of the same name.

Here crpix, crval, cdelt, ctype, and cunit inputs will generally be arrays of length two, with the first three of Float_Type and last two of String_Type. The first element of each array will be used to construct a set of WCS transform keywords for the first image axis, and likewise the set of second elements will apply to the second image axis. If crpix is not an array, or is only of length 1, keywords for the second image axis will be generated from FITS-conformant default values.

Notes

The alt_wcs_char may be one of 'a', ..., 'z', indicating which alternate WCS to use of WCSa, ... WCSz. The module interprets 'p' to mean that the given WCS should be viewed by DS9 as the physical coordinate system.

See Also

ds9_put_wcs_keys, ds9_put_wcs_struct, ds9_wcs_edit

7.22 ds9_put_wcs_keys

Synopsis

Apply WCS to displayed image, using pre-formatted FITS keywords

Usage

ds9_put_wcs_keys( from_file_name | string_array [, handle])

Description

Transmit a set of FITS world coordinate system header keywords to DS9, for application to the current image frame, replacing any previous WCS keywords of the same name.

Notes

Keyword name/value pairs may be formatted either in accordance with the FITS 80 character card standard, or simply separated by whitespace.

See Also

ds9_put_wcs , ds9_put_wcs_struct, ds9_wcs_edit

7.23 ds9_put_wcs_struct

Synopsis

Apply WCS to displayed image, using structure field values

Usage

ds9_put_wcs_struct(struct [, alt_wcs_char, handle])

Description

Like ds9_put_wcs(), except here the raw crpix, crval, cdelt, ctype, and cunit values will be taken from fields of the same name within the specified structure.

See Also

ds9_put_wcs , ds9_put_wcs_keys, ds9_wcs_edit

7.24 ds9_pan

Synopsis

Shift image position

Usage

ds9_pan( X, Y, [system="physical" , handle])

Description

Pan image by X pixels horizontally and Y pixels vertically, using the same coordinate system constraints as those described for ds9_get_coords.

Notes

X and Y may be negative.

See Also

ds9_center, ds9_put_crosshair

7.25 ds9_get_zoom

Synopsis

Retreive zoom level

Usage

Double_Type  ds9_get_zoom ( [handle] )

Description

Retrieve zoom level of current image frame, as a Double_Type value.

Notes
See Also

ds9_center, ds9_pan, ds9_set_zoom

7.26 ds9_set_zoom

Synopsis

Zoom in/out

Usage

ds9_set_zoom( zoom_factor [, handle])

Description

Set current zoom to specified value. Values greater than 1 zoom in to image features, while values less than 1 zoom out.

Notes
See Also

ds9_center, ds9_pan, ds9_get_zoom

7.27 ds9_send

Synopsis

Send arbitrary XPA command strings to DS9

Usage

ds9_send( ds9_xpa_command_string [, handle])

Description

This function provides a useful catch-all control mechanism, by allowing arbitrary XPA command strings to be sent to DS9. For example, at the time of this writing the DS9 module did not provide a high-level interface, through which various scaling factors can be set, such as ds9_scale("log"). Instead, the DS9 scale factor can be customized with the command ds9_send("scale log").

Notes

Use this function when the given XPA command is not expected to return a result to the caller. Use ds9_recv() when issuing XPA commands which are expected to return a result,

See Also

ds9_recv

7.28 ds9_recv

Synopsis

Send arbitrary XPA command strings to DS9 and return a result

Usage

result = ds9_recv( ds9_xpa_command_string [, handle])

Description

This is another catch-all function like ds9_send(), only it allows a result to be returned from DS9 to the caller.

Notes

Many of the higher level DS9 module functions reformat the information returned by DS9 into a more useful form before returning it to the caller. Because it is more generic, ds9_recv() DOES NOT do this. For example, suppose the zoom level in the DS9 GUI is 1. In this case the ds9_get_zoom() function would return a floating point value of 1, but ds9_recv("zoom") would return the string "1\n".

See Also

ds9_send

7.29 ds9_wcs_edit

Synopsis

Interactive WCS editor

Usage

ds9_wcs_edit()

Description

Launches a guilet from which WCS values may be applied to the current image.

Notes

The loading of this function is deferred until it is actually called, because it requires that the SLgtk module be installed on your system. When the function is first invoked the intepreter will also attempt to load SLgtk (if it has not already been loaded); if that fails this function will not be executed.

See Also

ds9_put_wcs, ds9_put_wcs_keys, ds9_put_wcs_struct

7.30 ds9_new

Synopsis

Establish connection to a DS9 process, returning an OO-like object

Usage

Struct_Type = ds9_new( [xpa_id="ds9", ds9_cl_arg1, ds9_cl_arg2, ... ])

Description

This function is similar to ds9_launch(), only instead of returning a handle it returns a structure which may subsequently be used in an object-oriented fashion. For example, consider

variable d = ds9_new(); d.put_array([1:100*100]);

Notes

This function accepts the same arguments as does ds9_launch().

See Also

ds9_launch


Next Previous Contents