NAME

CXC::Astro::Regions::DS9 - DS9 Compatible Regions

VERSION

version 0.02

SYNOPSIS

use CXC::Astro::Regions::DS9;

$circle = circle( center => [ 4096, 4096 ], radius => 200, fill => !!1 );
say $circle->render;
# outputs "circle 4096 4096 200 # fill=1"

$composite =
  composite( center => [4096, 4096],
             regions => [
                circle( center => [ 0, 0], radius => 200 ),
                circle( center => [ 10, 10], radius => 200 ),
             ]
   );

DESCRIPTION

This module provides an objected oriented interface to the region specifications supported by the ds9 https://ds9.si.edu astronomical image display and analysis program.

Each type of region is mapped onto a class (e.g. CXC::Astro::Region::DS9::Center) and an alternate constructor (e.g. circle()) is provided for the class. Classes have a render method which returns a DS9 compatible string representation of the region.

Parameters vs Properties

DS9 regions have both parameters (which generally specify location, size, number, and orientation attributes) and properties (which generally specify display and region management attributes). This interface hides those difference from the user. Just forget the difference.

Composite Regions

A composite region is a container for other regions. The regions are specified relative to the location of the composite region's location. Unlike the other regions, a composite region's render method returns an array of strings, rather than a single string.

INTERNALS

METHODS

All regions objects have the following methods:

render

$string   = $non_composite_region->render;
\@strings = $composite_region->render;

The render method returns a string (if a non-composite region) or an arrayref of strings (if a composite region) with DS9 compatible region specifications.

REGIONS

Conventions

In the descriptions below, optional parameters are preceded with a ?, e.g.

circle( ..., ?fill => <boolean>);

indicates that the fill parameter is optional.

<x> and <y> are X an Y positions.

Units

Positions

[num]                   # context-dependent (see below)
[num]d                  # degrees
[num]r                  # radians
[num]p                  # physical pixels
[num]i                  # image pixels
[num]:[num]:[num]       # hms for 'odd' position arguments
[num]:[num]:[num]       # dms for 'even' position arguments
[num]h[num]m[num]s      # explicit hms
[num]d[num]m[num]s      # explicit dms

A bare position (i.e. without units, as in [num]) takes on a unit corresponding to the current coordinate system. See the DS9 Regions reference manual (available from within DS9) for more information.

Lengths

[num]                   # context-dependent (see below)
[num]"                  # arc sec
[num]'                  # arc min
[num]d                  # degrees
[num]r                  # radians
[num]p                  # physical pixels
[num]i                  # image pixels

A bare length (i.e., without units, as in [num]) takes on a unit corresponding to the current coordinate system. See the DS9 Regions reference manual (available from within DS9) for more information.

Coordinate Systems

image                   # pixel coords of current file
linear                  # linear wcs as defined in file
fk4, b1950              # sky coordinate systems
fk5, j2000
galactic
ecliptic
icrs
physical                # pixel coords of original file using LTM/LTV
amplifier               # mosaic coords of original file using ATM/ATV
detector                # mosaic coords of original file using DTM/DTV
wcs,wcsa-wcsz           # specify which WCS system to be used for
                        # linear and sky coordinate systems

If no coordinate system is specified, physical is assumed. See the DS9 Regions reference manual (available from within DS9) for more information.

Constructors

The following DS9 regions are supported via both the traditional and alternate constructors, e.g.

$region = CXC::Astro::Regions::DS9::Circle->new( ... );
$region = circle( ... );

annulus

$region = annulus( center => [ <x>, <y> ],
                   inner  => <length>, outer => <length>,
                   n      => <nannuli> );

This returns an instance of CXC::Astro::Regions::DS9::Annulus_n, which extends CXC::Astro::Regions::DS9::Annulus.

$region = annulus( center => [ <x>, <y> ],
                   annuli => [ <r1>, <r2>, ... <rn> ] );

This returns an instance of CXC::Astro::Regions::DS9::Annulus_annuli, which extends CXC::Astro::Regions::DS9::Annulus.

box

$region = box( center => [ <x>, <y> ],
               width  => <length>, height => <length>,
               ?angle => <angle>,
               ?fill  => <boolean> );

This returns an instance of CXC::Astro::Regions::DS9::Box_plain, which extends CXC::Astro::Regions::DS9::Box.

$region = box( center => [ <x>, <y> ],
               inner  => [ <width>, <height> ],
               outer  => [ <width>, <height> ],
               n      => <nannuli>,
               ?angle => <angle> );

This returns an instance of CXC::Astro::Regions::DS9::Box_n, which extends CXC::Astro::Regions::DS9::Box.

