coordsys

class coordsys

Operations on CoordinateSystems

A Coordsys  is used to store and manipulate a Coordinate System (we will use the term ‘Coordinate System’ interchangeably with ‘Coordsys’). A Coordinate System is a collection of coordinates, such as a direction coordinate (E.g. RA/DEC), or a spectral coordinate (e.g. an LSRK frequency).

The main job of the Coordsys  is to convert between absolute pixel and world (physical) coordinates. It also supports relative pixel and world coordinates (relative to reference location).

A Coordinate System is generally associated with an image (manipulated via an Image ) but can also exist in its own right. An image is basically just a regular lattice of pixels plus a Coordinate System describing the mapping from pixel coordinate to world (or physical) coordinate.

Each coordinate is associated with a number of axes. For example, a direction coordinate has two coupled axes; a longitude and a latitude. A spectral coordinate has one axis. A linear coordinate can have an arbitrary number of axes, but they are all uncoupled. The Coordinate System actually maintains two kinds of axes; pixel axes and world axes.

As well as the coordinates, there is some extra information stored in the Coordinate System. This consists of the telescope, the epoch (date of observation), and the highly influential observer’s name. The telescope (i.e. position on earth) and epoch are important if you want to, say, change a spectral coordinate from LSRK to TOPO.

For general discussion about celestial coordinate systems, see the papers by Mark Calabretta and Eric Greisen. Background on the WCS system and relevant papers (including the papers published in

A&A 2002, 1061-1075 and 1077-1122

can be found . Note that the actual system implemented originally in  was based on a 1996 draft of these papers. The final papers are being implemented while new version of the defining library become available.

Many of the Coordsys  functions use a world coordinate value as an argument. This world value can be formatted in many ways.

Some functions (e.g. toworld) have a function argument called format which takes a string. This controls the format in which the coordinate is output and hence possibly input into some other function.

Possibilities for format are :

• ’n’ - means the world coordinate is given as a numeric vector (actually doubles). The units are implicitly those returned by function units.

• ’q’ - means the world coordinate is given as a vector of quantities (value and unit) - see the quanta module. If there is only one axis (e.g. spectral coordinate), you will get a single quantum only.

• ’m’ - means the world coordinate is given as a record of measures - see the measures module.

  The record consists of fields named direction, spectral, stokes, linear, and tabular, depending upon which coordinate types are present in the Coordinate System.

  The direction field holds a direction measure.

  The spectral field holds further subfields frequency, radiovelocity, opticalvelocity, betavelocity. The frequency subfield holds a frequency measure. The radiovelocity subfield holds a doppler measure using the radio velocity definition. The opticalvelocity subfield holds a doppler measure using the optical velocity definition. The betavelocity subfield holds a doppler measure using the True or beta velocity definition.

  The stokes field just holds a string giving the Stokes type (not a real measure).

  The linear and tabular fields hold a vector of quanta (not a real measure).

• ’s’ - means the the world coordinate is given as a vector of formatted strings

You can give a combination of one or more of the allowed letters when using the format argument. The coordinate is given as a record, with possible fields ’numeric’, ’quantity’, ’measure’ and ’string’ where each of these fields is given as described above.

There are functions torel and toabs used to inter-convert between absolute and relative world and pixel coordinates. These functions have an argument isworld whereby you can specify whether the coordinate is a pixel coordinate or a world coordinate. In general, you should not need to use this argument because any coordinate variable generated by Coordsys  functions ’knows’ whether it is absolute or relative, world or pixel. . However, you may be inputting a coordinate variable which you have generated in some other way, and then you may need this.

Stokes axes don’t fit very well into our Coordinate model since they are not interpolatable. The alternative to having a Stokes Coordinate is having a Stokes pixel type (like double, complex). Both have their good and bad points. We have chosen to use a Stokes Coordinate.

With the Stokes Coordinate, any absolute pixel coordinate value must be in the range of 1 to \(nStokes\), where \(nStokes\) is the number of Stokes types in the Coordinate.

We define relative world coordinates for a Stokes axis to be the same as absolute world coordinates (it makes no sense to think of a relative value \(XY - XX\) say).

You can use the specialized functions stokes and setstokes to recover and set new Stokes values in the Stokes Coordinate.

The Coordinate System maintains what it calls pixel and world axes. The pixel axis is associated with, say, the axes of a lattice of pixels. The world axes describe notional world axes, generally in the same order as the pixel axes. However, they may be different. Imagine that a 3-D image is collapsed along one axis. The resultant image has 2 pixel axes. However, we can maintain the world coordinate for the collapsed axis (so we know the coordinate value still). Thus we have three world axes and two pixel axes. It is also possible for the C++ programmer to reorder these pixel and world axes. However, this is strongly discouraged, and you should never actually encounter a situation where the pixel and world axes are in different orders, but you may encounter cases where the number of world and pixela axes is different.

For those of us ( programmers) writing robust scripts, we must account for these possibilities, although the user really shouldn’t bother. Thus, the pixel and world vectors return the pixel and world axes of the found coordinate.

The functions referencevalue, increment, units, and names return their vectors in world axis order. However, function referencepixel returns in pixel axis order (and the world vectors might have more values than the referencepixel vector).

Overview of Coordsys tool functions

• Get/set - Functions to get and set various items within the Coordinate System are

  • referencepixel - get the reference pixel

  • setreferencepixel - set the reference pixel

  • referencevalue - get the reference value

  • setreferencevalue - set the reference value

  • setreferencelocation - Set reference pixel and value to these values

  • increment - get axis increments

  • setincrement - set axis increments

  • lineartransform - get linear transform

  • setlineartransform - set linear transform

  • names - get axis names

  • setnames - set axis names

  • units - get axis units

  • setunits - set axis units

  • stokes - get Stokes values

  • setdirection - set Direction coordinate values

  • setstokes - set Stokes values

  • setspectral - set Spectral coordinate tabular values

  • settabular - set Tabular coordinate tabular values

  • projection - get direction coordinate projection

  • setprojection - set direction coordinate projection

  • referencecode - get reference codes

  • setreferencecode - set reference codes

  • restfrequency - get the spectral coordinate rest frequency

  • setrestfrequency - set the spectral coordinate rest frequency

  • epoch - get the epoch of observation

  • setepoch - set the epoch of observation

  • telescope - get the telecope of the observation

  • settelescope - set the telecope of the observation

  • observer - get observer name

  • setobserver - set observer name

• Utility - There is a range of utility services available through the functions

  • axesmap - get mapping between pixel and world axes order

  • axiscoordinatetypes - get type of coordinate for each axis

  • coordinatetype - get type of coordinates

  • copy - make a copy of this tool

  • done - destroy this

  • findaxis - find specified axis (by number) in coordinate system

  • findcoordinate - find specified (by number) coordinate

  • fromrecord - set Coordinate System from a casapy record

  • id - get the fundamental identifier of this

  • naxes - get number of axes

  • ncoordinates - get the number of coordinates

  • reorder - reorder coordinates

  • summary - summarize the Coordinate System

  • torecord - Convert a Coordinate SYstem to a casapy record

  • type - the type of this

• Coordinate conversion

  • convert - Convert one numeric coordinate with mixed input and output formats (abs/rel/world/pixel)

  • toabs - Convert a relative coordinate to an absolute coordinate

  • topixel - Convert from absolute world coordinate to absolute pixel coordinate

  • torel - Convert an absolute coordinate to a relative coordinate

  • toworld - Convert from an absolute pixel coordinate to an absolute world coordinate

  • convertmany - Convert many numeric coordinates with mixed input and output formats (abs/rel/world/pixel)

  • toabsmany - Convert many relative coordinates to absolute coordinates

  • topixelmany - Convert many absolute world coordinates to absolute pixel coordinates

  • torelmany - Convert many absolute coordinates to relative coordinates

  • toworldmany - Convert many absolute pixel coordinates to absolute world coordinates

  • frequencytovelocity - Convert from frequency to velocity

  • frequencytofrequency - Apply a relativistic Doppler shift to a list of frequencies

  • velocitytofrequency - Convert from velocity to frequency

  • setconversiontype - Set extra reference frame conversion layer

  • conversiontype - Recover extra reference frame conversion types

• Tests -

  • coordsystest - Run test suite for Coordsys

Methods Summary

addcoordinate	Add default coordinates of the specified types.
axesmap	This function returns a vector describing the mapping from pixel to world or world to pixel axes.
axiscoordinatetypes	This function returns a vector string giving the coordinate type for each axis (world or pixel) in the Coordinate System.
conversiontype	Some coordinates contain a reference code.
convert	This function converts between mixed pixel/world/abs/rel numeric coordinates.
convertdirection	Convert the direction coordinate in the coordinate system to the specified frame by rotating about the reference pixel so that the resulting coordinate axes are parallel to the cardinal directions.
convertmany	This function converts between many mixed pixel/world/abs/rel numeric coordinates.
coordinatetype	This function returns a string describing the type of the specified coordinate.
coordsys	coordsys method
copy	This function returns a copy, not a reference, of the Coordsys .
done	If you no longer need to use a Coordsys calling this function will free up its resources and restore the default coordsys tool.
epoch	This function returns the epoch of the observation as a Measure.
findaxis	This function finds the specified axis in the Coordinate System.
findaxisbyname	Find the world axis based on its name.
findcoordinate	This function finds the axes in the Coordinate System for the specified coordinate (minimum match is active for argument type).
frequencytofrequency	This function converts frequencies to frequencies by applying a relativistic Doppler shift: fout = fin * sqrt((1.-v/c)/(1.+v/c)) .
frequencytovelocity	This function converts frequencies to velocities.
fromrecord	You can convert a Coordinate System to a record (torecord).
getconversiontype	See conversiontype for more complete description.
increment	Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel).
lineartransform	Recover the linear transform component for the specified coordinate type.
names	Each axis associated with the Coordinate System has a name (they don’t mean anything fundamental).
naxes	Find the number of axes in the Coordinate System.
ncoordinates	This function recovers the number of coordinates in the Coordinate System.
newcoordsys	By default, this constructor makes an empty Coordsys .
observer	This function returns the name of the observer.
parentname	This function returns the parent image name for ‘coordsys’.
projection	If the Coordinate System contains a direction coordinate, this function can be used to recover information about the projection.
referencecode	This function returns the reference code for all, or the specified coordinate type.
referencepixel	Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel).
referencevalue	Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel).
reorder	This function reorders the coordinates in the Coordinate System.
replace	This function replaces one coordinate in the current Coordinate System by one coordinate in the given Coordinate System.
restfrequency	If the Coordinate System contains a spectral coordinate, then it has a rest frequency.
setconversiontype	Some coordinates contain a reference code.
setdirection	When you construct a Coordsys , if you include a Direction Coordinate, it will have some default parameters.
setepoch	This function sets a new epoch (supplied as an epoch measure) of the observation.
setincrement	Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel).
setlineartransform	This function set the linear transform component.
setnames	Each axis associated with the Coordinate System has a name.
setobserver	If you want to grab all the glory, or transfer the blame, this function sets a new observer of the observation.
setparentname	Set the parent image name (normally not needed by end-users)
setprojection	If the Coordinate System contains a direction coordinate, this function can be used to set the projection.
setreferencecode	This function sets the reference code for the specified coordinate type.
setreferencelocation	This function sets the reference pixel and reference value to the specified values.
setreferencepixel	Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel).
setreferencevalue	Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel).
setrestfrequency	If the Coordinate System contains a spectral coordinate, then it has a rest frequency.
setspectral	When you construct a Coordsys , if you include a Spectral Coordinate, it will be linear in frequency.
setstokes	If the Coordinate System contains a Stokes Coordinate, this function allows you to change the Stokes types defining it.
settabular	When you construct a Coordsys , if you include a Tabular Coordinate, it will be linear.
settelescope	This function sets a new telescope of the observation.
setunits	Each axis associated with the Coordinate System has a unit.
stokes	If the Coordinate System contains a Stokes Coordinate, this function recovers the Stokes types defining it.
subimage	You can convert a Coordinate System to another coordinatesystem applicable to a subImage.
summary	This function summarizes the information contained in the Coordinate System.
telescope	This function returns the telescope contained in the Coordinate System as a simple string.
toabs	This function converts a relative coordinate to an absolute coordinate.
toabsmany	This function converts many relative coordinates to absolute.
topixel	This function converts between world (physical) coordinate and absolute pixel coordinate (0-rel).
topixelmany	This function converts many absolute world coordinates to pixel coordinates.
torecord	You can convert a Coordinate System to a record with this function.
torel	This function converts an absolute coordinate to a relative coordinate.
torelmany	This function converts many absolute coordinates to relative.
toworld	This function converts between absolute pixel coordinate (0-rel) and absolute world (physical coordinate).
toworldmany	This function converts many absolute pixel coordinates to world coordinates.
transpose	This method transposes the axes (both world and pixel) in the coordinate system.
type	This function returns the string ‘coordsys’.
units	Each axis associated with the Coordinate System has a unit.
velocitytofrequency	This function converts velocities to frequencies.

