The Python interface to casacore images.

An image can be constructed in a variety of ways:

• Opening an existing image. The image format is determined automatically and can be casacore, HDF5, FITS, or MIRIAD. FITS and MIRIAD always have data type float, but casacore and HDF5 images can have data type float, double, complex, or dcomplex.
• Open an image expression by giving a LEL expression string. Note that in an expression $im can be used similar to TaQL commands (see function tables.taql()).
• Create a new temporary image from a shape or a numpy array.
• Virtually concatenate a number of images along a given axis. This can be used to form a spectral line image cube from separate channel images.

The following arguments can be given:

imagename

It can be given in several forms:

If it is a tuple or list, the image is opened as the virtual concatenation of the given image names or objects.

Otherwise it should be a string giving the image name (or expression). If argument values or shape is given, a new image with that name is created using the values or shape. If the name is empty, a temporary image is created which can be written later using saveas().

Otherwise it is tried to open an existing image with that name.

If the open fails, it is opened as a LEL image expression.

axis

The axis number along which images have to be concatenated.

maskname

The name of the mask to be used when opening an existing image. If not given, the default image mask is used.

If an image is created, a mask with this name is created.

images

Possible images objects to be used for $n arguments in an expression string.

‘values`

If given, the image will be created and these values will be stored in it. It should be a numpy array or masked array. If it is a masked array, its mask acts as the mask argument described below. The data type of the image is derived from the array’s data type.

coordsys

The coordinate system to be used when creating an image. If not given, an appropriate default coordnate system will be used.

overwrite

If False, an exception is raised if the new image file already exists. Default is True.

ashdf5

If True, the image is created in HDF5 format, otherwise in casacore format. Default is casacore format.

mask

An optional mask to be stored in the image when creating the image. If a mask is given, but no maskname is given, the mask will get the name mask0.

Note that the mask can also be given in argument values (see above).

shape

If given, the image will be created. If values is also given, its shape should match. If values is not given, an image with data type double will be created.

tileshape

Advanced users can give the tile shape to be used. See the tables module for more information about Tiled Storage Managers.

For example:

im = image('3c343.fits')          # open existing fits image
im = image('a.img1 - a.img2')     # open as expression
im = image(shape=(256,256))       # create temp image 
im = image('a', shape=(256,256))  # create image a

attrcreategroup(groupname)¶

Create a new attribute group.

attrfindrows(groupname, attrname, value)¶

Get the row numbers of all rows where the attribute matches the given value.

attrget(groupname, attrname, rownr)¶

Get the value of an attribute in the given row in a group.

attrgetcol(groupname, attrname)¶

Get the value of an attribute for all rows in a group.

attrgetmeas(groupname, attrname)¶

Get the measinfo (type, frame) of an attribute in a group.

attrgetrow(groupname, key, value=None)¶

Get the values of all attributes of a row in a group.

If the key is an integer, the key is the row number for which the attribute values have to be returned.

Otherwise the key has to be a string and it defines the name of an attribute. The attribute values of the row for which the key matches the given value is returned. It can only be used for unique attribute keys. An IndexError exception is raised if no or multiple matches are found.

attrgetunit(groupname, attrname)¶

Get the unit(s) of an attribute in a group.

attrgroupnames()¶

Get the names of all attribute groups.

attrnames(groupname)¶

Get the names of all attributes in this group.

attrnrows(groupname)¶

Get the number of rows in this attribute group.

attrput(groupname, attrname, rownr, value, unit=[], meas=[])¶

Put the value and optionally unit and measinfo of an attribute in a row in a group.

coordinates()¶

Get the coordinatesystem of the image.

datatype()¶

Get data type of the image.

get(blc=(), trc=(), inc=())¶

Get image data and mask.

Get the image data and mask (see :getdata() and getmask()) as a numpy masked array.

getdata(blc=(), trc=(), inc=())¶

Get image data.

Using the arguments blc (bottom left corner), trc (top right corner), and inc (stride) it is possible to get a data slice.

The data is returned as a numpy array. Its dimensionality is the same as the dimensionality of the image, even if an axis has length 1.

getmask(blc=(), trc=(), inc=())¶

Get image mask.

Using the arguments blc (bottom left corner), trc (top right corner), and inc (stride) it is possible to get a mask slice. Not all axes need to be specified. Missing values default to begin, end, and 1.

The mask is returned as a numpy array. Its dimensionality is the same as the dimensionality of the image, even if an axis has length 1. Note that the casacore images use the convention that a mask value True means good and False means bad. However, numpy uses the opposite. Therefore the mask will be negated, so it can be used directly in numpy operations.

If the image has no mask, an array will be returned with all values set to False.

haslock(write=False)¶

Test if the image holds a read or write lock.

See func:`tables.table.haslock for more information.

