Current Version

Current Version

Document TitleWFCAM HDS container and FITS headers
Document Number
Date 2003-Oct-27
Document Prepared By:Alan PickupSignature and Date
Document Prepared By:Signature and Date
Document Prepared By:Signature and Date

Change Record

IssueDateSection AffectedChange Description
0.12002-Oct-16all 1st version for time of Software CDR
0.22003-Feb-10allTables include comment records; new headers including “TSCAN”s
0.32003-Feb-13allCorrection of typos (thanks to Jim Lewis); some additional comments; addition of sections listing example headers.
0.42003-Feb-14all“TSCAN” becomes “JITTER”; added READOUT; expanded environment headers (from JAC); updated examples.
0.52003-Feb-24allDocument title changed form WFCAM FITS headers to WFCAM HDS container and FITS headers
New section on contents of HDS container
New astrometric (WCS) headers: CDi_j and PV1_n
New examples
0.62003-Mar-05allRemoved NOFFSETS header
New HDSTRACE and examples
1.02003-Oct-21allAdded TILENUM, MJD-OBS
Revised WCS items following discussions
Added section on WFCAM WCS usage
Added types for FITS values
New HDSTRACE and examples
1.12003-Oct-273.1PV3_3 corrected to PV2_3
1.12003-Oct-274Minor changes and corrections


This document illustrates the contents of a typical HDS container file into which WFCAM data is written and provides a list of FITS headers for that instrument. The FITS headers were based initially on those used for imaging with UIST but have been modified in the light of discussions, primarily in the area of the World Coordinate System headers.

Data from each of the four WFCAM cameras is to be written as NDF structures into separate HDS container files, usually as one file for each camera for each frame in a microstep pattern.

For a microstep frame, each container holds two NDF structures:

  • The first, named I1, holds the image data frame, typically a 2048×2048 array of type _REAL. Associated with this is an array of character strings in MORE.FITS that contains the FITS headers specifically associated with this frame.
  • The second NDF structure is named HEADER and is a repository for a more comprehensive array of FITS headers associated with the observation, again in a MORE.FITS extension. As all NDF structures must, HEADER contains its own DATA_ARRAY but in this case, it is simply a dummy one.

The reason for having separate HEADER and I1 structures is to make it possible to add additional I2I3 etc. structures in the same container, with the contents of HEADER being common to all the frames. At present, this facility will be exploited for focus tests, with frames at multiple focus positions being written as separate NDF structures into one container, each with its own focus setting encoded in its own frame level MORE.FITS.

See the following section for a listing of the typical structure of a WFCAM HDS container file.

Example HDSTRACE of WFCAM Container File

The following listing illustrates the structure of a typical WFCAM container file, generated using the HDSTRACE command.


X20031020_00008 <UKIRT_HDS>

I1 <NDF> {structure}

DATA_ARRAY <ARRAY> {structure}

DATA(2048,2048) <_INTEGER> 5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,

… 21,21,21,21,21,21,21,21,21,21,21


HISTORY <HISTORY> {structure}

CREATED <_CHAR*24> ‘2003-OCT-20 22:04:46.000’


RECORDS(10) <HIST_REC> {array of structures}

Contents of RECORDS(1)

DATE <_CHAR*24> ‘2003-OCT-20 22:04:46.000’

COMMAND <_CHAR*9> ‘<unknown>’

USER <_CHAR*5> ‘wfcam’

HOST <_CHAR*15> ‘’

DATASET <_CHAR*48> ‘/home/wfcam/data/raw/20031020/…’

TEXT(2) <_CHAR*72> ‘Arguments: <unknown>’,’Softwar…’

AXIS(2) <AXIS> {array of structures}

Contents of AXIS(1)

DATA_ARRAY <ARRAY> {structure}

DATA(2048) <_REAL> 0.5,1.5,2.5,3.5,4.5,5.5,6.5,

… 2044.5,2045.5,2046.5,2047.5


MORE <EXT> {structure}

FITS(4) <_CHAR*80> ‘UTSTART = 14.409722 /…’

… ‘FOC_OFF = 0.00…’

HEADER <NDF> {structure}

DATA_ARRAY <ARRAY> {structure}

DATA(1,1) <_REAL> 0


HISTORY <HISTORY> {structure}

CREATED <_CHAR*24> ‘2003-OCT-20 22:04:47.000’


RECORDS(10) <HIST_REC> {array of structures}

Contents of RECORDS(1)

DATE <_CHAR*24> ‘2003-OCT-20 22:04:47.000’

COMMAND <_CHAR*9> ‘<unknown>’