addcoordinate(direction=False, spectral=False, stokes='', linear=0, tabular=False)

Add default coordinates of the specified types. This function allows multiple coordinates of the same type which are not well supported. Use only for assay tests.

Parameters

• direction (bool=False) - Add a direction coordinate ?

• spectral (bool=False) - Add a spectral coordinate ?

• stokes (stringVec='') - Add a Stokes coordinate with these Stokes

• linear (int=0) - Add a linear coordinate with this many axes

• tabular (bool=False) - Add a tabular coordinate

Returns

bool

Examples

#
print "\t----\t addcoordinate Ex 1 \t----"
mycs=cs.newcoordsys()
mycs.addcoordinate(direction=True)
mycs.done()
#

axesmap(toworld=True)

This function returns a vector describing the mapping from pixel to world or world to pixel axes. It is not for general user use.

See the about pixel and world axis ordering. Generally they will be in the same order.

Parameters

• toworld (bool=True) - Map from pixel to world ?

Returns

intVec

Examples

#
print "\t----\t axesmap Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
csys.axesmap(T);
#[1L, 2L, 3L]
csys.axesmap(F);
#[1L, 2L, 3L]
#

axiscoordinatetypes(world=True)

This function returns a vector string giving the coordinate type for each axis (world or pixel) in the Coordinate System.

See the about pixel and world axis ordering.

Parameters

• world (bool=True) - World or pixel axes ?

Returns

stringVec

Examples

#
print "\t----\t axiscoordinatetypes Ex 1 \t----"
csys=cs.newcoordsys(direction=True,spectral=True)
csys.axiscoordinatetypes()
#['Direction', 'Direction', 'Spectral']
#

conversiontype(type='direction')

Some coordinates contain a reference code. Examples of reference codes are B1950 and J2000 for direction coordinates, or LSRK and BARY for spectral coordinates. When you do conversions between pixel and world coordinate, the coordinates are in the reference frame corresponding to these codes.

Function setconversiontype allows you to specify a different reference frame which is used when converting between world and pixel coordinate.

This function allows you to recover those conversion types. If no extra conversion layer has been set, you get back the native reference types.

Parameters

• type (string='direction') - Coordinate type, direction, spectral

Returns

string

Examples

#
print "\t----\t conversiontype Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
print csys.conversiontype (type='direction'), ' ', csys.conversiontype (type='spectral')
#J2000   LSRK
csys.setconversiontype (direction='GALACTIC', spectral='BARY')
print csys.conversiontype (type='direction'), ' ', csys.conversiontype (type='spectral')
#GALACTIC   BARY
#

convert(coordin='', absin=[True], dopplerin='radio', unitsin=['Native'], absout=[True], dopplerout='radio', unitsout=['Native'], shape=[-1])

This function converts between mixed pixel/world/abs/rel numeric coordinates. The input and output coordinates are specified via a numeric vector giving coordinate values, a string vector giving units, a boolean vector specifying whether the coordinate is absolute or relative (to the reference pixel) and doppler strings specifying the doppler convention for velocities.

The units string may include pix for pixel coordinates and velocity units (i.e. any unit consistent with m/s).

The allowed doppler strings and definition are described in function summary.

The shape argument is optional. If your Coordinate System is from an image, then assign the image shape to this argument. It is used only when making mixed (pixel/world) conversions for Direction Coordinates to resolve ambiguity.

The example clarifies the use of this function.

Parameters

• coordin (doubleVec='') - Input coordinate, as a numeric vector

• absin (boolVec=[True]) - Are input coordinate elements absolute ?

• dopplerin (string='radio') - Input doppler type for velocities

• unitsin (stringVec=['Native']) - Input units, string vector

• absout (boolVec=[True]) - Are output coordinate elements absolute ?

• dopplerout (string='radio') - Output doppler type for velocities

• unitsout (stringVec=['Native']) - Output units

• shape (intVec=[-1]) - Image shape, integer vector

Returns

doubleVec

Examples

In this example we convert from a vector of absolute pixels
to a mixture of pixel/world and abs/rel.


#
print "\t----\t convert Ex 1 \t----"
csys=cs.newcoordsys(direction=True, spectral=True)    # 3 axes
cout=csys.convert(coordin=[10,20,30],absin=[T,T,T],
                  unitsin=["pix","pix","pix"],
                  absout=[T,F,T], dopplerout='optical',
                  unitsout=["pix","arcsec","km/s"])
print cout
#[10.0, 1140.0058038878046, 1139.1354056919731]
#

convertdirection(frame='')

Convert the direction coordinate in the coordinate system to the specified frame by rotating about the reference pixel so that the resulting coordinate axes are parallel to the cardinal directions. The resulting coordinate will not have a conversion layer, even if the input direction coordinate does. A conversion layer can be set after by running cs.setconversiontype(). Be aware that if you attach the resulting coordinate system to an image whose pixels have not been rotated around the reference pixel in the same manner, you will likely get an image for which the pixels do not match up to world coordinate values. This method should only be used by experienced users who know what they are doing. It was written originally to facilitate rotating the direction coordinate since the implementation of imregrid requires this in certain circumstances. The conversion is done in place; a new coordinate system tool is not created. The returned record represents an angular quantity through which the old direction coordinate was rotated to create the new coordinate.

Parameters

• frame (string='') - Reference frame to convert to.

Returns

record

convertmany(coordin='', absin=[True], dopplerin='radio', unitsin=['Native'], absout=[True], dopplerout='radio', unitsout=['Native'], shape=[-1])

This function converts between many mixed pixel/world/abs/rel numeric coordinates. See function convert for more information.

The only diffference with that function is that you provide a matrix holding many coordinates to convert and a matrix of many converted coordinates is returned.

Parameters

• coordin (variant='') - Input coordinate, numeric matrix

• absin (boolVec=[True]) - Are input coordinate elements absolute ?

• dopplerin (string='radio') - Input doppler type for velocities

• unitsin (stringVec=['Native']) - Input units, string vector

• absout (boolVec=[True]) - Are output coordinate elements absolute ?

• dopplerout (string='radio') - Output doppler type for velocities

• unitsout (stringVec=['Native']) - Output units

• shape (intVec=[-1]) - Image shape, integer array

Returns

variant

Examples

#
print "\t----\t convertmany Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)    # 3 axes
# absolute pixel coordinates; 10 conversions each of length 3; spectral
cin=[(15, 15, 15, 15, 15, 15, 15, 15, 15, 15),  # pixel runs from 1 to 10
     (20, 20, 20, 20, 20, 20, 20, 20, 20, 20),
     ( 1,  2,  3,  4,  5,  6,  7,  8,  9, 10)]
cout = csys.convertmany (coordin=cin,     
                         absin=[T,T,T],
                         unitsin=["pix","pix","pix"],
                         absout=[T,F,T],
                         dopplerout='optical',
                         unitsout=["pix","deg","km/s"]);
print cout
#[(15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0),
# (0.31666827885771637, 0.31666827885771637, 0.31666827885771637,
#  0.31666827885771637, 0.31666827885771637, 0.31666827885771637,
#  0.31666827885771637, 0.31666827885771637, 0.31666827885771637,
#  0.31666827885771637),
# (1145.3029083129913, 1145.0902316004676, 1144.8775551885467,
#  1144.6648790772279, 1144.4522032665102, 1144.2395277563601,
#  1144.0268525468437, 1143.8141776379266, 1143.6015030296085,
#  1143.3888287218554)]
#

coordinatetype(which=-1)

This function returns a string describing the type of the specified coordinate. If which=unset the types for all coordinates are returned.

Possible output values are ’Direction’, ’Spectral’, ’Stokes’, ’Linear’, and ’Tabular’

Parameters

• which (int=-1) - Which coordinate ? (0-rel)

Returns

stringVec

Examples

#
print "\t----\t coordinatetype Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
csys.coordinatetype(0)
#'Direction'
cs.coordinatetype()
#['Direction', 'Spectral']
#

coordsys()

coordsys method

copy()

This function returns a copy, not a reference, of the Coordsys . It is your responsibility to call the done function on the new .

done()

If you no longer need to use a Coordsys calling this function will free up its resources and restore the default coordsys tool.

epoch()

This function returns the epoch of the observation as a Measure.

findaxis(world=True, axis=0)

This function finds the specified axis in the Coordinate System. If the axis does not exist, it throws an exception.

Parameters

• world (bool=True) - is axis a world or pixel axis ?

• axis (int=0) - Axis in coordinate system

Returns

record

Examples

#
print "\t----\t findaxis Ex 1 \t----"
csys=cs.newcoordsys(direction=True, linear=2)          # RA/DEC/Lin1/Lin2
rtn=csys.findaxis(T,1)                              # DEC
rtn
#{'axisincoordinate': 1L, 'coordinate': 0L}
rtn = csys.findaxis(T,2)                            # Lin1
rtn
#{'axisincoordinate': 0L, 'coordinate': 1L}
#



In these examples, the Coordinate System has 2 coordinates and 4 axes
(0-rel, both world and pixel the same).  The first example finds the
DEC axis (coordinate system axis 1) to be the second axis of the
Direction Coordinate (coordinate 0). The second example finds the
first linear axis (coordinate system axis 2) to be the first axis of
the Linear Coordinate (coordinate 1).