Locks are only used for images in casacore format. For other formats (un)locking is a no-op, so this method always returns True.

history()¶

Get the image processing history.

imageinfo()¶

Get the standard image info.

imagetype()¶

Get image type of the image (PagedImage, HDF5Image, etc.).

info()¶

Get coordinates, image info, and unit”.

ispersistent()¶

Test if the image is persistent, i.e. stored on disk.

lock(write=False, nattempts=0)¶

Acquire a read or write lock on the image.

See func:`tables.table.haslock for more information.

Locks are only used for images in casacore format. For other formats (un)locking is a no-op, so this method always returns True.

Only advanced users should use locking. In normal operations explicit locking and unlocking is not necessary.

miscinfo()¶

Get the auxiliary image info.

name(strippath=False)¶

Get image name.

ndim()¶

Get dimensionality of the image.

put(value, blc=(), trc=(), inc=())¶

Put image data and mask.

Put the image data and optionally the mask (see :getdata() and getmask()). If the value argument is a numpy masked array, but data and mask will bw written. If it is a normal numpy array, only the data will be written.

putdata(value, blc=(), trc=(), inc=())¶

Put image data.

Using the arguments blc (bottom left corner), trc (top right corner), and inc (stride) it is possible to put a data slice. Not all axes need to be specified. Missing values default to begin, end, and 1.

The data should be a numpy array. Its dimensionality must be the same as the dimensionality of the image.

putmask(value, blc=(), trc=(), inc=())¶

Put image mask.

Using the arguments blc (bottom left corner), trc (top right corner), and inc (stride) it is possible to put a data slice. Not all axes need to be specified. Missing values default to begin, end, and 1.

The data should be a numpy array. Its dimensionality must be the same as the dimensionality of the image. Note that the casacore images use the convention that a mask value True means good and False means bad. However, numpy uses the opposite. Therefore the mask will be negated, so a numoy masked can be given directly.

The mask is not written if the image has no mask and if it the entire mask is False. In that case the mask most likely comes from a getmask operation on an image without a mask.

regrid(axes, coordsys, outname='', overwrite=True, outshape=(), interpolation='linear', decimate=10, replicate=False, refchange=True, forceregrid=False)¶

Regrid the image to a new image object.

Regrid the image on the given axes to the given coordinate system. The output is stored in the given file; it no file name is given a temporary image is made. If the output shape is empty, the old shape is used. replicate=True means replication rather than regridding.

saveas(filename, overwrite=True, hdf5=False, copymask=True, newmaskname='', newtileshape=())¶

Write the image to disk.

Note that the created disk file is a snapshot, so it is not updated for possible later changes in the image object.

overwrite

If False, an exception is raised if the new image file already exists. Default is True.

ashdf5

If True, the image is created in HDF5 format, otherwise in casacore format. Default is casacore format.

copymask

By default the mask is written as well if the image has a mask.

‘newmaskname`

If the mask is written, the name is the same the original or mask0 if the original mask has no name. Using this argument a different mask name can be given.

tileshape

Advanced users can give a new tile shape. See the tables module for more information about Tiled Storage Managers.

shape()¶

Get image shape.

size()¶

Get nr of pixels in the image.

statistics(axes=(), minmaxvalues=(), exclude=False, robust=True)¶

Calculate statistics for the image.

Statistics are returned in a dict for the given axes. E.g. if axes [0,1] is given in a 3-dim image, the statistics are calculated for each plane along the 3rd axis. By default statistics are calculated for the entire image.

