A Toolkit Approach to WCS David Berry Starlink

A Tool-kit Approach to WCS David Berry (Starlink) IVOA Inter-operability Meeting Cambridge 12 -16 th May 2003 1

2 Importance of WCS is needed to: l Locate data within the region of interest l Align data sets from disparate sources l Annotate data displays

3 The “prescriptive” approach l Prescribes a limited number of allowed recipes which may be used to describe the relationships between specified co-ordinate systems. l As WCS needs change, new recipes need to be added – can end up with lots of “specificcase” code (does not scale well). l It can be difficult to reach agreement on what the allowed recipes should be.

4 The “tool-kit” approach l Provides a wide range of simple WCS components (tools) which can be “connected together” in any way to create a complete WCS representation. l There are no prescribed recipes; the developer is free to use the most appropriate representation for the WCS information. l Components are self-describing.

5 The AST library l An implementation of a tool-kit approach to WCS representation and management. l See http: //www. ast. man. ac. uk/~dsb/ast. html

6 AST Base classes l The basic tools in the AST tool-kit are Mappings, Frames and Frame. Sets. l Each base class encapsulates the general properties and methods of the class – subclasses are provided for specific case. l All can be serialised, for instance as XML.

7 The Mapping class l. A Mapping transforms a set of positions using a specified mathematical operation. l No assumptions are made about the nature of the input or output co-ordinate systems. l The input and output positions need not be of the same dimensionality. l Many (but not all) Mappings will be in invertible.

8 Mapping sub-classes Sub-classes of Mapping are provided which implement: – Axis scaling – Shift of origin – Matrix multiplication – Spherical projections – Cartesian to spherical conversion

9 Mapping sub-classes – Axis permutation and selection – Arbitrary algebraic expressions – Pin-cushion distortion – Transformations between celestial, spectral and (shortly) time co-ordinate systems, all based on SLALIB – Others can be added easily

10 Compound Mappings l. A Cmp. Map is a sub-class of Mapping which encapsulates two other Mappings. l Series Cmp. Maps: Map 1 l Parallel Cmp. Maps: Map 1 Map 2

11 Compound Mappings l Since a Cmp. Map is itself a Mapping, a Cmp. Map can encapsulate other Cmp. Maps. l This allows arbitrarily complex Mappings to be constructed: Map 2 Map 3 Map 1 Map 4

12 The Frame class l. A Frame describes a physical domain such as “the sky”, “a pixel array”, “a spectrum”, “time”, “a focal plane”, “ 3 D space”, etc. l The base Frame class represents a basic Ndimensional Euclidean space which can be used to describe a user-specified domain. l Sub-classes of Frame exist to describe celestial and spectral positions (“time” to follow shortly).

13 The Frame class l The description given by a Frame includes: – The domain name – The dimensionality of the domain – The particular co-ordinate system used to describe positions within the domain (subclasses support a range of different co-ordinate systems appropriate to the sub-class domain) – A moment in time which specifies the coordinate system

14 The Frame class l The description given by a Frame includes: – Label, Unit and Symbol strings for each axis of the co-ordinate system. – The topology of the domain (allows navigation around the domain) – The Mappings needed to transform between the different co-ordinate systems which can be used to describe positions within the domain.

15 The Sky. Frame l Describes positions on the sky l Co-ordinate systems currently supported include equatorial (FK 4, FK 4 -NO-E, FK 5, GAPPT, ICRF), ecliptic, galactic, supergalactic. Heliocentric systems to follow… l Extra properties: Equinox.

16 A Serialised Sky. Frame Begin Sky. Frame # Description of celestial coordinate system # Title = "FK 4 equatorial coordinates; mean equinox B 1950. 0; epoch B 1987. 67101 " # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain Epoch = 1987. 67 # Julian epoch of observation # Lbl 1 = "Right ascension" # Label for axis 1 # Lbl 2 = "Declination" # Label for axis 2 System = "FK 4" # Coordinate system type # Uni 1 = "hh: mm: ss. s" # Units for axis 1 # Uni 2 = "ddd: mm: ss" # Units for axis 2 # Dir 1 = 0 # Plot axis 1 in reverse direction # Bot 2 = -1. 5707963267949 # Lowest legal axis value # Top 2 = 1. 5707963267949 # Highest legal axis value Ax 1 = # Axis number 1 Begin Sky. Axis # Celestial coordinate axis End Sky. Axis Ax 2 = # Axis number 2 Begin Sky. Axis # Celestial coordinate axis End Sky. Axis Is. A Frame # Coordinate system description Eqnox = 1950 # Besselian epoch of mean equinox End Sky. Frame

17 The Spec. Frame l Describes positions within an electromagnetic spectrum l Co-ordinate systems include frequency, wavelength, energy, velocity (radio, optical, relativistic), etc, all in any appropriate unit (including log, sqrt, units, etc). l Extra properties: Rest frame, observer position, source position, rest frequency, source velocity. . .

