regionmanager¶
-
class
regionmanager
[source]¶ 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 \(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.
Methods Summary
Convert region type value to a string
Create a pixel box region
Create the complement of a world region
Concatenate world regions along a new axis
Delete regions from a Table
Create the difference of two world regions
Destroy this regionmanager
Create a world coordinate region based on box-chan-stokes input
Create a region record(s) from a file(s).
Save regions stored in a record into a Table
Restore regions from a Table to a record
Create a region dictionary from a region text string.
Create a region dictionary from a region text file.
Create the intersection of some world regions
Is this region a pixel region ?
Is this region a world region ?
Create a union of world regions
Find the names of the regions stored in a Table
Construct a regionmanager
Get an array of zero-based selected channel numbers from an input string specificaiton.
Set new default Coordinate System
Create a region record file that can be read by from filetorecord.
Create a world box region
Create a world polygon region with quantities
-
absreltype
(absrelvalue=0)[source]¶ 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
Parameters
absrelvalue (int=0)
- Region type value
-
box
(blc=[0], trc=[- 1], inc=[1], absrel='relref', frac=False, comment='')[source]¶ 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’}).
Parameters
blc (doubleArray=[0])
- blc of the boxtrc (doubleArray=[-1])
- trc of the boxinc (doubleArray=[1])
- incrementabsrel (string='relref')
- Absolute or relative coordinatesfrac (bool=False)
- Pixel or fractional coordinatescomment (string='')
- A comment stored with the region
-
complement
(region='', comment='')[source]¶ Create the complement of a world region
This function (short-hand name { t 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.
Parameters
region (variant='')
- The world regioncomment (string='')
- A comment stored with the region
-
concatenation
(box='', regions='', comment='')[source]¶ Concatenate world regions along a new axis
This function (short-hand name { t 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.
Parameters
box (variant='')
- The axis to concatenate alongregions (variant='')
- World regionscomment (string='')
- A comment stored with the region
-
deletefromtable
(tablename='', regionname='')[source]¶ 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.
Parameters
tablename (string='')
- The tableregionname (string='')
- Name(s) of the region(s) to delete
-
difference
(region1='', region2='', comment='')[source]¶ 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.
Parameters
region1 (record='')
- The first world regionregion2 (record='')
- The second world regioncomment (string='')
- A comment stored with the region
-
done
()[source]¶ Destroy this regionmanager
This function destroys the contents of the {stf regionmanager} ool(including its GUI). The oolstill exists as a Glish variable, but it is no longer a Regionmanager ! You are unlikely to need this function.
-
frombcs
(csys='', shape=[0], box='', chans='', stokes='', stokescontrol='a', region='')[source]¶ 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.
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 “”.
-
fromfiletorecord
(filename='', verbose=True, regionname='')[source]¶ 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.
Parameters
filename (string='')
- List of files containing the Image Regionsverbose (bool=True)
- Report successful savesregionname (string='')
- Name(s) of the region(s) when saved in the table
-
fromrecordtotable
(tablename='', regionname='', regionrec='', asmask=False, verbose=True)[source]¶ 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 ipsppTable on disk (any kind of table).
If the parameter { t asmask} is { t 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
Parameters
tablename (string='')
- The tableregionname (variant='')
- Name(s) of the region(s) when saved in the tableregionrec (record='')
- Region(s) to saveasmask (bool=False)
- save region as a mask rather than regionverbose (bool=True)
- Report successful saves
-
fromtabletorecord
(tablename='', regionname='', verbose=True)[source]¶ Restore regions from a Table to a record
This function restores a region from an ipsppTable to the global name space.
For the {stfaf tablename} argument, you can specify an image ool, a table ool, or a string. If you give a string, it should be the name of an existing ipspptable 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.
Parameters
tablename (string='')
- The tableregionname (variant='')
- Name of the region(s) to restoreverbose (bool=True)
- Report successful restores
-
fromtext
(text='', shape=[1], csys='')[source]¶ 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.
Parameters
text (string='')
- region descriptionshape (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()
-
fromtextfile
(filename='', shape=[0], csys='')[source]¶ 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.
Parameters
filename (string='')
- List of text file containing the region descriptionshape (intArray=[0])
- Image shape.csys (record='')
- Coordinate system record. Defaults to coordinate system used in rg.setcoordinates()
-
intersection
(regions='', comment='')[source]¶ 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).
Parameters
regions (variant='')
- World regions and commentcomment (string='')
- A comment stored with the region
-
ispixelregion
(region='')[source]¶ Is this region a pixel region ?
NOT IMPLEMENTED IN CASA
This function returns T if the region is a pixel region. For any other glishvariable it returns F.
Parameters
region (record='')
- The region
-
isworldregion
(region='')[source]¶ Is this region a world region ?
NOT IMPLEMENTED IN CASA
This function returns T if the region is a world region. For any other glishvariable it returns F.
Parameters
region (record='')
- The region
-
makeunion
(regions='', comment='')[source]¶ 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).
Parameters
regions (variant='')
- World regions and commentcomment (string='')
- A comment stored with the region
-
namesintable
(tablename='')[source]¶ 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 ipspptable on disk (any kind of table).
Parameters
tablename (string='')
- The table
-
regionmanager
()[source]¶ Construct a regionmanager
This is the only egionmanagerconstructor. It should generally be unnecessary for you to make one as there is little state in a
egionmanager(you can set a Coordinate System with setcoordinates); the default egionmanager{stf rg} should be all you need.
-
selectedchannels
(specification='', shape=[0])[source]¶ 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.
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.
-
setcoordinates
(csys='')[source]¶ 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} ooland is created with the coordsys oolfunction.
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.
Parameters
csys (record='')
- Default Coordinate System for use in world regions
-
tofile
(filename='', region='')[source]¶ 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
Parameters
filename (string='')
- List of files containing the Image Regionsregion (record='')
- region record/dict to store in the file
-
wbox
(blc='', trc='', pixelaxes=[- 1], csys='', absrel='abs', comment='')[source]¶ 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 egionmanagerwith the setcoordinates function.
In the egionmanagerwe 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 egionmanager.
Parameters
blc (variant='')
- blc of the box ; a vector of quantitiestrc (variant='')
- trc of the box; a vector of quantitiespixelaxes (intArray=[-1])
- Which pixel axescsys (record='')
- Coordinate Systemabsrel (string='abs')
- Absolute or relative coordinates- Vector of
strings from ‘abs’, ‘relref’ and ‘relcen’
comment (string='')
- A comment stored with the region
-
wpolygon
(x='', y='', pixelaxes=[- 1], csys='', absrel='abs', comment='')[source]¶ 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}
ooland 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 egionmanagerwe 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 egionmanager.
Parameters
x (variant='')
- The x vector; a vector of quantitiesy (variant='')
- The y vector; vector of quantitiespixelaxes (intArray=[-1])
- which pixel axes; vector of integers ..default -1means [0,1]
csys (record='')
- Coordinate Systemabsrel (string='abs')
- Absolute or relative coordinates; possibilities are ‘abs’, ‘rel’, ‘relcen’comment (string='')
- A comment stored with the region