# Presentation: 575507

## The Current State of FITS

- And the consequences for SolarSoft
- (and SECCHI)

## The History of FITS

- FITS was originally developed in the late 1970s as an archive and interchange format.
- First FITS definition paper published in 1981 in *Astronomy & Astrophysics*.
- Later papers extended the concept:
- 1981: Groups extension
- 1988: Generalized extensions
- 1988: ASCII tables
- 1994: IMAGE extension
- 1995: Binary tables
- 2001: Revised definition, including above extensions
- 2002: World Coordinate System
- 2002: Celestial Coordinate System

## IAU FITS Working Group

- The IAU FITS Working Group was formed in 1988 as the international control authority for the FITS standard.
- There are also four regional FITS committees in Australia/New Zealand, Europe, Japan, and North America.
- Any proposed FITS standard must first be approved by the regional committees before going to the IAU-FWG.
- All of the papers in the previous slide were approved through this process.

## Recent FITS activity

- Official MIME types for FITS
- “image/fits”
- “application/fits”
- Adopted as official some of the binary table appendices
- TDIM convention
- Variable-length arrays
- Considering adding support for 64-bit integers

## World Coordinate System

- There are currently four papers which  make up the World Coordinate System:
- “Representations of world coordinates in FITS”, Greisen, E.W. and Calabretta, M.R., 2002, *A&A,* **395**, 1061-1075.
- “Representations of celestial coordinates in FITS”, Calabretta, M.R. and Greisen, E., 2002, *A&A*, **395**, 1077-1122.
- “Representations of spectral coordinates in FITS”, Greisen, E.W., Calabretta, M.R., Valdes, F.G., and Allen, S.L., 2005, *in review process*.
- “Representations of distortions in FITS world coordinate systems”, Calabretta, M.R., Valdes, F.G, and Allen, S.L., 2005, *rough draft*.

## Coordinates in theoriginal FITS specification.

- The original FITS specification had five keywords dedicated to coordinates:
**CRVAL***j*	coordinate value at reference point
**CRPIX***j*		array location of the reference pixel
**CDELT***j**	*	coordinate increment at reference point
**CTYPE***j**	*	axis type (8 characters)
**CROTA***j*	rotation from stated coordinate type
- Unfortunately, the definition of **CROTA***j* did not specify what it meant—the data provider was encouraged to explain the meaning in comments.

## World Coordinate System implementation

- The basic concept of the first WCS paper was to abandon **CROTA***j* in favor of a transformation matrix.
- The **PC***i*_*j* keywords in the header contain the relative dependence of each spatial coordinate *i* on each pixel coordinate *j*.
- The alternate **CD***i*_*j* formulation incorporates the **CDELT***j* keywords within the transformation matrix.
- One can have either **CROTA***j, *or **PC***i_j,* or **CD***i_j*, but not any combination simultaneously.
- The usage of **CROTA***j* must be considered to be restricted to only the simplest of cases.

## Examples

- In the old formalism, one might have the following keywords:
- 	NAXIS   = 2
- 	NAXIS1  = 100
- 	NAXIS2  = 100
- 	CRPIX1  = 50.5
- 	CRPIX2  = 50.5
- 	CRVAL1  = 0
- 	CRVAL2  = 0
- 	CDELT1  = 10
- 	CDELT2  = 10
- 	CROTA1  = 30
- 	CROTA2  = 30
- In the WCS representation, the same information would look like the following:
- 	NAXIS   = 2
- 	NAXIS1  = 100
- 	NAXIS2  = 100
- 	CRPIX1  = 50.5
- 	CRPIX2  = 50.5
- 	CRVAL1  = 0
- 	CRVAL2  = 0
- 	CDELT1  = 10
- 	CDELT2  = 10
- 	PC1_1   =  0.866025	/ Cos(Theta)
- 	PC1_2   = -0.500000	/-Sin(Theta)
- 	PC2_1   =  0.500000	/ Sin(Theta)
- 	PC2_2   =  0.866025	/ Cos(Theta)

*The ****CD***i_j* case would look the same, except that the ****CDELT***j* keywords would be gone, and the ****CD***i_j* values would be 10 times larger than the ****PC***i_j* values shown.*

## Using CROTAj

