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
This function is not intended for general user use.
This function creates a multi-dimensional pixel box region.
This function (short-hand name
comp
) creates the complement of a world region(s).This function (short-hand name
concat
) creates a region which is the concatenation along a new axis of the given world regions.This function deletes a region stored in an casa Table.
This function (short-hand name diff) creates a region which is the difference of two world regions.
This function destroys the contents of the regionmanager (including its GUI).
This function creates a multi-dimensional world coordinate region based on box, chans, stokes inputs familiar from image analysis tasks.
This function reads files containing ImageRegion objects and turns them into Region Records.
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).
This function restores a region from an Table to the global name space.
This function reads a region region text descriptions and converts it to a python region dictionary.
This function reads a text file containing region descriptions and converts it to a python dictionary.
This function (short-hand name int) creates a region which is the intersection of the given world regions.
NOT IMPLEMENTED IN CASA
NOT IMPLEMENTED IN CASA
This function takes a minimum of two world regions and creates a region which is the union of the given regions.
This function returns the names of regions stored in an CASA Table.
This is the only constructor.
This method returns all the selected zero-based channel numbers from the specified string within the image.
This function allows you to (re)set the default Coordinate System used by the functions that make world regions.
This function is to store a region created by the regionmanager in a disk file for future use
This function creates a multi-dimensional world box region; the corners of the box are specified in world coordinates.
This function (short-hand name wpoly) creates a 2D world polygon region.
- absreltype(absrelvalue=0)[source]
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
Returns
string
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 -
- box(blc=[0], trc=[-1], inc=[1], absrel='relref', frac=False, comment='')[source]
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’).
Parameters
blc (doubleVec=[0])
- blc of the boxtrc (doubleVec=[-1])
- trc of the boxinc (doubleVec=[1])
- incrementabsrel (string='relref')
- Absolute or relative coordinatesfrac (bool=False)
- Pixel or fractional coordinatescomment (string='')
- A comment stored with the region
Returns
record
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.
- complement(region='', comment='')[source]
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.
Parameters
region (variant='')
- The world regioncomment (string='')
- A comment stored with the region
Returns
record
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$
- concatenation(box='', regions='', comment='')[source]
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.
Parameters
box (variant='')
- The axis to concatenate alongregions (variant='')
- World regionscomment (string='')
- A comment stored with the region
Returns
record
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.
- deletefromtable(tablename='', regionname='')[source]
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.
Parameters
tablename (string='')
- The tableregionname (string='')
- Name(s) of the region(s) to delete
Returns
bool
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'}.
- difference(region1='', region2='', comment='')[source]
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.
Parameters
region1 (record='')
- The first world regionregion2 (record='')
- The second world regioncomment (string='')
- A comment stored with the region
Returns
record
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.
- done()[source]
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.
- frombcs(csys='', shape=[0], box='', chans='', stokes='', stokescontrol='a', region='')[source]
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 (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 “”.
Returns
record
- fromfiletorecord(filename='', verbose=True, regionname='')[source]
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
Returns
record
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.
- fromrecordtotable(tablename='', regionname='', regionrec='', asmask=False, verbose=True)[source]
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
isTrue
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
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
Returns
string
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
- fromtabletorecord(tablename='', regionname='', verbose=True)[source]
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.
Parameters
tablename (string='')
- The tableregionname (variant='')
- Name of the region(s) to restoreverbose (bool=True)
- Report successful restores
Returns
record
Examples
- img = ia.open('hcn') - rec = rg.fromtabletorecord(img, numberfields=True) - print is_region(rec[0]) The record fields are numbered, not named.
- fromtext(text='', shape=[1], csys='')[source]
This function reads a region region text descriptions and converts it to a python region dictionary.
Parameters
text (string='')
- region descriptionshape (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()
Returns
record
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
- fromtextfile(filename='', shape=[0], csys='')[source]
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 (intVec=[0])
- Image shape.csys (record='')
- Coordinate system record. Defaults to coordinate system used in rg.setcoordinates()
Returns
record
- intersection(regions='', comment='')[source]
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).
Parameters
regions (variant='')
- World regions and commentcomment (string='')
- A comment stored with the region
Returns
record
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.
- ispixelregion(region='')[source]
NOT IMPLEMENTED IN CASA
This function returns T if the region is a pixel region. For any other variable it returns F.
Parameters
region (record='')
- The region
Returns
bool
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
- isworldregion(region='')[source]
NOT IMPLEMENTED IN CASA
This function returns T if the region is a world region. For any other variable it returns F.
Parameters
region (record='')
- The region
Returns
bool
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
- makeunion(regions='', comment='')[source]
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
Returns
record
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.
- namesintable(tablename='')[source]
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).
Parameters
tablename (string='')
- The table
Returns
stringVec
Examples
- names=rg.namesintable('hcn') - names r1 poly2 int0
- regionmanager()[source]
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.
- selectedchannels(specification='', shape=[0])[source]
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 (intVec=[0])
- Image shape. Used to determine if the specificaiton lies outside the image.
Returns
intVec
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()
- setcoordinates(csys='')[source]
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.
Parameters
csys (record='')
- Default Coordinate System for use in world regions
Returns
bool
Examples
- ia.open('quiqui') - csys = ia.coordsys() - rg.setcoordinates(csys.torecord()) - r1 = rg.wbox() Using private CoordinateSystem from image "quiqui"
- tofile(filename='', region='')[source]
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
Returns
bool
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.
- wbox(blc='', trc='', pixelaxes=[-1], csys='', absrel='abs', comment='')[source]
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 .
Parameters
blc (variant='')
- blc of the box ; a vector of quantitiestrc (variant='')
- trc of the box; a vector of quantitiespixelaxes (intVec=[-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
Returns
record
Examples
- r = rg.wbox() This region, on application to an image, will select the entire image.
- wpolygon(x='', y='', pixelaxes=[-1], csys='', absrel='abs', comment='')[source]
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 .
Parameters
x (variant='')
- The x vector; a vector of quantitiesy (variant='')
- The y vector; vector of quantitiespixelaxes (intVec=[-1])
- which pixel axes; vector of integers ..default -1 means [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
Returns
record
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.