Reference Manual for SLxpa Version 0.5.0 Michael S. Noble, mnoble@space.mit.edu Jul 9, 2008 ____________________________________________________________ Table of Contents Preface Introduction 1. Brief History 2. Backwards Compatibility 3. Using the XPA Module 3.1 Building 3.2 Running 4. A Word About Examples 5. Interactive Image Analysis with SAOds9 5. Module Overview 6. Versioning 7. Omitted Arguments 8. Error Checking 9. Contacting Multiple Servers 10. Unimplemented Functions 10.1 Server 10.2 Client 10.2 High Level XPA Interface 11. xpaset 12. xpaget 13. xpaaccess 13. Low Level XPA Interface 14. XPA_Type 15. XPAOpen 16. XPAClose 17. XPAGet 18. XPAGetB 19. XPAGetToFile 20. XPASet 20. Using DS9 from S-Lang 21. Examples 21.1 Getting Started 21.2 Sending Images to DS9 21.3 Retrieving Images from DS9 22. Point and Click Interactivity 23. Regions 24. World Coordinate Systems 24..1 Formatted WCS Strings 24..2 Raw/Unformatted WCS Values 24.1 WCS Structures 24.2 Alternate WCS 24.3 Erasing WCS 25. WCS Editor GUI 26. Shutting Down 27. Optional Arguments 28. Return Values 28. DS9 Function Reference 29. ds9_launch 30. ds9_connect 31. ds9_quit 32. ds9_clear 33. ds9_center 34. ds9_get_cmap 35. ds9_set_cmap 36. ds9_get_coords 37. ds9_get_crosshair 38. ds9_put_crosshair 39. ds9_get_version 40. ds9_get_array 41. ds9_put_array 42. ds9_get_file 43. ds9_put_file 44. ds9_view 45. ds9_get_regions 46. ds9_put_regions 47. ds9_get_scale 48. ds9_set_scale 49. ds9_put_wcs 50. ds9_put_wcs_keys 51. ds9_put_wcs_struct 52. ds9_pan 53. ds9_get_zoom 54. ds9_set_zoom 55. ds9_send 56. ds9_recv 57. ds9_wcs_edit 58. ds9_new ______________________________________________________________________ 1. Preface SLxpa is a software package which provides XPA bindings for the S-Lang scripting language. It was originally developed in 2002 at the Smithsonian Astrophysical Observatory, as part of the CIAO analysis package developed to support the Chandra X-Ray Observatory, and is covered by the notice COPYRIGHT.SAO in the root of the CIAO distribution (and included below). The standalone module (distributable independently of CIAO) was created at the MIT Center for Space Research between 2003 and 2004. /************************************************************************/ /* Copyrights: */ /* */ /* Copyright (c) 2002 Smithsonian Astrophysical Observatory */ /* */ /* Permission to use, copy, modify, distribute, and sell this */ /* software and its documentation for any purpose is hereby */ /* granted without fee, provided that the above copyright */ /* notice appear in all copies and that both that copyright */ /* notice and this permission notice appear in supporting docu- */ /* mentation, and that the name of the Smithsonian Astro- */ /* physical Observatory not be used in advertising or publicity */ /* pertaining to distribution of the software without specific, */ /* written prior permission. The Smithsonian Astrophysical */ /* Observatory makes no representations about the suitability */ /* of this software for any purpose. It is provided "as is" */ /* without express or implied warranty. */ /* THE SMITHSONIAN ASTROPHYSICAL OBSERVATORY DISCLAIMS ALL */ /* WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL */ /* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO */ /* EVENT SHALL THE SMITHSONIAN ASTROPHYSICAL OBSERVATORY BE */ /* LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES */ /* OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA */ /* OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR */ /* OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH */ /* THE USE OR PERFORMANCE OF THIS SOFTWARE. */ /* */ /************************************************************************/ 2. Introduction SLxpa binds the XPA library to the S-Lang language. It provides an importable module and associated .sl script which make XPA callable directly from S-Lang scripts. The S-Lang interpreter is part of the widely-used, open-source library of the same name, and provides a scripting environment well-suited for scientific and engineering tasks, due to the powerful, compact, fast, and robust multidimensional numerical capabilities that are native to the language. XPA is a set of libraries (ANSI C, Tcl/Tk) and commandline tools, written at the Smithsonian Astrophysical Observatory, which provide a clean and simple IPC (inter-process communication) mechanism that is also surprisingly powerful. It can be used to build loosely-coupled client/server programs that interact either on a single machine or across local and wide-area networks; we have also found it useful for automated regression testing, especially for GUIs that are traditionally difficult to test in this manner. The XPA library provides much of the functionality of more well-known mechanisms like CORBA, Java RMI, and the now-defunct ToolTalk, but is much smaller and, we feel, can be easier to learn, embed, deploy, and utilize. The SAOds9 image display and analysis tool is perhaps the most well- known XPA command server. Also written at the Smithsonian Astrophysical Observatory, SAOds9 is one of the single most widely used programs in observational astronomy. CIAO, a software system created to assist in the analysis of data generated by the Chandra X- Ray Telescope, provides a number of programs (e.g. ChIPS and Prism) that function both as XPA clients (by interacting with DS9 and each other) and servers (by providing XPA access points of their own). Other software employing XPA includes fv and POW (a FITS file viewer and plotting tool, respectively, available within both the FTOOLS and HEASOFT astronomy software suites), as well as the SAS package created for the XMM-Newton X-Ray Telescope. A set of Perl bindings to XPA also exists in CPAN. 2.1. Brief History S-Lang bindings for XPA were originally developed at the Smithsonian Astrophysical Observatory in 2002, as part of CIAO, an analysis software package developed in part to support the Chandra X-Ray Telescope. The SLxpa package, created at the MIT Center for Space Research between 2003 and 2004, adds significant enhancements to the original bindings, in order to: o take better advantage of S-Lang features (such as returning multiple values from a function) o clarify precisely what values slxpa_errno may hold o provide new get routines which return BString_Type data o indicate the number of servers contacted by xpaset o return names and messages arrays from XPAGet and XPASet o properly flush files created during XPAGetToFile calls o simplify runtime debugging with slirp_debug_pause (see documentation at the SLIRP website ) o improve internal robustness o provide CIAO-independent example and test scripts o provide improved documentation Moreover, SLxpa extends their scope of potential use to a considerably wider audience, in that the package may be obtained independently of CIAO, allowing developers to avoid downloading hundreds of megabytes of astronomical software and data just to obtain a 100 Kb module. 2.2. Backwards Compatibility As noted in the respective function descriptions, some of the SLxpa enhancements described above change the semantics of the XPA bindings as originally developed within CIAO. However, SLxpa may still be used as a drop-in replacement for those bindings, simply by declaring the variable _CIAO3_XPA_COMPAT_ in the Global namespace prior to loading the package, e.g. as public variable _CIAO3_XPA_COMPAT_; The variable need not be initialized to any particular value. 2.3. Using the XPA Module 2.3.1. Building SLxpa ships with a configure script generated by autoconf, and in most cases can be built by issuing the following standard commands within a UNIX-like (e.g. Linux or Cygwin) environment: ./configure [options] make make install The third step is optional, but recommended. Version 2.1.4 or later of XPA is recommended. Versions of SLxpa prior to 0.5 were compatible with S-Lang 1, but SLxpa versions 0.5 and later require S-Lang 2.1 or later (e.g. to support the use of named qualifers in function calls). The ./configure --help command will display all available configure options. 2.3.2. Running To use the XPA module in a S-Lang script it is first necessary to make the functions in the package known to the interpreter, via () = evalfile ("xpa"); or, if the application embedding the interpreter supports the require function, require ("xpa"); may be used. You may also load the package into a namespace, such as () = evalfile ("xpa", "xpans"); This would place the XPA symbols into the xpans namespace (creating it, if necessary). Once the package has been loaded functions and variables defined within may be used in the usual way, e.g. require ("xpa"); . . () = xpaset("ds9","quit"); Finally, recall that the S-Lang autoload function may be used to avoid explicitly evalfile-ing or require-ing the package prior to using the functions defined within. The remainder of this document assumes the reader is familiar with the XPA suite of command line tools and/or the XPA application programming interface (api). For more information consult the XPA website . 2.4. A Word About Examples To make the most of the examples given below it is encouraged that you run them and experiment. In support of that you should first: o ensure that XPA and DS9 (version 3.0 or later) are installed on your system o build SLxpa (installation is not required to run the examples) o change to the examples directory of the SLxpa distribution o invoke a copy of DS9 The examples reference programs mentioned in the introduction with which you may not be familiar. Do not fret, as you need not actually run an example within the given application for it to still serve most of its didactic purpose, because what's being shown are not specific features of the application, per se, but rather how XPA function calls may be made through the S-Lang interpreter. The XPA functions may be called in the exact same manner from any application which embeds the S-Lang interpreter and supports module importation. In fact, most of the examples can be cut and pasted into a S-Lang script and then invoked from within the S-Lang shell (slsh, distributed with the S- Lang library, and assumed to be installed on your system). 2.5. Interactive Image Analysis with SAOds9 As described in chapter ``DS9_Package'', SLxpa also bundles a script which streamlines interactions with the SAOds9 image display and analysis tool. By augmenting the numerical strength and modular extensibility of the S-Lang platform with the imaging capabilities of SAOds9, the DS9 script can make a powerful addition to your image analysis toolset. 3. Module Overview The SLxpa api provides both high-level and low-level views on the underlying XPA library. At the high-level SLxpa seeks to mimic the three most commonly used XPA command line utilities: xpaset, xpaget, and xpaaccess. It is anticipated that the corresponding S-Lang functions will also be the most commonly used SLxpa features. At the low-level SLxpa aims at mirroring the XPA api more closely. To that end, rather than replicate the XPA documentation here we simply note discrepancies between the respective apis and refer the reader to the XPA website . Note that for brevity we use the terms XPA access point and XPA command, and likewise XPA server and target, interchangeably. 3.1. Versioning SLxpa indicates version information in the variables _xpa_module_version An integer containing the value (10000*major_ver) + (100*minor_ver) + micro_ver _xpa_module_version_string A string containing the value major_ver.minor_ver.micro_ver Earlier releases of SLxpa used the variables _slxpa_version and _slxpa_version_string to convey this information, but these have been deprecated. As a user convenience SLxpa also indicates the version of XPA against which it was built, via the floating point variable xpa_version 3.2. Omitted Arguments If a function argument is omitted at invocation time, and a default value is given in the functions Usage statement, the underlying XPA C function will be invoked as if the default value were specified for the omitted argument. Note that, as is the case with, say, C++, in order to default the Nth argument each of arguments 1 through N-1 must be specified. 3.3. Error Checking SLxpa introduces the slxpa_errno variable, which indicates the last error which occurred internal to the XPA module. The module zeros slxpa_errno at import time, and explicitly assigns only the following values 1 XPA_COULD_NOT_CONNECT 2 XPA_SERVER_ERROR 3 XPA_MALLOC_ERROR during subsequent execution. As with the errno variable defined by C, it is the caller's responsibility to zero slxpa_errno when needed. 3.4. Contacting Multiple Servers The XPA_MAXHOSTS environment variable, when set, signifies the upper limit for the number of application servers that any single SLxpa call will contact. By default this value is 5. Note that this variable is also utilized by the XPA library itself, as are others described in the XPA documentation. 3.5. Unimplemented Functions 3.5.1. Server The XPA module supports only the client portion of the XPA library; no server functions have yet been wrapped. 3.5.2. Client Several client functions have been omitted: o XPAInfo o XPANSLookup o XPASetFd It is unclear if any applications have been written which provide info XPA access points. Although technically speaking SLxpa does provide a wrapper for XPASetFd, namely XPASetFromFile, at present it is only an empty stub. 4. High Level XPA Interface 4.1. xpaset Synopsis Send data to one or more XPA servers Usage Integer_Type xpaset(targets, xpa_cmd [, param, param, ... [,data]]) Description This function is used to send information or commands to one or more XPA server(s). The return value indicates the number of application servers contacted. Example () = xpaset("ds9","file new stars.fits") () = xpaset("ds9","cmap","heat") These commands load a new file into DS9 and select the heat col- ormap, discarding the return values. They also demonstrate the flexibility with which XPA parameters may be passed to the server, either by concatenation with the XPA command name or as distinct comma-separated arguments. Internally the function automatically appends all scalar parameters (char, short, integer, long, float, or string) to the XPA command name before transmission. When a non-scalar parameter argument is present (e.g. an array of floats) it will be treated as data (see the XPA documentation) for the command, and all subsequent arguments will be ignored. The next example creates two test patterns directly from an in- memory S-Lang array: () = evalfile("./setup.sl"); variable arr = Short_Type[2500]; arr[[0:499]] = 100; arr[[500:999]] = 200; arr[[1000:1499]] = 400; arr[[1500:1999]] = 800; arr[[2000:2499]] = 1600; () = xpaset("ds9","frame new"); () = xpaset("ds9","cmap rainbow"); () = xpaset("ds9","array [dim=50,bitpix=16]",arr); () = xpaset("ds9","frame new"); () = xpaset("ds9","cmap green"); () = xpaset("ds9","array [dim=50,bitpix=-64]",log10(arr)); and should yield a result which looks like The first block of xpaset invocations sends 2500 short integers, as binary data, to the DS9 array command, along with instructions that it be visualized in the rainbow colormap and treated as a 50x50 image with 16 bits per pixel. The subsequent statements generate a new image by performing a base 10 logarithmic transform of the original image, indicating how simple and natural it can be to perform sophisticated image manipulations. Moreover, instead of the log10 function one could in principle substitute any numerical function callable from S-Lang scope, such as that which might be provided by the GSL module (which binds the GNU Scientific Library to S-Lang), or even your own homegrown C or FORTRAN codes. The entire script may be executed from the examples directory, under UNIX for instance, via your_unix_machine % slsh testpattern.sl See Also XPASet, xpaget Compatibility Note In the CIAO 3.0 bindings this function did not return a value. This was intended to reflect the most common usage, namely that the the number of servers contacted is usually ignored at the command line, avoiding superfluous () = xpaset(...); notation in scripts (which would be required in S-Lang 1.x to explicitly pop the return value off the stack), in favor of the "more natural" xpaset(...); The caller could determine the number of servers contacted during these calls by inspecting the slxpa_errno variable upon return. See section ``Backwards_Compatibility'' to restore this behavior. 4.2. xpaget Synopsis Retrieve information from XPA servers, by name Usage Array_Type xpaget(targets [, xpa_cmd = ""]) Description This function is used to retrieve information from the specified XPA server(s). Results are returned as an array of strings, one from each application server contacted. When no XPA command is given the application(s) contacted typically return a list of the XPA commands that the application supports. Example vmessage( xpaget("ds9") [0] ); This command dumps to the screen the entire list of XPA commands supported by DS9. As another example, if DS9 were invoked as your_unix_machine % ds9 examples/stars.fits & then the following vmessage( xpaget("ds9","file") [0] ); would print examples/stars.fits See Also XPAGet, XPAGetToFile, xpaset Compatibility Note In the CIAO 3.0 bindings this function would return a single string, rather than an array containing only 1 string, when only a single application server responded. See section ``Backwards_Compatibility'' to restore this behavior. 4.3. xpaaccess Synopsis Determine how many XPA servers offer the specified command(s) Usage Integer_Type xpaaccess(targets [, acc_mode = "gs"]) Description Returns 0, 1, or more to indicate how many XPA servers are running which offer commands (access points) matching the given target template. Example Bring down any running instances of DS9, then launch it 3 times via your_unix_machine % ds9 & and observe how your_unix_machine % slsh <. The package may be accessed from any S- Lang-enabled interpreter through the usual means, such as autoload(), or () = evalfile ("ds9"); or, if the application embedding the interpreter supports the require function, require ("ds9"); 6.1. Examples In this section we illustrate a number of ways in which the DS9 package may be employed, with an emphasis on the common case and ease of use. For context we show the functions as they might be invoked from the interactive prompts of ChIPS and ISIS (and in the latter case assume Isis_Append_Semicolon = 1). The examples may also be executed in batch within slsh scripts, or interactively from the prompt of the readline-enabled slsh, and so forth. Additional details are available in the function reference in the next chapter, or in the short usage message that most of the DS9 functions will emit when invoked with zero arguments. The reader may also wish to inspect the DS9-related scripts, within the tests subdirectory, for supplemental examples. 6.1.1. Getting Started If DS9 is not already running it may be launched from S-Lang via commands such as isis> ds9_launch Struct_Type isis> ds9_view( "image.fits" ) isis> ds9_view( [ 1 : 512 * 512] ) A second DS9 process will not be invoked here if one is already running, even if it was started outside of S-Lang. Moreover, DS9 will continue running after the S-Lang application from which it may have been launched has been terminated. In the first command parentheses have been intentionally omitted, since ds9_launch may be called with zero or more arguments. Likewise, the return value, a so-called handle structure, has been purposely left on the stack (and is subsequently cleared/echoed by ISIS). The second and third forms are likely to be preferred, since ds9_view not only launches DS9 but also causes it to immediately display the specified image. The first view command shown here simply sends the name of a file, from which DS9 will load the default image. The second is more interesting: it creates an 1D inlined array of 262144 elements, initialized to the values 1 through 512*512, and transmits the result directly to DS9, resulting in a visual which should resemble 6.1.2. Sending Images to DS9 Our next example reveals one of the most powerful features in the DS9 package, namely the ds9_put_array function. With it we can rewrite the preceding example as isis> ds9_launch isis> ds9_put_array( [ 1 : 512 * 512] ) The ds9_put_array method is faster and cleaner than alternatives, such as dumping data to temporary files and explicitly constructing command strings to pass to the system() function for launching external pro- cesses. Instead, by fostering direct communication between S-Lang and DS9 we avoid creating file litter which must be cleaned up later, as well as the need to load additional software to read and write FITS files. As a result the analysis process becomes more fluid and nim- ble, promoting iterative exploration. Similarly, if DS9 is already running then isis> ds9_put_file ( "image.fits" ) may be used to transmit the name of a file from which DS9 should visu- alize an image. 6.1.3. Retrieving Images from DS9 The put functions described above have natural inverses. For example, to retrieve the name of the file currently being displayed we might do chips> filename = ds9_get_file() chips> print(filename) image.fits or, more succinctly, chips> ds9_get_file image.fits Likewise, to retrieve the actual image being displayed one might do chips> image = ds9_get_array following which one can perform all of the expected S-Lang array manipulations, such as chips> image UChar_Type[900,900] which reveals the image dimensions, or chips> image2 = sqrt(image) which constructs a new image (of Double_Type) as the square root of the first, or chips> ds9_put_array(image2) which sends the result back to DS9. 6.2. Point and Click Interactivity See the function reference (in the next chapter) and test scripts. 6.3. Regions Here's the simplest case showing how regions may be retrieved directly to a S-Lang string array isis> s = ds9_get_regions() isis> print(s) yielding a result like # Region file format: DS9 version 4.0 # Filename: im1.fits global color=green font=\"helvetica 10 normal\" select=1 highlite=1 edit=1 move=1 delete=1 include=1 fixed=0 source image circle(268,257,20) The regions were returned in the "image" coordinate system because it is what was selected in the Region menu of the GUI. A different coor- dinate system may be selected using the named coord_sys qualifier isis> s = ds9_get_regions( ; coord_sys="physical") isis> print(s) which might change the last two lines of the above output to something like "physical" "circle(4280.5,4104.5,320)" Named qualifiers in S-Lang must appear after positional parameters, and are separated from them by the semicolon delimiter. Another way to achieve the same end would be to reset the region coordinate system prior to retrieving the regions themselves, such as isis> ds9_send("regions system physical") This setting persists until changed, allowing the region retrieval to again be as cleanly expressed isis> s = ds9_get_regions() as in the first example. Regions may also be saved to a file, e.g. isis> s = ds9_get_regions("/tmp/my.reg") isis> !cat /tmp/my.reg # Region file format: DS9 version 4.0 # Filename: im1.fits global color=green font="helvetica 10 normal" select=1 highlite=1 edit=1 move=1 delete=1 include=1 fixed=0 source physical circle(4280.5,4104.5,320) Observe that the regions were again returned in the "physical" coordi- nate system, because the GUI retains the previous selection. 6.4. World Coordinate Systems Our examples so far have treated images only as arrays of raw pixel values. We now highlight how coordinate systems may be attached to these images, thereby rendering them of greater practical significance to the astronomer. 6.4.0.1. Formatted WCS Strings Suppose we would like to attach a WCS transform described by the strings "CRPIX1 256" "CRVAL1 512" "CDELT1 2" "CTYPE1 X" "CRPIX2 256" "CRVAL2 512" "CDELT2 2" "CTYPE2 Y" (which simply multiplies the coordinate values of each axis by 2) to the DS9 image generated by chips> ds9_view( [ 1 : 512 * 512] ) If the transform was contained within the text file image.wcs, then the command chips> ds9_put_wcs_keys("image.wcs") would attach it to the current image. The same function would be used if the transform strings were instead contained within an 8-element array variable named wcs, only now it would be invoked as chips> ds9_put_wcs_keys(wcs) As the function reference indicates, the key/value pairs given here may also be formatted in accordance with the FITS 80 character card standard. 6.4.0.2. Raw/Unformatted WCS Values Now suppose that we wanted to apply the transform not from formatted strings, but rather from raw S-Lang values. For example, we might apply the transform to the first axis of the image with chips> ds9_put_wcs(256, 512, 2) or to both axes of the image via something like chips> crpix = [256, 256] chips> crval = [512, 512] chips> cdelt = [2, 2] chips> ds9_put_wcs(crpix, crval, cdelt) 6.4.1. WCS Structures Now suppose that the arrays given in the preceding example were morphed into fields of the same name within an S-Lang structure, such as isis> s = struct { crpix, crval, cdelt, ctype, cunit} isis> s.crpix = crpix isis> s.crval = crval isis> s.cdelt = cdelt The entire structure could then be applied at once via isis> ds9_put_wcs_struct(s) 6.4.2. Alternate WCS Both FITS and DS9 allow multiple coordinate systems to be associated with an image. The DS9 module facilitates this by supporting an optional alt_wcs_char parameter in each of its WCS functions. For example, isis> ds9_put_wcs_struct(s, 'a') would create a so-called WCSa coordinate system. Similarly, isis> crpix = [256, 256] isis> crval = [512, 512] isis> cdelt = [2, 2] isis> ds9_put_wcs(crpix, crval, cdelt, , , 'p') would create a WCSp coordinate system. As a convenience the DS9 mod- ule assigns the WCSp coordinate system as the physical coordinate sys- tem within the DS9 GUI, by transparently passing an additional FITS keyword WCSNAMEP with value 'PHYSICAL'. Note that in the above call ctype and cunit have been omitted (positional parameters 4 and 5 are empty); their values will default to NULL. More information on how DS9 treats alternate WCS is available within the DS9 FAQ, which can be accessed through Help->FAQ->Coordinates within the GUI. 6.4.3. Erasing WCS A transform may be removed simply by replacing it with an empty transform, such as chips> ds9_put_wcs_keys("") 6.5. WCS Editor GUI If you have SLgtk installed then you'll also be able to modify image WCS values from within the WCS editor guilet, launched via ds9_wcs_edit The next figure shows the GUI being used to double image coordinate values along the X axis, and halve them along the Y axis. 6.6. Shutting Down A DS9 process may be terminated either interactively from the GUI or programmatically via isis> ds9_quit() 6.7. Optional Arguments As discussed earlier in ``Omitted_Arguments'', order matters when specifying optional arguments. For example, consider ds9_clear(), which accepts 2 optional arguments: a handle cannot be specified when this function is invoked unless the frame argument is also specified. Fortunately, the API has been coded to accept NULL as a default value in such cases. This exploits the fact that omitted arguments delimited by commas default to the value NULL in S-Lang, allowing such functions to be conveniently invoked, for example, as ds9_clear( , handle); 6.8. Return Values Note that some routines in the DS9 package do not return a value which can be inspected for an error condition. There are two reasons for this. One is that the package is intended primarily for interactive use, so when a function fails such will be immediately evident to the user. Second, functions can only return error codes when SAOds9 itself indicates that an error condition exists, but unfortunately this information is not returned to the caller in all cases. While XPA supports sending to and receiving from multiple servers in a single call, the functions described here return results from at most 1 instance of SAOds9. 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 Table of Contents 1. Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Brief History . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 6 2.3. Using the XPA Module . . . . . . . . . . . . . . . . . . . . 6 2.3.1. Building . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3.2. Running . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. A Word About Examples . . . . . . . . . . . . . . . . . . . . 7 2.5. Interactive Image Analysis with SAOds9 . . . . . . . . . . . 8 3. Module Overview . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Omitted Arguments . . . . . . . . . . . . . . . . . . . . . . 9 3.3. Error Checking . . . . . . . . . . . . . . . . . . . . . . . 9 3.4. Contacting Multiple Servers . . . . . . . . . . . . . . . . . 10 3.5. Unimplemented Functions . . . . . . . . . . . . . . . . . . . 10 3.5.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.5.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. High Level XPA Interface . . . . . . . . . . . . . . . . . . . 11 4.1. xpaset . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. xpaget . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.3. xpaaccess . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Low Level XPA Interface . . . . . . . . . . . . . . . . . . . . 15 5.1. XPA_Type . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.2. XPAOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.3. XPAClose . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.4. XPAGet . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.5. XPAGetB . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.6. XPAGetToFile . . . . . . . . . . . . . . . . . . . . . . . . 17 5.7. XPASet . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 6. Using DS9 from S-Lang . . . . . . . . . . . . . . . . . . . . . 20 6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 20 6.1.1. Getting Started . . . . . . . . . . . . . . . . . . . . . . 20 6.1.2. Sending Images to DS9 . . . . . . . . . . . . . . . . . . . 21 6.1.3. Retrieving Images from DS9 . . . . . . . . . . . . . . . . 21 6.2. Point and Click Interactivity . . . . . . . . . . . . . . . . 22 6.3. Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 6.4. World Coordinate Systems . . . . . . . . . . . . . . . . . . 24 6.4.0.1. Formatted WCS Strings . . . . . . . . . . . . . . . . . . 24 6.4.0.2. Raw/Unformatted WCS Values . . . . . . . . . . . . . . . 25 6.4.1. WCS Structures . . . . . . . . . . . . . . . . . . . . . . 25 6.4.2. Alternate WCS . . . . . . . . . . . . . . . . . . . . . . . 25 6.4.3. Erasing WCS . . . . . . . . . . . . . . . . . . . . . . . . 26 6.5. WCS Editor GUI . . . . . . . . . . . . . . . . . . . . . . . 26 6.6. Shutting Down . . . . . . . . . . . . . . . . . . . . . . . . 26 6.7. Optional Arguments . . . . . . . . . . . . . . . . . . . . . 27 6.8. Return Values . . . . . . . . . . . . . . . . . . . . . . . . 27 7. DS9 Function Reference . . . . . . . . . . . . . . . . . . . . 28 7.1. ds9_launch . . . . . . . . . . . . . . . . . . . . . . . . . 28 7.2. ds9_connect . . . . . . . . . . . . . . . . . . . . . . . . . 28 7.3. ds9_quit . . . . . . . . . . . . . . . . . . . . . . . . . . 28 7.4. ds9_clear . . . . . . . . . . . . . . . . . . . . . . . . . . 29 7.5. ds9_center . . . . . . . . . . . . . . . . . . . . . . . . . 29 7.6. ds9_get_cmap . . . . . . . . . . . . . . . . . . . . . . . . 30 7.7. ds9_set_cmap . . . . . . . . . . . . . . . . . . . . . . . . 30 7.8. ds9_get_coords . . . . . . . . . . . . . . . . . . . . . . . 30 7.9. ds9_get_crosshair . . . . . . . . . . . . . . . . . . . . . . 31 7.10. ds9_put_crosshair . . . . . . . . . . . . . . . . . . . . . 31 7.11. ds9_get_version . . . . . . . . . . . . . . . . . . . . . . 31 7.12. ds9_get_array . . . . . . . . . . . . . . . . . . . . . . . 32 7.13. ds9_put_array . . . . . . . . . . . . . . . . . . . . . . . 32 7.14. ds9_get_file . . . . . . . . . . . . . . . . . . . . . . . . 33 7.15. ds9_put_file . . . . . . . . . . . . . . . . . . . . . . . . 33 7.16. ds9_view . . . . . . . . . . . . . . . . . . . . . . . . . . 34 7.17. ds9_get_regions . . . . . . . . . . . . . . . . . . . . . . 34 7.18. ds9_put_regions . . . . . . . . . . . . . . . . . . . . . . 35 7.19. ds9_get_scale . . . . . . . . . . . . . . . . . . . . . . . 35 7.20. ds9_set_scale . . . . . . . . . . . . . . . . . . . . . . . 35 7.21. ds9_put_wcs . . . . . . . . . . . . . . . . . . . . . . . . 36 7.22. ds9_put_wcs_keys . . . . . . . . . . . . . . . . . . . . . . 36 7.23. ds9_put_wcs_struct . . . . . . . . . . . . . . . . . . . . . 37 7.24. ds9_pan . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.25. ds9_get_zoom . . . . . . . . . . . . . . . . . . . . . . . . 37 7.26. ds9_set_zoom . . . . . . . . . . . . . . . . . . . . . . . . 38 7.27. ds9_send . . . . . . . . . . . . . . . . . . . . . . . . . . 38 7.28. ds9_recv . . . . . . . . . . . . . . . . . . . . . . . . . . 39 7.29. ds9_wcs_edit . . . . . . . . . . . . . . . . . . . . . . . . 39 7.30. ds9_new . . . . . . . . . . . . . . . . . . . . . . . . . . 39