- If one does use **CROTA***j*, it has a very specific meaning within the WCS formalism.
- The relative spatial coordinates *x,y* are calculated from the pixel coordinates *i,j* by the formulae:
- 	ρ = CROTAj
- 	x = CDELTicos(ρ)i – CDELTjsin(ρ)j
- 	y = CDELTisin(ρ)i + CDELTjcos(ρ)j
- 	where *x* and *i *refer to the longitude axis, and *y* and *j* refer to the latitude axis.
- The conversion from the old formalism to the transformation matrices is given by the following equations:

*Examples assume 1=longitude, 2=latitude*

## Other WCS innovations

- Introduced the keyword **CUNIT***j* to describe the units along each axis.
- Defined a “4-3” style for the **CTYPE***j* keywords, where the first four characters define the coordinate type, followed by a dash, and then three characters to define a coordinate “projection”.  For example,
- 	CTYPE1  = ‘TEMP-LOG’
- 	would stand for the log of the temperature.
- Introduced the capability of having multiple alternative coordinate systems within the FITS files, by having a separate series of keywords which end in a single letter code, e.g.
- 	CRPIX1A, CRVAL1A, PC1_1A, ...
- 	For example, one  might have solar coordinates as the primary coordinate system, and celestial right ascension and declination as a secondary coordinate system.
- Formalized the specification of units, based on the IAU style guide.

## Celestial Coordinates

- The second WCS paper discussed the problem of spherical coordinates.
- Celestial coordinate axis labels have one of two forms for the **CTYPE***j* keyword:
- sLON-xxx *or* ssLN-xxx	Longitude
- sLAT-xxx *or* ssLT-xxx	Latitude
- 	where “s” or “ss” is a code for the type of coordinate (e.g. “G” for galactic), and “xxx” represents the spherical projection.
- An example of a projection is “MER” for the Mercator projection.  In general, spherical projections are too complicated to go into here in detail.

## The TAN projection

- One projection you are familiar with, even if you don’t know it, is the gnomonic or “TAN” projection.
- That’s the projection implicitly used by just about every solar imaging instrument, e.g. EIT, MDI, etc.
- With the TAN projection, the meaning the **CDELT***j*, **CRVAL***j*, **PC***i_j* (or **CROTA***j*), ... keywords are quite conventional.
- Traditionally, solar coordinates have been calculated as “quick-and-dirty” planar pseudo-angles, rather than as fully realized spherical coordinates.
- On the other hand, planar pseudo-angles are extremely useful, and differ only minutely from the full-blown spherical result.

## Comparison of calculations using the TAN projection

- After applying **CRPIX***j*, **CDELT***j, *and **PC***i_j* (or **CROTA***j*), one ends up with intermediate coordinates *x,y*.
- In the normal “quick and dirty” approach, the coordinates α and δ are calculated from **CRVAL***j *via
- α = x + αp
- δ = y + δp
- In the full-blown spherical approach, the following equations are used:

- Obviously, a lot faster!

- For typical solar data, the difference is on the order of milliarcseconds.

## Spectral Coordinates

- The third WCS paper, on spectral coordinates, is currently being reviewed by the regional FITS committees.
- Defines standard labels for spectral coordinate axes:
- 	FREQ		Frequency
- 	WAVE		Vacuum wavelength
- 	AWAV		Air wavelength
- 	ENER		Energy
- 	WAVN		Wavenumber
- 	VELO		Apparent radial velocity
- 	VRAD		Radio velocity
- 	VOPT		Optical velocity
- 	ZOPT		Redshift
- 	BETA		Beta factor (v/c)
- Also defines various spectral coordinate projections, e.g. F2W for data sampled as frequency, but expressed as wavelength.
- When the coordinate transformation is straightforward, one has simple entries like CTYPE3=‘WAVE’.

## Other Spectral Coordinate Innovations

- Grism projections GRI and GRA for non-linear wavelength dispersion from gratings and prisms.
- In practice, fit parameters to match dispersion.
- Formal definition of LOG projection
- Table lookup projection (TAB)
- Somewhat complicated scheme for looking up coordinates in a separate table.
- Both LOG and TAB are also applicable to non-spectral axes.
- Discussion of coordinate reference frames, and keywords for specifying rest wavelengths.

## Distortions paper

- Still in rough draft form—not yet “ready for prime time”
- Designed for small corrections on top of regular coordinate projection
- Encodes distortion parameters within a structure framework in the header
- Types of distortions addressed:
- Polynomial
- Cubic spline
- B-spline
- Lookup table

## Solar WCS Implementation

