/ 
Image-DS9-v1.0.1
River stage zero No dependents
/ Image::DS9::Manual::Interface

NAME

Image::DS9::Manual::Interface - Image::DS9 Interface

VERSION

version v1.0.1

DOCUMENTATION

The document describes the general concepts of how the interface with DS9 works.

Arguments

Commands sent to DS9 are sent as strings. Many of the option strings are available as Perl constants. See Image::DS9::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 methods, in particular fits, may return a scalar reference when 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. See each method's documentation (in Image::DS9::Manual::Connect, and Image::DS9::Manual::API) for details.

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

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

returns a reference to an array, while

$size = $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 keys are the names of the servers, and the values are 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::Dump;

dd scalar $dsp-cmap;

yields

"grey"

while

dd $dsp->cmap;

yields

(
  "DS9:ds9 7f000001:43117",
  { buf => "grey", name => "DS9:ds9 7f000001:43117" },
)

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::Dump;
dd $dsp->bin( 'about' );

yields.

(
  "DS9:ds9 7f000001:43117",
  { buf => [0, 0], name => "DS9:ds9 7f000001:43117" },
)

Sending data doesn't result in a return value; if there's an error an exception is thrown.

Error Returns

In case of error, an exception is thrown via croak(). The "res" in Image::DS9::Manual::Connect 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.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-image-ds9@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Image-DS9

Source

Source is available at

https://gitlab.com/djerius/image-ds9

and may be cloned from

https://gitlab.com/djerius/image-ds9.git

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

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