18 A Serialised Spec. Frame Begin Spec. Frame # Description of spectral coordinate system # Title = "Frequency ( l. SRK)" # Title of coordinate system Naxes = 1 # Number of coordinate axes # Domain = "SPECTRUM" # Coordinate system domain Epoch = 1995. 55138507871 # Julian epoch of observation # Lbl 1 = "Frequency" # Label for axis 1 System = "FREQ" # Coordinate system type # Uni 1 = "GHz" # Units for axis 1 Ax 1 = # Axis number 1 Begin Axis # Coordinate axis Unit = "GHz" # Axis units End Axis Is. A Frame # Coordinate system description So. R = "LSRK" # Standard of rest Ref. RA = 0. 0286375917587126 # Reference RA ( rads, FK 5 J 2000) Ref. Dec = 0. 0223112108219319 # Reference Dec ( rads, FK 5 J 2000) Geo. Lat = 0. 345973275091431 # Observers geodetic latitude ( rads) Geo. Lon = -2. 71358558214735 # Observers geodetic longitude ( rads) Rst. Frq = 230537999000 # Rest frequency (Hz) Src. Vel = 110000 # Source velocity (m/s) Src. VRF = "LSRK" # Source velocity rest frame UFreq = "GHz" # Preferred units for frequency End Spec. Frame

19 Compound Frames l The Cmp. Frame class combines two component Frames to form a Frame which describes two physical domains. l For instance, a spectral cube can be described by a Cmp. Frame which combines a Sky. Frame and a Spec. Frame. l Since a Cmp. Frame is itself a Frame, complex Cmp. Frames can be constructed which encapsulate other Cmp. Frames.

20 The Convert method l Convert – a method of the Frame class, extended by sub-classes. l Returns a Mapping which converts positions in ‘this’ Frame into another supplied Frame, or a null reference if no conversion is possible. l Hides all details of conversion between different co-ordinate systems – a non-trivial task for Cmp. Frames!

21 Putting it all together Frame. Sets l. A Frame. Set is a network of Frames connected together by Mappings. l Each Frame represents one or more of the co -ordinate systems which can be used to describe the position of a data value. l Each Mapping describes how to transform a position from one Frame to another.

22 Putting it all together – Frame. Sets SKY p 3 a M XI-ETA: Tangent plane standard co-ordinates without barrel distortion. XI-ETA p 2 a M PIXEL Map 1 SKY: RA/Dec without added barrel distortion. XI-ETA -B Ma p 4 XI-ETA-B: Tangent plane standard co-ordinates with barrel distortion. SKY-B: RA/Dec with barrel distortion.

23 The Convert method again l Frame. Set inherits from Frame. When viewed as a Frame, a Frame. Set is equivalent to its current Frame. l Frame. Set extends the Frame. Convert method to find a Mapping which “aligns” two Frame. Sets: it uses the Convert method recursively on all pairs of Frames. l Even works with Cmp. Frames!

24 The Find. Frame method l Searches a Frame. Set for a Frame with given properties. l A template Frame defines the required properties. l Properties may be left undefined in the template – they are used as “wild-cards”.

25 An AST representation of FITS -WCS l An AST Frame. Set can be automatically generated to describe the WCS information in a FITS header. Consider the following simple FITS header as an example: CRPIX 1 CRPIX 2 CRVAL 1 CRVAL 2 CTYPE 1 CTYPE 2 CD 1_1 CD 1_2 CD 2_1 CD 2_2 RADESYS EQUINOX MJD-OBS = = = = 256 257 45. 83 63. 57 'RA---TAN' 'DEC—-TAN' -0. 003 0. 0005 -0. 0005 0. 003 'FK 5 ' 2000. 0 44258. 7856 / / / / Pixel X coordinate of reference point Pixel Y coordinate of reference point RA (degs) at reference point Dec (degs) at reference point Gnomonic projection giving RA/DEC Matrix which rotates and scales pixel coordinates into projection plane (X, Y) coordinates in degrees RA/DEC are in the FK 5 frame Mean equator and equinox of J 2000. 0 Modified Julian Date at start of observation

26 An AST representation of FITS -WCS PIXEL l The Map SKY example FITS header on the previous slide can be described using an AST Frame. Set holding 2 Frames connected together by a Mapping. l These components are described over the next few slides…

27 An AST representation of FITS -WCS PIXEL l The Map SKY “PIXEL” Frame represents the pixel array. Positions within the pixel array are described using the usual Cartesian FITS pixel co-ordinate system. l This Frame describes the input co-ordinates supplied to the Mapping.

28 An AST representation of FITS -WCS PIXEL l The Map SKY “SKY” Sky. Frame (a sub-class of Frame) represents the sky. Positions on the sky are described in the system specified by the FITS keywords CTYPEi, RADESYS, EQUINOX and MJD-OBS. l This Sky. Frame describes the output coordinates produced by the Mapping.

29 An AST representation of FITS -WCS PIXEL l “Map” Map SKY is a Cmp. Map (a compound Mapping) which combines several simpler atomic Mappings in series. l Each atomic Mapping represents a step in the FITS-WCS recipe for converting pixel positions into sky positions. These Mappings are described over the next few slides…

