regionmanager

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 \(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

absreltype	Convert region type value to a string
box	Create a pixel box region
complement	Create the complement of a world region
concatenation	Concatenate world regions along a new axis
deletefromtable	Delete regions from a Table
difference	Create the difference of two world regions
done	Destroy this regionmanager
frombcs	Create a world coordinate region based on box-chan-stokes input
fromfiletorecord	Create a region record(s) from a file(s).
fromrecordtotable	Save regions stored in a record into a Table
fromtabletorecord	Restore regions from a Table to a record
fromtext	Create a region dictionary from a region text string.
fromtextfile	Create a region dictionary from a region text file.
intersection	Create the intersection of some world regions
ispixelregion	Is this region a pixel region ?
isworldregion	Is this region a world region ?
makeunion	Create a union of world regions
namesintable	Find the names of the regions stored in a Table
regionmanager	Construct a regionmanager
selectedchannels	Get an array of zero-based selected channel numbers from an input string specificaiton.
setcoordinates	Set new default Coordinate System
tofile	Create a region record file that can be read by from filetorecord.
wbox	Create a world box region
wpolygon	Create a world polygon region with quantities

absreltype(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

Parameters

• absrelvalue (int=0) - Region type value

box(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’}).

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

complement(region='', comment='')

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 region

• comment (string='') - A comment stored with the region

concatenation(box='', regions='', comment='')

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 along

• regions (variant='') - World regions

• comment (string='') - A comment stored with the region

deletefromtable(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.

Parameters

• tablename (string='') - The table

• regionname (string='') - Name(s) of the region(s) to delete

difference(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.

Parameters

• region1 (record='') - The first world region

• region2 (record='') - The second world region

• comment (string='') - A comment stored with the region

done()

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='')

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='')

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 Regions

• verbose (bool=True) - Report successful saves

• regionname (string='') - Name(s) of the region(s) when saved in the table

fromrecordtotable(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 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 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

fromtabletorecord(tablename='', regionname='', verbose=True)

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 table

• regionname (variant='') - Name of the region(s) to restore

• verbose (bool=True) - Report successful restores

fromtext(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.

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()

fromtextfile(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.

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()

intersection(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).

Parameters

• regions (variant='') - World regions and comment

• comment (string='') - A comment stored with the region

ispixelregion(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 glishvariable it returns F.

Parameters

• region (record='') - The region

isworldregion(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 glishvariable it returns F.

Parameters

• region (record='') - The region

makeunion(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).

Parameters

• regions (variant='') - World regions and comment

• comment (string='') - A comment stored with the region

namesintable(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 ipspptable on disk (any kind of table).

Parameters

• tablename (string='') - The table

regionmanager()

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])

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='')

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='')

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 Regions

• region (record='') - region record/dict to store in the file

wbox(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 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 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

wpolygon(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}

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 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