User's Guide

for

Common Data Format (CDF)-to-Flexible Planetary Data System (PDS)
Translator

David Han

September 10, 2007

National Space Science Data Center,

Goddard Space Flight Center

Phone: 301-286-3617

E-mail: <david.b.han@nasa.gov>

# Introduction

This document is designed for computer programmers and scientists who
would like to understand how the CDF-to-PDS translator (hereinafter
referred to as the Translator) program works and what changes need to be
made to adapt the translator to handle Common Data Format (CDF) files
that are other than the following:

> \- CDFs for Apollo 14 and 15 Cold Cathode Ion Gage (CCIG) data
> (1971-1973)
>
> \- CDFs for Apollo 12 and 15 Solar Wind Spectrometer (SWS) data
> (1971-1973)

# Platforms, compilers, and library

The translator is written in C, and it's tested on an Intel Linux
machine with Fedora Core 6. The program doesn't contain system-dependent
calls, and it should compile fine on any platform with any ANSI C
compilers.

The translator reads a generic CDF file and creates a detached PDS label
and ASCII table. Reading CDF data and metadata requires CDF 3.1 library
or later that is available at http://cdf.gsfc.nasa.gov.

## How to Compile and Link on Linux

> cc -o cdf-to-pds -I\<CDF_include_directory\> cdf-to-pds.c
> \<CDF_library_directory\>/libcdf.a -lm
>
> For example, if the CDF library is installed under /home/cdf, then the
> compilation command should be
>
> cc --o cdf-to-pds --I/home/cdf/include cdf-to-pds.c
> /home/cdf/lib/libcdf.a -lm

## How to Invoke the Translator

> cdf-to-pds \<CDF_FILE_NAME\>
>
> where CDF_FILE_NAME is the full path name of the CDF file to be
> translated.
>
> Entering the name of the program (cdf-to-pds) alone will display the
> help message on the screen.
>
> Examples:
>
> cdf-to-pds apollo15_sws_cdf
>
> cdf-to-pds /home/my_account/Apollo/apollo15_sws_cdf
>
> By default, the name of the PDS output file is the same as the name of
> the input CDF file. For example, if you translate my_data.cdf, it'll
> create my_data.LBL (label file) and my_data.TAB (ASCII table file).
> One can override the default output file name with the -output option.

cdf-to-pds -output XYZ apollo15_sws_cdf

# Translator Description

The translator reads a generic CDF file and creates a detached PDS label
and ASCII table. It also creates a basic PDS catalog file. One should
examine the catalog file (DATASET.CAT) and expand it as necessary. The
translator currently understands scalar variables and doesn't understand
vectors and higher dimensional arrays. Support for these structures will
be implemented in the near future.

The translator only creates PDS labels (no PDS tables) for the Apollo 14
and 15 (1971 - 1973) CCIG atmospheric density plot that are stored in
external TIFF files. External TIFF images are simply referenced in the
labels.

## Structure of CDF (variables and attributes)

CDF has two entities: variable and attributes. CDF\'s \"variable\" is a
generic name or an object that represents data where data can be
0-dimensional (scalar data) or multi-dimensional (up to 10-dimension),
and it does not have any scientific context associated it. For example,
a variable can be data representing an independent variable, a dependent
varibale, time and date value, or whatever data might be (e.g. image,
XML file, etc.). In other words, the variable doesn\'t contain any
hidden meanings other than the data itself.

CDF attributes are the mechanism for storing metadata, and there are two
different types of attributes: global attributes and variable
attributes. Global attributes can include any information that describes
a CDF file such as a title of the CDF, data set documentation, or a CDF
modification history. Variable attributes describe the individual
variables and their values. Examples of variable attributes would
include such things as a field name for the variable, the valid minimum
and maximum, the units in which the variable data values are stored, the
format in which the data values are to be displayed, and a fill value
for errant or missing data,

## CDF Global Attributes to PDS mapping 

