1.1.1.0 image.setrestoringbeam

NRAO Home > CASA > CASA Toolkit Reference Manual

image.setrestoringbeam - Function

1.1.1 Set the restoringbeam

Description

This function sets the restoring beam(s) for an image.

You may supply the beam in one of two ways.

First, you can use the argument beam which you must assign to a record containing fields ’major’, ’minor’ and ’positionangle’. Each of these fields contains a quantity. This record is in the same format as one returned by function restoringbeam. If beam is used, the arguments major, minor, & pa are ignored.

Second, you can use the arguments major, minor and pa. Only the ones that you assign are used. Each argument should be assigned either a quantity or a float (units are implicitly those of the current beam - or if none, arcsec for the axes and degrees for the position angle). These parameters are only used if beam is not specified.

An image must have exactly one of the following states:

1. An image can have a single ”traditional” beam. In that case, the beam applies to every channel and polarization in the image.

2. If an image has more than one spectral channel or more than one polarization, it can have a set of beams. In this case, each channel and/or polarization will have its own beam.

3. An image can have neither a traditional beam nor a beam set.

It is never permissible for an image to have both a traditional (global) beam and a set of per-plane beams. Task and method behavior is undefined in that case and any resulting products are considered corrupt.

RULES FOR BEAM MODIFICATION

If an image has no beams, a traditional (global) beam can be added by setting both channel and polarization to negative values.

If an image has no beams, a set of per-plane beams can be added by setting either or both channel and/or polarization to a non-negative value. In this case, a number of per-plane beams are added consistent with the image and they are all set to be the same with parameters equal to those specified by either the beam or major/minor/pa parameters.

If an image has a traditional beam, it can be modified by setting both channel and polarization to negative values. If one or both is not set to a negative value, an exception is thrown, and nothing is modified.

If an image has a set of per plane beams, one at a time of these can be modified by setting the appropriate channel number and/or polarization number. All the per-plane beams can be modified to the same values in one go by setting both channel and polarization to negative values. Also, in the case where an image has multiple channels, the beams associated with all channels for a given polarization can be modified to the same beam by setting polarization equal to the desired polarization plane number and by setting channel to a negative value. Similarly, in the case where an image has multiple polarizations, the beams associated with all polarizations for a given spectral channel can be modified to the same beam by setting channel equal to the desired spectral channel number and by setting polarization to a negative value.

A beam or set of beams can be copied from another image using the imagename parameter to specify that image’s name. If both the current image and specified image have multiple beams, the current image shape must be consistent with the specified image beam set shape.

The traditional beam or a set of multiple beams can be deleted from an image by setting delete=T. If set to true, all other parameters are then ignored; all existing beams will be irrevocably deleted.

Arguments


Inputs
major	Major axis FWHM, Quantity or float (e.g., 1arcsec). Default is unset.
	allowed:	any
	Default:	variant 1arcsec
minor	Minor axis FWHM, Quantity or float (e.g., 1arcsec). Default is unset.
	allowed:	any
	Default:	variant 1arcsec
pa	Position angle, Quantity or float (e.g., ’5deg’). Default is unset.
	allowed:	any
	Default:	variant 0deg
beam	The complete restoring beam (output of restoringbeam()). Default is unset.
	allowed:	record
	Default:
remove	Delete the restoring beam?
	allowed:	bool
	Default:	false
log	Write new beam values to the logger?
	allowed:	bool
	Default:	true
channel	Zero-based channel number for which to set a per plane beam. If the image has a traditional beam, set to less than zero. Default -1.
	allowed:	int
	Default:	-1
polarization	Zero-based polarization number for which to set a per plane beam. If the image has a traditional beam, set to less than zero. Default -1.
	allowed:	int
	Default:	-1
imagename	Copy the beam(s) from the specified image to this image. If multiple beams, the current image must be able to hold a beam set of the shape in the specified image.
	allowed:	string
	Default:

Returns
bool

Example

"""

ia.maketestimage(’hcn’,overwrite=true)
rb = ia.restoringbeam()        # returns beam in record
print rb
#{’major’: {’unit’: ’arcsec’, ’value’: 53.500004857778549},
# ’minor’: {’unit’: ’arcsec’, ’value’: 34.199998900294304},
# ’positionangle’: {’unit’: ’deg’, ’value’: 6.0}}
rb[’minor’][’value’] = 12.5
# new beam specified in record
# NOTE This will not work for an image with multiple beams
ia.setrestoringbeam(beam=rb)
print ia.restoringbeam()
#{’major’: {’unit’: ’arcsec’, ’value’: 53.500004857778549},
# ’minor’: {’unit’: ’arcsec’, ’value’: 12.5},
# ’positionangle’: {’unit’: ’deg’, ’value’: 6.0}}

# beam specified using parameter
# NOTE This will only work for an image with a traditional beam
ia.setrestoringbeam(major=’36arcsec’)
print ia.restoringbeam()
#{’major’: {’unit’: ’arcsec’, ’value’: 36.0},
# ’minor’: {’unit’: ’arcsec’, ’value’: 12.5},
# ’positionangle’: {’unit’: ’deg’, ’value’: 6.0}}
ia.setrestoringbeam(remove=true)
print ia.restoringbeam()
#{}
ia.setrestoringbeam(major=’53.5arcsec’,minor=’34.2arcsec’,pa=’6deg’)
print ia.restoringbeam()
#{’major’: {’unit’: ’arcsec’, ’value’: 53.5},
# ’minor’: {’unit’: ’arcsec’, ’value’: 34.200000000000003},
# ’positionangle’: {’unit’: ’deg’, ’value’: 6.0}}
ia.close()

# Copy all beams from an image with multiple beams to another
# image with the same number of channels and polarizations

ia.open("multibeam.im")
ib = iatool()
ib.open("target.im")

# ensure target has no beam(s) at start, not always necessary
# but it doesn’t hurt to do it.
ib.setrestoringbeam(remove=True)
# Now copy the beams. This only will work correctly if both images
# have the same number of channels and polarizations. nchan is set to
# the number of channels and npol is set to the number of polarizations
for c in range(nchan):
    for p in range(npol):
        beam = ia.restoringbeam(channel=c, polarization=p)
        ib.setrestoringbeam(beam=beam, channel=c, polarization=p)

ia.done()
ib.done()

"""

__________________________________________________________________

[next] [prev] [prev-tail] [front] [up]

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

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