/ 
Image-DS9-0.09
River stage zero No dependents
/ Image::DS9

NAME

Image::DS9 - interface to the DS9 image display and analysis program

SYNOPSIS

use Image::DS9;
use Image::DS9 qw( :<group> );  # import constants from group <group>
use Image::DS9 qw( :all );	  # import all constants

$dsp = new Image::DS9;
$dsp = new Image::DS9( \%attrs );

DESCRIPTION

This class provides access to the DS9 image display and analysis program through its XPA access points.

DS9 is a rather flexible and feature-rich image display program. Rather than extol its virtues, please consult the website in "REQUIREMENTS".

This class is rather bare at present, providing a low level interface to the XPA access points. Eventually these will be hidden by an elegant framework that will make life wonderful.

To use this class, first construct a Image::DS9 object, and then apply it's methods. It is possible to both address more than one DS9 with a single object, as well as having multiple Image::DS9 objects communicate with their own DS9 invocations. Eventually there will be documentation spelling out how to do this.

METHODS

Constants

Commands sent to DS9 are sent as strings. To prevent typos (and other unwanted sideeffects) Image::DS9 makes many of the commands and subcommands available as Perl constants -- mistype these and the compiler will complain, not DS9.

Predefined constants may be imported when the Image::DS9 package is loaded, by specifying one or more of the following tags: frame, tile, filetype, display, scale, mode_ops, orient_ops, or all.

For example:

use Image::DS9 qw( :frame :tile :filetype :display );

The frame group imports FR_active, FR_all, FR_center, FR_clear, FR_delete, FR_first, FR_hide, FR_last, FR_new, FR_next, FR_prev, FR_refresh, FR_reset, FR_show.

The tile group imports T_Grid, T_Column, T_Row.

The filetype group imports FT_MosaicImage, FT_MosaicImages, FT_Mosaic, FT_Array.

The display group imports D_blink, D_tile, D_single.

The scale group imports S_linear, S_log, S_squared, S_sqrt, S_minmax, S_zscale, S_user, S_local, S_global, S_limits, S_mode, S_scope.

The mode_ops group imports MB_pointer, MB_crosshair, MB_colorbar, MB_pan, MB_zoom, MB_rotate, MB_examine.

The orient-ops group imports OR_X, OR_Y, OR_XY.

The all group imports all of the above groups, as well as ON, OFF, YES NO.

Boolean values

Some methods take boolean values; these may be the strings on, off, yes, no, or the integers 1 or 0.

Return values

Because a single Image::DS9 object may communicate with multiple instances of DS9, most return values are hashes, rather than scalars. The hash has as keys the names of the servers, with the values being references to hashes with the keys name, buf and message. The buf key will be present if there are no errors for that server, the message if there were.

For example,

use Data::Dumper;
%colormaps = $dsp->colormap;
print Dumper \@colormaps;

yields

$VAR1 = {
         'DS9:ds9 838e2ab4:32832' =>
          {
            'name' => 'DS9:ds9 838e2ab4:32832',
            'buf' => 'Grey'
          }
        };

If you know that there is only one server out there (for example, if the object was created with max_servers set to 1), you can call a method in a scalar environment, and it will directly return the value:

$colormap = $dsp->colormap;

If there is more than one server, you'll get the results for a randomly chosen server.

Sending data usually doesn't result in a return:

$dsp->colormap( 'Grey' );

Error Returns

In case of error, an exception is thrown via croak(). The res() method will return a hash, keyed off of the servers name. For each server which had an error, the hash value will be a reference to a hash containing the keys name and message; the latter will contain error information. For those commands which return data, and for those servers which did not have an error, the buf key will be available.

Methods

new
$dsp = new Image::DS9;
$dsp = new Image::DS9( \%attrs );

Construct a new object. It returns a handle to the object. It throws an exception (catch via eval) upon error.

The optional hash attrs may contain one of the following keys:

Server

An alternate server to which to communicate. It defaults to ds9.

max_servers

The maximum number of servers to which to communicate. It defaults to the number of DS9 servers running at the time the constructor is called.

min_servers

The minimum number of servers which should respond to commands. If a response is not received from at least this many servers, an exception will be thrown. It defaults to 1.

For example,

$dsp = new Image::DS9( { max_servers => 3 } );
nservers
$nservers = $dsp->nservers;

This returns the number of servers which the object is communicating with.

array
$dsp->array( $image );
$dsp->array( $image, \%attrs );

This is a simple interface to the array access point, which displays images. If $image is a PDL object, all required information is extracted from it, and it is passed to DS9. Otherwise, it should be binary data suitable for DS9, and the attrs hash should be used to pass dimensional and size data to DS9. attrs may contain the following elements:

xdim

The X coordinate array extent.

ydim

The Y coordinate array extent.

bitpix

The number of bits per pixel. Negative values indicate a floating point number.

colormap
$dsp->colormap( $colormap );
@colormaps = $dsp->colormap;

If an argument is specified, it should be the name of a colormap (case is not important). If no argument is specified, the current colormaps for all of the DS9 instances is returned, as a list containing references to hashes with the keys name and buf. The latter will contain the colormap name.

display
$dsp->display( $state );
%displays = $dsp->display;

If an argument is specified, this call will change how the data are displayed. $state may be one of the constants D_blink, D_tile, or D_single (or, equivalently, 'blink', 'tile', 'single' ). The constants are available by importing the display tag.

