Difference between revisions of "Notes for Labelling FITS files"

From The SBN Wiki
Jump to navigation Jump to search
(Creation - Safety Save)
(Safety Save)
Line 3: Line 3:
 
== Scalar Data Types ==
 
== Scalar Data Types ==
  
Regardless if the data structure, the supported data types are
+
Regardless of the data structure, the supported data types are
 
strictly limited by the FITS standard.  Here are the types you may encounter in FITS files (as specified by the '''BITPIX''' keyword), and their PDS4 equivalents:
 
strictly limited by the FITS standard.  Here are the types you may encounter in FITS files (as specified by the '''BITPIX''' keyword), and their PDS4 equivalents:
  
Line 10: Line 10:
 
! BITPIX Value !! PDS Data Type(s)
 
! BITPIX Value !! PDS Data Type(s)
 
|-
 
|-
| align="center" | 8 || UnsignedByte <br>'' -or- ''<br>
+
| align="center" | 8 || UnsignedByte '' -or- '' 7-bit ASCII character
7-bit ASCII character (could be any of the ''ASCII_*'' types)
 
 
|-
 
|-
 
| align="center" | 16 || SignedMSB2 (integer)
 
| align="center" | 16 || SignedMSB2 (integer)
Line 24: Line 23:
 
|}
 
|}
  
 +
Table types will always have "''BITPIX = 8''".  Binary tables will have data types for each
 +
individual field (all corresponding to one of the types above) indicated by the ''TFORM'' keywords.  ASCII tables are restricted to 7-bit ASCII printable characters + carriage-control, and the individual fields will have types corresponding to the various ''ASCII_*'' data types of PDS4.
  
 
== Headers ==
 
== Headers ==
Line 33: Line 34:
 
* The ''&lt;object_length&gt;'' must be the number of FITS blocks comprising the header * 2880 (the size of a single FITS block).
 
* The ''&lt;object_length&gt;'' must be the number of FITS blocks comprising the header * 2880 (the size of a single FITS block).
  
 +
== Arrays ==
  
== 2D Images and Arrays ==
+
=== Axis Ordering ===
 +
Fits array data are are stored such that the ''NAXIS1'' subscript varies fastest, ''NAXIS2'' next fastest, and so on up to ''NAXISn''.  So the storage order is first-index-fastest in FITS notation.
  
== 3D Images and Arrays ==
+
In PDS, arrays are stored so that axis 1 (the axis described by the ''&lt;Axis_Array&gt;'' that has ''&lt;sequence_number&gt;'' of "1") varies least rapidly, axis 2 next least rapidly, and so on to axis ''n''.
  
== Higher-Dimensional Arrays ==
+
So, when labeling a FITS array as a PDS ''Array''-type object, the highest-numbered ''NAXIS*'' becomes axis 1 in the PDS array, the next-highest ''NAXIS*'' becomes axis 2, and so on.
 +
 
 +
=== Array Elements Description ===
 +
 
 +
In the FITS primary data header or image extension header, the following reserved FITS keywords also have direct PDS4 equivalents in the ''&lt;Element_Array&gt;'' class.
 +
 
 +
{| class="wikitable"
 +
! FITS !! PDS4 ''Array''
 +
|-
 +
| BSCALE || &lt;Element_Array&gt;/&lt;scaling_factor&gt;
 +
|-
 +
| BZERO  || &lt;Element_Array&gt;/&lt;value_offset&gt;
 +
|-
 +
| BUNIT  || &lt;Element_Array&gt;/&lt;unit&gt;
 +
|-
 +
| BLANK <br> ''integer data only'' || ''see below''
 +
|-
 +
| DATAMAX || &lt;Object_Statistics&gt;/&lt;derived_maximum&gt;
 +
|-
 +
| DATAMIN || &lt;Object_Statistics&gt;/&lt;derived_minimum&gt;
 +
|}
 +
 
 +
The ''BLANK'' keyword, when used according to the FITS standard, may only be used with integer data, and may either be a blank (if BSCALE is 1 and BZERO is 0), otherwise it contains a flag value indicating null data.  If you need to specify a null value, add the ''&lt;Special_Constants&gt;'' class to the ''Array'' class, and select the appropriate special constant for the case in hand.  Note that the ''BLANK'' value is the value read from the file - ''before'' any scale factor and offset are applied.
 +
 
 +
=== 2D Images ===
 +
 
 +