USER <_CHAR*5> ‘wfcam’

HOST <_CHAR*15> ‘’

DATASET <_CHAR*52> ‘/home/wfcam/data/raw/20031020/…’

TEXT(2) <_CHAR*72> ‘Arguments: <unknown>’,’Softwar…’

MORE <EXT> {structure}

FITS(129) <_CHAR*80> ‘ ‘,’ …’

… ‘DET_TEMP= 25….’

End of Trace.


Two tables are provided:

  • A table in section 3.1 of top-level headers which appears in the MORE.FITS section of an NDF structure called HEADER in the HDS container file;
  • A table in section 3.2 of frame level headers that appear in the MORE.FITS section of each integration within the HDS container file.

Each table lists the:

  • FITS keyword of the header;
  • Comment field in the FITS string;
  • Source of the FITS value when WFCAM is used on UKIRT (see below);
  • The usual source of the FITS value during engineering tests;
  • Type of the FITS value (either logical, character string, integer, or floating-point).

The possible sources of the FITS value are:

  • fix – The value is fixed in the header definition table;
  • om – Set from the sequencer level of observation control via the OM Translator and the OOS task. This is likely to be blank (see below) when WFCAM is run from its non-OM engineering interface;
  • inst – Set from the instrument control level (the WFIS);
  • TCS – Read from the telescope control system;
  • EPICS – Obtained from the EPICs database. When this is not available during engineering tests, this may be a fixed value;
  • data – Obtained as attribute alongside data received from the camera controller;
  • DHS – Set within the DHS system;
  • CSO – Obtained from CSO monitor task;
  • blank – The FITS value field will be blank.

Note that these sources are as seen from the point of view of the DHS. The ones in the “om” may, in turn, originate in some aspect of a survey definition, be specified by the Observer, or be specified or derived in some other way, for example from an entry in a lookup table read by the OT.

Definition of Top Level FITS Headers

