NAME

Image::DS9::Manual::Connect - Controlling the communications with DS9

VERSION

version v1.0.1

DESCRIPTION

Image::DS9 uses the IPC::XPA module to communicate (via the XPA library) with one or more instances of DS9. It provides an API which mimics the commands which DS9 provides.

The methods documented here provide control over those communications, either by initializing it (e.g. "new") or by allowing the user to bypass the Image::DS9 layer and send commands directly to DS9 via IPC::XPA. This is useful if Image::DS9 doesn't directly support some functionality.

For reference documentation for the methods which map onto DS9's commands, see Image::DS9::Manual::API.

For more information on calling conventions, see Image::DS9::Manual::Interface.

CONSTRUCTORS

new

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

Construct and return an object representing the connection to DS9. It throws an exception on error.

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

Server

The title of the ds9 process with which to communicate. It defaults to ds9.

WaitTimeOut

DEPRECATED; use "QueryTimeOut" and "StartTimeOut"

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

QueryTimeOut

The number of seconds that the wait() method should try to contact existing DS9 servers. It defaults to 2 seconds.

StartTimeOut

The number of seconds that the wait() method should wait for a connection after starting a DS9 server. It defaults to 2 seconds.

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.

auto_start

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 "QueryTimeOut" before creating a new one.

ds9

Path to the ds9 executable. It defaults to ds9, which will find it in the user's executable path, but may be set to any other valid path.

terminate_on_destroy

A flag to determine if and when to terminate the ds9 process when the Image::DS9 object is destroyed. The flag is set with constants available via:

  use Image::DS9::Constants::V1 -terminate_ds9;

The bitwise or of the following values:

TERMINATE_DS9_STARTED

terminate if this process started the ds9 process.

TERMINATE_DS9_ATTACHED

terminate if this process attached to an existing ds9 process.

or the following values

TERMINATE_DS9_YES

Essentially TERMINATE_DS9_STARTED | TERMINATE_DS9_ATTACHED.

TERMINATE_DS9_NO

Don't terminate on object destruction. Don't or this with anything, it won't do

kill_on_destroy

DEPRECATED; use "terminate_on_destroy". A true value is translated into TERMINATE_DS9_YES, and a false value is translated into TERMINATE_DS9_NO

daemonize

Caveat: *nix Only

If true the ds9 process will be detached from the current process. This is useful in situations where the current process is launched under a process manager which will only exit when all of its sub-processes have completed. The "terminate_on_destroy" option can be used with "daemonize".

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,

        $ds9 = new Image::DS9( { max_servers => 3 } );

METHODS

nservers

  $nservers = $ds9->nservers;

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

res

  %res = $ds9->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

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

Try to contact the DS9 servers, and wait until at least min_servers have replied. It will attempt this for QueryTimeOut seconds if no timeout is supplied, else the given time. It returns true upon success.

set_attr

  $ds9->set_attr( $attr_name => $attr_value, ... );

Set the attribute to the given value. The following attributes may be set:

  StartTimeOut
  QueryTimeOut
  WaitTimeInterval
  min_servers
  kill_on_destroy
  auto_start
  verbose

Changing other attributes will result in undefined behavior.

get_attr

  $attr_value = $ds9->get_attr( $attr_name );

Retrieve the value of an attribute. Valid attribute names are those which can be passed to "new".

Set

  $ds9->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 = $ds9->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. See Image::DS9::Manual::API for more information.

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.

• Image::DS9

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

cpanm Image::DS9

perl -MCPAN -e shell
install Image::DS9