CDF global attributes are translated as PDS keywords in a PDS label
file. Below is a list of the CDF global attributes recognized by the
Translator and their mapped PDS keywords.

  ---------------------------------- -- ----------------------------------
  CDF global attribute                  PDS keyword

                                        

  PDS_VERSION_ID                        PDS_VERSION_ID

  RECORD_TYPE                           RECORD_TYPE

  PDS\_ RECORD_TYPE                     RECORD_TYPE

  MISSION_NAME                          MISSION_NAME

  PDS\_ MISSION_NAME                    MISSION_NAME

  INSTRUMENT_HOST_ID                    INSTRUMENT_HOST_ID

  PDS\_ INSTRUMENT_HOST_ID              INSTRUMENT_HOST_ID

  INSTRUMENT_HOST_NAME                  INSTRUMENT_HOST_NAME

  PDS_INSTRUMENT_HOST_NAME              INSTRUMENT_HOST_NAME

  INSTRUMENT_ID                         INSTRUMENT_ID

  PDS\_ INSTRUMENT_ID                   INSTRUMENT_ID

  INSTRUMENT_NAME                       INSTRUMENT_NAME

  PDS\_ INSTRUMENT_NAME                 INSTRUMENT_NAME

  DATA_SET_ID                           DATA_SET_ID

  PDS\_ DATA_SET_ID                     DATA_SET_ID

  PRODUCT_ID                            PRODUCT_ID

  PDS\_ PRODUCT_ID                      PRODUCT_ID

  SPACECRAFT_CLOCK_START_TIME           SPACECRAFT_CLOCK_START_TIME

  PDS\_ SPACECRAFT_CLOCK_START_TIME     SPACECRAFT_CLOCK_START_TIME

  SPACECRAFT_CLOCK_STOP_TIME            SPACECRAFT_CLOCK_STOP_TIME

  PDS\_ SPACECRAFT_CLOCK_STOP_TIME      SPACECRAFT_CLOCK_STOP_TIME

  SPACECRAFT_CLOCK_START_COUNT          SPACECRAFT_CLOCK_START_COUNT

  PDS\_ SPACECRAFT_CLOCK_START_COUNT    SPACECRAFT_CLOCK_START_COUNT

  SPACECRAFT_CLOCK_STOP_COUNT           SPACECRAFT_CLOCK_STOP_COUNT

  PDS\_ SPACECRAFT_CLOCK_STOP_COUNT     SPACECRAFT_CLOCK_STOP_COUNT

  START_TIME                            START_TIME

  PDS\_ START_TIME                      START_TIME

  STOP_TIME                             STOP_TIME

  PDS\_ STOP_TIME                       STOP_TIME

  TARGET_NAME                           TARGET_NAME

  PDS\_ TARGET_NAME                     TARGET_NAME
  ---------------------------------- -- ----------------------------------

One can override the value of the DATA_SET_ID or PDS_DATA_SET_ID by
specifying the desired DATA_SET_ID value from the command line with the
-dataset_id option.

cdf-to-pds -dataset_id \<new data set ID\> \<input CDF\>

## CDF variables and variable attributes to PDS mapping 

Individual CDF variable is translated as a PDS column and its variable
attributes are captured as PDS column attributes in the COLUMN object.
Since PDS column attributes must be PDS approved names, not all CDF
variable attributes are captured. Below is a list of the CDF variable
attributes captured and their corresponding PDS attribute names.

  ----------------------------- ---------- -------------------------------
  CDF variable attribute                   PDS column attribute

                                           

  CATDESC                                  DESCRIPTION

  FILLVAL                                  MISSING_CONSTANT

  FORMAT                                   FORMAT

  UNITS                                    UNIT
  ----------------------------- ---------- -------------------------------

### CDF units to PDS units mapping file 

The PDS system for units, where applicable, is the Systeme
Internationale d'Unites (SI). If the value of the CDF variable attribute
named UNITS doesn't conform to SI, one can change the value of the UNITS
attribute by editing the cdf_to_pds_mapping.dat file. This mapping file
is an ASCII text file that can be edited with any text editor. Each line
in the mapping file that doesn't start with "#" defines the mapping
information, and it contains two columns. The first column represents
the value of the CDF's variable attribute named UNITS and the second
column specifies the value of the UNIT attribute of the COLUMN object in
a PDS label.

The name of the default mapping file is cdf_to_pds_mapping.dat. If one
wants to use its own mapping file, one can specify the name of the
user-supplied mapping file with the -map option.

cdf-to-pds -map my_mapping_file.dat \<input cdf file\>

### Changing the Order and/or Content of PDS Label File 

PDS label file is generated in a function called write_pds_label. If you
would like to change the order of the keywords and/or add or remove PDS
keywords, please change this function.

# PDS Label and Table Validation 

PDS labels and ASCII tables generated from the Translator are validated
against the lvtool and pdstv programs, respectively.