$region = box( center => [ <x>, <y> ],
               annuli => [ [ <width>, <height> ], ... ],
               ?angle => <angle> );

This returns an instance of CXC::Astro::Regions::DS9::Box_annuli, which extends CXC::Astro::Regions::DS9::Box.

bpanda

$region = epanda( center  => [ <x>, <y> ],
                  angles  => [ <start angle>, <end angle> ],
                  nangles => <integer>,
                  inner   => [ <length>, <length> ],
                  outer   => [ <length>, <length> ],
                  nannuli => <integer>,
                  ?angle  => <float, degrees> );

circle

$region = circle( center => [ <x>, <y> ],
                  radius => <length>,
                  ?fill  => <boolean> );

compass

$region = compass( center  => [ <x>, <y> ],
                   length  => <length>,
                   ?coords => <coordinate system>,
                   ?north  => <string>,
                   ?east   => <string>,
                   ?arrows => [ <boolean>, <boolean> ] );

where

coords: See "Coordinate Systems"
north and east: labels for the north and east points of the compass
arrows: indicates if the north and east vectors are decorated with arrowheads.

composite

$region = composite( center  => [ <x>, <y> ],
                     regions => [ $region, ... ],
                     ?angle  => <angle> );

Create a composite region for the specified regions (which are instances of other regions, but not of another composite region). The regions are specified relative to the composite region's reference frame.

Unlike other the regions, a composite region object's render method returns an arrayref of string specifications, not a single string.

ellipse

$region = ellipse( center => [ <x>, <y> ],
                   rx     => <length>, ry => <length>,
                   ?angle => <angle>,
                   ?fill  => <boolean> );

This returns an instance of CXC::Astro::Regions::DS9::Ellipse_plain, which extends CXC::Astro::Regions::DS9::Ellipse.

$region = ellipse( center => [ <x>, <y> ],
                   inner  => [ <rx>, <ry> ],
                   outer  => [ <rx>, <ry> ],
                   n      => <nannuli>,
                   ?angle => <angle> );

This returns an instance of CXC::Astro::Regions::DS9::Ellipse_n, which extends CXC::Astro::Regions::DS9::Ellipse.

$region = ellipse( center => [ <x>, <y> ],
                   annuli => [ [ <rx>, <ry> ], ... ],
                   ?angle => <angle> );

This returns an instance of CXC::Astro::Regions::DS9::Ellipse_annuli, which extends CXC::Astro::Regions::DS9::Ellipse.

line

$region = line( v1      => [ <x>, <y> ],
                v2      => [ <x>, <y> ],
                ?arrows => [ <boolean>, <boolean> ] );

where arrows determines if the start and end of the line are decorated with arrowheads.

epanda

$region = epanda( center  => [ <x>, <y> ],
                  angles  => [ <start angle>, <end angle> ],
                  nangles => <integer>,
                  inner   => [ <length>, <length> ],
                  outer   => [ <length>, <length> ],
                  nannuli => <integer>,
                  ?angle  => <float, degrees> );

panda

$region = panda( center  => [ <x>, <y> ],
                  angles  => [ <start angle>, <end angle> ],
                  nangles => <integer>,
                  inner   => <length>,
                  outer   => <length>,
                  nannuli => <integer> );

point

$region = point( position => [<x>, <y>],
                 ?symbol  => <symbol>,
                 ?size    => <integer> );

Draw a symbol at the specified region.

The available symbols are

circle box diamond cross x arrow boxcircle

The default is boxcircle

polygon

$region = line( vertices => [ [<x>, <y>], ... ],
                ?fill    => <boolean> );

projection

$region = projection( v1    => [ <x>, <y> ],
                      v2    => [ <x>, <y> ],
                      width => <length> );

ruler

$region = ruler( v1      => [ <x>, <y> ],
                 v2      => [ <x>, <y> ],
                 ?coords => <coords> );

where coords is one of

pixels degrees arcmin arcsec

text

$region = text( position => [ <x>, <y> ],
                text => <string> );

vector

$region = vector( base   => [ <x>, <y> ],
                  length => <length>,
                  angle  => <float, degrees>
                  ?arrow => <boolean> );

where arrow indicates that the head of the vector should be decorated with an arrowhead.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-cxc-astro-regions@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=CXC-Astro-Regions

Source

Source is available at

https://gitlab.com/djerius/cxc-astro-regions

and may be cloned from

https://gitlab.com/djerius/cxc-astro-regions.git

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007

To install CXC::Astro::Regions, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CXC::Astro::Regions

CPAN shell

perl -MCPAN -e shell
install CXC::Astro::Regions

For more information on module installation, please visit the detailed CPAN module installation guide.

	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)