Edit on GitHub

WCS.jl

Code Build Status PkgEval Coverage License

Astronomical World Coordinate System library for Julia. This package wraps the WCSLIB C library. This is a tool made for users who are already familiar with WCS transformations. If you are not, please reference the following manuscripts

  1. Representation of world coordinates in FITS
  2. Representations of celestial coordinates in FITS
  3. Representations of spectral coordinates in FITS
  4. Representations of distortions in FITS world coordinate systems

Table of Contents

Installation

From the REPL, press ] to enter Pkg mode

(v 1.2) pkg> add WCS

Usage

Import the library

julia> using WCS

There are many ways to utilize WCS transformations. Let's make one for a 2-dimensional array (like an image) from scratch.

julia> wcs = WCSTransform(2;
                          cdelt = [-0.066667, 0.066667],
                          ctype = ["RA---AIR", "DEC--AIR"],
                          crpix = [-234.75, 8.3393],
                          crval = [0., -90],
                          pv    = [(2, 1, 45.0)])
WCSTransform(naxis=2,cdelt=[-0.066667, 0.066667],crval=[0.0, -90.0],crpix=[-234.75, 8.3393])

We can also create one from a FITS header if it contains the appropriate keywords

# Or from a FITS header with appropriate keywords
julia> wcs_array = WCS.from_header(header)

julia> wcs = wcs_array[1]

Now we can do conversions between pixel and world coordinates.

Note

that WCS transforms use pixel (0, 0) as the top-left corner (not 1-indexed!!!)

# convert pixel -> world coordinates
julia> pixcoords = [0.0  24.0  45.0;  # x coordinates
                    0.0  38.0  98.0]  # y coordinates
2×3 Matrix{Float64}:
 0.0  24.0  45.0
 0.0  38.0  98.0

julia> worldcoords = pix_to_world(wcs, pixcoords)
2×3 Matrix{Float64}:
 267.965   276.539   287.771
 -73.7366  -71.9741  -69.6781
julia> pixcoords = world_to_pix(wcs, worldcoords)
2×3 Matrix{Float64}:
  1.16529e-12  24.0  45.0
 -7.10543e-14  38.0  98.0

API/Reference

WCS.WCSTransform — Type
WCSTransform(naxis; kwds...)

Construct a WCS transformation with the given number of axes naxis. Keyword arguments can be passed to set various attributes of the transform. Specifying keyword arguments is equivalent to setting them after construction:

julia> wcs = WCSTransform(2; crpix=[1000., 1000.])

is equilvalent to:

julia> wcs = WCSTransform(2)

julia> wcs.crpix = [1000., 1000.]

Properties

Below is the entire list of public properties for a WCSTransform

KeywordTypeDescription
naxisIntNumber of dimensions
crvalVector{Float}[naxis]coordinate value at reference point
crpixVector{Float}[naxis]array location of the reference point in pixels
cdeltVector{Float}[naxis]coordinate increment at reference point
crderVector{Float}[naxis]random error in coordinate
csyerVector{Float}[naxis]systematic error in coordinate
ctypeVector{String}[naxis]axis type (8 characters)
crotaVector{Float}[naxis]rotation from stated coordinate type
cunitVector{String}[naxis]units of axes
cunitVector{String}[naxis]names of axes
pcMatrix{Float}[naxis, naxis]linear transformation matrix
cdMatrix{Float}[naxis, naxis]linear transformation matrix (with scale)
equinoxFloatthe equinox associated with dynamical equatorial or ecliptic coordinate systems
latpoleFloatthe native latitude of the celestial pole
lonpoleFloatthe native longitude of the celestial pole
mjdavgFloatModified Julian Date corresponding to DATE-AVG
mjdobsFloatModified Julian Date corresponding to DATE-OBS
restfrqFloatrest frequency (Hz)
restwavFloatrest wavelength (m)
velanglFloatvelocity angle
velosysFloatrelative radial velocity
zsourceFloatthe redshift of the source
colnumIntcolumn of FITS binary table associated with this WCS
dateavgStringrepresentative mid-point of the date of observation
dateobsStringstart of the date of observation
radesysStringthe equatorial or ecliptic coordinate system type
specsysStringspectral reference frame (standard of rest)
ssysobsStringspectral reference frame
ssyssrcStringspectral reference frame for redshift
wcsnameStringname of this coordinate representation
obsgeoVector{Float}[3] or Vector{Float}[6]location of the observer in a standard terrestrial reference frame
altStringcharacter code for alternate coordinate descriptions
source
WCS.from_header — Method
from_header(header[; relax=WCS.HDR_ALL, ctrl=0, ignore_rejected=false, table=false])