FITS NameFITS CommentUKIRT SourceEng SourceType
TELESCOPTelescope namefixfixstring
CAMNUMNumber of this cameradatadatainteger
DHSVERData handling versionfixfixstring
HDTFILEName of global hdt filefixfixstring
OBSERVERObservers namesomomstring
USERIDUserid logged in asomomstring
OBSREFPATT or other referenceomomstring
PROJECTTime-allocation codeomomstring
SURVEYSurvey nameomomstring
SURVEY_IPointing ID within surveyomomstring
MSBIDId min.schedulable blockomomstring
OBJECTObject name from telescopeTCSblankstring
Data Reduction:
RECIPEData reduction recipe to be usedomomstring
OBSNUMObservation numberDHSDHSinteger
GRPNUMGroup number applied to all membersDHSDHSinteger
GRPMEMGroup membership omomlogical
TILENUMTile number applied to all membersDHSDHSinteger
STANDARDIs the target a standard staromomlogical
NJITTERNumber of positions in telescope jitter patternomominteger
JITTER_ISerial number of this telescope jitter patternomominteger
JITTER_X[arcsec] X (RA) offset in telescope jitter patternomomfloat
JITTER_Y[arcsec] Y (Dec) offset in telescope jitter patternomomfloat
NUSTEPNumber of positions in microstep patternomominteger
USTEP_ISerial number in this microstep patternomominteger
USTEP_X[arcsec] X (RA) offset in microstep patternomomfloat
USTEP_Y[arcsec] Y (Dec) offset in microstep patternomomfloat
NFOCNumber of positions in focus scaninstinstinteger
NFOCSCANNumber of focus scans in focus testinstinstinteger
Astrometric and time information:
UTDATEUT date as integer in yyyymmdd formatinstinststring
DATE-OBSDate and time (UTC) of start of observationdatedatestring
DATE-ENDDate and time (UTC) of end of observationdatedatestring
MJD-OBSDATE-OBS as Modified Julian Datedatadatafloat
WCSAXESNumber of axes in world co-ordinate systemfixfixinteger
RADESYSMean IAU 1984 equatorial co-ordinatesfixfixstring
EQUINOX[yr] Equinox of object positionTCSfixfloat
CTYPE1Algorithm type for axis 1fixfixstring
CTYPE2Algorithm type for axis 2fixfixstring
CRPIX1[pixel] Reference pixel along axis 1 (RA)instinstfloat
CRPIX2[pixel] Reference pixel along axis 2 (Dec)instinstfloat
CRVAL1[deg] Right ascension at the reference pixelTCSfixfloat
CRVAL2[deg] Declination at the reference pixelTCSfixfloat
CRUNIT1Unit of right ascension co-ordinatesfixfixstring
CRUNIT2Unit of declination co-ordinatesfixfixstring
CD1_1Transformation matrix elementinstinstfloat
CD1_2Transformation matrix elementinstinstfloat
CD2_1Transformation matrix elementinstinstfloat
CD2_2Transformation matrix elementinstinstfloat
PV2_1Pol. coefficient. for pixel -> celestial coord.instinstfloat
PV2_2Pol. coefficient. for pixel -> celestial coord.instinstfloat
PV2_3Pol. coefficient. for pixel -> celestial coord.instinstfloat
RABASE[h] Right ascension of base positionTCSfixfloat
DECBASE[deg] Declination of base position TCSfixfloat
TRAOFF[arcsec] Right ascension telescope offset TCSfixfloat
TDECOFF[arcsec] Declination telescope offsetTCSfixfloat
AMSTARTAirmass at start of observationTCSfixfloat
AMENDAirmass at end of observationTCSfixfloat
TELRA[h] Current telescope right ascension TCSfixfloat
TELDEC[deg] Current telescope declinationTCSfixfloat
GSRA[h] Right ascension of guide starTCSfixfloat
GSDEC[deg] Declination of guide starTCSfixfloat
Instrument detector configuration:
DETECTORType of detector array used fixfixstring
DETECTIDSerial number of detector arraydatadatastring
NINTNumber of integrations in observationdatadatainteger
DROWS[pixel] Number of detector rowsdatadatainteger
DCOLUMNS[pixel] Number of detector columnsdatadatainteger
RDOUT_X1Start column of array readoutdatadatainteger
RDOUT_X2End column of array readoutdatadatainteger
RDOUT_Y1Start row of array readoutdatadatainteger
RDOUT_Y2End row of array readoutdatadatainteger
PIXLSIZE[arcsec] Pixel sizeinstinstfloat
Detector controller:
PCSYSIDPC system identifierinstinststring
SDSUIDSerial number of SDSU controller instinststring
READMODEName of camera readmodeinstinststring
CAPPLICNName of camera readout applicationdatadatastring
CAMROLECamera role (masterlslavelunsync)instinststring
READOUTCamera readout (CDSINDRISARIRRR)datadatastring
EXP_TIME[s] Integration time per exposureinstinstfloat
NEXPNumber of exposures in integrationinstinstinteger
READINT[s] Interval between readsdatadatafloat
NREADSNumber of reads per exposuredatadatainteger
GAIN[electrons/ADU] Detector gaindatadatagloat
Instrument optical configuration:
FOC_MM[mm] Base focus positionEPICSEPICSstring
AIRTEMP[degC] Air temperatureEPICSfixfloat
BARPRESSAmbient pressureEPICSfixfloat
DEWPOINT[degC] DewpointEPICSfixfloat
DOMETEMP[degC] Dome temperaureEPICSfixfloat
HUMIDITYRelative humidityEPICSfixfloat
MIRRBSW[degC] Temperature mirror B SWEPICSfixfloat
MIRR_NE[degC] MIrror temperature NEEPICSfixfloat
MIRR_NW[degC] Mirror temperature NWEPICSfixfloat
MIRR_SE[degC] Mirror temperature NEEPICSfixfloat
MIRR_SW[degC] Mirror temperature SWEPICSfixfloat
MIRRBTNW[degC] Mirror bottom temp. NWEPICSfixfloat
MIRRTPNW[degC] Mirror top temp. NWEPICSfixfloat
SECONDAR[degC] Temperature of secondaryEPICSfixfloat
TOPAIRNW[degC] Top air NWEPICSfixfloat
TRUSSENE[degC] Truss leg ENEEPICSfixfloat
TRUSSWSW[degC] Truss les WSW EPICSfixfloat
WIND_DIR[deg] Truss leg ENEEPICSfixfloat
WIND_SPD[km/h] Wind speedEPICSfixfloat
CSOTAUTau at 225 GHz from CSOCSOfixfloat
TAUDATETime and date of Tau readingCSOfixstring
TAUSRCSource or opacity dataCSOfixstring
CNFINDEXConfiguration indexEPICSEPICSinteger
DET_TEMP[K] Array temperatureEPICS EPICSfloat
< More camera engineering data will go here >

Example of Top Level FITS Headers



TELESCOP= ‘UKIRT ‘ / Telescope name

INSTRUME= ‘WFCAM ‘ / Instrument

CAMNUM = 2 / Number of WFCAM camera (1, 2, 3 or 4)

DHSVER = ‘UKDHS 2002 Oct 31 ‘ / Data handling version

