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

NAME

CXC::Astro::Regions::CFITSIO - CFITSIO Compatible Regions

VERSION

version 0.03

SYNOPSIS

use CXC::Astro::Regions::CFITSIO '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 CFITSIO 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::CFITSIO::Circle) and an alternate constructor (e.g. circle()) is provided for the class. Classes have a render method which returns a CFITSIO compatible string representation of the region.

There is no support for algebraic manipulation of regions.

Units

CXC::Astro::Regions::CFITSIO verifies that input values for positions and lengths are acceptable to CFITSIO. However, it does not verify that the *mix* of units is appropriate. For example, if positions are specified in pixels, lengths must also be specified in pixels, but this module does not verify that sort of consistency.

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]p                  # pixel
[num]"                  # arc sec
[num]'                  # arc min
[num]d                  # degrees
[num]                   # degrees

CONSTRUCTORS

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

$region = CXC::Astro::Regions::CFITSIO::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::CFITSIO::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::CFITSIO::Box.

circle

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

diamond

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

ellipse

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

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

elliptannulus

$region = elliptannulus( center => [ <x>, <y> ],
                         inner   => [ <length>, <length> ],
                         outer   => [ <length>, <length> ],
                         angles  => [ <inner>, <outer> ]  );

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

line

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

point

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

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

polygon

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

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

rectangle

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

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

sector

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

This returns an instance of CXC::Astro::Regions::CFITSIO::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 CFITSIO 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