In addition to the above correspondences, the PDS4 ''Array_2D_Image'' class has the following additional correspondences.
 +
 
 +
* ''NAXIS1'' corresponds to axis 2, and axis 2 '''must''' have an ''&lt;axis_name&gt;'' of "Sample".
 +
* ''NAXIS2'' corresponds to axis 1, and axis 1 '''must''' have an ''&lt;axis_name&gt;'' of "Line".
 +
 
 +
Also note that the FITS standard says nothing about display direction.  It seems to be universally true that samples (NAXIS1) are always drawn left-to-right; but lines are drawn either top-to-bottom or bottom-to-top with roughly equal frequency.  You will have to look at your FITS images and determine the correct order of display.
 +
 
 +
The display order is specified in the ''&lt;Display_2D_Image&gt;'' class.
  
 
== Binary Tables ==
 
== Binary Tables ==
  
 
== ASCII Tables ==
 
== ASCII Tables ==

Revision as of 18:44, 28 February 2013

Fits tables, images and arrays are all compliant as they are with the PDS4 data formatting standards. Follow the guidelines below for filling in the PDS4 attribute values.

Scalar Data Types

Regardless of the data structure, the supported data types are strictly limited by the FITS standard. Here are the types you may encounter in FITS files (as specified by the BITPIX keyword), and their PDS4 equivalents:

BITPIX Value PDS Data Type(s)
8 UnsignedByte -or- 7-bit ASCII character
16 SignedMSB2 (integer)
32 SignedMSB4 (integer)
-32 IEEE754MSBSingle (float)
64 SignedMSB8 (integer)
-64 IEEE754MSBDouble (float)

Table types will always have "BITPIX = 8". Binary tables will have data types for each individual field (all corresponding to one of the types above) indicated by the TFORM keywords. ASCII tables are restricted to 7-bit ASCII printable characters + carriage-control, and the individual fields will have types corresponding to the various ASCII_* data types of PDS4.

Headers

Use the PDS4 Header object to describe any type of FITS header.

  • For <encoding_type>, use "Character"
  • For <external_standard_id>, use "FITS 3.0". This is not a valid standard value, but the current value is not sufficiently specific. If you want to reference an earlier version of the FITS standard, check with your PDS consultant.
  • The <object_length> must be the number of FITS blocks comprising the header * 2880 (the size of a single FITS block).

Arrays

Axis Ordering

Fits array data are are stored such that the NAXIS1 subscript varies fastest, NAXIS2 next fastest, and so on up to NAXISn. So the storage order is first-index-fastest in FITS notation.

In PDS, arrays are stored so that axis 1 (the axis described by the <Axis_Array> that has <sequence_number> of "1") varies least rapidly, axis 2 next least rapidly, and so on to axis n.

So, when labeling a FITS array as a PDS Array-type object, the highest-numbered NAXIS* becomes axis 1 in the PDS array, the next-highest NAXIS* becomes axis 2, and so on.

Array Elements Description

In the FITS primary data header or image extension header, the following reserved FITS keywords also have direct PDS4 equivalents in the <Element_Array> class.

FITS PDS4 Array
BSCALE <Element_Array>/<scaling_factor>
BZERO <Element_Array>/<value_offset>
BUNIT <Element_Array>/<unit>
BLANK
integer data only
see below
DATAMAX <Object_Statistics>/<derived_maximum>
DATAMIN <Object_Statistics>/<derived_minimum>

The BLANK keyword, when used according to the FITS standard, may only be used with integer data, and may either be a blank (if BSCALE is 1 and BZERO is 0), otherwise it contains a flag value indicating null data. If you need to specify a null value, add the <Special_Constants> class to the Array class, and select the appropriate special constant for the case in hand. Note that the BLANK value is the value read from the file - before any scale factor and offset are applied.

2D Images

In addition to the above correspondences, the PDS4 Array_2D_Image class has the following additional correspondences.

  • NAXIS1 corresponds to axis 2, and axis 2 must have an <axis_name> of "Sample".
  • NAXIS2 corresponds to axis 1, and axis 1 must have an <axis_name> of "Line".

Also note that the FITS standard says nothing about display direction. It seems to be universally true that samples (NAXIS1) are always drawn left-to-right; but lines are drawn either top-to-bottom or bottom-to-top with roughly equal frequency. You will have to look at your FITS images and determine the correct order of display.

The display order is specified in the <Display_2D_Image> class.

Binary Tables

ASCII Tables