The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
CXC-Astro-Regions-0.02
River stage zero No dependents
/ CXC::Astro::Regions::DS9

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

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) 2023 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007