findaxisbyname(axisname='', allowfriendlyname=True)

Find the world axis based on its name. Matching is not case sensitive and minimal match is supported, eg “dec” will match “Declination”. In addition, if allowfriendlyname is True, other common terms will match the expected axis. Currently supported are: “spectral” matches frequency type axes, eg “Frequency” or “Velocity”, “ra” matches “Right Ascension”. These names must be spelled out completely; eg “spectral” rather than simply “spec”. The first matching axis (zero-based) number is returned. If no axis can be matched, an exception is thrown.

Parameters

• axisname (string='') - Name of axis to find. Minimal match supported

• allowfriendlyname (bool=True) - Support friendly naming. Eg “spectral” will match “frequency” or “velocity”, “ra” will match “right ascension”

Returns

int

Examples

# Find the declination axis
ia.open("myimage")
csys = ia.coordsys()
ia.done()
try:
    dec_axis_number = csys.findaxisbyname("dec", False)
except Exception
    print "Declination axis not found

# find the spectral axis
try:
    spec_axis_number = csys.findaxisbyname("spectral", True)
except Exception:
    print "Spectral axis could not be found.

findcoordinate(type='direction', which=0)

This function finds the axes in the Coordinate System for the specified coordinate (minimum match is active for argument type). By default it finds the first coordinate, but if there is more than one (can happen for linear coordinates), you can specify which. It returns a dictionary with ’return’, ’pixel’, and ’world’ as keys. The associated value of ’return’ is a boolean indicating if the specified coordinate was found. The values of ’pixel’ and ’world’ are arrays indicating the indices of the associated pixel and world axes, respectively, of the specified coordinate. If the coordinate does not exist, these arrays will be empty.

See also the function axesmap which returns the mapping between pixel and world axes.

Parameters

• type (string='direction') - Type of coordinate to find: direction, stokes, spectral, linear, or tabular

• which (int=0) - Which coordinate if more than one

Returns

record

Examples

#
print "\t----\t findcoordinate Ex 1 \t----"
csys=cs.newcoordsys(direction=True)
rtn=cs.findcoordinate('direction')
print rtn
#{'world': [0L, 1L], 'pixel': [0L, 1L]}
print 'pixel, world axes =', rtn['pixel'], rtn['world']
#pixel, world axes = [0 1] [0 1]
#

frequencytofrequency(value='', frequnit='', velocity='')

This function converts frequencies to frequencies by applying a relativistic Doppler shift: fout = fin * sqrt((1.-v/c)/(1.+v/c)) .

The input frequencies are specified via a vector of numeric values and a specified unit (frequnit). If you don’t give a frequency unit, it is assumed that the units are those given by function coordsys units() for the spectral coordinate.

This function does not make any frame conversions (e.g. LSR to BARY).

This function fails if there is no spectral coordinate in the Coordinate System. See also function frequencytovelocity.

Parameters

• value (doubleVec='') - Frequencies to convert

• frequnit (string='') - Unit of input frequencies. Default is unit of the spectral coordinate.

• velocity (variant='') - Velocity

Returns

doubleVec

Examples

  ia.open('M100line.image')
  mycs = ia.coordsys()
  ia.close()

  mycs.frequencytofrequency(value=[115271201800.0], frequnit='Hz', velocity='1000km/s')
results in
  array([114887337607.0])

Let's see if this is correct
  print 115271201800.0*sqrt((1.-1000000./299792458.0)/(1.+1000000./299792458.0))
Result: 1.14887337607e+11

frequencytovelocity(value='', frequnit='', doppler='radio', velunit='km/s')

This function converts frequencies to velocities.

The input frequencies are specified via a vector of numeric values and a specified unit (frequnit). If you don’t give a frequency unit, it is assumed that the units are those given by function coordsys units() for the spectral coordinate.

This function does not make any frame conversions (e.g. LSR to BARY) but you can specifiy the velocity doppler definition via the doppler argument (see image summary() for possible values).

The velocities are returned in a vector for which you specify the units (velunit - default is km/s).

This function will return a fail if there is no spectral coordinate in the Coordinate System. See also function velocitytofrequency.

Parameters

• value (doubleVec='') - Frequency to convert

• frequnit (string='') - Unit of input frequencies. Default is unit of the spectral coordinate.

• doppler (string='radio') - Velocity doppler definition

• velunit (string='km/s') - Unit of output velocities

Returns

doubleVec

Examples

#
print "\t----\t frequencytovelocity Ex 1 \t----"
im = ia.fromshape(shape=[10,10,10])
csys = ia.coordsys()
rtn = csys.findcoordinate('spectral')   # Find spectral axis
pa=rtn['pixel']
wa=rtn['world']
pixel = csys.referencepixel();          # Use reference pixel for non-spectral
nFreq = ia.shape()[pa];                 # Length of spectral axis
freq = [];
for i in range(nFreq):
  pixel[pa] = i            # Assign value for spectral axis of pixel coordinate
  w = csys.toworld(value=pixel, format='n')   # Convert pixel to world
  freq.append(w['numeric'][wa]);              # Fish out frequency
print "freq=", freq
#freq= [1414995000.0, 1414996000.0, 1414997000.0, 1414998000.0,
# 1414999000.0, 1415000000.0, 1415001000.0, 1415002000.0, 1415003000.0, 1415004000.0]
vel = csys.frequencytovelocity(value=freq, doppler='optical', velunit='km/s')
print "vel=", vel
#vel= [1146.3662963847394, 1146.153618169159, 1145.9409402542183, 1145.7282626398826,
# 1145.5155853261515, 1145.3029083129911, 1145.0902316004676, 1144.8775551885467,
# 1144.6648790772279, 1144.4522032665104]
#



In this example, we find the optical velocity in km/s of every pixel
along the spectral axis of our image.  First we  obtain the Coordinate
System from the image.  Then we find which axis of the Coordinate System
(image) pertain to the spectral coordinate.  Then we loop over each
pixel of the spectral axis, and convert a pixel coordinate (one for each
axis of the image) to world.  We obtain the value for the spectral axis
from that world vector, and add it to the vector of frequencies.  Then
we convert that vector of frequencies to velocity.

fromrecord(record='')

You can convert a Coordinate System to a record (torecord). This function (fromrecord) allows you to set the contents of an existing Coordinate System from such a record. In doing so, you overwrite its current contents.

Parameters

• record (record='') - Record containing Coordinate System

Returns

bool

Examples

#
print "\t----\t fromrecord Ex 1 \t----"
csys = cs.newcoordsys(direction=True, stokes="I Q")
print csys.ncoordinates()
#2
r = csys.torecord()
cs2 = cs.newcoordsys()
print cs2.ncoordinates()
#0
cs2.fromrecord(r)
print cs2.ncoordinates()
#2
#

getconversiontype(type='', showconversion=True)

See conversiontype for more complete description.

Parameters

• type (string='') - Conversion type

• showconversion (bool=True) - Show the conversion layer

Returns

string

increment(format='n', type='')

Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel). These are used in the mapping from pixel to world coordinate.

This function returns the increment (in world axis order). You can recover the increments either for all coordinates (leave type unset) or for a specific coordinate type (mimumum match of the allowed types will do). If you ask for a non-existent coordinate an exception is generated.

See the regarding the formatting possibilities available via argument format.

You can set the increment with function setincrement.

Parameters

• format (string='n') - Format string from combination of “n”, “q”, “s”, “m”

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all.

Returns

record

Examples

#
print "\t----\t increment Ex 1 \t----"
csys=cs.newcoordsys(direction=True,spectral=True)
print csys.increment(format='q')
#{'quantity': {'*1': {'unit': "'", 'value': -1.0},
#              '*2': {'unit': "'", 'value': 1.0},
#              '*3': {'unit': 'Hz', 'value': 1000.0}}}
print csys.increment(format='n')
#{'numeric': [-1.0, 1.0, 1000.0]}
print csys.increment(format='n', type='spectral')
#{'numeric': [1000.0]}
#

lineartransform(type='')

Recover the linear transform component for the specified coordinate type.

You can set the linear transform with function setlineartransform.

Parameters

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”

Returns

variant

Examples

#
print "\t----\t lineartransform Ex 1 \t----"
csys=cs.newcoordsys(direction=True,linear=3)
csys.lineartransform('dir')                             # 2 x 2
# [(1.0, 0.0), (0.0, 1.0)]
csys.lineartransform('lin')                             # 3 x 3
# [(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]
#

names(type='')

Each axis associated with the Coordinate System has a name (they don’t mean anything fundamental). This function returns those names in world axis order.

You can recover the names either for all coordinates (leave type unset) or for a specific coordinate type (mimumum match of the allowed types will do). If you ask for a non-existent coordinate an exception is generated.

You can set the names with function setnames.

Parameters

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all.

Returns

stringVec

Examples

#
print "\t----\t names Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
n = csys.names()
print n[0]
#Right Ascension 
print n[1]
#Declination 
print n[2]
#Frequency 
print cs.names('spec')
#Frequency
#

naxes(world=True)

Find the number of axes in the Coordinate System.

You may find the number of world or pixel axes; these are generally the same and general users can ignore the distinction. See the about pixel and world axis ordering.

Parameters

• world (bool=True) - Find number of world or pixel axes ?

Returns

int

Examples

#
print "\t----\t naxes Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
n = csys.naxes(T)
print n
#3                          # 2 direction axes, 1 spectral
n = csys.naxes(F)
print n
#3
#

ncoordinates()

This function recovers the number of coordinates in the Coordinate System.

newcoordsys(direction=False, spectral=False, stokes='', linear=0, tabular=False)

By default, this constructor makes an empty Coordsys . You can ask it to include various sorts of coordinates through the arguments. Except for Stokes, you don’t have any control over the coordinate contents (e.g. reference value etc.) it does make for you on request. But you can edit the Coordinate System after creation if you wish.

If you wish to make a Stokes coordinate, then you assign stokes to a string (or a vector of strings) saying which Stokes you want.  allows rather a lot of potential Stokes types.

Probably most useful is some combination of the basic I, Q, U, V, XX, YY, XY, YX, RR, LL, RL, and LR.

However, a more esoteric choice is also possible: RX, RY, LX, LY, XR, XL, YR, YL (these are mixed linear and circular), PP, PQ, QP, QQ (general quasi-orthogonal correlation products) RCircular, LCircular, Linear (single dish polarization types).

