/ 
CXC-Astro-Regions-0.03
River stage zero No dependents
/ CXC::Astro::Regions::CIAO

NAME

CXC::Astro::Regions::CIAO - CIAO Compatible Regions

VERSION

version 0.03

SYNOPSIS

use CXC::Astro::Regions::CIAO 'circle', 'region';

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

# equivalent using factory subroutine
$circle = region( circle =>
                  center => [ 4096, 4096 ],
                  radius => 200 );

say $circle->render;
# outputs "circle(4096,4096,200)"

DESCRIPTION

This module provides an objected oriented interface to the region specifications supported by the CIAO https://cxc.harvard.edu/ciao X-ray astronomy data reduction software suite.

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

There is no support for algebraic manipulation of regions.

Units

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

Positions

Positions must have the following forms

[num]                   # physical
[num]d                  # degrees
[num]:[num]:[num]       # hms for RA, or dms for Declination

Lengths

Lengths must have the following forms

[num]                   # physical
[num]"                  # arc sec
[num]''                 # arc sec (double apostrophye)
[num]'                  # arc min
[num]d                  # degrees

CONSTRUCTORS

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

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

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

box( ..., ?angle => <angle>);

indicates that the angle parameter is optional.

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

annulus

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

This returns an instance of CXC::Astro::Regions::CIAO::Annulus. It represents a single annulus.

box

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

This returns an instance of CXC::Astro::Regions::CIAO::Box.

circle

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

ellipse

$region = ellipse( center => [ <x>, <y> ],
                   radii  => [ <xradius>, <yradius>],
                   ??angle => <angle> );

This returns an instance of CXC::Astro::Regions::CIAO::Ellipse.

field

$region = field();

This returns an instance of CXC::Astro::Regions::CIAO::Field.

pie

$region = pie( center => [ <x>, <y> ],
               radii => [ <inner>, <outer> ],
               angles => [ <min>, <max> ] );

This returns an instance of CXC::Astro::Regions::CIAO::Pie.

point

$region = point( center => [ <x>, <y> ] );

This returns an instance of CXC::Astro::Regions::CIAO::Point.

polygon

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

This returns an instance of CXC::Astro::Regions::CIAO::Polygon.

rectangle

$region = rectangle( xmin => <xmin>, ymin => <ymin>,
                     xmax => <xmax>, ymax => <ymax> );

This returns an instance of CXC::Astro::Regions::CIAO::Rectangle.

region

$region = region ( file => <file> );

This returns an instance of CXC::Astro::Regions::CIAO::Region.

rotbox

$region = rotbox( center => [ <x>, <y> ],
                  width  => <length>, height => <length>,
                  angle => <angle> );

This returns an instance of CXC::Astro::Regions::CIAO::Rotbox.

sector

$region = sector( center => [ <x>, <y> ],
                  angles => [ <min>, <max> ] );

This returns an instance of CXC::Astro::Regions::CIAO::Sector.

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   = $region->render;

The render method returns a string with a CIAO compatible region specification.

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