NAME

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

VERSION

version 0.03

SYNOPSIS

use CXC::Astro::Regions::DS9 'circle', 'mkregion';

$circle = circle( center => [ 4096, 4096 ],
                  radius => 200, fill => !!1 );

# equivalent using factory subroutine
$circle = mkregion( 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::Circle) 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.

Units

CXC::Astro::Regions::DS9 verifies that input values for positions and lengths are acceptable to DS9.

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.

Common Properties

In addition to region specific properties documented with each region, all share the following:

text => String
textangle => Number
color => String
dashlist => ArrayRef [PositiveInt]
linewidth => PositiveInt
font => FontString
select => Boolean
highlite => Boolean
dash => Boolean
fixed => Boolean
edit => Boolean
move => Boolean
rotate => Boolean
delete => Boolean
include => Boolean

defaults to true
srctype => Enum [ 'source', 'background' ]
tags => ArrayRef[Str]

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( ... );

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.

annulus

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

This returns an instance of CXC::Astro::Regions::DS9::Annulus_n, which extends CXC::Astro::Regions::DS9::Annulus. It represents a series of n nested annuli

$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> ], [ <width>, <height> ], ... ],
               ?angle => <angle> );

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

bpanda

$region = bpanda( 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( base  => [ <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> ],
                   radii  => [ <xradius>, <yradius>],
                   ?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  => [ <xradius>, <yradius> ],
                   outer  => [ <xradius>, <yradius> ],
                   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 => [ [ <xradius>, <yradius> ], ... ],
                   ?angle => <angle> );

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

epanda

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

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.

panda

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

point

$region = point( center => [<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( center => [ <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.

mkregion

$region = mkregion( $shape, @pars );

A generic factory routine which calls the constructor for the named shape (e.g. circle, annulus, etc).

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.

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)