NAME

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

SYNOPSIS

use Image::DS9;

$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".

While one could communicate with DS9 solely via the IPC::XPA class, this class provides a cleaner, less error prone interface, as it checks the passed commands and arguments for syntax and data type. It also cleans up returned data from DS9.

To use this class, first construct a Image::DS9 object, and then apply its 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

The methods in this class closely follow the XPA access points. The documentation here tries to cover the mechanics of calling the methods. For more information on what the methods do, or how the arguments affect things, please consult the DS9 documentation.

Arguments

Commands sent to DS9 are sent as strings. Many of the option strings are available as Perl constants. See "Constants" for more details.

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, queries may return more than one value. Because one usually communicates with a single DS9 instance, if a query is made in scalar mode, the result is returned as a scalar, i.e.:

$cmap = $dsp->cmap();

In this mode, if more than one server responds, you'll get the results for a randomly chosen server. Some commands, in particular some of the options to the fits, will return a scalar reference in called in scalar mode, as the returned data may be large, and it makes no sense to have multiple copies of the data floating about. These commands are documented below.

If a return value is multi-valued, a query in scalar context yields a reference to an array, not a scalar. For instance:

$res = $dsp->bin( 'about' );
($x, $y ) = @$res;

returns a reference to an array, while

$res = $dsp->bin( 'buffersize' );

returns a scalar. Don't attempt to do

($x, $y ) = $dsp->bin( 'about' ); # ERROR DON"T DO THIS

as it will return a full blown hash as documented next.

When queries are made in list mode, the 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 message element is present if there was an error. The buf element contains the results of a query.

For example,

use Data::Dumper;
%cmaps = $dsp->cmap;
print Dumper \%cmaps;

yields

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

Ordinarily, the buf element will be unaltered (except for the removal of trailing newlines) from what DS9 outputs. For multi-valued return results, buf is set to an array containing the values:

use Data::Dumper;
%res = $dsp->bin( 'about' );
print Dumper \%res;

$VAR1 = {
         'DS9:ds9 838e2ab4:32832' =>
          {
            'name' => 'DS9:ds9 838e2ab4:32832',
            'buf' => [ 20, 30 ],
          }
        };

Sending data doesn't result in a return value.

Error Returns

In case of error, an exception is thrown via croak(). The res() method will return a hash, keyed off of the servers' names. 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.

Administrative 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.

WaitTimeOut

The default number of seconds that the wait() method should try to contact DS9 servers.

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.

ResErrCroak

If true, queries sent to ds9 which returns fewer values than expected will result in croak()s. This may be a problem if ds9 is queried for inappropriate information. For example, it will return an empty result if a image (i.e. not a binned event list) is displayed in the current frame and the names of the binned columns are queried (which of course makes no sense). See the ResErrWarn and ResErrIgnore attributes for ways of handling this.

If too many results are returned, this module will always croak. ResErrCroak is the default mode.

ResErrWarn

If true, queries sent to ds9 which returns fewer values than expected will result in carp()s and will be compensated for by filling in the missing values with empty strings.

ResErrIgnore

Queries sent to ds9 which returns fewer values than expected are silently compensated for by filling in the missing values with empty strings.

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.

res

%res = $dsp->res;

In case of error, the returned results from the failing XPA call are available via this method. It returns a hash, keyed off of the server signature(s). See the IPC::XPA documentation for more information on what the hashes contain.

wait

$dsp->wait();
$dsp->wait($timeout);

Try to contact the DS9 servers, and wait until at least min_servers have replied. It will attempt this for WaitTimeOut seconds if no timeout is supplied, else the given time. It returns true upon success. This routine is useful for doing things like:

$dsp = new Image::DS9;
unless ( $dsp->nservers )
{
  system("ds9 &" );
  $dsp->wait() or die( "unable to connect to DS9\n" );
}

Control Methods

Most methods exactly parallel the DS9 XPA commands. In general each element in a command is passed as a separate argument to the method. For example, to change the binning factor:

$dsp->bin( factor => 0.2 );

Some commands have more arguments:

$dsp->bin( smooth => function => 'boxcar' );
$dsp->bin( smooth => radius => 33 );
$dsp->bin( about => ( 3, 3 ) );
$dsp->bin( cols => ( 'rt_x', 'rt_y' ) );

Note the use of the => operator to force preceding barewords to be treated as strings, and the frivolous use of extra parenthesis for aesthetics. Some arguments are concatenated to avoid confusion; see the documentation for the individual methods.

Some commands can query DS9 for state information as well as set it. For example,

$function = $dsp->bin( smooth => function );

Image::DS9 differentiates between the setting and requesting of values by the presence or absence of the argument containing the information.

Some commands take a hash as their last argument, which contains attributes which are passed on to DS9.

True Boolean values may be one of the following: 1, yes, true. False Boolean values may be one of the following: 0, no, false. Boolean values returned by a command are always translated into either 0 or 1.

The documentation for the commands lists the options supported and any deviations from the general approach described above. Refer to the DS9 XPA documentation to determine which commands permit queries and the allowed data types for the arguments. Image::DS9 checks that all data passed to DS9 is of the appropriate type.

The documentation which follows uses doubled square brackets to indicate an optional argument.

array

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

This is a interface to the array access point, which displays images. $image may be a PDL object, a scalar, or a scalar reference. If it 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 (similar to the FITS standard).

bin

The following options are supported:

about, buffersize, cols, factor, filter, function, average, sum, to fit or tofit

blink

To query the whether blink is on:

$is_blink_on = $dsp->blink( 'state' );

To turn blink on:

$dsp->blink;

cd

$dsp->cd( $dir );
$dir = $dsp->cd;

cmap

The following options are supported:

file, invert, value.

To query the current colormap,

$cmap = $dsp->cmap;

contour

The following options are supported:

copy, paste, save.

To turn contouring on or off:

$dsp->contour( $boolean_value );

To query the state of contouring:

$is_contour_on = $dsp->contour;

crosshair

$dsp->crosshair( [[x, y, <coordinate system>, [[<sky frame>]],
                                             [[<sky format>]] ]] );
$coords = $dsp->crosshair( [[<coordinate system>,
                      [[<sky frame>]], [[<sky format>]] ]] );
($x, $y ) = @$coords

To query the position, pass no coordinates to the method. The return value is multi-valued.

cursor

$dsp->cursor( $x, $y );

Set the cursor position to the given position.

dss

The following options are supported:

name coord server survey size

When queried, some of the options may return more than one value. In those cases, a query yields a reference to an array, not a scalar. For instance:

$res = $dsp->dss( 'coord' );
($x, $y ) = @$res;

returns a reference to an array, while

$res = $dsp->dss( 'server' );

returns a scalar. Don't attempt to do

($x, $y ) = $dsp->dss( 'coord' ); # ERROR DON"T DO THIS

As it will return a full blown hash as documented in "Return Values".

exit

No options, just the grand finale.

file

return the current file name loaded for the current frame:

$dsp->file( $file );

Save the frame as a file:

$dsp->file( 'save', [[<save options>>,]] $file );

Display the specified $file.

$dsp->file( [[<type>]], $file, [[\%attrs]] );

The attributes are the possible options for the array type (see the DS9 docs), as well as the following options:

new boolean: create a new frame.
bin columns.: columns should be an array ref containing the names of the columns upon which to bin the data
extname string: The name of the FITS extension HDU to display.
filter string: A DS9 filter specification

fits

Return the current frame (as a fits file) as a scalar ref

$scalar_ref = $dsp->fits( [[<type>]], [[<type options>]], [[\%attr]] );

Load an image from a scalar:

$dsp->fits( [[<type>]], [[%attrs]] );

The available attributes are

new boolean: create a new frame.
bin columns.: columns should be an array ref containing the names of the columns upon which to bin the data
extname string: The name of the FITS extension HDU to display.
filter string: A DS9 filter specification