- My draft paper, “Coordinate systems for solar image data”, discusses how to apply WCS papers I & II to the Sun.
- This paper may come up for review by the FITS committees sometime over the next year.
- http://orpheus.nascom.nasa.gov/~thompson/papers/coordinates.pdf

## Types of coordinate systems

- Heliographic

- Cartesian

- Radial

- All of these can be incorporated within the WCS formalism.
- Often, even all three in the same file.

- Heliographic coordinates can also be expressed as synoptic maps with the proper projection.

- Distinction drawn between distances and angles.

## WCS Implementations

- Helioprojective-Cartesian
- Keyword values
- CTYPE1  = ‘HPLN-TAN’	/X-axis
- CTYPE2  = ‘HPLT-TAN’	/Y-axis
- Appropriate **PC***i_j* matrix (or **CROTA***j *keywords)
**CUNIT***j* values can be ‘deg’, ‘arcmin’, or ‘arcsec’
- All other keywords have normal meaning.
- Helioprojective-Radial
- Keyword values
- CTYPE1  = ‘HRLN-TAN’	/Position angle
- CTYPE2  = ‘HRLT-TAN’	/Radial distance
**PC***i_j* matrix (or **CROTA***j* keywords) relative to reference position angle.
**CUNIT***j* values *must* be ‘deg’.
**CRVAL***j* for position angle measured CCW from solar North.
**CRVAL***j* for radial direction defined such that Sun center is -90°.

*Examples assume 1=longitude, 2=latitude.*

## Heliographic Coordinates

- Stonyhurst Heliographic
- In simplest case, reference pixel is disk center
**CDELT***j* values multiplied by (D☼/R☼-1), i.e. size of one heliographic degree at disk center
- Keyword values
- CTYPE1  = ‘HGLN-AZP’	/Longitude
- CTYPE2  = ‘HGLT-AZP’	/Latitude
- Appropriate **PC***i_j* matrix (or **CROTA***j *keywords)
**CUNIT***j* values must be ‘deg’
- The keyword **PV***j***_1 **contains the value - D☼/R☼,, where *j* is the latitude dimension.  (In this example,* j*=2)
- Note minus sign
- E.g., at 1 A.U., one would have PV2_1 = -214.9
- All other keywords have normal meaning.
- Carrington Heliographic
- Same except with keyword values
- CTYPE1  = ‘CRLN-AZP’	/Longitude
- CTYPE2  = ‘CRLT-AZP’	/Latitude

*Examples assume 1=longitude, 2=latitude.*

## Application of projections to solar data

*Helioprojective-radial coordinates with the plate-carr**é**e (****CAR)**** projection*

**Standard images:** Helioprojective-cartesian with TAN projection (e.g. EIT)
**Coronal spectrometers:** Helioprojective-radial with TAN projection (e.g. UVCS)
**Synoptic maps:** Carrington or Stonyhurst heliographic with cylindrical projection
**All-sky maps:** Celestial coordinates with pseudo-cylindrical projection (e.g. SWAN, SMEI)

## Degrees vs. Arcseconds

- It’s a somewhat contentious issue within the FITS/WCS community to use any other angular units than degrees.
- However, it’s standard within the solar community to use arcseconds.
- I argue that solar coordinates are different from normal celestial coordinates.
- They’re not intended to be used for other celestial bodies.
- They can also be projected onto a plane, rather than a sphere.
- Arcseconds (or arcminutes) are *only* to be used for Helioprojective-Cartesian coordinates in the TAN projection, and only relatively close to the Sun.
- i.e. typical solar images (e.g. EIT, TRACE, LASCO, etc.)
- I think I can get this by the FITS committees—I consider it a deal breaker.
- Instruments such as coronagraphs, which also see extra-solar targets (e.g. stars, comets, ...) should also include an alternative celestial coordinate system such as R.A. & Dec. (in degrees).

## Observer’s Position

- Missions such as STEREO need to also provide information about the position that the data were taken from:
- Propose new set of keywords:
- DSUN_OBS		Distance from Sun, in meters
- HGLN_OBS		Heliographic longitude of observer
- 						relative to Earth
- HGLT_OBS		Heliographic latitude (*B*0)
- Additional set of keywords, based on standard heliospheric coordinates, e.g.
- HCIX_OBS		Heliocentric Inertial coordinates
- HCIY_OBS			in meters
- HCIZ_OBS

## WCS within SolarSoft

