Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/regionmanager.py: 75%
59 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from regionmanager.xml #############
2##################### 4ff09691e40ce125872be37332fdf213 ##############################
3from __future__ import absolute_import
4from .__casac__.regionmanager import regionmanager as _regionmanager
6from .errors import create_error_string
7from .typecheck import CasaValidator as _validator
8_pc = _validator( )
9from .coercetype import coerce as _coerce
12class regionmanager:
13 _info_group_ = """images"""
14 _info_desc_ = """Create and manipulate regions of interest"""
15 ### self
16 def __init__(self, *args, **kwargs):
17 """This is the only regionmanager constructor. It should generally be
18 unnecessary for you to make one as there is little state in a
19 regionmanager (you can set a Coordinate System with
20 setcoordinates); the
21 default regionmanager {stf rg} should be all you need.
22 """
23 self._swigobj = kwargs.get('swig_object',None)
24 if self._swigobj is None:
25 self._swigobj = _regionmanager()
27 def absreltype(self, absrelvalue=int(0)):
28 """This function is not intended for general user use.
30 Regions may be specified with coordinates which are absolute or
31 relative. This function converts the integer code defining the
32 absolute/relative type of the coordinates (which is stored in the
33 region) into a string (maybe for printing purposes).
35 The different types are
38 Integer String Description
39 1 abs Absolute coordinate
40 2 relref Relative reference pixel
41 3 relcen Relative to center of image
42 4 reldir Relative to some direction
45 """
46 return self._swigobj.absreltype(absrelvalue)
48 def box(self, blc=[ float(0) ], trc=[ float(-1) ], inc=[ float(1) ], absrel='abs', frac=False, comment=''):
49 """This function creates a multi-dimensional pixel box region. The box is
50 specified by a bottom-left corner, and top-right corner and an increment
51 (or stride). Pixel coordinates are considered to run from 1 at the
52 bottom left corner of the image to the image shape at the top-right
53 corner of the image.
55 You can specify whether the coordinates are given as pixel coordinates
56 ({stfaf frac=F}) or fractions of the image shape ({stfaf frac=T}).
57 Absolute fractions are in the range [0,1].
59 You can also specify whether the coordinates are given as absolute
60 coordinates ({stfaf absrel='abs'}) or relative to the reference pixel
61 ({stfaf absrel='relref'}) or relative to the center of the image
62 ({stfaf absrel='relcen'}).
63 """
64 return self._swigobj.box(blc, trc, inc, absrel, frac, comment)
66 def frombcs(self, csys={ }, shape=[ int(0) ], box='', chans='', stokes='', stokescontrol='a', region=[ ]):
67 """This function creates a multi-dimensional world coordinate region based
68 on box, chans, stokes inputs familiar from image analysis tasks. It is
69 being introduced as a temporary means of refactoring some python level
70 task code into C++. However, if users find it to have value, its existence
71 can be permanent.
72 """
73 return self._swigobj.frombcs(csys, shape, box, chans, stokes, stokescontrol, region)
75 def complement(self, region=[ ], comment=''):
76 """This function (short-hand name {tt comp}) creates the complement of
77 a world region(s).
79 The region parameter can be a single region record defining a simple
80 or complex region or it can contain several region records in a
81 Python dictionary. If multiple regions are given then the union of
82 this set of regions is taken first, and the complement is found from
83 the union.
85 NOTE: ia.statistics() is UNABLE to handle complement regions in CASA yet.
86 """
87 return self._swigobj.complement(region, comment)
89 def concatenation(self, box=[ ], regions=[ ], comment=''):
90 """This function (short-hand name {tt concat}) creates a region which is
91 the concatenation along a new axis of the given world regions.
93 This function is similar to the
94 extension function. The
95 {stfaf concatenation} function allows you to take many world regions,
96 and concatenate them along one axis (rather than take one region and
97 extend it along many axes which is what function {stff extension}
98 does).
100 For example, you may have generated a different polygonal region for
101 each spectral pixel of a spectral-line cube and you wish to concatenate them
102 together to form the overall region for use in a deconvolution
103 application.
105 The axis to concatenate along is specified as a 1-dimensional world box.
106 The shape of the 1D box must contain as many pixels (although you
107 don't have to specify it in pixels) as there are regions
108 to concatenate.
110 Because this function is most likely to be used in a script, the
111 interface takes a record containing {stff region} records, Python
112 dictionaries, as there might be a lot of them.
113 """
114 return self._swigobj.concatenation(box, regions, comment)
116 def deletefromtable(self, tablename='', regionname=''):
117 """This function deletes a region stored in an casa Table.
119 For the {stfaf tablename} argument,
121 you have to give the name of an existing
122 CASA table on disk (any kind of table).
124 You specify the name of the region with the {stfaf regionname}
125 arguments. If you set {stfaf regionname=''} then nothing is done. The names of all the regions stored in a Table can be found
126 with the function
127 namesintable.
128 """
129 return self._swigobj.deletefromtable(tablename, regionname)
131 def difference(self, region1={ }, region2={ }, comment=''):
132 """This function (short-hand name {stff diff}) creates
133 a region which is the difference of two world regions. The order
134 of the regions is important.
136 The difference consists of all pixels masked-on in the first
137 region and not masked-on in the second region.
138 """
139 return self._swigobj.difference(region1, region2, comment)
141 def done(self):
142 """This function destroys the contents of the {stf regionmanager} tool
143 (including its GUI). The tool still exists as a Glish variable, but
144 it is no longer a Regionmanager ! You are unlikely to need this
145 function.
147 """
148 return self._swigobj.done()
150 def selectedchannels(self, specification='', shape=[ int(0) ]):
151 """This method returns all the selected zero-based channel numbers from the specified string within the image.
156 """
157 return self._swigobj.selectedchannels(specification, shape)
159 def fromtextfile(self, filename='', shape=[ int(0) ], csys={ }):
160 """This function reads a text file containing region descriptions and
161 converts it to a python dictionary.
164 """
165 return self._swigobj.fromtextfile(filename, shape, csys)
167 def fromtext(self, text='', shape=[ int(1) ], csys={ }):
168 """This function reads a region region text descriptions and
169 converts it to a python region dictionary.
172 """
173 return self._swigobj.fromtext(text, shape, csys)
175 def fromfiletorecord(self, filename='', verbose=True, regionname=''):
176 """This function reads files containing ImageRegion objects and turns them
177 into Region Records.
179 The intended use for this method is to read the file saved by the casa
180 viewer and turn the files contents into regions that are usabla by the
181 image analysis tool.
182 """
183 return self._swigobj.fromfiletorecord(filename, verbose, regionname)
185 def tofile(self, filename='', region={ }):
186 """This function is to store a region created by the regionmanager in a disk file for future use
187 """
188 return self._swigobj.tofile(filename, region)
190 def fromrecordtotable(self, tablename='', regionname=[ ], regionrec={ }, asmask=False, verbose=True):
191 """This function saves regions into an casa Table
192 For the {stfaf tablename} argument the user should be the name of an existing
193 aipspp Table on disk (any kind of table).
195 If the parameter {tt asmask} is {tt True} then the table has to be an image table.
196 A mask makes sense with an image only.
199 You can specify the name the region will have ({stfaf
200 regionname}) when it is saved in the Table. If you don't specify this,
201 a digit based name is assigned to it or if specify a name that already
202 exists a new one will be generated which is close but different. The
203 function returns you the name the region is assigned
204 """
205 return self._swigobj.fromrecordtotable(tablename, regionname, regionrec, asmask, verbose)
207 def fromtabletorecord(self, tablename='', regionname=[ ], verbose=True):
208 """This function restores a region from an aipspp Table
209 to the global name space.
211 For the {stfaf tablename} argument, you can specify an
212 image tool, a table tool,
213 or a string. If you give a string, it should be the name of an existing
214 aipspp table on disk (any kind of table).
216 If {stfaf numberfields} is F, then the field names of the
217 record are the same as they are in the Table. Otherwise,
218 the regions are put into numbered fields (the field
219 names could be anything).
221 You can use the function
222 namesintable to find out the
223 names of the regions in the Table.
224 """
225 return self._swigobj.fromtabletorecord(tablename, regionname, verbose)
227 def intersection(self, regions=[ ], comment=''):
228 """This function (short-hand name {stff int}) creates a region which is
229 the intersection of the given world regions. The input regions can
230 themselves be compound regions (such as the union or intersection etc).
231 The input regions must be provided as a Python dictionary of regions
232 (see examples).
233 """
234 return self._swigobj.intersection(regions, comment)
236 def ispixelregion(self, region={ }):
237 """NOT IMPLEMENTED IN CASA
239 This function returns T if the region is a pixel region.
240 For any other glish variable it returns F.
241 """
242 return self._swigobj.ispixelregion(region)
244 def isworldregion(self, region={ }):
245 """NOT IMPLEMENTED IN CASA
247 This function returns T if the region is a world region.
248 For any other glish variable it returns F.
249 """
250 return self._swigobj.isworldregion(region)
252 def namesintable(self, tablename=''):
253 """This function returns the names of regions stored in an CASA Table.
255 For the {stfaf tablename} argument, you can specify a string; it should be the name of an existing
256 aipspp table on disk (any kind of table).
257 """
258 return self._swigobj.namesintable(tablename)
260 def setcoordinates(self, csys={ }):
261 """This function allows you to (re)set the default Coordinate System
262 used by the functions that make world regions. If you don't specifiy a
263 Coordinate System when you make the world region, the default Coordinate
264 System, if there is one, is used. The Coordinate System is
265 stored in a {stf coordinates} tool and is created with
266 the coordsys toolfunction.
268 Normally, the world region creating functions like
269 wbox and
270 wpolygon will issue a message
271 each time the private Coordinate System is used. However, if you set
272 {stfaf verbose=F} then this will not occur.
275 """
276 return self._swigobj.setcoordinates(csys)
278 def makeunion(self, regions=[ ], comment=''):
279 """This function takes a minimum of two world regions and creates a region which
280 is the union of the given regions. The input regions can themselves be
281 compound regions (such as the union or intersection etc). The input
282 regions must be a Pythion dictionary of at leat two regions
283 (see examples).
284 """
285 return self._swigobj.makeunion(regions, comment)
287 def wbox(self, blc=[ ], trc=[ ], pixelaxes=[ int(-1) ], csys={ }, absrel='abs', comment=''):
288 """This function creates a multi-dimensional world box region; the
289 corners of the box are specified in world coordinates. However, the box
290 is not a true world volume in that its sides do not follow world
291 contours. Its sides are parallel to the pixel axes. If you are in a
292 region of high world coordinate contour non-linearity (e.g. near a
293 pole), you are probably better off using a world polygon.
295 The box is specified by a bottom-left corner, and a top-right corner.
296 The coordinates are given as quantities, and you can give a vector of
297 quantities (e.g. {cf blc = qa.quantity("1rad 20deg")} or a
298 quantity of a vector (e.g.{cf blc = qa.quantity([10,30], 'rad')}).
300 You can specify whether the coordinates are given as absolute coordinates
301 ({stfaf absrel='abs'}) or relative to the reference pixel ({stfaf
302 absrel='relref'}) or relative to the center of the image ({stfaf
303 absrel='relcen'}). You can specify this for each axis (the same for the
304 blc and trc). If you specify less values than the number of
305 values in {stfaf blc} or {stfaf trc} then the last value you
306 did specify is used as the default for all higher numbered axes
307 (e.g. {stfaf absrel='relref'} means {stfaf absrel="relref relref"}
308 for two axes).
310 You specify which pixel axes in the image the {stfaf blc} and {stfaf
311 trc} vector refer to with the {stfaf pixelaxes} argument. If you
312 don't, it defaults to [0,1,2,...]. This specification is an important
313 part of world regions.
315 You must also specify the Coordinate System with the {stfaf csys}
316 argument. The Coordinate System is encapsulated in a {stfaf coordinates}
317 tool and can be recovered from an image with the
318 coordsys tool function. You can
319 also set a default Coordinate System in the regionmanager with the
320 setcoordinates
321 function.
323 In the regionmanager we have defined units `pix' and `frac'; these are
324 then known to the quanta system. This means
325 that you can effectively define a pixel box (except for the stride
326 capability) as a world box with most of the advantages of world regions
327 (can be used for compound regions). However, it is still not very
328 portable to other images because the coordinates are pixel based,
329 not world based.
331 Note that the need to deal with the {stfaf pixelaxes} and {stfaf csys}
332 is hidden from you when using the gui
333 interface of the regionmanager.
334 """
335 return self._swigobj.wbox(blc, trc, pixelaxes, csys, absrel, comment)
337 def wpolygon(self, x=[ ], y=[ ], pixelaxes=[ int(-1) ], csys={ }, absrel='abs', comment=''):
338 """This function (short-hand name {stff wpoly}) creates a 2D world
339 polygon region. The polygon is specified by an {stfaf x} and a {stfaf y}
340 vector. These must be quantities of a vector (the
341 world box function
342 allows both
343 quantities of vectors and vectors of quantities). This means that the
344 units are common to all elements of each vector. Thus, {cf
345 qa.quantity([1,2,3],'rad')} (a quantity of a vector) is different from
346 {cf qa.quantity("1rad 2rad 3rad")} (a vector of quantities) although
347 the information that they specify is the same.
349 You specify which pixel axes in the image the {stfaf x} and {stfaf
350 y} vectors pertain to with the {stfaf pixelaxes} argument. If you don't,
351 it defaults to [0,1]. This specification is an important part of
352 world regions.
354 You can specify whether the {stfaf x} and {stfaf y} vector coordinates are
355 given as absolute coordinates ({stfaf absrel='abs'}) or relative to the
356 reference pixel ({stfaf absrel='relref'}) or relative to the center of the
357 image ({stfaf absrel='relcen'}). This argument applies to both the axes
358 of the polygon.
360 You must also specify the Coordinate System with the {stfaf csys}
361 argument. The Coordinate System is encapsulated in a {stfaf coordinates}
362 tool and can be recovered from an image with the
363 coordsys function. You can
364 also set a default Coordinate System in the Regionmanager with the
365 setcoordinates
366 function.
368 In the regionmanager we have defined units `pix' and `frac'; these are
369 then known to the quanta system. This means
370 that you can effectively define a pixel box (except for the stride
371 capability) as a world box with most of the advantages of world regions
372 (can be used for compound regions). However, it is still not very
373 portable to other images because the coordinates are pixel based,
374 not world based.
376 Note that the need to deal with the {stfaf pixelaxes} and {stfaf csys}
377 is hidden from you when using the gui
378 interface of the regionmanager.
379 """
380 return self._swigobj.wpolygon(x, y, pixelaxes, csys, absrel, comment)