NRAO Home > CASA > CASA Toolkit Reference Manual
regionmanager.wbox - Function

1.1.2 Create a world box region


Description

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 Regionmanager with the setcoordinates function.

In the Regionmanager we have defined units ‘pix’ and ‘frac’; these are then known to the quanta system. This means that you can effectively define a pixel box (except for the stride capability) as a world box with most of the advantages of world regions (can be used for compound regions). However, it is still not very portable to other images because the coordinates are pixel based, not world based.

Note that the need to deal with the pixelaxes and csys is hidden from you when using the gui interface of the Regionmanager.

Arguments





Inputs

blc

blc of the box ; a vector of quantities

allowed:

any

Default:

variant

Unity

trc

trc of the box; a vector of quantities

allowed:

any

Default:

variant

Shape

pixelaxes

Which pixel axes

allowed:

intArray

Default:

-1

[0,1,2,...]

csys

Coordinate System

allowed:

record

Default:

Private Coordinate System

absrel

Absolute or relative coordinates Vector of strings from ’abs’, ’relref’ and ’relcen’

allowed:

string

Default:

’abs’

comment

A comment stored with the region

allowed:

string

Default:

Returns
record

Example

 
 
- r = rg.wbox()  
 
 
This region, on application to an image, will select the entire  
image.  
 

Example

 
 
- ia.open(’ada’)  
- csys = ia.coordsys()  
- csys.summary()  
 
Name             Proj Shape Tile   Coord value at pixel    Coord incr Units  
---------------------------------------------------------------------------  
Frequency                64   16  1.413350e+09     1.00  1.968717e+04 Hz  
Velocity                          1.378053e+02     1.00 -4.174021e+00 km/s  
Declination       SIN   178   89 -28.59.18.600    90.00  1.000000e+00 arcsec  
Right Ascension   SIN   155   31  17:42:29.303    90.00 -1.000000e+00 arcsec  
-  
-  
- blc = "17:42:29.303 -28.59.18.600"  
- trc = "17:42:28.303 -28.59.10.600"  
- r1 = rg.wbox(blc=blc,trc=trc,pixelaxes=[0,1],csys=csys.torecord())  
- ia.boundingbox(r1)  
[blc=[1 90 90] , trc=[64 98 103] , regionShape=[64 9 14], imageShape=[64 178 155] ]  
 
 
We have specified an RA and DEC for the blc and the trc (they should  
be quantities; for blc we do that explicitly, but for the trc  
we just give a vector of strings which is automatically converted  
for us to a vector of quantities).  
 
From the {\stff summary} listing you can see that RA and DEC correspond  
to pixel axes 3 and 2 respectively (don’t be confused by the dual  
listing for the spectral axis) so that is why the {\stfaf pixelaxes}  
argument is set to [3,2].  If we had set blc/trc in DEC/RA order then we  
would have put {\stfaf pixelaxes=[1,2]}.  For the unspecified frequency  
axis, all pixels are selected.  
 

Example

 
 
- ia.open(’bork’)  
- csys = ia.coordsys()  
- csys.summary()  
 
Name             Proj Shape Tile   Coord value at pixel    Coord incr Units  
---------------------------------------------------------------------------  
Right Ascension   SIN   155   31  17:42:29.303    90.00 -1.000000e+00 arcsec  
Declination       SIN   178   89 -28.59.18.600    90.00  1.000000e+00 arcsec  
 
- rg.setcoordinates(cs)  
T  
- blc = "-10pix -28.59.18.6"  
- trc = "10pix  -28.59.1.6"  
- r1 = rg.wbox(blc=blc,trc=trc,absrel="relref abs")   # pixelaxes defaults to [0,1]  
Using private CoordinateSystem from image "bork"  
- ia.boundingbox(r1)  
[blc=[80 90] , trc=[100 107] , regionShape=[21 18] , imageShape=[155 178] ]  
 
 
In this example, we use pixel coordinates relative to the reference  
pixel for the RA axis and absolute world coordinates for the DEC axis.  
We also set the state of the \regionmanager\ with a Coordinate  
System to use when making world regions.  You can see that when the  
region was made, a message was issued reminding you that the internal  
Coordinate System from the image {\sff bork} was being used.  
 

Example

 
 
- ia.open(’hcn’)  
- csys = ia.coordsys()  
- csys.summary()  
 
Name             Proj Shape Tile   Coord value at pixel    Coord incr Units  
---------------------------------------------------------------------------  
Right Ascension   SIN   155   31  17:42:29.303    90.00 -1.000000e+00 arcsec  
Declination       SIN   178   89 -28.59.18.600    90.00  1.000000e+00 arcsec  
Frequency                64   16  1.413350e+09     1.00  1.968717e+04 Hz  
Velocity                          1.378053e+02     1.00 -4.174021e+00 km/s  
T  
-  
- blc = "1.414E9Hz"  
- trc = "1.4145GHz"  
- r = rg.wbox(blc=blc, trc=trc, pixelaxes=[2], csys=cs)  
- ia.boundingbox(r)  
[blc=[1 1 34] , trc=[155 178 59] , regionShape=[155 178 26] , imageShape=[155 178 64] ]  
 
 
In this example we only specified a region for the frequency axis (note  
we used different units for the blc and trc).  Therefore, on  
application, the region selected for the RA and DEC axes is  
automatically the full image.  
 

__________________________________________________________________


More information about CASA may be found at the CASA web page

Copyright 2016 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search