Image::DS9 - interface to the DS9 image display and analysis program
version 0.188
use Image::DS9; $dsp = new Image::DS9; $dsp = new Image::DS9( \%attrs );
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.
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.
Commands sent to DS9 are sent as strings. Many of the option strings are available as Perl constants. See "Constants" for more details.
Some methods take boolean values; these may be the strings on, off, yes, no, or the integers 1 or 0.
on
off
yes
no
1
0
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.
fits
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.
name
buf
message
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.
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.
$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:
The title of the ds9 process with which to communicate. It defaults to ds9.
ds9
The default number of seconds that the wait() method should try to contact DS9 servers. It defaults to 2 seconds.
2
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.
DS9
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.
Create a ds9 process with the title specified by the Server attribute if one does not exist. It polls for an existing process for the time period specified via WaitTimeOut before creating a new one.
Server
WaitTimeOut
Terminate the ds9 process when the Image::DS9 object is destroyed.
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.
ResErrWarn
ResErrIgnore
If too many results are returned, this module will always croak. ResErrCroak is the default mode.
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.
Queries sent to ds9 which returns fewer values than expected are silently compensated for by filling in the missing values with empty strings.
$dsp = new Image::DS9( { max_servers => 3 } );
$nservers = $dsp->nservers;
This returns the number of servers which the object is communicating with.
%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.
$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.
$dsp->set_attr( $attr_name => $attr_value, ... );
Set the attribute to the given value. The following attributes may be set:
WaitTimeOut WaitTimeInterval min_servers kill_on_destroy auto_start verbose
Changing other attributes will result in undefined behavior.
$attr_value = $dsp->get_attr( $attr_name );
Retrieve the value of an attribute. Valid attribute names are those which can be passed to "new".
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.
true
false
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.
$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:
$image
The X coordinate array extent.
The Y coordinate array extent.
The number of bits per pixel. Negative values indicate a floating point number (similar to the FITS standard).
The following options are supported:
about, buffersize, cols, factor, filter, function, average, sum, to fit or tofit
about
buffersize
cols
factor
filter
function
average
sum
to fit
tofit
To query the whether blink is on:
$is_blink_on = $dsp->blink( 'state' );
To turn blink on:
$dsp->blink;
$dsp->cd( $dir ); $dir = $dsp->cd;
file, invert, value.
file
invert
value
To query the current colormap,
$cmap = $dsp->cmap;
copy, paste, save.
copy
paste
save
To turn contouring on or off:
$dsp->contour( $boolean_value );
To query the state of contouring:
$is_contour_on = $dsp->contour;
$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.
$dsp->cursor( $x, $y );
Set the cursor position to the given position.
name coord server survey size
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;
$res = $dsp->dss( 'server' );
($x, $y ) = $dsp->dss( 'coord' ); # ERROR DON"T DO THIS
As it will return a full blown hash as documented in "Return Values".
No options, just the grand finale.
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.
$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
create a new frame.
bin
columns should be an array ref containing the names of the columns upon which to bin the data
extname
The name of the FITS extension HDU to display.
A DS9 filter specification
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
center, clear, new, delete, reset, refresh, hide, show, move, first, next, prev, last, frameno, all, center,
center
clear
delete
reset
refresh
hide
show
move
first
next
prev
last
frameno
all
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' );
The load and save options are supported.
load
With a boolean argument, specify the state of the coordinate grid, else return it.
$dsp->height( $height ); $height = $dsp->height;
$dsp->iconify($bool); $iconify_state = $dsp->iconify;
With a boolean argument, specify the iconification state, else return it.
$dsp->lower();
Lowers the DS9 window in the stacking order
Supports the options
mode, interval.
mode
interval
Their values may be queried by passing no arguments.
$mode = $dsp->mode; $dsp->mode( $state );
Set (or query) the first mouse button mode state.
name, server, skyformat.
skyformat
They may be queried by specifying no argument.
$state = $dsp->orient; $dsp->orient( $state );
Set (or query) the orientation of the current frame.
To reflect the XPA command sequence, the first argument must always be setup, e.g.
setup
$dsp->page( setup => orientation => 'portrait' );
The supported options are:
orientation, pagescale, pagesize.
orientation
pagescale
pagesize
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.
type
abs
to
rel
To get the pan position:
$pan = $dsp->pan( [[ <coordinate system> [[,<sky frame>]] [[,<sky format>]] ]] );
$dsp->pixeltable($bool); $state = $dsp->pixeltable;
With a boolean argument, specify the pixeltable state, else return it.
print only works if ds9 uses the local XPA transfer protocol. Set the XPA_METHOD environment variable to local prior to starting up ds9 and using this module.
local
destination, command, filename, palette, level, interpolate, resolution,
destination
command
filename
palette
level
interpolate
resolution
To print, specify no options. To query an option, don't specify a value for it.
Just do it.
$dsp->raise()
Raise the DS9 window in the windkow stacking order.
movefront, moveback, selectall, selectnone, deleteall, load, save, format, system, sky, skyformat, strip, shape, color, width, source, background, include, exclude, selected.
movefront
moveback
selectall
selectnone
deleteall
format
system
sky
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.
-format
-system
-sky
-skyformat
-strip
$regions = $dsp->regions( \%attr );
$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
jpeg, tiff, png, ppm.
jpeg
tiff
png
ppm
datasec, limits, mode, scope.
datasec
limits
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.
To query the whether single mode is set:
$is_single_on = $dsp->single( 'state' );
To turn single mode on:
$dsp->single;
Just use the source, Luke.
Nothing special here, move along.
mode, grid, grid mode, grid layout, grid gap, row, column.
grid
layout
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.
The now option is passed via a hash:
$dsp->update( { now => 1 } );
Queries and returns DS9's version.
Supported options are:
layout, info, panner, magnifier, buttons, colorbar, graph, filename, object, minmax, lowhigh, frame, image, physical, wcs, wcsa..wcsz. red, green, blue
info
panner
magnifier
buttons
colorbar
graph
object
minmax
lowhigh
frame
image
physical
wcs
wcsa
wcsz
red
green
blue
All aboard!
The options supported are:
wcs, wcsa..wcsz, system, sky, skyformat, align, reset replace, append, replace, append.
align
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.
Set (or query) the web address in DS9's built in browser.
$dsp->width( $width ); $width = $dsp->width;
$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
$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.
%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.
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:
_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.
_
These methods were available in previous versions of DS9, but are no longer supported.
This hid tile yes|no, blink, and single. Call them directly.
tile yes|no
blink
single
This was really tile, but without the tile yes|no option. Call tile instead.
tile
The constants previous available from Image::DS9 are now available via Image::DS9::OldConstants.
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/.
http://hea-www.harvard.edu/RD/ds9/
XPA is available at http://hea-www.harvard.edu/RD/xpa/.
http://hea-www.harvard.edu/RD/xpa/
This software is released under the GNU General Public License. You may find a copy at
http://www.fsf.org/copyleft/gpl.html
Diab Jerius ( djerius@cfa.harvard.edu )
You can make new bug reports, and view existing ones, through the web interface at https://rt.cpan.org/Public/Dist/Display.html?Name=Image-DS9.
Please see those modules/websites for more information related to this module.
Image::DS9
IPC::XPA
Diab Jerius <djerius@cpan.org>
This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007
To install Image::DS9, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Image::DS9
CPAN shell
perl -MCPAN -e shell install Image::DS9
For more information on module installation, please visit the detailed CPAN module installation guide.