Establish connection to a DS9 process
Struct_Type = ds9_launch( [xpa_id="ds9", ds9_cl_arg1, ds9_cl_arg2, ... [ ; timeout=num_seconds, verbosity=integer])
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.
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.
Establish connection to a DS9 process
Struct_Type = ds9_connect( [xpa_id="ds9", ds9_cl_arg1, ds9_cl_arg2, ... ])
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.
Terminate a DS9 process
ds9_quit ( [handle] )
Terminates the DS9 process associated with the given handle.
When handle is omitted the routine will terminate the default process, as described above.
Erase DS9 frame
ds9_clear( [frame_number | "all"][, handle] )
Erase the contents of the specified DS9 frame, which by default is the current frame.
Center image at position
ds9_center( X, Y, [system="physical" , handle])
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.
(name, inverted) = ds9_get_cmap( [handle] )
Retrieve the name of the colormap applied to the current image frame, and an integer value indicating whether it is inverted.
ds9_set_cmap( "grey|red|..." [, inverted, handle])
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"].
Unsupported colormap parameters will be ignored.
Retrieve position of next mouseclick within any frame
(x,y) = ds9_get_coords( [coord_sys="physical" , handle])
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".
Requires DS9 version 3.0b9 or later.
Retrieve position of crosshair cursor
(x, y) = ds9_get_crosshair( [coord_sys="physical" , handle])
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).
When an image is loaded into a frame the crosshair cursor will be positioned at its center, even if the crosshair is invisible.
Set position of crosshair cursor
ds9_put_crosshair( x, y, [system="physical" , handle])
Set the position of the crosshair cursor, using the same coordinate system constraints as those described for ds9_get_coords.
Retrieve DS9 version information
String = ds9_get_version([handle])
Returns a string containing the software version of the DS9 process in use.
When the DS9 version is obtained directly from a command prompt, say via
linux% xpaget ds9 version
the application name is included in the version. This function removes that redundancy, so in this instance would return only "3.0b9".
Retrieve displayed image
Array_Type = ds9_get_array( [handle] )
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.
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.
Visualize an image pixel array
ds9_put_array(image_pixel_array [, handle] )
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.
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.
Retrieve name of file being displayed
String_Type ds9_get_file ( [handle] )
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.
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.
Load FITS file
ds9_put_file (FITS_file_name [, handle])
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
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.
Launch DS9 with file or image pixel array
ds9_view( filename | image_pixel_array [, ds9_arg1, ...])
A convenience function, which issues a ds9_launch() command followed by ds9_put_file() or ds9_put_array() as appropriate.
All parameters after the first will be interpreted as DS9 command line arguments.
ds9_launch, ds9_put_file, ds9_put_array
Retrieve descriptions of regions applied to displayed image
String_Type = ds9_get_regions( [file_name | NULL, handle; coord_sys=String ; format=fmt])
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.
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.
Request that region descriptions be applied to displayed image
ds9_put_regions( from_file_name | string_array | NULL [, handle ]
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.
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.
Retrieve image scale
String_Type ds9_get_scale ( [handle] )
Retreive the scale setting of the current image frame, as a string.
Change image scale
ds9_set_scale( "linear|log|sqrt ..." [, handle])
Redraw the image within the current frame, using the specified scale.
Unsupported scale parameters will be ignored.
Apply WCS to displayed image, using raw numeric/string values
ds9_put_wcs(crpix, crval, cdelt [, ctype, cunit, alt_wcs_char, handle])
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.
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.
ds9_put_wcs_keys, ds9_put_wcs_struct, ds9_wcs_edit
Apply WCS to displayed image, using pre-formatted FITS keywords
ds9_put_wcs_keys( from_file_name | string_array [, handle])
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.
Keyword name/value pairs may be formatted either in accordance with the FITS 80 character card standard, or simply separated by whitespace.
ds9_put_wcs , ds9_put_wcs_struct, ds9_wcs_edit
Apply WCS to displayed image, using structure field values
ds9_put_wcs_struct(struct [, alt_wcs_char, handle])
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.
ds9_put_wcs , ds9_put_wcs_keys, ds9_wcs_edit
Shift image position
ds9_pan( X, Y, [system="physical" , handle])
Pan image by X pixels horizontally and Y pixels vertically, using the same coordinate system constraints as those described for ds9_get_coords.
X and Y may be negative.
Retreive zoom level
Double_Type ds9_get_zoom ( [handle] )
Retrieve zoom level of current image frame, as a Double_Type value.
ds9_center, ds9_pan, ds9_set_zoom
ds9_set_zoom( zoom_factor [, handle])
Set current zoom to specified value. Values greater than 1 zoom in to image features, while values less than 1 zoom out.
ds9_center, ds9_pan, ds9_get_zoom
Send arbitrary XPA command strings to DS9
ds9_send( ds9_xpa_command_string [, handle])
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").
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,
Send arbitrary XPA command strings to DS9 and return a result
result = ds9_recv( ds9_xpa_command_string [, handle])
This is another catch-all function like ds9_send(), only it allows a result to be returned from DS9 to the caller.
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".
Interactive WCS editor
Launches a guilet from which WCS values may be applied to the current image.
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.
ds9_put_wcs, ds9_put_wcs_keys, ds9_put_wcs_struct
Establish connection to a DS9 process, returning an OO-like object
Struct_Type = ds9_new( [xpa_id="ds9", ds9_cl_arg1, ds9_cl_arg2, ... ])
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]);
This function accepts the same arguments as does ds9_launch().