30 An AST representation of FITS PIXEL -WCS Map 1 The first atomic Mapping is a Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 FITS keywords. A Win. Map is a sub-class of Mapping which maps a specified rectangular input window onto a specified output window by applying a linear scale and shift to each axis. The input to this Mapping is a position in the PIXEL Frame. l

31 An AST representation of FITS PIXEL -WCS Map 1 l. A Map 2 l Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 keywords. The second atomic Mapping is a Matrix. Map which rotates and scales the axes as described by the CDi_j FITS keywords. A Matrix. Map is a sub-class of Mapping which multiplies each input N-dimensional position by an M x N matrix to produce an M-dimensional output position.

32 An AST representation of FITS PIXEL -WCS Map 1 l. A Map 2 l The Map 3 Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 keywords. second atomic Mapping is a Matrix. Map which rotates and scales the axes as described by the CDi_j FITS keywords. The third atomic Mapping is a Wcs. Map which produces native longitude and latitude, using the spherical projection specified by the CTYPEi FITS keywords. A Wcs. Map is a sub-class of Mapping which can perform any of the FITS-WCS spherical projections. l

33 An AST representation of FITS PIXEL -WCS Map 1 l. A Map 2 l The Map 3 Map 4 Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 keywords. second atomic Mapping is a Matrix. Map which rotates and scales the axes as described by the CDi_j FITS keywords. l The third atomic Mapping is a Wcs. Map which produces native longitude and latitude, using the spherical projection specified by the CTYPEi FITS keywords. The fourth atomic Mapping is a Sph. Map which converts native longitude and latitude into corresponding Cartesian (X, Y, Z) values on a unit sphere. A Sph. Map is a sub-class of Mapping which performs spherical to Cartesian conversion. l

34 An AST representation of FITS PIXEL -WCS Map 1 l. A Map 2 l. A Map 3 Map 4 Map 5 Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 keywords. Matrix. Map which rotates and scales the axes as described by the CDi_j FITS keywords. l. A Wcs. Map which produces native longitude and latitude, using the spherical projection specified by the CTYPEi FITS keywords. l. A Sph. Map which converts native longitude and latitude into corresponding Cartesian (X, Y, Z) values on a unit sphere. The fifth Mapping is a 3 x 3 Matrix. Map which does a 3 -D rotation to put the RA/Dec position given by FITS keywords CRVALi at the reference point (with the default value for the LONPOLE keyword). l

35 An AST representation of FITS PIXEL -WCS Map 1 l. A Map 2 l. A Map 3 Map 4 Map 5 Map 6 Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 keywords. Matrix. Map which rotates and scales the axes as described by the CDi_j FITS keywords. l. A Wcs. Map which produces native longitude and latitude, using the spherical projection specified by the CTYPEi FITS keywords. l. A Sph. Map which converts native longitude and latitude into corresponding Cartesian (X, Y, Z) values on a unit sphere. l. A 3 x 3 Matrix. Map which does a 3 -D rotation to put the RA/Dec position given by FITS keywords CRVALi at the reference point. The final Mapping is an inverted Sph. Map which converts Cartesian (X, Y, Z) values back into longitude (RA) and latitude (Dec). l

36 An AST representation of FITS PIXEL -WCS Map 1 l. A Map 2 l. A Map 3 Map 4 Map 5 Map 6 SKY Win. Map which shifts the origin as described by the CRPIX 1 & CRPIX 2 keywords. Matrix. Map which rotates and scales the axes as described by the CDi_j FITS keywords. l. A Wcs. Map which produces native longitude and latitude, using the spherical projection specified by the CTYPEi FITS keywords. l. A Sph. Map which converts native longitude and latitude into corresponding Cartesian (X, Y, Z) values on a unit sphere. l. A 3 x 3 Matrix. Map which does a 3 -D rotation to put the RA/Dec position given by FITS keywords CRVALi at the reference point. l An inverted Sph. Map which converts Cartesian (X, Y, Z) values back into longitude (RA) and latitude (Dec). The output from this final Mapping is the required RA/Dec position.

37 An AST representation of FITS -WCS p. A a M PIXEL Map. B Ma p. C WCSNAMEA WCSNAMEB WCSNAMEC l FITS header which have alternate axis descriptions can be represented by a more complicated Frame. Set as shown above.

38 Benefits of the “tool-kit” approach to WCS l Flexibility: provides a wider range of options for describing novel WCS arrangements. l Abstract interface: Frame methods can be used on any class of Frame so general purpose applications can be written which know nothing about the details of the WCS. l Scalability: Complex WCS arrangement can be extended simply by adding new Frames.

39 Benefits of the “tool-kit” approach to WCS l Scalability: New classes of Frame and Mapping can be added and used without need for application code to be changed. l Functionality: Allows powerful methods such as Convert and Find. Frame to be written. l Ease of use: Hides all the specific details of different co-ordinate systems and the conversions between them.

40 Conclusions l Tool-kit approaches to WCS description and management ease future development as WCS requirements evolve. l The description and handling of co-ordinate systems crops up in many areas of VO work. Adoption of a single unified system would reduce integration issues and the over-all development effort.