All pixels coordinates are zero relative.
The fundamental operations available to the user of a CoordinateSystem are:
Note that all the knowledge to do with removing and transposing axes is maintained by the CoordinateSystem. The individual Coordinates, of which it is made, know nothing about this.
Although the CoordinateSystem exists in the absence of an image, the usual place you will find one is attached to an object derived from ImageInterface such as PagedImage. When you do so, the physical (or pixel) axes in the image map one to one with the pixel axes contained in the CoordinateSystem. It cannot be any other way as when you create a PagedImage, it is checked that there are equal numbers of image and CoordinateSystem pixel axes. It is up to the creator of the PagedImage to make sure that they are in the correct order.
However, the CoordinateSystem may have more world axes than pixel axes because it is possible to remove a pixel axis but not its associated world axis (for example for a moment image). Now, if you use the CoordinateSystem functions referencePixel and referenceValue, you will find the vector of reference values will have more values than the vector of reference pixels, if a pixel axis has been removed but not the world axis. You must use the ancilliary functions provided to find out what is where.
Let's consider an example where a CoordinateSystem consisted of a DirectionCoordinate and a SpectralCoordinate. Let us say that the first two pixel axes of the image associate (roughly of course because lines of constant RA and DEC are not parallel with the pixel coordinates) with the DirectionCoordinate (RA and DEC say) and the third pixel axis is the SpectralCoordinate. Now imagine we collapse the image along the second pixel axis (roughly, the DEC axis). For the output image, we remove the second pixel axis from the CoordinateSystem, but leave the world axis intact. This enables us to still be able to make coordinate conversions for the first (roughly RA) pixel axis. Thus, CoordinateSystem::referenceValue would return a Vector of length 3 (for RA, DEC and spectral), but CoordinateSystem::referencePixel would return a vector length 2 (for RA and spectral).
Now this CoordinateSystem has two Coordinates, a DirectionCoordinate and a SpectralCoordinate, and let us state that that is the order in which they exist in the CoordinateSystem (you can change them about if you wish); they are coordinates number 0 and 1. The DirectionCoordinate has two axes (RA and DEC) and the SpectralCoordinate has one axis. Only the CoordinateSystem knows about removed axes, the DirectionCoordinate itself is ignorant that it has been bisected. If you want to find out what axis in the Coordinate system is where, you can use the functions findPixelAxis or findWorldAxis.
If we asked the former to find pixel axis 0, it would tell us that the Coordinate number was 0 (the DirectionCoordinate) and that the axis in that coordinate was 0 (the first axis in a DirectionCoordinate is always longitude, the second always latitude). If we asked it to find pixel axis 1, it would tell us that the coordinate number was 1 (the SpectralCoordinate) and that the axis in that coordinate was 0 (there is only one axis in a SpectralCoordinate). If we asked for pixelAxis 2 that would generate an error because our squashed image only has 2 pixel axes.
Now, if we asked findWorldAxis similar questions, it would tell us that worldAxis 0 in the CoordinateSystem can be found in coordinate 0 (the DirectionCoordinate) in axis 0 of that DirectionCoordinate. Similarly, worldAxis 1 in the CoordinateSystem (which has not been removed) is in coordinate 0 (the DirectionCoordinate) in axis 1 of that Finally, worldAxis 2 in the CoordinateSystem is in coordinate 1 (the SpectralCoordinate) in axis 0 of that SpectralCoordinate.
Other handy functions are pixelAxes and worldAxes. These list the pixel and world axes in the CoordinateSystem for the specified coordinate. Thus, if we asked pixelAxes to find the pixel axes for coordinate 0 (the DirectionCoordinate) in the CoordinateSystem it would return a vector [0, -1] indicating the second axis of the DirectionCoordinate has been removed. However, the worldAxes function would return [0,1] as no world axis has been removed. Similarly, if operated on coordinate 1 (the SpectralCoordinate), pixelAxes would return [1] and worldAxes would return [2].
Because you can transpose the CoordinateSystem about, you should NEVER ASSUME ANYTHING except that the pixel axes of the CoordinateSystem map to the pixel axes of the image when you first construct the image.
SpectralCoordinate and DirectionCoordinate both have a (non-virtual) function called setReferenceConversion. This enables an extra conversion layer so that conversion between pixel and world can go to a reference frame other than the construction reference. When you use the function convert, these layers are active, but ONLY if the requested conversion is purely between pixel and world. For a SpectralCoordinate this must always be true (only has one axis) but for the DirectionCoordinate you might request a mixed pixel/world conversion. In this case, the extra conversion layer is ill-defined and not active (for the DirectionCoordinate part of it).
Copying constructor (copy semantics)
Assignment (copy semantics).
Destructor
Add another Coordinate to this CoordinateSystem. This addition is done by copying, so that if coord changes the change is NOT reflected in the CoordinateSystem.
Transpose the CoordinateSystem so that world axis 0 is newWorldOrder(0) and so on for all the other axes. newPixelOrder works similarly. Normally you will give the same transformation vector for both the world and pixel transformations, however this is not required.
Find the world and pixel axis mappings to the supplied CoordinateSystem from the current coordinate system. False is returned if either the supplied or current coordinate system, has no world axes (and a message recoverable with function errorMessage indicating why). Otherwise True is returned. worldAxisMap(i) is the location of world axis i (from the supplied CoordinateSystem, cSys, in the current CoordinateSystem. worldAxisTranspose(i) is the location of world axis i (from the current CoordinateSystem) in the supplied CoordinateSystem, cSys. The output vectors are resized appropriately by this function. A value of -1 in either vector means that the axis could not be found in the other CoordinateSystem. The vector refChange says if the types are the same, is there a reference type change (e.g. TOPO versus LSR for the SpectralCoordinate, or J2000 versus GALACTIC for DirectionCoordinate). Thus if refChange(i) is True, it means world axis i in the current CoordinateSystem was matched, but has a different reference type to that of the supplied CoordinateSystem.
Remove a world or pixel axis. When its value is required for forward or
backwards transformations, use replacement
When a world axis is removed, the corresponding pixel axis is removed
too, because it makes no sense having a pixel axis without world
coordinates.
Removing a pixel axis without removing the corresponding world axis
is, however, possible and meaningful. It can be used when e.g. a
frequency plane is taken from a cube. The plane has 2 pixel axes, but
the 3rd world axis can still describe the frequency coordinate.
See also the functions in CoordinateUtil
for removing lists of pixel/world axes (tricky because they shift down)
False is returned (an error in errorMessage() will be set) if the axis is illegal, else returns True.
False is returned (an error in errorMessage() will be set) if the axis is illegal, else returns True.
You can set the replacement values with these functions. You can only do this after you have removed an axis or False will be returned (and an error in errorMessage()) will be set. Use the same axis number as in the removePixelAxis and removeWorldAxis calls.
False is returned (an error in errorMessage() will be set) if the axis is illegal, else returns True.
The newShape vector is only needed for the StokesCoordinate, if any. If this vector is of length zero, the new StokesCoordinate is formed from all of the available input Stokes after application of the shift and increment factor. Otherwise, the new Stokes axis length is equal to that specified after appliction of the shift and increment and excess values discarded. In addition, for any StokesCoordinate, the shift and factor must be integer. So Int(value+0.5) is taken before they are used.
Untranspose and undelete all axes. Does not undo the effects of subimaging.
Returns the number of Coordinates that this CoordinateSystem contains. The order might be unrelated to the axis order through the results of transposing and removing axes.
For a given Coordinate say where its world and pixel axes are in this CoordinateSystem. The position in the returned Vector is its axis number in the Coordinate, and its value is the axis number in the CoordinateSystem. If the value is less than zero the axis has been removed from this CoordinateSystem.
Return the type of the given Coordinate.
Returns the type of the given Coordinate as a string.
Return the given Coordinate as a reference to the base class object.
Return the given Coordinate. Throws an exception if retrieved as the wrong type.
Replace one Coordinate with another. The mapping of the coordinate axes to the CoordinateSystem axes is unchanged, therefore the number of world and pixel axes must not be changed. You can, somewhat dangerously, change the type of the coordinate however. For example, replace a SpectralCoordinate with a 1-D Linearcoordinate. It is dangerous because the world replacement values (see removeWorldAxis) have to be scaled. The algorithm tries to find a scale factor between the old and new units and applies it to the replacement values. If it can't find a scale factor (non-conformant units) then the reference value is used for any world replacement values. If the latter occurs, it returns False, else True is returned.
Find the Coordinate number that corresponds to the given type. Since there might be more than one Coordinate of a given type you can call this multiple times setting afterCoord to the last value found. Returns -1 if a Coordinate of the desired type is not found.
Given an axis number (pixel or world) in the CoordinateSystem, find the corresponding coordinate number and axis in that Coordinate. The returned values are set to -1 if the axis does not exist.
Find the world axis for the given pixel axis in a CoordinateSystem. Returns -1 if the world axis is unavailable (e.g. if it has been removed).
Find the pixel axis for the given world axis in a CoordinateSystem. Returns -1 if the pixel axis is unavailable (e.g. if it has been removed).
Returns Coordinate::COORDSYS
Always returns "System"
Sums the number of axes in the Coordinates that the CoordinateSystem contains, allowing for removed axes.
Convert a pixel position to a world position or vice versa. Returns True if the conversion succeeds, otherwise it returns False and errorMessage() contains an error message. The input vector must be of length nPixelAxes or nWorldAxes. The output vector is resized appropriately.
This is provided as a convenience since it is a very commonly desired operation through CoordinateSystem. The output vector is resized.
Batch up a lot of transformations. The first (most rapidly varying) axis of the matrices contain the coordinates. Returns False if any conversion failed and errorMessage() will hold a message. The failures array (True for fail, False for success) is the length of the number of conversions and holds an error status for each conversion.
Mixed pixel/world coordinate conversion. worldIn and worldAxes are of length nworldAxes. pixelIn and pixelAxes are of length nPixelAxes. worldAxes(i)=True specifies you have given a world value in worldIn(i) to convert to pixel. pixelAxes(i)=True specifies you have given a pixel value in pixelIn(i) to convert to world. You cannot specify the same axis via worldAxes and pixelAxes. Values in pixelIn are converted to world and put into worldOut in the appropriate world axis location. Values in worldIn are copied to worldOut. Values in worldIn are converted to pixel and put into pixelOut in the appropriate pixel axis location. Values in pixelIn are copied to pixelOut. Vectors worldMin and worldMax specify the range of the world coordinate (in the world axis units of that world axis in the coordinate system) being solved for in a mixed calculation for each world axis. They are only actually used for DirectionCoordinates and for all other coordinates the relevant elements are ignored. Functions setWorldMixRanges, worldMixMin, worldMixMax can be used to compute and recover the world ranges. If you don't know the values, use functions setDefaultWorldMixRanges, worldMixMin, worldMixMax. Removed axes are handled (for example, a removed pixel axis with remaining corresponding world axis will correctly be converted to world using the replacement value). Returns True if the conversion succeeds, otherwise it returns False and errorMessage() contains an error message. The output vectors are resized.
Compute and recover the world min and max ranges, for use in function toMix, for a lattice of the given shape (must be of length nPixelAxes()). Removed pixel axes (with remaining world axes are handled). With the retrieval functions, the output vectors are resized. They return False if they fail (and then setDefaultWorldMixRanges generates the ranges) with a reason in errorMessage(). The setDefaultWorldMixRanges function gives you a useful default range if you don't know the shape. The only Coordinate type for which these ranges are actually used in toMix is DirectionCoordinate (because its coupled). For the rest the functionality is provided but never used by toMix.
Make absolute coordinates relative and vice-versa (relative to the reference pixel/value). The vectors must be of length nPixelAxes() or nWorldAxes()
Make absolute coordinates relative and vice versa with respect to the given reference value. Add the other functions in this grouping as needed. The vectors must be of length nPixelAxes() or nWorldAxes()
Batch up a lot of absolute/relative transformations. Parameters as above for toWorldMany and toPixelMany
General coordinate conversion. Only works if no axes have been removed and no axis reordering has occurred. That is pixel axes and world axes are the same.
Specify the input coordinate values, input units, whether value is absolute (or relative). For output specify units and abs/rel. Units may be 'pix' and velocity consistent units (e.g. m/s). Specify doppler types if velocities involved. The pixel offsets allow for the input and output pixel coordinates to be something other than 0-rel. If your pixel coordinates are 1-rel input and output, set the offsets to -1 and 1
The Matrix interface lets you do many conversions efficiently. Use Matrix(nAxes, nConversions) and Matrix.column()=coordinate or Matrix(axis, iConversion) to get the order right.
These functions invoke toMix so make sure you call setWorldMixRanges first to set up the world ranges.
Return the requested attribute.
Set the requested attribute. Note that these just change the internal values, they do not cause any recomputation.
Set/get the units. Adjust the increment and reference value by the ratio of the old and new units. This implies that the units must be known Unit strings, and that they must be compatible, e.g. they can't change from time to length.
Comparison function. Any private Double data members are compared with the specified fractional tolerance. Don't compare on the specified pixel axes in the CoordinateSystem. If the comparison returns False, errorMessage() contains a message about why.
This function compares this and the other coordinate system, but ONLY for the non-removed pixel axes. It is less strict than near, which, for example, insists the number of coordinates is the same in each CS
Format a world value nicely through the common format interface. See Coordinate for basics.
You specify a world value and its corresponding world axis in the CoordinateSystem.
For the specified worldAxis, the coordinate number in the CoordinateSystem is found and the actual derived Coordinate class object for that number is created. The arguments to the formatting function are then passed on to the formatter for that Coordinate. So refer to the other derived Coordinate classes for specifics on the formatting.
Miscellaneous information related to an observation, for example the observation date.
Find the CoordinateSystem (you can safely caste the pointer to a CoordinateSystem) for when we Fourier Transform ourselves. This pointer must be deleted by the caller. Axes specifies which pixel axes of the Coordinate System you wish to transform. Shape specifies the shape of the image associated with all the axes of the CoordinateSystem. Currently you have no control over the reference pixel, it is always shape/2.
Save the CoordinateSystem into the supplied record using the supplied field name. The field must not exist, otherwise False is returned. If the CoordinateSystem is empty False is also returned. If False is returned, errorMessage() contains a message about why.
Restore the CoordinateSystem from a record. The fieldName can be empty, in which case the CoordinateSystem is restored directly from the Record, rather than a subrecord of it. A null pointer means that the restoration did not succeed - probably because fieldName doesn't exist or doesn't contain a CoordinateSystem.
Make a copy of the CoordinateSystem using new. The caller is responsible for calling delete.
Convert a CoordinateSystem to FITS, i.e. fill in ctype etc. In the record the keywords are vectors, it is expected that the actual FITS code will split them into scalars and upcase the names. Returns False if one of the keywords is already taken.
If writeWCS is True, attempt to write the WCS convention (Greisen and Calabretta "Representation of celestial coordinates in FITS"). This is a DRAFT convention evolving rapidly. It is not recommended that you write this convention in general. Use oneRelative=True to convert zero-relative pixel coordinates to one-relative FITS coordinates.
prefix gives the prefix for the FITS keywords. E.g., if prefix="c" then crval, cdelt etc. if prefix="d" then drval, ddelt etc.
Probably even if we return False we should set up the best linear coordinate that we can. Use oneRelative=True to convert one-relative FITS pixel coordinates to zero-relative aips++ coordinates. On output, stokesFITSValue holds the FITS value of any unofficial Stokes (beam, optical depth, spectral index) for the last unofficial value accessed (-1 if none). The idea is that if the Stokes axis is of length one and holds an unofficial value, you should drop the STokes axis and convert that value to ImageInfo::ImageTypes with ImageInfo::imageTypeFromFITSValue. If on input, stokesFITSValue is positive, then a warning is issued if any unofficial values are encountered. Otherwise no warning is issued.
List all header information. By default, the reference values and pixel increments are converted to a "nice" unit before formatting (e.g. RA is shown as HH:MM:SS.S). For spectral axes, both frequency and velocity information is listed. You can specify what velocity definition you want with velocityType If you wish, you can specify two shapes; a lattice and tile shape (perhaps an image from which the CoordinateSystem came) If you give (both of) these, they are included in the listing. If you pass in zero length IPositions then they are not included in the listing. If postlocally=True the formatted summary lines are written locally only to the sink, and then returned by the return value vector.
Helper functions to group common code.
Check pixel replacement axis is legal and find it
Delete temporary maps
Many abs/rel conversions
Do subImage for Stokes
Strip out coordinates with all world and pixel axes removed
All these functions are in support of the list function