frame

The following options are supported:

center, clear, new, delete, reset, refresh, hide, show, move, first, next, prev, last, frameno, all, center,

To load a particular frame, specify the frame number as the argument:

$dsp->frame(3).

The all option returns an array of the frames:

$array_ref = $dsp->frame( 'all' );

grid

The load and save options are supported.

With a boolean argument, specify the state of the coordinate grid, else return it.

height

$dsp->height( $height );
$height = $dsp->height;

iconify

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

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

lower

$dsp->lower();

Lowers the DS9 window in the stacking order

minmax

Supports the options

mode, interval.

Their values may be queried by passing no arguments.

mode

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

Set (or query) the first mouse button mode state.

nameserver

The following options are supported:

name, server, skyformat.

They may be queried by specifying no argument.

orient

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

Set (or query) the orientation of the current frame.

page

To reflect the XPA command sequence, the first argument must always be setup, e.g.

$dsp->page( setup => orientation => 'portrait' );

The supported options are:

orientation, pagescale, pagesize.

They may be queried by specifying no argument.

pan

To set the pan position:

$dsp->pan( [[<type>,]] $x, $y,
      [[ <coordinate system> [[,<sky frame>]] [[,<sky format>]] ]] );

where type is one of abs or to to specify an absolute position, or rel or unspecified for a relative pan.

To get the pan position:

$pan = $dsp->pan(
        [[ <coordinate system> [[,<sky frame>]] [[,<sky format>]] ]] );

pixeltable

$dsp->pixeltable($bool);
$state = $dsp->pixeltable;

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

print

The supported options are:

destination, command, filename, palette, level, interpolate, resolution,

To print, specify no options. To query an option, don't specify a value for it.

quit

Just do it.

raise

$dsp->raise()

Raise the DS9 window in the windkow stacking order.

regions

The supported options are:

movefront, moveback, selectall, selectnone, deleteall, load, save, format, system, sky, skyformat, strip, shape, color, width, source, background, include, exclude, selected.

To query the state of options which are subject to query, don't pass a value for the option (just the option name).

To send DS9 a region, pass regions a scalar or scalar ref:

$dsp->regions( $region );

To query the current list of regions and receive the results using the current attribute formats,

$regions = $dsp->regions();

Alternatively, one can request a different attribute format directly in the query by passing a hash reference with the following available keys: -format, -system, -sky, -skyformat, -strip.

$regions = $dsp->regions( \%attr );

rotate

$rotate = $dsp->rotate;	  # query current angle
$dsp->rotate( abs => $angle );  # absolute
$dsp->rotate( to => $angle );   # absolute
$dsp->rotate( rel => $angle );  # relative
$dsp->rotate( $angle );         # relative

saveas

The following options are supported:

jpeg, tiff, png, ppm.

scale

The following options are supported:

datasec, limits, mode, scope.

To query the state of the options, don't pass a value for the option. A query of limits returns an array ref, as it is multi-valued.

single

To query the whether single mode is set:

$is_single_on = $dsp->single( 'state' );

To turn single mode on:

$dsp->single;

source

Just use the source, Luke.

tcl

Nothing special here, move along.

tile

The following options are supported:

mode, grid, grid mode, grid layout, grid gap, row, column.

To specify grid modes, layout and gap, do this:

$dsp->tile( grid => mode => 'automatic' );

To turn tiling on or off,

$dsp->tile( $boolean ).

To query tiling state, either

$state = $dsp->tile;
$state = $dsp->tile( 'state' ); # same as blink and single

To query those options that support query, don't pass a value for the option. Note that a query of the grid layout will return an arrayref.

update

The now option is passed via a hash:

$dsp->update( { now => 1 } );

version

Queries and returns DS9's version.

view

Supported options are:

layout, info, panner, magnifier, buttons, colorbar, graph, filename, object, minmax, lowhigh, frame, image, physical, wcs, wcsa..wcsz. red, green, blue