You can also specify some polarization ‘Stokes’ types: Ptotal (Polarized intensity (\((Q^2+U^2+V^2)^{1/2}\)), Plinear (Linearly Polarized intensity (\((Q^2+U^2)^{1/2}\)), PFtotal (Polarization Fraction (Ptotal/I)), PFlinear (Linear Polarization Fraction (Plinear/I)), and Pangle (Linear Polarization Angle (\(0.5~arctan(U/Q)\) in radians)).

Probably you will find the more unusual types aren’t fully supported throughout the system.

You can make a LinearCoordinate with as many uncoupled axes as you like. Thus, linear=2 makes one LinearCoordinate with 2 axes (think of it like a DirectionCoordinate which also has 2 axes [but coupled in this case], a longitude and a latitude).

If you make a TabularCoordinate, it is linear to start with. You can change it to a non-linear one by providing a list of pixel and world values to function settabular.

Parameters

• direction (bool=False) - Make a direction coordinate ?

• spectral (bool=False) - Make a spectral coordinate ?

• stokes (stringVec='') - Make a Stokes coordinate with these Stokes

• linear (int=0) - Make a linear coordinate with this many axes

• tabular (bool=False) - Make a tabular coordinate

Returns

coordsys

Examples

#
print "\t----\t newcoordsys Ex 1 \t----"
cs1=cs.newcoordsys()
print 'ncoordinates =',cs1.ncoordinates()
#0
cs1.done()
#True
cs2=cs.newcoordsys(direction=True,stokes=['I','V'])
print 'ncoordinates =',cs2.ncoordinates()
#2L
print cs2.coordinatetype()
#['Direction', 'Stokes']
cs2.summary()
#


The second Coordinate System contains a direction coordinate
and a Stokes coordinate.   This means that there are three `axes'
associated with the 2 coordinates.

observer()

This function returns the name of the observer. You can set it with the function setobserver.

parentname()

This function returns the parent image name for ‘coordsys’.

projection(type='')

If the Coordinate System contains a direction coordinate, this function can be used to recover information about the projection. For discussion about celestial coordinate systems, including projections, see the papers by Mark Calabretta and Eric Greisen. The initial draft from 1996 (implemented in . Background information can be found .

What this function returns depends upon the value you assign to type.

• type=unset. In this case (the default), the actual projection type and projection parameters are returned in a record with fields type and parameters, respectively.

• type=’all’. In this case, a vector of strings containing all of the possible projection codes is returned.

• type=code. If you specify a valid projection type code (see list by setting type=’all’) then what is returned is the number of parameters required to describe that projection (useful in function setprojection).

You can change the projection with setprojection.

If the Coordinate System does not contain a direction coordinate, an exception is generated.

Parameters

• type (string='') - Type of projection. Defaults to current projection.

Returns

record

Examples

#
print "\t----\t projection Ex 1 \t----"
csys = cs.newcoordsys(direction=True)
print csys.projection()
#{'type': 'SIN', 'parameters': [0.0, 0.0]}
print csys.projection('all')
#{'all': True, 'types': ['AZP', 'TAN', 'SIN', 'STG', 'ARC', 'ZPN', 'ZEA',
# 'AIR', 'CYP', 'CAR', 'MER', 'CEA', 'COP', 'COD', 'COE', 'COO', 'BON',
# 'PCO', 'SFL', 'PAR', 'AIT', 'MOL', 'CSC', 'QSC', 'TSC']}
print csys.projection('ZPN')
#{'nparameters': 100}
#


We first recover the projection type and parameters from
the direction coordinate.  Then we find the list of all
possible projection types.  FInally, we recover the number of 
parameters required to describe the 'ZPN' projection.

referencecode(type='', list=False)

This function returns the reference code for all, or the specified coordinate type. Examples of the reference code are B1950 and J2000 for direction coordinates, or LSRK and BARY for spectral coordinates.

If type is left unset, then a vector of strings is returned, one code for each coordinate type in the Coordinate System.

If you specify type then select from ’direction’, ’spectral’, ’stokes’, and ’linear’ (the first two letters will do). However, only the first two coordinate types will return a non-empty string. If the Coordinate System does not contain a coordinate of the type you specify, an exception is generated.

The argument list is ignored unless you specify a specific type. If list=T, then this function returns the list of all possible reference codes for the specified coordinate type. Otherwise, it just returns the actual code current set in the Coordinate System.

The list of all possible types is returned as a record (it is actually generated by the listcodes function in the measures system). This record has two fields. These are called ’normal’ (containing all normal codes) and ’extra’ (maybe empty, with all extra codes like planets).

You can set the reference code with setreferencecode.

Parameters

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all.

• list (bool=False) - List all possibilities?

Returns

stringVec

Examples

#
print "\t----\t referencecode Ex 1 \t----"
csys = cs.newcoordsys(direction=True)
clist = csys.referencecode('dir', True)
print clist
# ['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'B1950_VLA', 'BMEAN', 'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO', 'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC', 'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS', 'MERCURY', 'VENUS', 'MARS', 'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE', 'PLUTO', 'SUN', 'MOON', 'COMET']
print csys.referencecode('dir')
#J2000
#



In this example we first get the list of all possible reference codes
ofor a direction coordinate. Then we
get the actual reference code for the direction coordinate in our
Coordinate System.

referencepixel(type='')

Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel). These are used in the mapping from pixel to world coordinate.

This function returns the reference pixel (in pixel axis order). You can recover the reference pixel either for all coordinates (leave type unset) or for a specific coordinate type (mimumum match of the allowed types will do). If you ask for a non-existent coordinate an exception is generated.

You can set the reference pixel with function setreferencepixel.

Parameters

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all.

Returns

record

Examples

#
print "\t----\t referencepixel Ex 1 \t----"
csys = cs.newcoordsys(spectral=True, linear=2)
csys.setreferencepixel([1.0, 2.0, 3.0])
print csys.referencepixel()
#{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 1.,  2.,  3.])}
print csys.referencepixel('lin')
#{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 2.,  3.])}
#

referencevalue(format='n', type='')

Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel). These are used in the mapping from pixel to world coordinate.

This function returns the reference value (in world axis order). You can recover the reference value either for all coordinates (leave type unset) or for a specific coordinate type (mimumum match of the allowed types will do). If you ask for a non-existent coordinate an exception is generated.

See the regarding the formatting possibilities available via argument format.

You can set the reference value with function setreferencevalue.

Parameters

• format (string='n') - Format string. Combination of “n”, “q”, “s”, “m”

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all.

Returns

record

Examples

#
print "\t----\t referencevalue Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
print csys.referencevalue(format='q')
#{'ar_type': 'absolute',
# 'pw_type': 'world',
# 'quantity': {'*1': {'unit': "'", 'value': 0.0},
#              '*2': {'unit': "'", 'value': 0.0},
#              '*3': {'unit': 'Hz', 'value': 1415000000.0}}}
print csys.referencevalue(format='n')
#{'ar_type': 'absolute',
# 'numeric': array([  0.00000000e+00,   0.00000000e+00,   1.41500000e+09]),
# 'pw_type': 'world'}
print csys.referencevalue(format='n', type='spec')
#{'ar_type': 'absolute',
# 'numeric': array([  1.41500000e+09]),
# 'pw_type': 'world'}
#

reorder(order='')

This function reorders the coordinates in the Coordinate System. You specify the new order of the coordinates in terms of their old order.

Parameters

• order (intVec='') - New coordinate order

Returns

bool

Examples

#
print "\t----\t reorder Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True, linear=2)
print csys.coordinatetype()
#['Direction', 'Spectral', 'Linear']
csys.reorder([1,2,0]);
print csys.coordinatetype()
#['Spectral', 'Linear', 'Direction']
#

replace(csys='', whichin='', whichout='')

This function replaces one coordinate in the current Coordinate System by one coordinate in the given Coordinate System. The specified coordinates must have the same number of axes.

Parameters

• csys (record='') - Coordinate System to replace from. Use coordsys’ torecord() to generate required record.

• whichin (int='') - Index of input coordinate (0-rel)

• whichout (int='') - Index of output coordinate

Returns

bool

Examples

#
print "\t----\t replace Ex 1 \t----"
cs1 = cs.newcoordsys(direction=True, linear=1)
print cs1.coordinatetype()
#['Direction', 'Linear']
cs2 = cs.newcoordsys(spectral=True)
cs1.replace (cs2.torecord(),0,1)
print cs1.coordinatetype()
#['Direction', 'Spectral']
#

restfrequency()

If the Coordinate System contains a spectral coordinate, then it has a rest frequency. In fact, the spectral coordinate can hold several rest frequencies (to handle for example, an observation where the band covers many lines), although only one is active (for velocity conversions) at a time.

This function recovers the rest frequencies as a quantity vector. The first frequency is the active one.

You can change the rest frequencies with setrestfrequency.

If the Coordinate System does not contain a frequency coordinate, an exception is generated.

setconversiontype(direction='', spectral='')

Some coordinates contain a reference code. Examples of reference codes are B1950 and J2000 for direction coordinates, or LSRK and BARY for spectral coordinates. When you do conversions between pixel and world coordinate, the coordinates are in the reference frame corresponding to these codes.

This function allows you to specify a different reference frame which is used when converting between world and pixel coordinate (see function conversiontype to recover the conversion types). If it returns F, it means that although the conversion machines were successfully created, a trial conversion failed. This usually means the REST frame was involved which requires a radial velocity (not yet implemented). If this happens, the conversion type will be left as it was. The function fails if more blatant things are wrong like a missing coordinate, or an incorrect reference code.

The list of possible reference codes can be obtained via function referencecode.

With this function, you specify the desired reference code. Then, when a conversion between pixel and world is requested, an extra conversion is done to (toWorld) or from (toPixel) the specified reference frame.

The summary function shows the extra conversion reference system to the right of the native reference system (if it is different) and in parentheses.

Note that to convert between different spectral reference frames, you need a position, epoch and direction. The position (telescope) and epoch (date of observation), if not in your coordinate system can be set with functions settelescope and setepoch. The direction is the reference direction of the required direction coordinate in the coordinate system.

As an example, let us say you are working with a spectral coordinate which was constructed with the LSRK reference frame. You want to convert some pixel coordinates to barycentric velocities (reference code BARY).

#
print "\t----\t setconversiontype Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True); # Create coordinate system
rtn=csys.findcoordinate('spectral')             # Find spectral coordinate
wa=rtn['world']
pa=rtn['pixel']
u = csys.units()[wa]                            # Spectral unit
print csys.referencecode(type='spectral')       # Which is  in LSRK reference frame
#LSRK
p = [10,20,30]
w = csys.toworld(p, format='n')           # Convert a pixel to LSRK world
print 'pixel, world = ', p, w['numeric']
#pixel, world =  [10, 20, 30] [21589.999816660376, 20.000112822985134, 1415030000.0]
p2 = csys.topixel(w)                      # and back to pixel
print 'world, pixel = ', w['numeric'], p2
#world, pixel =  [21589.999816660376, 20.000112822985134, 1415030000.0]
# [10.00000000000248, 19.999999999999801, 30.0]
# Convert LSRK frequency to LSRK velocity
v = csys.frequencytovelocity(value=w['numeric'][wa], frequnit=u, 
                             doppler='RADIO', velunit='m/s');
print 'pixel, frequency, velocity = ', p[pa], w['numeric'][wa], v
#pixel, frequency, velocity =  30 1415030000.0 1134612.30321
csys.setconversiontype(spectral='BARY')   # Specify BARY reference code
w = csys.toworld(p, format='n')           # Convert a pixel to BARY world
print 'pixel, world = ', p, w['numeric']
#pixel, world =  [10, 20, 30] [21589.999816660376, 20.000112822985134, 1415031369.0081882]
p2 = csys.topixel(w)                      # and back to pixel
print 'world, pixel = ', w['numeric'], p2
#world, pixel =  [21589.999816660376, 20.000112822985134, 1415031369.0081882]
# [10.00000000000248, 19.999999999999801, 30.0]
# Convert BARY frequency to BARY velocity
v = csys.frequencytovelocity(value=w['numeric'][wa], frequnit=u, 
                              doppler='RADIO', velunit='m/s');
print 'pixel, frequency, velocity = ', p[pa], w['numeric'][wa], v
#pixel, frequency, velocity =  30 1415031369.01 1134323.35878
#

You must also be aware of when this extra layer is active and when it is not. It’s a bit nasty.

• • Whenever you use toWorld, toPixel toWorldMany, or toPixelMany the layer is active.

• • Whenever you use convert or convertMany the layer may be active. Here are the rules !

  It is only relevant to spectral and direction coordinates.

  For the direction coordinate part of your conversion, if you request a pure world or pixel conversion it is active. Any pixel/world mix will not invoke it (because it is ill defined).

  For the spectral coordinate part it is always active (only one axis so must be pixel or world).

• • This layer is irrelevant to all functions converting between frequency and velocity, and absolute and relative. The values are in whatever frame you are working with.

The summary function lists the reference frame for direction and spectral coordinates. If you have also set a conversion reference code it also lists that (to the right in parentheses).

Parameters

• direction (string='') - Reference code

• spectral (string='') - Reference code

Returns

bool

setdirection(refcode='', proj='', projpar=[-1], refpix=[-1], refval='', incr='', xform='', poles='')

When you construct a Coordsys , if you include a Direction Coordinate, it will have some default parameters. This function simply allows you to replace the values of the Direction Coordinate.

You can also change almost all of those parameters (such as projection, reference value etc.) via the individual functions setreferencecode, setprojection, setreferencepixel, setreferencevalue, setincrement, and setlineartransform provided by the Coordsys . See those functions for more details about the formatting of the above function arguments.

Bear in mind, that if your Coordinate System came from a real image, then the reference pixel is special and you should not change it.

Parameters

• refcode (string='') - Reference code. Default is no change.

• proj (string='') - Projection type. Default is no change.

• projpar (doubleVec=[-1]) - Projection parameters. Default is no change.

• refpix (doubleVec=[-1]) - Reference pixel. Default is no change.

• refval (variant='') - Reference value. Default is no change.

• incr (variant='') - Increment. Default is no change.

• xform (variant='') - Linear transform. Default is no change.

• poles (variant='') - Native poles. Default is no change.

Returns

bool

Examples

#
print "\t----\t setdirection Ex 1 \t----"
csys = cs.newcoordsys(direction=True);
csys.setdirection (refcode='GALACTIC', proj='SIN', projpar=[0,0],
                   refpix=[-10,20], refval="10deg -20deg");
print csys.projection()
#{'type': 'SIN', 'parameters': array([ 0.,  0.])}
print csys.referencepixel()
#{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([-10.,  20.])}
print csys.referencevalue(format='s')
#{'ar_type': 'absolute', 'pw_type': 'world', 
# 'string': array(['10.00000000 deg', '-20.00000000 deg'], dtype='|S17')}
#

setepoch(value='')

This function sets a new epoch (supplied as an epoch measure) of the observation. You can get the current epoch with function epoch.

Parameters

• value (record='') - New epoch measure

Returns

bool

Examples

#
print "\t----\t setepoch Ex 1 \t----"
csys = cs.newcoordsys()
ep = csys.epoch()
print ep
#{'type': 'epoch', 'm0': {'value': 54161.766782997685, 'unit': 'd'}, 'refer': 'UTC'}
ep = me.epoch('UTC', 'today')
csys.setepoch(ep)
print csys.epoch()
#{'type': 'epoch', 'm0': {'value': 54161.766782997685, 'unit': 'd'}, 'refer': 'UTC'}
#

setincrement(value='', type='')

Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel). These are used in the mapping from pixel to world coordinate.

This function allows you to set a new increment. You should not do this on “stokes” axes unless you are an adept or a big risk taker.

You can set the increments either for all axes (type=unset) or for just the axes associated with a particular coordinate type.

You may supply the increments in all of the formats described in the discussion.

In addition, you can also supply the increments as a quantity of vector of doubles. For example qa.quantity([-1,2],’arcsec’).

You can recover the current increments with function increment.

Parameters

• value (variant='') - Increments

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all

Returns

bool

Examples

#
print "\t----\t setincrement Ex 1 \t----"
csys=cs.newcoordsys(direction=True, spectral=True)
rv = csys.increment(format='q')
print rv
# {'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': -1.0, 'unit': "'"},
#              '*2': {'value': 1.0, 'unit': "'"},
#              '*3': {'value': 1000.0, 'unit': 'Hz'}}}
rv2 = qa.quantity('4kHz');
csys.setincrement(value=rv2, type='spec')
print csys.increment(type='spec', format='q')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': 4000.0, 'unit': 'Hz'}}}
csys.setincrement(value='5kHz', type='spec')
print csys.increment(type='spec', format='q')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': 5000.0, 'unit': 'Hz'}}}
print csys.increment(format='q')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': -1.0, 'unit': "'"},
#              '*2': {'value': 1.0, 'unit': "'"},
#              '*3': {'value': 5000.0, 'unit': 'Hz'}}}
csys.setincrement (value="-2' 2' 2e4Hz")
print csys.increment(format='q')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': -2.0, 'unit': "'"},
#              '*2': {'value': 2.0, 'unit': "'"},
#              '*3': {'value': 20000.0, 'unit': 'Hz'}}}
#



In the example we first recover the increments as a vector of
quantities. We then create a quantity for a new value for the spectral
coordinate increment.  Note we use units of kHz whereas the spectral
coordinate is currently expressed in units of Hz.  We then set the
increment for the spectral coordinate.  We then recover the increment
again; you can see 4kHz has been converted to 4000Hz.  We also show
how to set the increment using a string interface.

setlineartransform(type='', value='')

This function set the linear transform component. For Stokes Coordinates this function will return T but do nothing.

You can recover the current linear transform with function lineartransform.

Parameters

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular”. Leave empty for all.

• value (variant='') - Linear transform

Returns

bool

Examples

#
print "\t----\t setlineartransform Ex 1 \t----"
csys = cs.newcoordsys(spectral=True, linear=3)
xf = csys.lineartransform('lin')
print xf
#[(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]
xf[0]=list(xf[0])
xf[0][1]=0.01
#xf[0]=tuple(xf[0])
csys.setlineartransform('lin',xf)
print csys.lineartransform('lin')
#[(1.0, 0.01, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]

setnames(value='', type='')

Each axis associated with the Coordinate System has a name. It isn’t used in any fundamental way.

This function allows you to set new axis names.

You can set the names either for all axes (type=unset) or for just the axes associated with a particular coordinate type.

You can recover the current axis names with function names.

Parameters

• value (stringVec='') - Names

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular” or leave empty for all

Returns

bool

Examples

#
print "\t----\t setnames Ex 1 \t----"
csys = cs.newcoordsys(spectral=True, linear=2)
csys.setnames(value="a b c")
print csys.names()
#['a', 'b', 'c']
csys.setnames("flying fish", 'lin')
print csys.names()
#['a', 'flying', 'fish']
#

setobserver(value='')

If you want to grab all the glory, or transfer the blame, this function sets a new observer of the observation. You can get the current observer with function observer. The observer’s name is not fundamental to the Coordinate System !

Parameters

• value (string='') - New observer

Returns

bool

Examples

#
print "\t----\t setobserver Ex 1 \t----"
csys = cs.newcoordsys()
print csys.observer()
#Karl Jansky 
csys.setobserver('Ronald Biggs')
print csys.observer()
#Ronald Biggs 
#

setparentname(imagename='')

Set the parent image name (normally not needed by end-users)

Parameters

• imagename (string='') - String named parent image

Returns

bool

setprojection(type='', parameters=[-1])

If the Coordinate System contains a direction coordinate, this function can be used to set the projection. For discussion about celestial coordinate systems, including projections, see the papers by Mark Calabretta and Eric Greisen. The initial draft from 1996 (implemented in ) can be found .

You can use the function projection to find out all the possible types of projection. You can also use it to find out how many parameters you need to describe a particular projection. See Calabretta and Greisen for details about those parameters (see section 4 of their paper); in FITS terms these parameters are what are labelled as PROJP.

Some brief help here on the more common projections in astronomy.

• SIN has either 0 parameters or 2. For coplanar arrays like East-West arrays, one can use what is widely termed the NCP projection. This is actually a SIN projection where the parameters are 0 and \(1/tan(\delta_0)\) where \(\delta_0\) is the reference declination. Images made from the ATNF’s Compact Array with  will have such a projection. Otherwise, the SIN projection requires no parameters (but you can give it two each of which is zero if you wish).

• TAN is used widely in optical astronomy. It requires 0 parameters.

• ZEA (zenithal equal area) is used widely in survey work. It requires 0 parameters.

If the Coordinate System does not contain a direction coordinate, an exception is generated.

Parameters

• type (string='') - Type of projection

• parameters (doubleVec=[-1]) - Projection parameters

Returns

bool

Examples

#
print "\t----\t Ex setprojection 1 \t----"
im = ia.maketestimage('cena',overwrite=True)
csys = ia.coordsys()
print csys.projection()
#{'type': 'SIN', 'parameters': array([ 0.,  0.])}
print csys.projection('ZEA')
#{'nparameters': 0}
csys.setprojection('ZEA')
im2 = ia.regrid('cena.zea', csys=csys.torecord(), overwrite=True)
#


We change the projection of an image from SIN to 
ZEA (which requires no parameters).

setreferencecode(value='', type='direction', adjust=True)

This function sets the reference code for the specified coordinate type. Examples of reference codes are B1950 and J2000 for direction coordinates, or LSRK and BARY for spectral coordinates.

You must specify type, selecting from ’direction’, or ’spectral’ (the first two letters will do). If the Coordinate System does not contain a coordinate of the type you specify, an exception is generated.

Specify the new code with argument value. To see the list of possible codes, use the function referencecode (see example).

If adjust is T, then the reference value is recomputed. This is invariably the correct thing to do. If adjust is F, then the reference code is simply overwritten; do this very carefully.

Parameters

• value (string='') - Reference code

• type (string='direction') - Coordinate type: direction or spectral

• adjust (bool=True) - Adjust reference value ?

Returns

bool

Examples

#
print "\t----\t Ex setreferencecode 1 \t----"
csys = cs.newcoordsys(direction=True)
clist = csys.referencecode('dir', True)      # See possibilities
print clist
#['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'B1950_VLA', 'BMEAN', 'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO', 'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC', 'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS', 'MERCURY', 'VENUS', 'MARS', 'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE', 'PLUTO', 'SUN', 'MOON', 'COMET']

print cs.referencecode('dir')
#J2000
cs.setreferencecode('B1950', 'dir', True)
#



In this example we first get the list of all possible reference codes
for a direction coordinate.  Then we set the actual reference code for the direction
coordinate in our Coordinate System.

setreferencelocation(pixel=[-1], world='-1', mask=[False])

This function sets the reference pixel and reference value to the specified values. The world coordinate can be specified in any of the formats that the output world coordinate is returned in by the toworld function.

You can specify a mask (argument mask) indicating which pixel axes are set (T) and which are left unchanged (F). This function will refuse to change the reference location of a Stokes axis (gets you into trouble otherwise).

This function can be rather useful when regridding images. It allows you to keep easily a particular feature centered in the regridded image.

Parameters

• pixel (intVec=[-1]) - New reference pixel. Defaults to old reference pixel.

• world (variant='-1') - New reference value. Defaults to old reference value.

• mask (boolVec=[False]) - Indicates which axes to center. Defaults to all.

Returns

bool

Examples

#
print "\t----\t setreferencelocation Ex 1 \t----"
csys = cs.newcoordsys(linear=2)
print csys.referencepixel()
#[0.0, 0.0]
print csys.referencevalue()
#{'numeric': array([ 0.,  0.])}
w = csys.toworld([19,19], format='n')
shp = [128,128]
p = [64, 64]
csys.setreferencelocation (pixel=p, world=w)
print csys.referencepixel()
#[64.0, 64.0]  
print csys.referencevalue()
#{'numeric': array([ 19.,  19.])}
#

setreferencepixel(value='', type='')

Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel). These are used in the mapping from pixel to world coordinate.

This function allows you to set a new reference pixel. You should not do this on “stokes” axes unless you are an adept or a big risk taker.

You can set the reference pixel either for all axes (type=unset) or for just the axes associated with a particular coordinate type.

Bear in mind, that if your Coordinate System came from a real image, then the reference pixel is special and you should not change it for Direction Coordinates.

You can recover the current reference pixel with function referencepixel.

Parameters

• value (doubleVec='') - Reference pixel

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular” or leave unset for all

Returns

bool

Examples

#
print "\t----\t setreferencepixel Ex 1 \t----"
csys = cs.newcoordsys(spectral=True, linear=2)
csys.setreferencepixel(value=[1.0, 2.0, 3.0])
print csys.referencepixel()
#[1.0, 2.0, 3.0]
csys.setreferencepixel([-1, -1], 'lin')
print csys.referencepixel()
#[1.0, -1.0, -1.0]
#

setreferencevalue(value='', type='')

Each axis associated with the Coordinate System has a reference value, reference pixel and an increment (per pixel). These are used in the mapping from pixel to world coordinate.

This function allows you to set a new reference value. You should not do this on “stokes” axes unless you are an adept or a big risk taker.

You may supply the reference value in all of the formats described in the discussion.

You can recover the current reference value with function referencevalue.

Note that the value argument should be one of the specified possibilitioes. Especially a measure will be accepted, but will have a null effect, due to the interpretation as a generic record.

Parameters

• value (variant='') - Reference value

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabular” or leave empty for all.

Returns

bool

Examples

#
print "\t----\t setreferencevalue Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
rv = csys.referencevalue(format='q')
print rv
#{'quantity': {'*1': {'value': 0.0, 'unit': "'"},
# '*2': {'value': 0.0, 'unit': "'"}, '*3': {'value': 1415000000.0, 'unit': 'Hz'}}}
rv2 = rv['quantity']['*3']
rv2['value'] = 2.0e9
print rv2
#{'value': 2000000000.0, 'unit': 'Hz'}
csys.setreferencevalue(type='spec', value=rv2)
print csys.referencevalue(format='n')
#{'numeric': array([  0.00000000e+00,   0.00000000e+00,   2.00000000e+09])}
#
# To set a new direction reference value, the easiest way, given a
# direction measure dr would be:
dr = me.direction('j2000','30deg','40deg')
# SHOULD BE SIMPLIFIED!!!
newrv=csys.referencevalue(format='q')
newrv['quantity']['*1']=dr['m0']
newrv['quantity']['*2']=dr['m1']
csys.setreferencevalue(value=newrv)
print csys.referencevalue(format='q')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': 1800.0, 'unit': "'"},
#              '*2': {'value': 2399.9999999999995, 'unit': "'"},
#              '*3': {'value': 1415000000.0, 'unit': 'Hz'}}}
#

setrestfrequency(value='', which=0, append=False)

If the Coordinate System contains a spectral coordinate, then it has a rest frequency. In fact, the spectral coordinate can hold several rest frequencies (to handle for example, an observation where the band covers many lines), although only one is active (for velocity conversions) at a time.

This function allows you to set new rest frequencies. You can provide the rest frequency as a quantity, or as a quantity string, or a double (units of current rest frequency assumed).

You specify whether the list of frequencies will be appended to the current list or whether it will replace that list. You must select which of the frequencies will become the active one. By default its the first in the list. The index refers to the final list (either appended or replaced).

You can recover the current rest frequencies with restfrequency.

If the Coordinate System does not contain a frequency coordinate, an exception is generated.

Parameters

• value (variant='') - New rest frequencies

• which (int=0) - Which is the active rest frequency

• append (bool=False) - Append this list or overwrite ?

Returns

bool

Examples

#
print "\t----\t setrestfrequency Ex 1 \t----"
csys = cs.newcoordsys(spectral=True)
print csys.restfrequency()
#{'value': array([  1.42040575e+09]), 'unit': 'Hz'}
csys.setrestfrequency(qa.quantity('1.4GHz'))
print csys.restfrequency()
#{'value': array([  1.40000000e+09]), 'unit': 'Hz'}
csys.setrestfrequency(1.3e9)
print csys.restfrequency()
#{'value': array([  1.30000000e+09]), 'unit': 'Hz'}
csys.setrestfrequency (value=[1.2e9, 1.3e9], which=1)
print csys.restfrequency()
#{'value': array([  1.30000000e+09,   1.20000000e+09]), 'unit': 'Hz'}
csys.setrestfrequency (qa.quantity([1,2],'GHz'), which=3, append=True)
print csys.restfrequency()
#{'value': array([  2.00000000e+09,   1.20000000e+09,   1.30000000e+09,
#         1.00000000e+09]), 'unit': 'Hz'}
csys.setrestfrequency ("1.4E9Hz 1667MHz")
print csys.restfrequency()
#{'value': array([  1.40000000e+09,   1.66700000e+09]), 'unit': 'Hz'}
#

setspectral(refcode='', restfreq='', frequencies='1GHz', doppler='', velocities='1km/s')

When you construct a Coordsys , if you include a Spectral Coordinate, it will be linear in frequency. This function allows you to replace the Spectral Coordinate by a finite table of values. Coordinate conversions between pixel and world are then done by interpolation.

You may specify either a vector of frequencies or velocities. If you specify frequencies, you can optionally specify a (new) reference code (see function setreferencecode for more details) and rest frequency (else the existing ones will be used).

If you specify velocities, you can optionally specify a (new) reference code and rest frequency (else the existing ones will be used). You must also give the doppler type (see function summary for more details). The velocities are then converted to frequency for creation of the Spectral Coordinate (which is fundamentally described by frequency).

You may specify the rest frequency as a Quantum or a double (native units of Spectral Coordinate used).

Parameters

• refcode (string='') - Reference code. Leave unset for no change.

• restfreq (variant='') - Rest frequency. Leave unset for no change.

• frequencies (variant='1GHz') - Vector of frequencies. Leave unset for no change.

• doppler (string='') - Doppler type. Leave unset for no change.

• velocities (variant='1km/s') - Vector of velocities types. Leave unset for no change.

Returns

bool

Examples

print "\t----\t setspectral Ex 1 \t----"
csys = cs.newcoordsys(spectral=True);
f1 = [1,1.01,1.03,1.4]
fq = qa.quantity(f1, 'GHz')
csys.setspectral(frequencies=fq)
v = csys.frequencytovelocity(f1, 'GHz', 'radio', 'km/s')
print 'v=', v
#v= [88731.317461076716, 86620.706055687479, 82399.483244909003, 4306.8612455073862]
vq = qa.quantity(v, 'km/s')
csys.setspectral(velocities=vq, doppler='radio')
f2 = csys.velocitytofrequency(v, 'GHz', 'radio', 'km/s')
print 'f1 = ', f1
#f1 =  [1, 1.01, 1.03, 1.3999999999999999]
print 'f2 = ', f2
#f2 =  [1.0, 1.01, 1.03, 1.3999999999999999]

We make a linear Spectral Coordinate.  Then overwrite it with
a list of frequenices.  Convert those values to velocity,
then overwrite the coordinate starting with a list of
velocities. Then convert the velocities to frequency
and show we get the original result.

setstokes(stokes='')

If the Coordinate System contains a Stokes Coordinate, this function allows you to change the Stokes types defining it. If there is no Stokes Coordinate, an exception is generated.

See the coordsys constructor to see the possible Stokes types you can set.

You can set the Stokes types with function setstokes.

Parameters

• stokes (stringVec='') - Stokes types

Returns

bool

Examples

#
print "\t----\t setstokes Ex 1 \t----"
csys = cs.newcoordsys(stokes="I V")
print csys.stokes()
#['I', 'V']
csys.setstokes("XX RL")
print csys.stokes()
#['XX', 'RL']
#

settabular(pixel=[-1], world=[-1], which=0)

When you construct a Coordsys , if you include a Tabular Coordinate, it will be linear. This function allows you to replace the Tabular Coordinate by a finite table of values. Coordinate conversions between pixel and world are then done by interpolation (or extrapolation beyond the end). The table of values must be at least of length 2 or an exception will occur.

You may specify a vector of pixel and world values (in the current units of the Tabular Coordinate). These vectors must be the same length. If you leave one of them unset, then the old values are used, but again, ultimately, the pixel and world vectors must be the same length.

The new reference pixel will be the first pixel value. The new reference value will be the first world value.

Presently, there is no way for you to recover the lookup table once you have set it.

If you have more than one Tabular Coordinate, use argument which to specify which one you want to modify.

Parameters

• pixel (doubleVec=[-1]) - Vector of (0-rel) pixel values. Default is no change.

• world (doubleVec=[-1]) - Vector of world values. Default is no change.

• which (int=0) - Which Tabular coordinate

Returns

bool

Examples

#
print "\t----\t settabular Ex 1 \t----"
csys = cs.newcoordsys(tabular=True);
print csys.settabular (pixel=[1,10,15,20,100], world=[10,20,50,100,500])
#True
#


We make a linear Tabular Coordinate.  Then overwrite it with
a non-linear list of pixel and world values.

settelescope(value='')

This function sets a new telescope of the observation. The telescope position may be needed for reference code conversions; this is why it is maintained in the Coordinate System. So it is fundamental to the Coordinate System and should be correct.

You can find a list of the observatory names know to  with the Measures obslist function.

You can get the current telescope with function telescope.

Parameters

• value (string='') - New telescope

Returns

bool

Examples

#
print "\t----\t settelescope Ex 1 \t----"
csys = cs.newcoordsys()
print csys.telescope()
#ATCA
csys.settelescope('VLA')
print csys.telescope()
#VLA
csys.settelescope('The One In My Backyard')
#Tue Mar 6 21:41:24 2007      WARN coordsys::settelescope:
#This telescope is not known to the casapy system
#You can request that it be added
print me.obslist()
#ALMA ARECIBO ATCA BIMA CLRO DRAO DWL GB GBT GMRT IRAM PDB IRAM_PDB
# JCMT MOPRA MOST NRAO12M NRAO_GBT PKS SAO SMA VLA VLBA WSRT
#

setunits(value='', type='', overwrite=False, which=-10)

Each axis associated with the Coordinate System has a unit. This function allows you to set new axis units.

You can set the units either for all axes (type=unset) or for just the axes associated with a particular coordinate type.

In general, the units must be consistent with the old units. When you change the units, the increment and reference value will be adjusted appropriately. However, for a linear or tabular coordinate, and only when you specify type=’linear’ or type=’tabular’ (i.e. you supply units only for the specified linear of tabular coordinate), and if you set overwrite=T, you can just overwrite the units with no further adjustments. Otherwise, the overwrite argument will be silently ignored. Use argument which to specify which coordinate if you have more than one of the specified type.

You can recover the current axis units with function units.

Parameters

• value (stringVec='') - Units

• type (string='') - Coordinate type: “direction”, “stokes”, “spectral”, “linear”, “tabules” or leave unset for all.

• overwrite (bool=False) - Overwrite linear or tabular coordinate units?

• which (int=-10) - Which coordinate if more than one of same type. Default is first.

Returns

bool

Examples

#
print "\t----\t setunits Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
csys.summary()
csys.setunits(value="deg rad mHz");
csys.summary()
#

stokes()

If the Coordinate System contains a Stokes Coordinate, this function recovers the Stokes types defining it. If there is no Stokes Coordinate, an exception is generated.

You can set the Stokes types with function setstokes.

subimage(originshft='', newshape='')

You can convert a Coordinate System to another coordinatesystem applicable to a subImage. The newshape does not matter as this is the coordinatesystem not the image except for Stokes axis; therefore you can ignore newshape except when your sub-image you are considering has only a section of your original Stokes axis.

Parameters

• originshft (variant='') - The shift value from original reference (vector of values in pixels)

• newshape (intVec='') - The new shape of the image it will applicable to (pixel shape)

Returns

record

Examples

#
print "\t----\t subimage Ex 1 \t----"
ia.open('original.image')
csys = ia.coordsys()
imshape=ia.shape()
#want to make an empty sub image of the 11th channel
#keeping other reference pixel as is
refshft=[0,0,0,10]
subcoordsysrec=csys.subimage(neworigin=refshft)
imshape[3]=1
ia.fromshape(outfile='Eleventh_chan_template.image', shape=imshape, csys=subcoordsysrec)

summary(doppler='RADIO', list=True)

This function summarizes the information contained in the Coordinate System.

For spectral coordinates, the information is listed as a velocity as well as a frequency. The argument doppler allows you to specify what doppler convention it is listed in. You can choose from radio, optical and beta. Alternative names are z for optical, and relativistic for beta. The default is radio. The definitions are

• radio: \(1 - F\)

• optical: \(-1 + 1/F\)

• beta: \((1 - F^2)/(1 + F^2)\)

where \(F = \nu/\nu_0\) and \(\nu_0\) is the rest frequency. If the rest frequency has not been set in your image, you can set it with the function setrestfrequency.

These velocity definitions are provided by the measures system via the Doppler measure (see example).

If you set list=F, then the summary will not be written to the global logger. However, the return value will be a vector of strings holding the summary information, one string per line of the summary.

For direction and spectral coordinates, the reference frame (e.g. J2000 or LSRK) is also listed. Along side this, in parentheses, will be the conversion reference frame as well (if it is different from the native reference frame). See function setconversion to see what this means.

Parameters

• doppler (string='RADIO') - List velocity information with this doppler definition

• list (bool=True) - List to global logger

Returns

stringVec

Examples

#
print "\t----\t summary Ex 1 \t----"
d = me.doppler('beta')
print me.listcodes(d)
#[normal=RADIO Z RATIO BETA GAMMA OPTICAL TRUE RELATIVISTIC, extra=] 
csys = cs.newcoordsys(direction=True, spectral=True)
print csys.summary(list=False)
#
#Direction reference : J2000
#Spectral  reference : LSRK
#Velocity  type      : RADIO
#Rest frequency      : 1.42041e+09 Hz
#Telescope           : ATCA
#Observer            : Karl Jansky
#Date observation    : 2007/07/14/04:49:31
#
#Axis Coord Type      Name             Proj   Coord value at pixel    Coord incr Units
#-------------------------------------------------------------------------------------
#0    0     Direction Right Ascension   SIN  00:00:00.000     0.00 -6.000000e+01 arcsec
#1    0     Direction Declination       SIN +00.00.00.000     0.00  6.000000e+01 arcsec
#2    1     Spectral  Frequency                 1.415e+09     0.00  1.000000e+03 Hz
#                     Velocity                    1140.94     0.00 -2.110611e-01 km/s
#
#

telescope()

This function returns the telescope contained in the Coordinate System as a simple string.

The telescope position may be needed for reference code conversions; this is why it is maintained in the Coordinate System.

The conversion from string to position is done with Measures observatory. The example shows how.

toabs(value='', isworld=-1)

This function converts a relative coordinate to an absolute coordinate. The coordinate may be a pixel coordinate or a world coordinate.

If the coordinate is a pixel coordinate, it is supplied as a numeric vector. If the coordinate is a world coordinate, you may give it in all of the formats described in the discussion.

If the coordinate value is supplied by a Coordsys  function (e.g. toworld) then the coordinate ’knows’ whether it is world or pixel (and absolute or relative). However, you might supply the value from some other source as a numeric vector (which could be world or pixel) in which case you must specify whether it is a world or pixel coordinate via the isworld argument.

Parameters

• value (variant='') - Relative coordinate

• isworld (int=-1) - Is coordinate world or pixel? Default is unset.

Returns

record

Examples

#
print "\t----\t toabs Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
aw = csys.toworld([100,100,24], 's')
rw = csys.torel(aw)
aw2 = csys.toabs(rw)
print aw
#{'ar_type': 'absolute', 'pw_type': 'world', 
# 'string': array(['23:53:19.77415678', '+01.40.00.84648186',
#                  '1.41502400e+09 Hz'], dtype='|S19')}
print rw
#{'ar_type': 'relative', 'pw_type': 'world',
# 'string': array(['-6.00084720e+03 arcsec', '6.00084648e+03 arcsec',
#                  '2.40000000e+04 Hz'], dtype='|S23')}
print aw2
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'string': array(['23:53:19.77415672', '+01.40.00.84648000',
#                  '1.41502400e+09 Hz'], dtype='|S19')}
#



This example uses world coordinates.

toabsmany(value='', isworld=-1)

This function converts many relative coordinates to absolute. It exists so you can efficiently make many conversions (which would be rather slow if you did them all with toabs). Because speed is the object, the interface is purely in terms of numeric matrices, rather than being able to accept strings and quanta etc. like toabs can.

When dealing with world coordinates, the units of the numeric values must be the native units, given by function units.

Parameters

• value (variant='') - Relative coordinates

• isworld (int=-1) - Is coordinate world or pixel? Default is unset.

Returns

record

Examples

#
print "\t----\t toabsmany Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)    # 3 axes
rv = csys.referencevalue();                 # reference value
w = csys.torel(rv)                          # make relative
inc = csys.increment();                     # increment
off=[]
for idx in range(100):
  off.append(inc['numeric'][2]*idx)         # offset for third axis
wrel = ia.makearray(0,[3,100])              # 100 conversions each of length 3
for i in range(3):
  for j in range(100):
    wrel[i][j]=w['numeric'][i]
for j in range(100):
  wrel[2][j] += off[j]                      # Make spectral axis values change
wabs  = csys.toabsmany (wrel, T)['numeric'] # Convert
print wabs[0][0],wabs[1][0],wabs[2,0]       # First absolute coordinate
#0.0 0.0 1415000000.0
print wabs[0][99],wabs[1][99],wabs[2][99]   # 100th absolute coordinate
#0.0 0.0 1415099000.0
#


This example uses world coordinates.

topixel(value='')

This function converts between world (physical) coordinate and absolute pixel coordinate (0-rel).

The world coordinate can be provided in one of four formats via the argument world. These match the output formats of function toworld.

If you supply fewer world values than there are axes in the Coordinate System, your coordinate vector will be padded out with the reference value for the missing axes. Excess values will be silently ignored.

You may supply the world coordinate in all of the formats described in the discussion.

Parameters

• value (variant='') - Absolute world coordinate

Returns

record

Examples

#
print "\t----\t topixel Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True, stokes="I V", linear=2)
w = csys.toworld([-2,2,1,2,23,24], 'n')
print csys.topixel(w)
#{'ar_type': 'absolute', 'pw_type': 'pixel',
# 'numeric': array([ -2.,   2.,   1.,   2.,  23.,  24.])}
w = csys.toworld([-2,2,1,2,23,24], 'q')
print csys.topixel(w)
#{'ar_type': 'absolute', 'pw_type': 'pixel',
# 'numeric': array([ -2.,   2.,   1.,   2.,  23.,  24.])}
w = csys.toworld([-2,2,1,2,23,24], 'm')
print csys.topixel(w)
#{'ar_type': 'absolute', 'pw_type': 'pixel',
# 'numeric': array([ -2.,   2.,   1.,   2.,  23.,  24.])}
w = csys.toworld([-2,2,1,2,23,24], 's')
print cs.topixel(w)
#{'ar_type': 'absolute', 'pw_type': 'pixel',
# 'numeric': array([ -2.,   2.,   1.,   2.,  23.,  24.])}
w = csys.toworld([-2,2,1,2,23,24], 'mnq')
print cs.topixel(w)                            
#{'ar_type': 'absolute', 'pw_type': 'pixel',
# 'numeric': array([ -2.,   2.,   1.,   2.,  23.,  24.])}
#

topixelmany(value='')

This function converts many absolute world coordinates to pixel coordinates. It exists so you can efficiently make many conversions (which would be rather slow if you did them all with topixel). Because speed is the object, the interface is purely in terms of numeric matrices, rather than being able to accept strings and quanta etc. like topixel can.

The units of the numeric values must be the native units, given by function units.

Parameters

• value (variant='') - Absolute world coordinates

Returns

record

Examples

#
print "\t----\t topixelmany Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)    # 3 axes
rv = csys.referencevalue();                 # reference value
inc = csys.increment();                     # increment
off = []
for idx in range(100):
  off.append(inc['numeric'][2] * idx)       # offset for third axis
wabs = ia.makearray(0, [3,100])             # 100 conversions each of length 3
for i in range(3):
  for j in range(100):
    wabs[i][j]=rv['numeric'][i]
for j in range(100):
  wabs[2][j] += off[j]                      # Make spectral axis values change
pabs  = csys.topixelmany (wabs)['numeric']; # Convert
print pabs[0][0], pabs[1][0], pabs[1][2]    # First absolute pixel coordinate
#0.0 0.0 0.0
print pabs[0][99], pabs[1][99], pabs[2][99] # 100th absolute pixel coordinate
#0.0 0.0 99.0
#

torecord()

You can convert a Coordinate System to a record with this function. There is also fromrecord to set a Coordinate System from a record.

These functions allow Coordsys  to be used as parameters in the methods of other tools.

torel(value='', isworld=-1)

This function converts an absolute coordinate to a relative coordinate. The coordinate may be a pixel coordinate or a world coordinate.

Relative coordinates are relative to the reference pixel (pixel coordinates) or the reference value (world coordinates) in the sense \(relative = absolute - reference\).

If the coordinate is a pixel coordinate, it is supplied as a numeric vector. If the coordinate is a world coordinate, you may give it in all of the formats described in the discussion.

If the coordinate value is supplied by a Coordsys  function (e.g. toworld) then the coordinate ’knows’ whether it is world or pixel (and absolute or relative). However, you might supply the value from some other source as a numeric vector (which could be world or pixel) in which case you must specify whether it is a world or pixel coordinate via the isworld argument.

Parameters

• value (variant='') - Absolute coordinate

• isworld (int=-1) - Is coordinate world or pixel? Default is unset.

Returns

record

Examples

#
print "\t----\t torel Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
aw = csys.toworld([99,99,23], 's')
rw = csys.torel(aw)
aw2 = csys.toabs(rw)
print aw
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'string': array(['23:53:23.78086843', '+01.39.00.82133427',
# '1.41502300e+09 Hz'], dtype='|S19')}
print rw
#{'ar_type': 'relative', 'pw_type': 'world',
# 'string': array(['-5.94082202e+03 arcsec', '5.94082133e+03 arcsec',
# '2.30000000e+04 Hz'], dtype='|S23')}
print aw2
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'string': array(['23:53:23.78086818', '+01.39.00.82133000',
# '1.41502300e+09 Hz'], dtype='|S19')}
#



This example uses world coordinates.



#
print "\t----\t torel Ex 2 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
ap = csys.topixel()           # Reference value
rp = csys.torel(ap)
ap2 = csys.toabs(rp)
print ap
#{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 0.,  0.,  0.])}
print rp
#{'ar_type': 'relative', 'pw_type': 'pixel', 'numeric': array([ 0.,  0.,  0.])}
print ap2
#{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 0.,  0.,  0.])}
#


This example uses pixel coordinates.

torelmany(value='', isworld=-1)

This function converts many absolute coordinates to relative. It exists so you can efficiently make many conversions (which would be rather slow if you did them all with torel). Because speed is the object, the interface is purely in terms of numeric matrices, rather than being able to accept strings and quanta etc. like torel can.

When dealing with world coordinates, the units of the numeric values must be the native units, given by function units.

Parameters

• value (variant='') - Absolute coordinates

• isworld (int=-1) - Is coordinate world or pixel? Default is unset.

Returns

record

Examples

#
print "\t----\t torelmany Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)    # 3 axes
w = csys.referencevalue();                  # reference value
inc = csys.increment();                     # increment
off = []
for idx in range(100):
  off.append(inc['numeric'][2] * idx)       # offset for third axis
wabs = ia.makearray(0, [3,100])             # 100 conversions each of length 3
for i in range(3):
  for j in range(100):
    wabs[i][j] = w['numeric'][i]
for j in range(100):
  wabs[2][j] += off[j]                      # Make spectral axis values change
wrel  = cs.torelmany (wabs, T)['numeric']   # Convert
print wrel[0][0], wrel[1][0], wrel[2][0]    # First relative coordinate
#0.0 0.0 0.0
print wrel[0][99], wrel[1][99], wrel[2][99] # 100th relative coordinate
#0.0 0.0 99000.0
#


This example uses world coordinates.

toworld(value='', format='n')

This function converts between absolute pixel coordinate (0-rel) and absolute world (physical coordinate).

If you supply fewer pixel values than there are axes in the Coordinate System, your coordinate vector will be padded out with the reference pixel for the missing axes. Excess values will be silently ignored.

You may ask for the world coordinate in all of the formats described in the regarding the formatting possibilities available via argument format.

Parameters

• value (variant='') - Absolute pixel coordinate. Default is reference pixel.

• format (string='n') - Format string: combination of “n”, “q”, “s”, “m”

Returns

record

Examples

#
print "\t----\t toworld Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
print csys.toworld([-3,1,1], 'n')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'numeric': array([  3.00000051e+00,   1.00000001e+00,   1.41500100e+09])}
print csys.toworld([-3,1,1], 'q')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'quantity': {'*1': {'value': 3.0000005076962117, 'unit': "'"},
#              '*2': {'value': 1.0000000141027674, 'unit': "'"},
#              '*3': {'value': 1415001000.0, 'unit': 'Hz'}}}
print csys.toworld([-3,1,1], 'm')
#{'ar_type': 'absolute', 'pw_type': 'world', 'measure':
# {'spectral': {'radiovelocity': {'type': 'doppler', 'm0': {'value': 1140733.0762829871, 'unit': 'm/s'}, 'refer': 'RADIO'},
#             'opticalvelocity': {'type': 'doppler', 'm0': {'value': 1145090.2316004676, 'unit': 'm/s'}, 'refer': 'OPTICAL'},
#                 'frequency': {'type': 'frequency', 'm0': {'value': 1415001000.0, 'unit': 'Hz'}, 'refer': 'LSRK'},
#                'betavelocity': {'type': 'doppler', 'm0': {'value': 1142903.3485169839, 'unit': 'm/s'}, 'refer': 'TRUE'}},
# 'direction': {'type': 'direction', 'm1': {'value': 0.0002908882127680503, 'unit': 'rad'},
#                                    'm0': {'value': 0.00087266477368000634, 'unit': 'rad'}, 'refer': 'J2000'}}}
print csys.toworld([-3,1,1], 's')
#{'ar_type': 'absolute', 'pw_type': 'world',
# 'string': array(['00:00:12.00000203', '+00.01.00.00000085', '1.41500100e+09 Hz'], dtype='|S19')}
#

toworldmany(value='')

This function converts many absolute pixel coordinates to world coordinates. It exists so you can efficiently make many conversions (which would be rather slow if you did them all with toworld). Because speed is the object, the interface is purely in terms of numeric matrices, rather than being able to produce strings and quanta etc. like toworld can.

The units of the output world values are the native units given by function units.

Parameters

• value (variant='') - Absolute pixel coordinates

Returns

record

Examples

#
print "\t----\t toworldmany Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)    # 3 axes
rp = csys.referencepixel()['numeric'];            # reference pixel
pabs = ia.makearray(0,[3,100])              # 100 conversions each of length 3
for i in range(3):
  for j in range(100):
    pabs[i][j] = rp[i]
for ioff in range(100):                     # offset for third axis
  pabs[2][ioff] += ioff;                    # Make spectral axis values change
wabs  = csys.toworldmany (pabs)['numeric']; # Convert
print wabs[0][0], wabs[1][0], wabs[2][0]    # First absolute pixel coordinate
#0.0 0.0 1415000000.0
print wabs[0][99], wabs[1][99], wabs[2][99] # 100th absolute pixel coordinate
#0.0 0.0 1415099000.0
#

transpose(order='')

This method transposes the axes (both world and pixel) in the coordinate system. You specify the new order of the axes in terms of their old order, so eg order=[1,0,3,2] means reorder the axes so that the zeroth axis becomes the first axis, the first axis becomes the zeroth axis, the second axis becomes the third axis, and the third axis becomes the second axis.

Parameters

• order (intVec='') - New axis order

Returns

bool

Examples

csys = cstool()

# Create a coordinate system with axes, RA, Dec, Stokes, and Frequency
csys.newcoordsys(direction=True, spectral=True, stokes=["I","Q"])

# transpose the axes so that the order is RA, Dec, Frequency, and Stokes
csys.transpose(order=[0, 1, 3, 2])

type()

This function returns the string ‘coordsys’.

units(type='')

Each axis associated with the Coordinate System has a unit. This function returns those units (in world axis order).

You can recover the units either for all coordinates (leave type unset) or for a specific coordinate type (mimumum match of the allowed types will do). If you ask for a non-existent coordinate an exception is generated.

You can set the units with function setunits.

Parameters

• type (string='') - Coordinate type: ‘direction’, ‘stokes’, ‘spectral’, ‘linear’ or leave unset for all

Returns

stringVec

Examples

#
print "\t----\t units Ex 1 \t----"
csys = cs.newcoordsys(direction=True, spectral=True)
print csys.units()
#["'", "'", 'Hz']
print csys.units('spec')
#Hz
#

velocitytofrequency(value='', frequnit='', doppler='radio', velunit='km/s')

This function converts velocities to frequencies.

The input velocities are specified via a vector of numeric values, a specified unit (velunit), and a velocity doppler definition (doppler).

The frequencies are returned in a vector for which you specify the units (frequnit). If you don’t give the unit, it is assumed that the units are those given by function units for the spectral coordinate.

This function will return a fail if there is no spectral coordinate in the Coordinate System. See also the function frequencytovelocity.

Parameters

• value (doubleVec='') - Velocity to convert

• frequnit (string='') - Unit of output frequencies. Default is intrinisic units.

• doppler (string='radio') - Velocity doppler definition

• velunit (string='km/s') - Unit of input velocities

Returns

doubleVec

Examples

#
print "\t----\t velocitytofrequency Ex 1 \t----"
ia.fromshape('hcn.cube',[64,64,32,4], overwrite=True)
csys = ia.coordsys()
rtn = csys.findcoordinate('spectral')   # Find spectral axis
pixel = csys.referencepixel();          # Use reference pixel for non-spectral
pa = rtn['pixel']
wa = rtn['world']
nFreq = ia.shape()[pa]                  # Length of spectral axis
freq = []
for i in range(nFreq):
  pixel[pa] = i;                        # Assign value for spectral axis of pixel coordinate
  w = csys.toworld(value=pixel, format='n')# Convert pixel to world
  freq.append(w['numeric'][wa])         # Fish out frequency
print "freq=", freq
vel = csys.frequencytovelocity(value=freq, doppler='optical', velunit='km/s')
freq2 = csys.velocitytofrequency(value=vel, doppler='optical', velunit='km/s')
print "vel=",vel
print "freq2=",freq2
csys.done()
#
exit() # This is last example so exit casapy if you wish.
#



In this example, we find the optical velocity in km/s of every pixel
along the spectral axis of our image.  First we  obtain the Coordinate
System from the image.  Then we find which axis of the Coordinate System
(image) pertain to the spectral coordinate.  Then we loop over each
pixel of the spectral axis, and convert a pixel coordinate (one for each
axis of the image) to world.  We obtain the value for the spectral axis
from that world vector, and add it to the vector of frequencies.  Then
we convert that vector of frequencies to velocity.  Then we convert it
back to frequency.  They better agree.