HDTFILE = ‘wfcam.hdt ‘ / Name of global hdt file

HDTFILE2= ‘wfcam2.hdt ‘ / Name of camera-specific hdt file

OBSERVER= ‘Mrs Observer’ / Observers names

USERID = ‘abc ‘ / Userid logged in as

OBSREF = ‘notPATT99’ / PATT or other reference

PROJECT = ‘Example WFCAM data’ / Time-allocation code

SURVEY = ‘Demo survey 123’ / Survey name

SURVEY_I= ‘B1.99.4 ‘ / Pointing ID within survey

MSBID = ’42 ‘ / Id min.-schedulable block

OBJECT = ‘Laboratory wall’ / Object name from telescope

Data Reduction:

RECIPE = ‘QUICK_LOOK’ / Data reduction recipe to be used


OBSNUM = 8 / Observation number

GRPNUM = 8 / Group number applied to all members

GRPMEM = T / Group membership

TILENUM = 0 / Tile number applied to all members

STANDARD= F / Is the target a standard star observation?

NJITTER = 4 / Number of positions in tel jitter pattern

JITTER_I= 1 / Serial number in this tel jitter pattern

JITTER_X= 0.00 / [arcsec] X (RA) offset in tel jitter pattern

JITTER_Y= 0.00 / [arcsec] Y (Dec) offset in tel jitter pattern

NUSTEP = 4 / Number of positions in microstep pattern

USTEP_I = 1 / Serial number in this microstep pattern

USTEP_X = 0.00 / [arcsec] X (RA) offset in microstep pattern

USTEP_Y = 0.00 / [arcsec] Y (Dec) offset in microstep pattern

NFOC = 0 / Number of positions in focus scan

NFOCSCAN= 0 / Number of focus scans in focus test

Astrometric and time information:

UTDATE = ‘20031020’ / UT date as integer in yyyymmdd format

DATE-OBS= ‘2003-10-20T14:24:35Z’ / Date and time (UTC) of start of observation

DATE-END= ‘2003-10-20T14:24:39Z’ / Date and time (UTC) of end of observation

MJD-OBS = 52932.60040 / DATE-OBS as Modified Julian Date

WCSAXES = 2 / Number of axes in world co-ordinate system

RADESYS = ‘FK5 ‘ / Mean IAU 1984 equatorial co-ordinates

EQUINOX = 2000.000 / [yr] Equinox of object position

CTYPE1 = ‘RA—ZPN’ / Algorithm type for axis 1

CTYPE2 = ‘DEC–ZPN’ / Algorithm type for axis 2

CRPIX1 = -1000.0 / [pixel] Reference pixel along axis 1 (RA)

CRPIX2 = -1000.0 / [pixel] Reference pixel along axis 2 (Rec)

CRVAL1 = 300.16419 / [deg] Right ascension at the reference pixel

CRVAL2 = 29.9749447 / [deg] Declination at the reference pixel

CRUNIT1 = ‘deg ‘ / Unit of right ascension co-ordinates

CRUNIT2 = ‘deg ‘ / Unit of declination co-ordinates

CD1_1 = 0.000000E+00 / Transformation matrix element

CD1_2 = -1.000000E+00 / Transformation matrix element

CD2_1 = 5.000000E-01 / Transformation matrix element

CD2_2 = -5.000000E-01 / Transformation matrix element

PV2_1 = 1.000000E+00 / Pol.coeff. for pixel -> celestial coord

PV2_2 = 0.000000E+00 / Pol.coeff. for pixel -> celestial coord

PV2_3 = 7.500000E+01 / Pol.coeff. for pixel -> celestial coord

RABASE = 20.0109458 / [h] Right ascension of base position

DECBASE = 29.9749447 / [deg] Declination of base position

TRAOFF = 0.000 / [arcsec] Right ascension telescope offset

TDECOFF = 0.000 / [arcsec] Declination telescope offset

AMSTART = 1.771 / Airmass at start of observation

AMEND = 1.769 / Airmass at end of observation

TELRA = 20.0123456 / [h] Current telescope right ascension

TELDEC = 29.9876543 / [deg] Current telescope declination

GSRA = 20.0103456 / [h] Right ascension of guide star

GSDEC = 29.9806543 / [deg] Declination of guide star

Instrument detector configuration:

DETECTOR= ‘RSC Hawaii 2’ / Type of detector array used

DETECTID= ‘a.bc.234’ / Serial number of detector array

NINT = 1 / Number of integrations in observation

DROWS = 2048 / [pixel] Number of detector rows