- Have started developing a new set of WCS routines within SolarSoft
- The objectives of this software are as follows:
- Read in and parse FITS files using the WCS formalism
- Also ingest FITS files using the older system
- Allow FITS files using the new WCS keywords to be used in older software, such as the SolarSoft mapping routines.
- Promote standardization of FITS keywords.
- Write FITS files in the new formalism.
- Ultimately, manipulate the WCS to assist data analysis.
- Convert between coordinate systems.
- Convert between different projections.
- Part of the design philosophy is that the information in FITS headers should be “compiled” as soon as they are read, rather than having each routine do its own interpretation.

## WCS structure

- FITSHEAD2WCS ingests a FITS header (string array or structure), and forms a WCS structure, which will contain some or all of the following tags:
- COORD_TYPE	e.g. Helioprojective-Cartesian
- WCSNAME		Keyword in FITS header
- VARIATION	CROTA, PC, or CD
- COMPLIANT	True if header matches standard
- PROJECTION	e.g. TAN
- NAXIS		Dimensions
- IX		Longitude dimension
- IY		Latitude dimension
- CRPIX		Array of FITS keywords
- CRVAL		...
- CTYPE		...
- CUNIT		...
- CDELT		Unless CD variation
- PC		PC matrix
- CD		CD matrix
- ROLL_ANGLE	If applicable
- SIMPLE		True if certain conditions are met.
- PROJ_NAMES	Parameters to support projections
- PROJ_VALUES	...
- TIME		Substructure containing time information
- POSITION		Substructure containing position information

*The structure format isn’t static—it adjusts itself to the situation.  As the software gets more sophisticated, the structure will reflect that.*
*Only contains coordinate information—no annotation.  The data array is separate.*

## Time substructure

- The TIME structure will contain some subset of the following tags:
- FITS_DATE
- OBSERV_DATE		CORRECTED_DATE
- OBSERV_END		CORRECTED_END
- OBSERV_MID		CORRECTED_MID
- OBSERV_AVG		CORRECTED_AVG
- EXPTIME
- 	plus some keywords involving reference frames.
- If both DATE-xxx and DATE_xxx keywords are present, the assumption is that the DATE_xxx values are corrected for the difference in light travel time, relative to Earth.

## Position substructure

- The position substructure will contain some subset of the following tags:
- SOHO				True if SOHO observation
- POS_ASSUMED		True if position is assumed
- DSUN_OBS			Solar distance in meters
- SOLAR_B0			*B*0 angle
- CARR_EARTH			Carrington longitude of Earth
- HGLN_OBS, HGLT_OBS	Heliographic
- CRLN_OBS, CRLT_OBS	Carrington
- Various standard coordinate (x,y,z) triplets:
- GEI_OBS, GEO_OBS, GSE_OBS, GSM_OBS, SM_OBS, MAG_OBS, HAE_OBS, HEE_OBS, HEQ_OBS, HCI_OBS
- Note that SOLAR_B0, HGLT_OBS, and CRLT_OBS are all synonyms.
- Tries to determine at least DSUN_OBS, SOLAR_B0, and CARR_EARTH, based on the date.

## Decomposing Transformation Matrices

- The routine WCS_DECOMP_ANGLE examines the PC or CD matrix, and determines whether or not it can be decomposed into a roll angle (and **CDELT***j* values).
- If it can, then those parameters are added to the structure.
- Called automatically when the WCS is created.
- Conversely, for the CROTA variation, the roll angle is used to generate a PC matrix.

## Interaction with SolarSoft

- The routine WCS_SIMPLE tests whether a WCS is “simple”, i.e. if it meets the following conditions:
- The first dimension is longitude (*x*)
- The second dimension is latitude (*y*)
- The coordinate system is Cartesian.
- The projection is either “TAN” or blank.
- The CDELT and ROLL_ANGLE tags are present
- A simple WCS is suitable for passing to the SolarSoft mapping software.
- Routines WCS2MAP and MAP2WCS.
- INDEX2MAP modified to accept FITS files with PC or CD matrices that pass the WCS_SIMPLE test.

## WCS Rectification

- The routine WCS_RECTIFY resamples a data set to remove all cross terms in the PC or CD matrix.
- Equivalent to rotating the image to remove the roll
- Example:

- Note that the size increases to accommodate all the pixels.
- Currently, the interpolation scheme depends on the number of dimensions.

## A more complicated example

- The CDS spectrometer has a slant in the wavelength direction.
- Also, the pixel spacing is different in the two directions.
- In addition, CDS puts the wavelength in the first dimension.
- For an additional complication, I chose a data set where the spacecraft roll angle was significant.  (Same as EIT example.)