vo

All aboard!

wcs

The options supported are:

wcs, wcsa..wcsz, system, sky, skyformat, align, reset replace, append, replace, append.

The replace and append options may take either the file option (followed by a filename)

$dsp->wcs( replace => file => $filename );

or a scalar, scalar ref, hash ref, or array ref containing a WCS specification:

$dsp->wcs( replace => \%wcs ).
$dsp->wcs( replace => \@wcs ).
$dsp->wcs( replace => $wcs ).
$dsp->wcs( replace => \$wcs ).

If it is scalar, the scalar should hold the WCS record. If it is a hash reference, a WCS record is constructed from the keys and values. If it is an array reference, the record is constructed by appending a newline to each array value and concatenating the resultant strings.

Query the appropriate options by not passing a value for the option.

web

Set (or query) the web address in DS9's built in browser.

width

$dsp->width( $width );
$width = $dsp->width;

zoom

$zoom = $dsp->zoom;          # query
$dsp->zoom( to => $zoom );   # absolute
$dsp->zoom( abs => $zoom );  # absolute
$dsp->zoom( rel => $zoom );  # relative
$dsp->zoom( $zoom );         # relative
$dsp->zoom(0);               # zoom to fit
$dsp->zoom('tofit');         # zoom to fit
$dsp->zoom('to', 'fit');     # zoom to fit

Set

$dsp->Set( $cmd, $buf )

Send an arbitrary XPA Set command to the DS9 server. If there was an error sending the command to the server, or fewer than expected servers responded, it'll croak(). Messages from the server will be made available via the res() method. See IPC::XPA for more information on the format of those messages.

Get

%results = $dsp->Get( $cmd )

Send an arbitrary XPA Get command to the DS9 Server. If there was an error sending the command to the server, or fewer than expected servers responded, it'll croak(). Messages from the server will be made available via the res() method.

Upon success, it'll return the results of the command. If called in scalar mode, it'll return just one result (if there is more than one server, it returns results from an arbitrary server). In array mode, It'll return a hash, with the hash keys being the names of the server. The hash values are themselves references to hashes containing the results, with a key of buf.

Constants

Many of the options which must be passed as strings to the command methods are available as Perl constants. This provides a way for Perl to verify the strings at compile time, rather than run time. For example,

$ds9->regions( 'resett' );

will be caught at run time, while

$ds9->regions( _resett );

will be caught at compile time. There are some places where Perl will get confused as to whether you are using a constant or a string. For example, assume there's a constant named _mode:

$ds9->tile( _mode => 'grid' );

Because of the => operator, _mode will be turned into the string _mode, rather than being identified as the constant _mode, which presumably will resolve into the string mode. To avoid this, use the , operator:

$ds9->tile( _mode, 'grid' );

There are two ways to get to the constants: Image::DS9::OldConstants and Image::DS9::Constants. The former is the older deprecated way, which groups the constants by command and uses a group specific prefix to make the constants unique. This is confusing, as one has to remember all of the prefixes.

The new arrangement uses a single prefix for all constants. The prefix defaults to _, but may be specified by the user. See Image::DS9::Constants for more info.

Obsolete Methods, Changed Interfaces

These methods were available in previous versions of DS9, but are no longer supported.

display: This hid tile yes|no, blink, and single. Call them directly.
tile_mode: This was really tile, but without the tile yes|no option. Call tile instead.

The constants previous available from Image::DS9 are now available via Image::DS9::OldConstants.

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/.

LICENSE

This software is released under the GNU General Public License. You may find a copy at

http://www.fsf.org/copyleft/gpl.html

AUTHOR

Diab Jerius ( djerius@cfa.harvard.edu )

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

Arguments

Boolean values

Return Values

Error Returns

Administrative Methods

Control Methods

Constants

Obsolete Methods, Changed Interfaces

REQUIREMENTS

LICENSE

AUTHOR

SEE ALSO

Module Install Instructions