Parse the FITS image header in the String header, returning a Vector{WCSTransform} giving all the transforms defined in the header. The relax determines the treatment of non-standard keywords. The default is to accept all known non-standard keywords. Use relax=WCS.HDR_NONE to ignore all non-standard keywords. Use, e.g., relax=(WCS.HDR_RADECSYS & WCS.HDR_CROTAia) to only accept selected non-standard keywords.

source
WCS.obsfix — Method
obsfix(ctrl::Integer, wcs::WCSTransform)

Complete the obsgeo field wcs of observatory coordinates. That is, if only the (x,y,z) Cartesian coordinate triplet or the (l,b,h) geodetic coordinate triplet are set, then it derives the other triplet from it. If both triplets are set, then it checks for consistency at the level of 1 metre.

Parameters

  • ctrl: flag that controls behaviour if one triplet is defined and the other is only partially defined:
    • 0: Reset only the undefined elements of an incomplete coordinate triplet.
    • 1: Reset all elements of an incomplete triplet.
    • 2: Don't make any changes, check for consistency only. Returns an error if either of the two triplets is incomplete.
  • wcs: Coordinate transformation parameters. Its obsgeo field may be changed.

Returns

  • -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 5: Invalid parameter value.
source
WCS.pix_to_world! — Method
pix_to_world!(wcs, pixcoords, worldcoords[; stat=, imcoords=, phi=, theta=])

Convert the array of pixel coordinates pixcoords to world coordinates according to the WCSTransform wcs, storing the result in the worldcoords and stat arrays. pixcoords should be a 2-d array where "pixcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates. worldcoords must be the same size and type as pixcoords.

If given, the arrays stat, imcoords, phi, theta will be used to store intermediate results. Their sizes and types must all match pixcoords, except for stat which should be the same size but of type Cint (typically Int32).

source
WCS.pix_to_world — Method
pix_to_world(wcs, pixcoords)

Convert the array of pixel coordinates pixcoords to world coordinates according to the WCSTransform wcs. pixcoords should be a 2-d array where "pixcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates.

The return value is the same shape as pixcoords.

source
WCS.to_header — Method
to_header(wcs[; relax=WCS.HDR_NONE])

Encode the WCSTransform wcs as a FITS header string. The relax keyword controls how non-standard extensions to the WCS standard are handled.

source
WCS.world_to_pix! — Method
world_to_pix!(wcs, worldcoords, pixcoords[; stat=, phi=, theta=, imcoords=])

Convert the array of pixel coordinates worldcoords to pixel coordinates according to the WCSTransform wcs, storing the result in the pixcoords array. worldcoords should be a 2-d array where "worldcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates. pixcoords must be the same size and type as worldcoords.

If given, the arrays stat, imcoords, phi, theta will be used to store intermediate results. Their sizes and types must all match worldcoords, except for stat which should be the same size but of type Cint (typically Int32).

source
WCS.world_to_pix — Method
world_to_pix(wcs, worldcoords)

Convert the array of world coordinates worldcoords to pixel coordinates according to the WCSTransform wcs. worldcoords is a 2-d array where "worldcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates.

The return value is the same size as worldcoords.

source

Index