#
# stub class definition file for docstring parsing
#
[docs]class regionmanager:
"""
Create and manipulate regions of interest
**Overview of Regionmanager functionality**
- Create simple pixel-coordinate based regions with functions
Also related is function setcoordinates
- Convert pixel regions to world regions with
- There are some general utility functions, generally only of interest if you are writing scripts. These are
- There are some functions relating to interactive creation of regions with the . These are generally only of interest if you are writing scripts, and are
- There are some functions relating to communications. These are generally only of interest if you are writing scripts and are
When working with an image, one is generally interested in some part of that image on which astrophysical analysis is performed. This (or more generically and simply, the ‘region’) might be the whole image, or some subset of it.
Regions come in a few varieties. There are simple regular shapes (box, ellipsoid), simple irregular shapes (polygon), as well as compound regions made by combining other regions (simple or compound). For example unions or intersections of regions. In addition, the simple regions can be pixel-coordinate based or world-coordinate based. However, a compound regions must always comprise world-coordinate based regions.
It is the task of the () to manage your regions; it creates, lists and manipulates them. Apart from a , the only other way to create a is with the viewier (type viewer within the casapy environment). This allows you to interactively make, with the cursor and an image display, a box or polygonal region. The region so made may be collected by the (in fact the complete process can be initiated from the ).
The has a command line interface, but there are plans to have it interact directly with the CASA viewer. in the future. Currently the only way to interact is to save the regions created with the viewer to a file or as a region in the image , and use the function fromfiletorecord or fromtabletorecord, repsectively, to bring the regions in the CLI.
It is probably fair to say that for the simplest regions, such as a pixel box, there is little to choose between making a region with the GUI or the command line interface. However, for the world regions, the GUI is significantly better; it hides the details of handling the coordinate information.
**Simple Pixel and World regions**
Pixel regions are specified purely in terms of pixel coordinates. Pixel coordinates are considered to run from 1 at the bottom left corner (blc) of an image to the image shape at the top-right corner (trc).
For example, a pixel region might be box that runs from a bottom blc of [20,20] to a trc of [64,90] in a 2D image. Such a pixel region is NOT very portable though. If you are interested in a region about an astronomical source, pixel coordinates are only useful for a particular image. In some other image, the source may well have different pixel coordinates. However, pixel regions are easy to make and use, and they are valuable.
So far, we have been talking about absolute pixel coordinates. However, pixel regions can also be specified in relative coordinates. This is controlled through the argument absrel which may take on one of the values ’abs’ (absolute coordinates) ’relref’ (relative to the reference pixel of the image) or ’relcen’ (relative to the center of the image). You can use the summary function of the image module to see the reference pixel. The sense of the offset is :math:`rel = abs - ref`.
You may also define pixel regions in terms of fractional coordinates that are in the range [0,1] (blc to trc) - look for argument frac which can be T or F.
"""
[docs] def regionmanager(self):
"""
Construct a regionmanager
This is the only \regionmanager\ constructor. It should generally be
unnecessary for you to make one as there is little state in a
\regionmanager\ (you can set a Coordinate System with
setcoordinates); the
default \regionmanager\ {\stf rg} should be all you need.
"""
pass
[docs] def absreltype(self, absrelvalue=0):
"""
Convert region type value to a string
This function is not intended for general user use.
Regions may be specified with coordinates which are absolute or
relative. This function converts the integer code defining the
absolute/relative type of the coordinates (which is stored in the
region) into a string (maybe for printing purposes).
The different types are
Integer String Description
1 abs Absolute coordinate
2 relref Relative reference pixel
3 relcen Relative to center of image
4 reldir Relative to some direction
.. rubric:: Parameters
- ``absrelvalue (int=0)`` - Region type value
"""
pass
[docs] def box(self, blc=[0], trc=[-1], inc=[1], absrel='relref', frac=False, comment=''):
"""
Create a pixel box region
This function creates a multi-dimensional pixel box region. The box is
specified by a bottom-left corner, and top-right corner and an increment
(or stride). Pixel coordinates are considered to run from 1 at the
bottom left corner of the image to the image shape at the top-right
corner of the image.
You can specify whether the coordinates are given as pixel coordinates
({\stfaf frac=F}) or fractions of the image shape ({\stfaf frac=T}).
Absolute fractions are in the range [0,1].
You can also specify whether the coordinates are given as absolute
coordinates ({\stfaf absrel='abs'}) or relative to the reference pixel
({\stfaf absrel='relref'}) or relative to the center of the image
({\stfaf absrel='relcen'}).
.. rubric:: Parameters
- ``blc (doubleArray=[0])`` - blc of the box
- ``trc (doubleArray=[-1])`` - trc of the box
- ``inc (doubleArray=[1])`` - increment
- ``absrel (string='relref')`` - Absolute or relative coordinates
- ``frac (bool=False)`` - Pixel or fractional coordinates
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def frombcs(self, csys='', shape=[0], box='', chans='', stokes='', stokescontrol='a', region=''):
"""
Create a world coordinate region based on box-chan-stokes input
This function creates a multi-dimensional world coordinate region based
on box, chans, stokes inputs familiar from image analysis tasks. It is
being introduced as a temporary means of refactoring some python level
task code into C++. However, if users find it to have value, its existence
can be permanent.
.. rubric:: Parameters
- ``csys (record='')`` - Coordinate system record. Must be specified.
- ``shape (intArray=[0])`` - shape of the image. Necessary for boundedness checks. Must have the same number of dimensions as the associated coordinate system. Default = []
- ``box (string='')`` - Direction plane box specification as normally provided in image analysis tasks. "" means use entire directional plane as specified in shape. Default "".
- ``chans (string='')`` - Channel spec as normally provided to image analysis tasks. "" means use all channels, Default "".
- ``stokes (string='')`` - Stokes spec as normally provided to image analysis tasks. "" means use stokescontrol for setting stokes. Default "".
- ``stokescontrol (string='a')`` - Polarization set to use if stokes parameter is not specified. Choices are "a" (use all stokes) and "f" (use first stokes). Default "a".
- ``region (variant='')`` - Named region in the form imagename:regionname or region dictionary. Used only if box, chans, stokes not specified. Default "".
"""
pass
[docs] def complement(self, region='', comment=''):
"""
Create the complement of a world region
This function (short-hand name {\tt comp}) creates the complement of
a world region(s).
The region parameter can be a single region record defining a simple
or complex region or it can contain several region records in a
Python dictionary. If multiple regions are given then the union of
this set of regions is taken first, and the complement is found from
the union.
NOTE: ia.statistics() is UNABLE to handle complement regions in CASA yet.
.. rubric:: Parameters
- ``region (variant='')`` - The world region
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def concatenation(self, box='', regions='', comment=''):
"""
Concatenate world regions along a new axis
This function (short-hand name {\tt concat}) creates a region which is
the concatenation along a new axis of the given world regions.
This function is similar to the
extension function. The
{\stfaf concatenation} function allows you to take many world regions,
and concatenate them along one axis (rather than take one region and
extend it along many axes which is what function {\stff extension}
does).
For example, you may have generated a different polygonal region for
each spectral pixel of a spectral-line cube and you wish to concatenate them
together to form the overall region for use in a deconvolution
application.
The axis to concatenate along is specified as a 1-dimensional world box.
The shape of the 1D box must contain as many pixels (although you
don't have to specify it in pixels) as there are regions
to concatenate.
Because this function is most likely to be used in a script, the
interface takes a record containing {\stff region} records, Python
dictionaries, as there might be a lot of them.
.. rubric:: Parameters
- ``box (variant='')`` - The axis to concatenate along
- ``regions (variant='')`` - World regions
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def deletefromtable(self, tablename='', regionname=''):
"""
Delete regions from a Table
This function deletes a region stored in an casa Table.
For the {\stfaf tablename} argument,
you have to give the name of an existing
CASA table on disk (any kind of table).
You specify the name of the region with the {\stfaf regionname}
arguments. If you set {\stfaf regionname=''} then nothing is done. The names of all the regions stored in a Table can be found
with the function
namesintable.
.. rubric:: Parameters
- ``tablename (string='')`` - The table
- ``regionname (string='')`` - Name(s) of the region(s) to delete
"""
pass
[docs] def difference(self, region1='', region2='', comment=''):
"""
Create the difference of two world regions
This function (short-hand name {\stff diff}) creates
a region which is the difference of two world regions. The order
of the regions is important.
The difference consists of all pixels masked-on in the first
region and not masked-on in the second region.
.. rubric:: Parameters
- ``region1 (record='')`` - The first world region
- ``region2 (record='')`` - The second world region
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def done(self):
"""
Destroy this regionmanager
This function destroys the contents of the {\stf regionmanager} \tool\
(including its GUI). The \tool\ still exists as a Glish variable, but
it is no longer a Regionmanager ! You are unlikely to need this
function.
"""
pass
[docs] def selectedchannels(self, specification='', shape=[0]):
"""
Get an array of zero-based selected channel numbers from an input string specificaiton.
This method returns all the selected zero-based channel numbers from the specified string within the image.
.. rubric:: Parameters
- ``specification (string='')`` - Valid channel specification. See help par.chans for examples.
- ``shape (intArray=[0])`` - Image shape. Used to determine if the specificaiton lies outside the image.
"""
pass
[docs] def fromtextfile(self, filename='', shape=[0], csys=''):
"""
Create a region dictionary from a region text file.
This function reads a text file containing region descriptions and
converts it to a python dictionary.
.. rubric:: Parameters
- ``filename (string='')`` - List of text file containing the region description
- ``shape (intArray=[0])`` - Image shape.
- ``csys (record='')`` - Coordinate system record. Defaults to coordinate system used in rg.setcoordinates()
"""
pass
[docs] def fromtext(self, text='', shape=[1], csys=''):
"""
Create a region dictionary from a region text string.
This function reads a region region text descriptions and
converts it to a python region dictionary.
.. rubric:: Parameters
- ``text (string='')`` - region description
- ``shape (intArray=[1])`` - Image shape, only used if first region is a difference.
- ``csys (record='')`` - Coordinate system record. Defaults to coordinate system used in rg.setcoordinates()
"""
pass
[docs] def fromfiletorecord(self, filename='', verbose=True, regionname=''):
"""
Create a region record(s) from a file(s).
This function reads files containing ImageRegion objects and turns them
into Region Records.
The intended use for this method is to read the file saved by the casa
viewer and turn the files contents into regions that are usabla by the
image analysis tool.
.. rubric:: Parameters
- ``filename (string='')`` - List of files containing the Image Regions
- ``verbose (bool=True)`` - Report successful saves
- ``regionname (string='')`` - Name(s) of the region(s) when saved in the table
"""
pass
[docs] def tofile(self, filename='', region=''):
"""
Create a region record file that can be read by from filetorecord.
This function is to store a region created by the regionmanager in a disk file for future use
.. rubric:: Parameters
- ``filename (string='')`` - List of files containing the Image Regions
- ``region (record='')`` - region record/dict to store in the file
"""
pass
[docs] def fromrecordtotable(self, tablename='', regionname='', regionrec='', asmask=False, verbose=True):
"""
Save regions stored in a record into a Table
This function saves regions into an casa Table
For the {\stfaf tablename} argument the user should be the name of an existing
\aipspp\ Table on disk (any kind of table).
If the parameter {\tt asmask} is {\tt True} then the table has to be an image table.
A mask makes sense with an image only.
You can specify the name the region will have ({\stfaf
regionname}) when it is saved in the Table. If you don't specify this,
a digit based name is assigned to it or if specify a name that already
exists a new one will be generated which is close but different. The
function returns you the name the region is assigned
.. rubric:: Parameters
- ``tablename (string='')`` - The table
- ``regionname (variant='')`` - Name(s) of the region(s) when saved in the table
- ``regionrec (record='')`` - Region(s) to save
- ``asmask (bool=False)`` - save region as a mask rather than region
- ``verbose (bool=True)`` - Report successful saves
"""
pass
[docs] def fromtabletorecord(self, tablename='', regionname='', verbose=True):
"""
Restore regions from a Table to a record
This function restores a region from an \aipspp\ Table
to the global name space.
For the {\stfaf tablename} argument, you can specify an
image \tool, a table \tool,
or a string. If you give a string, it should be the name of an existing
\aipspp\ table on disk (any kind of table).
If {\stfaf numberfields} is F, then the field names of the
record are the same as they are in the Table. Otherwise,
the regions are put into numbered fields (the field
names could be anything).
You can use the function
namesintable to find out the
names of the regions in the Table.
.. rubric:: Parameters
- ``tablename (string='')`` - The table
- ``regionname (variant='')`` - Name of the region(s) to restore
- ``verbose (bool=True)`` - Report successful restores
"""
pass
[docs] def intersection(self, regions='', comment=''):
"""
Create the intersection of some world regions
This function (short-hand name {\stff int}) creates a region which is
the intersection of the given world regions. The input regions can
themselves be compound regions (such as the union or intersection etc).
The input regions must be provided as a Python dictionary of regions
(see examples).
.. rubric:: Parameters
- ``regions (variant='')`` - World regions and comment
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def ispixelregion(self, region=''):
"""
Is this region a pixel region ?
NOT IMPLEMENTED IN CASA
This function returns T if the region is a pixel region.
For any other \glish\ variable it returns F.
.. rubric:: Parameters
- ``region (record='')`` - The region
"""
pass
[docs] def isworldregion(self, region=''):
"""
Is this region a world region ?
NOT IMPLEMENTED IN CASA
This function returns T if the region is a world region.
For any other \glish\ variable it returns F.
.. rubric:: Parameters
- ``region (record='')`` - The region
"""
pass
[docs] def namesintable(self, tablename=''):
"""
Find the names of the regions stored in a Table
This function returns the names of regions stored in an CASA Table.
For the {\stfaf tablename} argument, you can specify a string; it should be the name of an existing
\aipspp\ table on disk (any kind of table).
.. rubric:: Parameters
- ``tablename (string='')`` - The table
"""
pass
[docs] def setcoordinates(self, csys=''):
"""
Set new default Coordinate System
This function allows you to (re)set the default Coordinate System
used by the functions that make world regions. If you don't specifiy a
Coordinate System when you make the world region, the default Coordinate
System, if there is one, is used. The Coordinate System is
stored in a {\stf coordinates} \tool\ and is created with
the coordsys \toolfunction.
Normally, the world region creating functions like
wbox and
wpolygon will issue a message
each time the private Coordinate System is used. However, if you set
{\stfaf verbose=F} then this will not occur.
.. rubric:: Parameters
- ``csys (record='')`` - Default Coordinate System for use in world regions
"""
pass
[docs] def makeunion(self, regions='', comment=''):
"""
Create a union of world regions
This function takes a minimum of two world regions and creates a region which
is the union of the given regions. The input regions can themselves be
compound regions (such as the union or intersection etc). The input
regions must be a Pythion dictionary of at leat two regions
(see examples).
.. rubric:: Parameters
- ``regions (variant='')`` - World regions and comment
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def wbox(self, blc='', trc='', pixelaxes=[-1], csys='', absrel='abs', comment=''):
"""
Create a world box region
This function creates a multi-dimensional world box region; the
corners of the box are specified in world coordinates. However, the box
is not a true world volume in that its sides do not follow world
contours. Its sides are parallel to the pixel axes. If you are in a
region of high world coordinate contour non-linearity (e.g. near a
pole), you are probably better off using a world polygon.
The box is specified by a bottom-left corner, and a top-right corner.
The coordinates are given as quantities, and you can give a vector of
quantities (e.g. {\cf blc = qa.quantity("1rad 20deg")} or a
quantity of a vector (e.g.{\cf blc = qa.quantity([10,30], 'rad')}).
You can specify whether the coordinates are given as absolute coordinates
({\stfaf absrel='abs'}) or relative to the reference pixel ({\stfaf
absrel='relref'}) or relative to the center of the image ({\stfaf
absrel='relcen'}). You can specify this for each axis (the same for the
blc and trc). If you specify less values than the number of
values in {\stfaf blc} or {\stfaf trc} then the last value you
did specify is used as the default for all higher numbered axes
(e.g. {\stfaf absrel='relref'} means {\stfaf absrel="relref relref"}
for two axes).
You specify which pixel axes in the image the {\stfaf blc} and {\stfaf
trc} vector refer to with the {\stfaf pixelaxes} argument. If you
don't, it defaults to [0,1,2,...]. This specification is an important
part of world regions.
You must also specify the Coordinate System with the {\stfaf csys}
argument. The Coordinate System is encapsulated in a {\stfaf coordinates}
tool and can be recovered from an image with the
coordsys tool function. You can
also set a default Coordinate System in the \regionmanager\ with the
setcoordinates
function.
In the \regionmanager\ we have defined units `pix' and `frac'; these are
then known to the quanta system. This means
that you can effectively define a pixel box (except for the stride
capability) as a world box with most of the advantages of world regions
(can be used for compound regions). However, it is still not very
portable to other images because the coordinates are pixel based,
not world based.
Note that the need to deal with the {\stfaf pixelaxes} and {\stfaf csys}
is hidden from you when using the gui
interface of the \regionmanager.
.. rubric:: Parameters
- ``blc (variant='')`` - blc of the box ; a vector of quantities
- ``trc (variant='')`` - trc of the box; a vector of quantities
- ``pixelaxes (intArray=[-1])`` - Which pixel axes
- ``csys (record='')`` - Coordinate System
- ``absrel (string='abs')`` - Absolute or relative coordinates
Vector of
strings from 'abs', 'relref' and 'relcen'
- ``comment (string='')`` - A comment stored with the region
"""
pass
[docs] def wpolygon(self, x='', y='', pixelaxes=[-1], csys='', absrel='abs', comment=''):
"""
Create a world polygon region with quantities
This function (short-hand name {\stff wpoly}) creates a 2D world
polygon region. The polygon is specified by an {\stfaf x} and a {\stfaf y}
vector. These must be quantities of a vector (the
world box function
allows both
quantities of vectors and vectors of quantities). This means that the
units are common to all elements of each vector. Thus, {\cf
qa.quantity([1,2,3],'rad')} (a quantity of a vector) is different from
{\cf qa.quantity("1rad 2rad 3rad")} (a vector of quantities) although
the information that they specify is the same.
You specify which pixel axes in the image the {\stfaf x} and {\stfaf
y} vectors pertain to with the {\stfaf pixelaxes} argument. If you don't,
it defaults to [0,1]. This specification is an important part of
world regions.
You can specify whether the {\stfaf x} and {\stfaf y} vector coordinates are
given as absolute coordinates ({\stfaf absrel='abs'}) or relative to the
reference pixel ({\stfaf absrel='relref'}) or relative to the center of the
image ({\stfaf absrel='relcen'}). This argument applies to both the axes
of the polygon.
You must also specify the Coordinate System with the {\stfaf csys}
argument. The Coordinate System is encapsulated in a {\stfaf coordinates}
\tool\ and can be recovered from an image with the
coordsys function. You can
also set a default Coordinate System in the Regionmanager with the
setcoordinates
function.
In the \regionmanager\ we have defined units `pix' and `frac'; these are
then known to the quanta system. This means
that you can effectively define a pixel box (except for the stride
capability) as a world box with most of the advantages of world regions
(can be used for compound regions). However, it is still not very
portable to other images because the coordinates are pixel based,
not world based.
Note that the need to deal with the {\stfaf pixelaxes} and {\stfaf csys}
is hidden from you when using the gui
interface of the \regionmanager.
.. rubric:: Parameters
- ``x (variant='')`` - The x vector; a vector of quantities
- ``y (variant='')`` - The y vector; vector of quantities
- ``pixelaxes (intArray=[-1])`` - which pixel axes; vector of integers ..default -1
means [0,1]
- ``csys (record='')`` - Coordinate System
- ``absrel (string='abs')`` - Absolute or relative coordinates; possibilities are 'abs', 'rel', 'relcen'
- ``comment (string='')`` - A comment stored with the region
"""
pass