minmaxvalues can be given to include or exclude pixels with values in the given range. If only one value is given, min=-abs(val) and max=abs(val).

By default robust statistics (Median, MedAbsDevMed, and Quartile) are calculated too.

subimage(blc=(), trc=(), inc=(), dropdegenerate=True)¶

Form a subimage.

An image object containing a subset of an image is returned. The arguments blc (bottom left corner), trc (top right corner), and inc (stride) define the subset. Not all axes need to be specified. Missing values default to begin, end, and 1.

By default axes with length 1 are left out.

A subimage is a so-called virtual image. It is not stored, but only references the original image. It can be made persistent using the saveas() method.

tofits(filename, overwrite=True, velocity=True, optical=True, bitpix=-32, minpix=1, maxpix=-1)¶

Write the image to a file in FITS format.

filename

FITS file name

overwrite

If False, an exception is raised if the new image file already exists. Default is True.

velocity

By default a velocity primary spectral axis is written if possible.

optical

If writing a velocity, use the optical definition (otherwise use radio).

bitpix

can be set to -32 (float) or 16 (short) only. When bitpix is 16 it will write BSCALE and BZERO into the FITS file. If minPix

minpix and maxpix

are used to determine BSCALE and BZERO if bitpix=16. If minpix is greater than maxpix (which is the default), the minimum and maximum pixel values will be determined from the ddta. Oherwise the supplied values will be used and pixels outside that range will be clipped to the minimum and maximum pixel values. Note that this truncation does not occur for bitpix=-32.

topixel(world)¶

Convert the world coordinates of an image value to pixel coordinates.

The coordinates must be given with the slowest varying axis first. Thus normally like frequency(,polarisation axis),Dec,Ra.

toworld(pixel)¶

Convert the pixel coordinates of an image value to world coordinates.

The coordinates must be given with the slowest varying axis first. Thus normally like frequency(,polarisation axis),Dec,Ra.

unit()¶

Get the pixel unit of the image.

unlock()¶

Release a lock on the image.

See func:`tables.table.haslock for more information.

Locks are only used for images in casacore format. For other formats (un)locking is a no-op, so this method always returns True.

view(tempname='/tmp/tempimage')¶

Display the image using casaviewer.

If the image is not persistent, a copy will be made that the user has to delete once viewing has finished. The name of the copy can be given in argument tempname. Default is ‘/tmp/tempimage’.

A thin wrapper for casacore coordinate systems. It dissects the coordinatesystem record returned from casacore images. This only handles one instance of each coordinate type. The possible types are ‘’direction’‘, ‘’spectral’‘, ‘’stokes’‘, ‘’linear’’ and ‘’tabular’‘.

It uses reference semantics for the individual coordinates, e.g. the following will work:

cs = im.coordinates()
cs["direction"].set_referencepixel([0.0,0.0])
# or equivalent
cs.get_coordinates("direction").set_referencepixel([0.0,0.0])

dict()

get_axes()

get_coordinate(name)

get_increment()

get_names()

Get the coordinate names

get_obsdate()

get_observer()

get_referencepixel()

get_referencevalue()

get_telescope()

get_unit()

set_coordinate(name, val)

set_increment(values)

set_referencepixel(values)

set_referencevalue(values)

summary()

Overwrite as neccessary

dict()

Get the coordinate info as a dict

get_axes()

get_axis_size(axis=0)

Get the length of the given axis in this coordinate

-1 is returned if unknown.

get_image_axis(axis=0)

Get the image axis number of the given axis in this coordinate

-1 is returned if unknown.

get_increment()

get_referencepixel()

get_referencevalue()

get_unit()

set_increment(inc)

set_referencepixel(pix)

set_referencevalue(val)

get_frame()

get_projection()

set_frame(val)

set_projection(val)

get_axes()

get_conversion()

get_frame()

get_increment()

get_referencepixel()

get_referencevalue()

get_restfrequency()

get_unit()

set_conversion(key, val)

set_frame(val)

set_increment(inc)

set_referencepixel(pix)

set_referencevalue(val)

get_stokes()

get_pixelvalues()

get_worldvalues()

set_pixelvalues(val)

set_worldvalues(val)