If no argument is specified, the current display states of the DS9 servers are returned (see "Return values" for the format). The state is will be returned as a string equivalent to the constants D_blink, D_tile or D_single. For instance:

my $ds9 = new DS9( { max_servers => 1 } );

print "We're blinking!\n" if D_blink eq $ds9->display;
file
$dsp->file( $file );
$dsp->file( $file, $type );
%files = $dsp->file;

Display the specified $file. The file type is optional, and may be one of the following constants: FT_MosaicImage, FT_MosaicImages, FT_Mosaic, FT_Array (or one of the strings 'mosaicimage', 'mosaicimages', 'mosaic', or 'array' ). (Import the filetype tag to get the constants).

If called without a value, it will return the current file name loaded for the current frame.

frame
@frames = $dsp->frame;

# perform a frame operation with no arguments
$dsp->frame( $frame_op );

# show the specified frame
$dsp->frame( show => $frame );

# delete the current frame
$dsp->frame( FR_delete );
  
# delete the specified frame
$dsp->frame( delete => $frame );

# delete all of the frames
$dsp->frame( delete => FR_all );

Command DS9 to do frame operations. Frame operations are nominally strings. As DS9 will interpret any string which isn't a frame operation as the name of frame to switch to (or create, if necessary), Image::DS9 provides constants for the standard operations to prevent typos. See "Constants". Otherwise, use the strings active, all, center, clear, delete, hide, new, refresh, reset, show, first, next, prev, last.

To load a particular frame, specify the frame name as the operator.

To show a frame which has been hidden, use the second form with the show operator.

For example,

$dsp->frame( FR_new );		# use the constant
$dsp->frame( 'new' );		# use the string literal
$dsp->frame( '3' );		# load frame 3
$dsp->frame( FR_hide );		# hide the current frame
$dsp->frame( show => 3 );	# show frame 3
$dsp->frame( FR_delete );	# delete the current frame

If frame() is called with no arguments, it returns a list of the current frames for all instances of DS9.

iconify
$iconify_state = $dsp->iconify;
%iconify_state = $dsp->iconify;
$dsp->iconify($bool);

With a boolean argument, specify the iconification state, else return it.

mode
$mode = $dsp->mode;
$dsp->mode( $state );

Change (or query) the first mouse button mode state. Predefined states are available via the mode_ops group; see "Constants".

orient
$state = $dsp->orient;
$dsp->orient( $state );

Change (or query) the orientation of the current frame. Predefined states are available via the orient_ops group; see "Constants".

rotate
$rotate = $dsp->rotate;
$dsp->rotate( abs => $rotate );
$dsp->rotate( rel => $rotate );
$dsp->rotate( $rotate );

Change or query the rotation angle (in degrees) for the current frame. A rotatation may be absolute or relative; this is explicitly specified in the second and third forms of the method invocation. If not specified (as in the last form) it is relative.

If no argument is specified, it returns the rotatation angle for the current frame.

res
$res = $dsp->res;

In case of error, the returned results from the failing XPA call are available via this method. It returns a reference to an array of hashes, one per instance of DS9 addressed by the object. See the IPC::XPA documentation for more information on what the hashes contain.

scale
$dsp->scale( $algorithm );
$dsp->scale( S_limits => [ $min, $max ] );
$dsp->scale( S_mode => $mode );
$dsp->scale( S_scope => $scope );

%scale = $dsp->scale;
%limits = $dsp->scale( S_limits );
%mode = $dsp->scale( S_mode );
%scope = $dsp->scale( S_scope );

This specifies how the data will be scaled. $algorithm may be one of the constants S_linear, S_log, S_squared, S_sqrt (or, equivalently, 'linear', 'log', 'squared', 'sqrt').

$mode may be one of S_minmax, S_zscale, S_user (or, equivalently, 'minmax', 'zscale', 'user').

$scope may be on of S_local, S_global (or, equivalently, 'local', 'global' ).

The constants are available if the scale tag is imported (see "Constants"). The second set of invocations shown above illustrates how to determine the current values of the scale parameters.

tile_mode
$dsp->tile_mode( $mode );

The tiling mode may be specified by setting $mode to T_Grid, T_Column, or T_Row. These constants are available if the tile_op tags are imported. Otherwise, use 'grid', c<'column'>, or 'row'. If called without a value, it will return the current tiling mode.

zoom
$zoom = $dsp->zoom;
$dsp->zoom( abs => $zoom );
$dsp->zoom( rel => $zoom );
$dsp->zoom( $zoom );

This changes the zoom value for the current frame. $zoom is a positive numerical value. A zoom value may be absolute or relative. This is explicitly specified in the second and third forms of the method invocation. If not specified (as in the last form) it is absolute. To zoom such that the image fits with in the frame, specify a zoom value of 0.

If no argument is specified, it returns the zoom value for the current frame.

REQUIREMENTS

Image::DS9 requires IPC::XPA to be installed. At present, both DS9 and xpans (part of the XPA distribution) must be running prior to any attempts to access DS9. DS9 will automatically start xpans if it is in the user's path.

DS9 is available at http://hea-www.harvard.edu/RD/ds9/.

XPA is available at http://hea-www.harvard.edu/RD/xpa/.

AUTHOR

Diab Jerius ( djerius@cfa.harvard.edu )

SEE ALSO

perl(1), IPC::XPA.