#
# stub class definition file for docstring parsing
#
[docs]class regionmanager:
r"""
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):
r"""
This is the only constructor. It should generally be unnecessary for you to make one as there is little state in a (you can set a Coordinate System with setcoordinates); the default rg should be all you need.
"""
pass
[docs] def absreltype(self, absrelvalue=0):
r"""
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
.. rubric:: Returns
``string``
.. rubric:: Examples
::
- r = rg.box(blc=[3,40], trc=[80,90]) # Create region
- v = r.get('arblc') # Get absrel value vector for blc
- for i in range( len(v) ):
+ print rg.absreltype(v[i]) # Print string conversion for each axis
-
"""
pass
[docs] def box(self, blc=[0], trc=[-1], inc=[1], absrel='relref', frac=False, comment=''):
r"""
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 (frac=F) or fractions of the image shape (frac=T). Absolute fractions are in the range [0,1].
You can also specify whether the coordinates are given as absolute coordinates (absrel=’abs’) or relative to the reference pixel (absrel=’relref’) or relative to the center of the image (absrel=’relcen’).
.. rubric:: Parameters
- ``blc (doubleVec=[0])`` - blc of the box
- ``trc (doubleVec=[-1])`` - trc of the box
- ``inc (doubleVec=[1])`` - increment
- ``absrel (string='relref')`` - Absolute or relative coordinates
- ``frac (bool=False)`` - Pixel or fractional coordinates
- ``comment (string='')`` - A comment stored with the region
.. rubric:: Returns
``record``
.. rubric:: Examples
::
ia.open('myimage')
ia.shape()
[155 178 256]
r = rg.box() # create region
-
- ia.boundingbox(r)
[blc=[1 1 1] , trc=[155 178 256] , inc=[1 1 1] , bbShape=[155 178 256] ,
regionShape=[155 178 256] , imageShape=[155 178 256] ]
This region, on application to an image, selects the entire image.
"""
pass
[docs] def frombcs(self, csys='', shape=[0], box='', chans='', stokes='', stokescontrol='a', region=''):
r"""
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 (intVec=[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 "".
.. rubric:: Returns
``record``
"""
pass
[docs] def complement(self, region='', comment=''):
r"""
This function (short-hand name ``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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- ia.open('hcn')
- csys = ia.coordsys()
- ia.shape()
[155 178]
-
- blc = "17:42:29.303 -28.59.18.600"
- trc = "17:42:28.303 -28.59.10.600"
- r2 = rg.wbox(blc,trc,[1,2],csys.torecord())
- r3 = rg.complement(r2);
-
- ia.statistics(region=r2) # Some output discarded
Selected bounding box [90, 90] to [103, 98]
No pts = 126
-
- ia.statistics(region=r3)
Selected bounding box [1, 1] to [155, 178] # Some output discarded
No pts = 27464
As expected, the number of pixels in the complement
is $(155*178)-126=27464$
"""
pass
[docs] def concatenation(self, box='', regions='', comment=''):
r"""
This function (short-hand name ``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 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 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 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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- ia.open('cube')
- csys = ia.coordsys()
- rg.setcoordinates(csys.torecord(), verbose=False) # Don't tell us each time
# private coordinates used
- box = rg.wbox(blc="20pix", trc="25pix", pixelaxes=[2])
- bb = ia.boundingbox(box)
-
- regs = {};
- local x, y;
- for i in bb.blc[3]:bb.trc[3]:
+ # Some code in function `mypolygon' generates the
+ # x and y vectors for this spectral pixel, perhaps interactively
+
+ mypolygon(x,y);
+ regs["reg"+str(j)] = rg.wpolygon(x,y,[0,1])
- rc = rg.concatenation(box, regs)
-
- ia.statistics(region=rc, axes=[1,2])
Plane Freq Npts Sum Mean Rms Sigma Minimum Maximum
20 1.413724e+09 25 -4.778154e+00 -1.911262e-01 2.578399e-01 1.766359e-01 -4.252437e-01 1.820721e-01
21 1.413744e+09 40 -7.476902e+00 -2.990761e-01 3.692736e-01 2.210687e-01 -6.073643e-01 1.634156e-01
22 1.413763e+09 32 -2.696485e+00 -1.078594e-01 1.916686e-01 1.617070e-01 -3.295788e-01 1.422531e-01
23 1.413783e+09 77 4.889158e-01 1.955663e-02 3.148451e-02 2.518293e-02 -3.671944e-02 6.521463e-02
24 1.413803e+09 25 -1.337832e+00 -5.351327e-02 6.296221e-02 3.385893e-02 -1.232493e-01 1.014871e-02
25 1.413823e+09 15 1.091297e+00 4.365189e-02 7.252339e-02 5.910932e-02 -6.364560e-02 1.630955e-01
In this example, we create a 1D box and use it to concatenate 2D xy
polygons along the z axis. We then ask for the statistics of each plane
in the region. There is a differerent number of pixels per plane
as each polygon is different.
"""
pass
[docs] def deletefromtable(self, tablename='', regionname=''):
r"""
This function deletes a region stored in an casa Table.
For the 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 regionname arguments. If you set 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
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
- names = rg.namesintable(hcn)
- rg.deletefromtable(img, names[0])
In this example, we delete the first region that is reported to be in the Table {\tt 'hcn'}.
"""
pass
[docs] def difference(self, region1='', region2='', comment=''):
r"""
This function (short-hand name 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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- ia.open('hcn')
- csys = ia.coordsys()
- rg.setcoordinates(csys.torecord())
-
- blc = "10pix 10pix"
- trc = "60pix 60pix"
- r1 = rg.wbox(blc,trc,[0,1])
-
- blc = "50pix 50pix"
- trc = "80pix 80pix"
- r2 = rg.wbox(blc, trc, [0,1])
-
- r3 = rg.difference(r1, r2) # r1 - r2
-
- ia.statistics(region=r1) # Some output discarded
Selected bounding box [10, 10] to [60, 60]
No pts = 2601
-
- ia.statistics(region=r3) # Some output discarded
Selected bounding box [10, 10] to [60, 60]
No pts = 2480
-
-
- r4 = rg.difference(r2, r1) # r2 - r1
-
- ia.statistics(region=r2) # Some output discarded
Selected bounding box [50, 50] to [80, 80]
No pts = 961
-
- ia.statistics(region=r4) # Some output discarded
Selected bounding box [50, 50, 1] to [80, 80, 64]
No pts = 840
We use pixel units and boxes in this example to make it clear what is
happening. The two regions overlap in the top right corner area of
region {\stf r1} by an area of $11\times11=121$~pixels. Therefore, the
difference region {\stf r3} has $2601-121=2480$~pixels in it. For
difference region {\stf r4}, the region of overlap is the bottom left
corner area of region {\stf r2} and still contains 121~pixels. We expect
$961-121=840$~pixels in the differnce region.
"""
pass
[docs] def done(self):
r"""
This function destroys the contents of the regionmanager (including its GUI). The 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]):
r"""
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 (intVec=[0])`` - Image shape. Used to determine if the specificaiton lies outside the image.
.. rubric:: Returns
``intVec``
.. rubric:: Examples
::
ia.fromshape("",[20,20,20])
rg.setcoordinates(ia.coordsys().torecord())
selected_channels = rg.selectedchannels(specification="range=[40km/s,50km/s]", shape=ia.shape())
ia.done()
"""
pass
[docs] def fromtextfile(self, filename='', shape=[0], csys=''):
r"""
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 (intVec=[0])`` - Image shape.
- ``csys (record='')`` - Coordinate system record. Defaults to coordinate system used in rg.setcoordinates()
.. rubric:: Returns
``record``
"""
pass
[docs] def fromtext(self, text='', shape=[1], csys=''):
r"""
This function reads a region region text descriptions and converts it to a python region dictionary.
.. rubric:: Parameters
- ``text (string='')`` - region description
- ``shape (intVec=[1])`` - Image shape, only used if first region is a difference.
- ``csys (record='')`` - Coordinate system record. Defaults to coordinate system used in rg.setcoordinates()
.. rubric:: Returns
``record``
.. rubric:: Examples
::
ia.open('test.image')
csys=ia.coordsys()
rg.setcoordinates(csys.torecord())
a=rg.fromtext("ellipse [[04h31m38.44139, 18d13m57.0861], [1.0arcsec, 1.0arcsec], 0.00000000deg]", shape=[1500, 1500, 1, 1])
ia.done()
In this example, we create a circular region of 1 arcsec radius centered on J2000 04h31m38.44139 18d13m57.0861
"""
pass
[docs] def fromfiletorecord(self, filename='', verbose=True, regionname=''):
r"""
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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- img = ia.open('hcn')
- rg.fromfiletorecord(T, "x1 x2", "file1, file2", r1, r2)
- ia.statistics( region=r1, verbose=True )
- ia.statistics( region=r2, verbose=True )
In this example, we create two regions called {\stf r1} and {\stf r2}
from the files ???
The regions are renamed to `x1' and `x2' as they are stored.
"""
pass
[docs] def tofile(self, filename='', region=''):
r"""
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
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
- img = ia.open('hcn')
- imcs=ia.coordsys()
- blc = ['16:28:25.50', '+040.49.05.61']
- trc = ['16:24:28.67', '+041.45.28.43']
- r1 = rg.wbox(blc=blc,trc=trc,pixelaxes=[0,1],csys=imcs.torecord())
- rg.tofile('myboxregion', r1)
- r1readback=rg.fromfiletorecord('myboxregion')
In this example we create a box region using world coordinates for blc and trc. We save that on disk in a file called {\tt 'myboxregion'}.
Then we read it back using the function rg.fromfiletorecord and store it in a variable {\tt r1readback}. {\tt r1} and {\tt r1readback} should be
identical.
"""
pass
[docs] def fromrecordtotable(self, tablename='', regionname='', regionrec='', asmask=False, verbose=True):
r"""
This function saves regions into an casa Table For the tablename argument the user should be the name of an existing Table on disk (any kind of table).
If the parameter ``asmask`` is ``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 (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
.. rubric:: Returns
``string``
.. rubric:: Examples
::
- ia.open('hcn')
- cs=ia.coordsys()
- blc = "16:28:25.50 +040.49.05.61"
- trc = "16:24:28.67 +041.45.28.43"
- r1 = rg.wbox(blc="10pix 20pix",trc="30pix 40pix",pixelaxes=[0,1],csys=cs.torecord())
- r2 = rg.wbox(blc=blc,trc=trc,pixelaxes=[0,1],csys=cs.torecord())
- rg.fromrecordtotable('hcn', "x", r1)
x
- rg.fromrecordtotable('hcn', "x", r2)
x0
- rg.namesintable('hcn')
x x0
"""
pass
[docs] def fromtabletorecord(self, tablename='', regionname='', verbose=True):
r"""
This function restores a region from an Table to the global name space.
For the tablename argument, you can specify an image , a table , or a string. If you give a string, it should be the name of an existing table on disk (any kind of table).
If 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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- img = ia.open('hcn')
- rec = rg.fromtabletorecord(img, numberfields=True)
- print is_region(rec[0])
The record fields are numbered, not named.
"""
pass
[docs] def intersection(self, regions='', comment=''):
r"""
This function (short-hand name 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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- ia.open('hcn')
- csys = ia.coordsys()
- rg.setcoordinates(csys.torecord())
-
- blc = "10pix 10pix 1pix"
- trc = "60pix 60pix 1pix"
- r1 = rg.wbox(blc=blc, trc=trc, pixelaxes=[0,1,2])
-
- x = qa.quantity([50,55,58,65,58,53,50], 'pix')
- y = qa.quantity([50,53,69,70,63,58,55], 'pix')
- r2 = rg.wpolygon(x=x, y=y, pixelaxes=[0,1])
-
- regions= {'region1':r1, 'region2':r2}
- r3 = rg.intersection(regions, 'This is the comment')
-
- ia.boundingbox(r1)
[blc=[10 10 1] , trc=[60 60 256] , regionShape=[51 51 256] , imageShape=[155 178 256] ]
- ia.boundingbox(r2)
[blc=[50 50 1] , trc=[65 70 256] , regionShape=[16 21 256] , imageShape=[155 178 256] ]
- ia.boundingbox(r3)
[blc=[50 50 1] , trc=[60 60 256] , regionShape=[11 11 256] , imageShape=[155 178 256] ]
-
- ia.statistics(region=r3) # Some output discarded
NORMAL: Selected bounding box [50, 50, 1] to [60, 60, 1]
Number points = 51
In this example, we use pixel coordinates so that it is clear what is
happening. You can see that the number of pixels in the intersection
(51) is less than the number in the bounding box of the intersection
(121) because the intersection is actually polygonal and does not fill
the bounding box.
"""
pass
[docs] def ispixelregion(self, region=''):
r"""
NOT IMPLEMENTED IN CASA
This function returns T if the region is a pixel region. For any other variable it returns F.
.. rubric:: Parameters
- ``region (record='')`` - The region
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
- ia.open('hcn')
- csys = ia.coordsys()
- r1 = rg.box() # A pixel region
- r2 = rg.wbox(csys=csys.torecord()) # A world region
- rg.ispixelregion(r1)
T
- rg.ispixelregion(r2)
F
- x = [20,30]
- rg.ispixelregion(x)
F
"""
pass
[docs] def isworldregion(self, region=''):
r"""
NOT IMPLEMENTED IN CASA
This function returns T if the region is a world region. For any other variable it returns F.
.. rubric:: Parameters
- ``region (record='')`` - The region
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
- ia.open('hcn')
- csys = ia.coordsys()
- r1 = rg.box() # A pixel region
- r2 = rg.wbox(csys=csys.torecord()) # A world region
- rg.isworldregion(r1)
F
- rg.isworldregion(r2)
T
- x = [20,30]
- rg.isworldregion(x)
F
"""
pass
[docs] def namesintable(self, tablename=''):
r"""
This function returns the names of regions stored in an CASA Table.
For the tablename argument, you can specify a string; it should be the name of an existing table on disk (any kind of table).
.. rubric:: Parameters
- ``tablename (string='')`` - The table
.. rubric:: Returns
``stringVec``
.. rubric:: Examples
::
- names=rg.namesintable('hcn')
- names
r1 poly2 int0
"""
pass
[docs] def setcoordinates(self, csys=''):
r"""
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 coordinates and is created with the coordsys .
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 verbose=F then this will not occur.
.. rubric:: Parameters
- ``csys (record='')`` - Default Coordinate System for use in world regions
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
- ia.open('quiqui')
- csys = ia.coordsys()
- rg.setcoordinates(csys.torecord())
- r1 = rg.wbox()
Using private CoordinateSystem from image "quiqui"
"""
pass
[docs] def makeunion(self, regions='', comment=''):
r"""
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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- ia.open('onno')
- csys = ia.coordsys()
- x = qa.quantity([3,6,9,6,5,5,3],'pix')
- y = qa.quantity([3,4,7,9,7,5,5],'pix')
- r1 = rg.wpoly(x,y,[1,2],csys.torecord())
-
- blc = "17:42:29.303 -28.59.18.600"
- trc = "17:42:28.303 -28.59.10.600"
- r2 = rg.wbox(blc,trc,[0,1],csys.torecord())
-
- regions= {'region1':r1, 'region2':r2}
- r3 = rg.makeunion(regions,'The mysteries of CASA')
-
- ia.shape()
[155 178 256]
- ia.boundingbox(r1)
[blc=[3 3 1] , trc=[9 9 256] , inc=[1 1 1] , bbShape=[7 7 256] ,
regionShape=[7 7 256] , imageShape=[155 178 256] ]
- ia.boundingbox(r2)
[blc=[90 90 1] , trc=[103 98 256] , inc=[1 1 1] , bbShape=[14 9 256] ,
regionShape=[14 9 256] , imageShape=[155 178 256] ]
- ia.boundingbox(r3)
[blc=[3 3 1] , trc=[103 98 256] , inc=[1 1 1] , bbShape=[101 96 256] ,
regionShape=[101 96 256] , imageShape=[155 178 256] ]
-
- ia.statistics(region=r1)
Selected bounding box [3, 3, 1] to [9, 9, 256]
Number points = 6400
-
- ia.statistics(region=r2)
Selected bounding box [90, 90, 1] to [103, 98, 256]
Number points = 32256
-
- ia.statistics(region=r3)
Selected bounding box [3, 3, 1] to [103, 98, 256]
Number points = 38656
When the polygon only is applied, it is auto extended along the third
axis. The {\stff statistics} function finds 6400 pixels in the region,
which is $6400/256=25$ pixels per plane. Likewise, when the box only is
applied, the {\stff statistics} function finds 32256 pixels in the
region, which is $32256/256=126$ pixels per plane. When the union is
applied, the {\stff statistics} function finds 38656 pixels in the
region. First it finds the union of the polygon and box (which are
specified only in the XY plane) and that union is extended. Thus we
expect $(25+126)*256=38656$ pixels in the region of the union, as found.
"""
pass
[docs] def wbox(self, blc='', trc='', pixelaxes=[-1], csys='', absrel='abs', comment=''):
r"""
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. blc = qa.quantity("1rad 20deg") or a quantity of a vector (e.g.blc = qa.quantity([10,30], ’rad’)).
You can specify whether the coordinates are given as absolute coordinates (absrel=’abs’) or relative to the reference pixel (absrel=’relref’) or relative to the center of the image (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 blc or trc then the last value you did specify is used as the default for all higher numbered axes (e.g. absrel=’relref’ means absrel="relref relref" for two axes).
You specify which pixel axes in the image the blc and trc vector refer to with the 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 csys argument. The Coordinate System is encapsulated in a coordinates tool and can be recovered from an image with the coordsys tool function. You can also set a default Coordinate System in the with the setcoordinates function.
In the 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 pixelaxes and csys is hidden from you when using the gui interface of the .
.. rubric:: Parameters
- ``blc (variant='')`` - blc of the box ; a vector of quantities
- ``trc (variant='')`` - trc of the box; a vector of quantities
- ``pixelaxes (intVec=[-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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
- r = rg.wbox()
This region, on application to an image, will select the entire
image.
"""
pass
[docs] def wpolygon(self, x='', y='', pixelaxes=[-1], csys='', absrel='abs', comment=''):
r"""
This function (short-hand name wpoly) creates a 2D world polygon region. The polygon is specified by an x and a 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, qa.quantity([1,2,3],’rad’) (a quantity of a vector) is different from 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 x and y vectors pertain to with the 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 x and y vector coordinates are given as absolute coordinates (absrel=’abs’) or relative to the reference pixel (absrel=’relref’) or relative to the center of the image (absrel=’relcen’). This argument applies to both the axes of the polygon.
You must also specify the Coordinate System with the csys argument. The Coordinate System is encapsulated in a coordinates 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 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 pixelaxes and csys is hidden from you when using the gui interface of the .
.. rubric:: Parameters
- ``x (variant='')`` - The x vector; a vector of quantities
- ``y (variant='')`` - The y vector; vector of quantities
- ``pixelaxes (intVec=[-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
.. rubric:: Returns
``record``
.. rubric:: Examples
::
ia.open('myim.im')
csys = ia.coordsys()
x = ["3pix", "6pix", "9pix", "6pix", "5pix","5pix","3pix"]
y = ["3pix","4pix","7pix","9pix","7pix","5pix","5pix"]
r1 = rg.wpolygon(x=x, y=y, pixelaxes=[0,1], csys=csys.torecord())
stats = ia.statistics(region=r1)
ia.done()
We applied the 2D polygon, defined in the XY plane with absolute pixel
coordinates, to a 3D image. Therefore, the third (Z) axis was
automatically extended to the whole image.
"""
pass