DCOLUMNS= 2048 / [pixel] Number of detector columns

RDOUT_X1= 1 / Start column of array readout

RDOUT_X2= 2048 / Start column of array readout

RDOUT_Y1= 1 / Start row of array readout

RDOUT_Y2= 2048 / Start row of array readout

PIXLSIZE= 0.4000 / [arcsec] Pixel size

Detector controller:

PCSYSID = ‘wfacq2 ‘ / PC system identifier

SDSUID = ‘00223 ‘ / Serial number of SDSU controller

READMODE= ‘CDS_v1 ‘ / Name of camera readmode

CAPPLICN= ‘applic01’ / Name of camera readout application

CAMROLE = ‘master ‘ / Camera role (master|slave|unsync)

READOUT = ‘CDS ‘ / Camera readout (CDS|NDR|SAR|RRR)

EXP_TIME= 1.000000 / [s] Integration time per exposure

NEXP = 1 / Number of exposures in integration

READINT = 1.000000 / [s] Interval between reads

NREADS = 0 / Number of reads per exposure

GAIN = 1.0 / [electrons/ADU] Detector gain

Instrument optical configuration:

FILTER = ‘whatever’ / Filter name

FOC_MM = 12.34 / [mm] Base focus position


AIRTEMP = 5.785 / [degC] Air temperature

BARPRESS= 650.000 / Ambient pressure

DEWPOINT= 2.000 / [degC] Dewpoint

DOMETEMP= 7.095 / [degC] Dome temperature

HUMIDITY= 35.450 / Relative humidity

MIRRBSW = 7.123 / [degC] Temperature mirror B SW

MIRRNE = 7.124 / [degC] Mirror temperature NE

MIRRNW = 7.125 / [degC] Mirror temperature NW

MIRRSE = 7.126 / [degC] Mirror temperature SE

MIRRSW = 7.127 / [degC] Mirror temperature SW

MIRRBTNW= 7.128 / [degC] Mirror bottom temp. NW

MIRRTPNW= 7.129 / [degC] Mirror top temp. NW

SECONDAR= 7.130 / [degC] Temperature of secondary

TOPAIRNW= 7.131 / [degC] Top air NW

TRUSSENE= 7.132 / [degC] Truss leg ENE

TRUSSWSW= 7.133 / [degC] Truss leg WSW

WIND_DIR= 106.987 / [deg] Wind direction, azimuth

WIND_SPD= 16.089 / [km/h] Wind speed

CSOTAU = 0.047 / Tau at 225 GHz from CSO

TAUDATE = ‘2001-11-30T04:07’ / Time and date of Tau reading

TAUSRC = ‘CSO ‘ / Source of opacity data


CNFINDEX= 1 / Configuration index

DET_TEMP= 25.0 / [K] Detector array temperature

Definition of Frame Level FITS Headers

FITS NameFITS CommentUKIRT SourceEng SourceType
UTSTART[h] Start time of integrationdatadatafloat
UTEND[h] End time of integrationdatadatafloat
FOC_ISerial number in focus scandatadatainteger
FOC_OFF[mm] Offset from base focus position datadatafloat

Example of Frame Level FITS Headers


UTSTART = 14.409722 / [h] Start time of integration

UTEND = 14.410833 / [h] End time of integration

FOC_I = 0 / Serial number in focus scan

FOC_OFF = 0.000 / [mm] Offset from base focus position


Several items in the top-level FITS headers are connected with World Coordinate System (WCS) information. Thanks to Andy Vick for the explanations.

Note that all but the CTYPEn values are candidates for being updated with new values during commissioning.

1. CTYPEn FITS items

CTYPE1 and CTYPE2 give the output format. That is to say, they give the format for the coordinates after you have applied all the transformations. In our case CTYPE1 is “RA—ZPN” and CTYPE2 is “DEC—ZPN”. This implies that the transformation is a zenith polynomial one.

2. CRVAL and CRPIX FITS items

These define the position of the reference pixel, which will initially be set to as near the optical axis of the instrument as possible.

3. CD FITS items

The CD FITS items (CD1_1, etc) specify a transformation from pixel space with respect to a reference point to projection plane coordinates with respect to a reference point.

4. PV FITS items

A comment in the ITS WCS document states in order to do a radial expansion, as in ZPN, then the coefficients go in the PV matrix keywords appropriate for the ‘latitude’ axis, which in our case is the second axis. The information is carried by the FITS keywords of the form PV2_n, and the PV1_n keywords are not used.

The initial values are:

  • PV2_1 = 1.0
  • PV2_2 = 0.0
  • PV2_3 = 75.0