## CDS example continued

- The FITS header is to the right.
- Note that both the *x* and *y* coordinates depend on wavelength (PC2_1 and PC3_1).
- Below is shown the spatial data, plotted as a SolarSoft map.

## WCS_SIMPLIFY

- The routine WCS_SIMPLIFY takes a complicated WCS, and simplifies it to make it compatible with the SolarSoft mapping software.
- If necessary, the WCS is first rectified.
- The coordinates are rearranged to put the longitude dimension first, and the latitude dimension second.
- WCS_SIMPLIFY was used to prepare the previous CDS example, so that I could use PLOT_MAP on it.

## WCS_GET_COORD

- WCS_GET_COORD returns the coordinates from any WCS structure.  (Inverse is WCS_GET_PIXEL.)
- Coordinates can be returned for the whole array, or for specific pixels.
- Currently, all but a few of the projections are supported.
- Cartesian, Radial, and Heliographic coordinates are supported.
- Spectral projections (e.g. GRI) are also supported.
- Eventually, all the projections will be supported.
- TAN projection:
- Can be calculated using either the “quick-and-dirty” calculation (/QUICK), or with the full-blown spherical calculation.
- Separate quick approximations for Cartesian and Radial.
- If all the pixels are within ~3 degrees of disk center, the software *automatically* uses the quick calculation, unless called with /FORCE_PROJ.

## Currently Supported Projections

- Spherical projections
- AZP: Azimuthal perspective
- SZP: Slant zenithal perspective
- TAN: Gnomonic
- STG: Stereographic
- SIN: Slant orthographic
- ARC: Zenithal equidistant
- ZEA: Zenithal equal-area
- CYP: Cylindrical perspective
- CEA: Cylindrical equal area
- CAR: Plate carrée
- MER: Mercator
- SFL: Sanson-Flamsteed
- PAR: Parabolic
- MOL: Mollweide’s (*no inverse*)
- AIT: Hammer-Aitoff
- COP: Conic perspective
- COE: Conic equal area
- COD: Conic equidistant
- COO: Conic orthomorphic
- BON: Bonne’s equal area

- Spectral projections
- F2W: Frequency-to-wavelength
- F2V: Frequency-to-velocity
- F2A: Frequency-to-air-wavelength
- W2F: Wavelength-to-frequency
- W2V: Wavelength-to-velocity
- W2A: Wavelength-to-air-wavelength
- V2F: Velocity-to-frequency
- V2W: Velocity-to-wavelength
- V2A: Velocity-to-air-wavelength
- A2F: Air-wavelength-to-frequency
- A2W: Air-to-vacuum wavelength
- A2V: Air-wavelength-to-velocity
- GRI: Vacuum grism projection
- GRA: Air grism projection
- Generic projections
- LOG: Logarithmic
- TAB: Lookup table

## Heliographic Coordinates

- The usual projection for heliographic coordinates is zenithal (AZP).
- This EIT example demonstrates the calculation of AZP coordinates.
- Coordinates outside the limb are marked as missing.

## Summary

- Burden on data providers relatively small
- Use standard keywords (**CRPIX***j*, **CDELT***j*, **CTYPE***j*, **CRVAL***j*, **CUNIT***j*)
- Don’t forget that FITS pixels start at 1, unlike IDL
- Use standard WCS labels for **CTYPE***j*, e.g. “HPLN-TAN” and “HPLT-TAN”.
- Use standard labels for units, e.g. “deg”, “arcmin”, “arcsec”
- Preferably, use **PC***i_j* matrix, instead of **CROTA***j*
- Software developers need to be aware of WCS
- Primarily, need to recognize **PC***i_j* matrix
- INDEX2MAP has already been modified
- What other generic FITS readers should be modified?
- e.g. IMAGE_TOOL
- Opportunity to address more complicated cases

## Implications for SECCHI

- SECCHI is already using the WCS convention, including the PC matrix
- A major driver was to make sure that SECCHI files could be imported into SolarSoft routines
- The coronagraph and HI files should include one or more secondary celestial coordinate systems to ease the analysis of non-solar objects such as comets, NEOs, etc.
- Possible systems:
- Ecliptic longitude/latitude
- Right ascension and declination
- Can be derived from SPICE
- Celestial coordinates must be in degrees
- What is the correct projection for HI-1 and HI-2?
- Might not be TAN
- WCS distortions paper might be useful