USGS  : Lunar Calibration, ROLO - Robotic Lunar Observatory : ROLO Facility Telescope
pseudoBanner - Lunar Calibration

Exchange File Formats

Currently all information exchange between a Spacecraft Calibration Team (SCT) and the USGS Lunar Calibration Team (LCT) is done with ASCII text files. The amount of information to be exchanged is modest, and ASCII files are easily read by both humans and computers. Eventually, comparisons of the spatially resolved lunar radiance will likely require binary information exchange.

Spectral Response Files (required only once)

The SCT should provide the system-level relative spectral response for each band, with a spectral resolution on the order of 1 nm (for spectrometers, the nominal full-width at half-maximum will generally be adequate). Absolute scaling is not important; the response functions can be normalized. A useful format for the LCT is a two-column ASCII text file for each band, with the first column being wavelength in nm and the second column being transmission or response. For response, the LCT must know whether the detectors respond to photons or energy.

Note: Once a band order is established for an instrument, that order should be maintained for all future file exchanges. Model results can optionally be sorted into ascending wavelength order.

Lunar Observation Files

The exchange files are generated by the SCT and LCT in pairs that roughly parallel one another. There are different formats for single and multiple observations of the Moon, with the Multiple Observation Files more common (time series of lunar views are the most useful; multiple observations are strongly encouraged). Because these files are ASCII text for input to computer programs, adherence to the standard formats is essential.

Each file begins with a label section that contains "keyword=value" entries, terminated by a separate line containing C_END. This section is followed by a table section containing the observation parameters (SCT) or model results (LCT). The label section may contain subsections, marked by the special keyword SECTION. This is done for readability, to distinguish the observational data supplied by the SCT from the model results generated by the LCT.

A line in the label section has the following elements:

  • A keyword, with no interior blanks. Valid keywords are listed and defined below. Keywords must appear exactly as in the list (case-sensitive).
  • An equal sign = between the keyword and value, with any number of blanks on either side (or none).
  • A value, which may be numeric or alpha-numeric. Embedded blanks are allowed, as are any number of surrounding blanks. Units may be indicated, enclosed between < and > -- this is for readability only, units for each item are prescribed.
  • An optional description/comment, initiated by an exclamation mark !.
  • The special keyword BEGIN_FREE, which starts a free-form area within the label section. This area typically is used to describe the table section, with column headers, formats, etc. This area may contain any number of text lines, and is terminated by the C_END line. For readability, free-form text lines that extend beyond 80 columns are discouraged.
  • The C_END line, which is always the last line before the table section.

The table section begins immediately after the C_END line, therefore any explicit column headers must appear before this line. The items in the table section must be space (not tab) delimited. Alignment is encouraged for human readability, but is not strictly required.

The contents of the label and table sections differ for single-observation and multi-observation files. For single observation files, the label section contains the observation geometry information, while the table section lists the irradiance information for each instrument band. For multiple observations, two sets of files are used, one (SCT/LCT pair) for geometry, one for irradiance. The rows of the table sections correspond to individual lunar observations, with the instrument bands arranged in columns. To accommodate all bands in one row, the table sections of these files can exceed an 80-character width. Further explanations of the table section contents have been appended in the examples linked below.

Examples

SCT Single Observation File [SCT_single.Sgrad]
LCT Single Observation Model Comparison File [LCT_single.Lgrad]

SCT Geometry Multiple Observation File [SCT_multi.Sgeom]
SCT Irradiance Multiple Observation File [SCT_multi.Lirad]
LCT Geometry Multiple Observation File [LCT_multi.Lgeom]
LCT Model Comparison Multiple Observation File [LCT_multi.Lirad]

Label Section Keywords

The keywords appearing in an exchange file label section are specific to the file type. Keyword definitions for each file type are listed below. All keywords must appear in the label section of SCT files, in the order listed (except the optional keyword NOTE).

SCT Single Observation File Keywords
LCT Single Observation File Keywords
SCT Multiple Observation File Keywords
LCT Multiple Observation File Keywords

SCT Single Observation File Keywords

Instrument = A unique identification of the instrument, possibly including separate optical components, e.g. ASTER SWIR. Internal blanks are allowed.

User = The name of the (one) person representing the SCT. Internal blanks are allowed.

Image_Time = Coordinated Universal Time (UTC) of the observation. For a push-broom system, this should be the time when the scan line crossed the geometric center of the Moon. The format is specific, and consistent with ISO-8601 (See http://www.w3.org/TR/NOTE-datetime). It must follow exactly (as in the single observation example linked above, 2001-11-01T21:05:43.):

  • four decimal characters of year
  • a dash (-)
  • two decimal characters of month
  • a dash (-)
  • two decimal characters of day within month
  • a "T" (T)
  • two decimal characters of hour
  • a colon (:)
  • two decimal characters of minute
  • a colon (:)
  • two decimal characters of integral second
  • optionally followed by a decimal point and decimal fraction of a second.

Spacecraft_X = The X coordinate of the spacecraft position at Image_Time in the J2000 coordinate system, expressed in kilometers. This is the non-rotating coordinate system normally used for orbital dynamics calculations.

Spacecraft_Y = The corresponding Y coordinate.

Spacecraft_Z = The corresponding Z coordinate.

Moon_Y_size = The apparent diameter of the Moon in the direction of elongation (or compression) of the image due to scanning, expressed in milliradians. This is measured to the geometric limbs, one possibly unilluminated. If the oversampling of the observation is known accurately, then this keyword can contain the oversampling factor (the SCT must inform the LCT if the oversampling factor is being used). For a framing imaging system that completely captures the Moon with short exposure time, this value is not needed (keyword is set to zero).

The following two keywords are relevant only if the Moon was not completely captured in the image, hence in the irradiance sum.

Missing_Fraction = The areal fraction of the geometric Moon not represented in the irradiance sum.

Clip_Angle = The azimuthal angle measured counterclockwise about the geometric center of the Moon from Celestial North to the middle of the missing section, expressed in degrees.

NOTE = A free-form line containing any additional text.

LCT Single Observation File Keywords

The label section for a LCT Single Observation File contains two subsections, marked by SECTION = lines. The first repeats the SCT label information, as a check. The second contains the computed geometric parameters for the observation, in the following keywords.

Process = The name of the software system that ran the model comparison.

Version = The version date of the Process software that was used.

Run_Time = The local date and time of the model run, as YearMonthDay hour:minute:second

Lunar_model = Identification of the lunar model version used. This includes identification of the model coefficients files used.

Barycentric_Time = Image_Time converted to barycentric dynamical time, expressed as a double-precision Julian date. This is the continuous, uniform time system used for planetary ephemeris calculations, and differs somewhat from UTC.

Sun_Moon_lon = The Selenographic longitude of the sub-solar point on the Moon, in degrees.

Sun_Moon_lat = The Selenographic latitude of the sub-solar point on the Moon, in degrees.

SC_Moon_lon = The Selenographic longitude of the sub-spacecraft point on the Moon, in degrees.

SC_Moon_lat = The Selenographic latitude of the sub-spacecraft point on the Moon, in degrees.

SC_Distance = The distance of the spacecraft from the center of the Moon at Image_Time, in kilometers.

Sun_Moon_Distance = The distance from the center of the Sun to the center of the Moon at Image_Time, in Astronomical Units (AU).

Distance_Factor = The multiplying factor to convert measured irradiance to that expected with the same geometric angles but with the spacecraft and Sun at standard distances from the Moon (384,400 km and 1 AU, respectively).

Phase_angle = The Sun-Moon-Spacecraft angle, in degrees, negative before Full Moon.

Moon_Diam_Angle = The angular diameter of the Moon (assumed circular) viewed from the spacecraft at Image_Time, expressed in milliradians.

Axis_Angle = The apparent orientation of the Lunar North polar spin axis, measured counterclockwise from Celestial North, in degrees.

Oversample_Factor = The image oversample factor, i.e. the factor by which the simple irradiance sum of a spacecraft image over-represents the true irradiance.

Flux_Factor = A composite multiplication factor applied to the spacecraft apparent irradiance to account for oversampling, any missing fraction of the Moon, and any radiometric units conversion.

SCT Multiple Observation File Keywords

SCT geometry and irradiance Multiple Observation Files are typically generated by some sort of automated process from primary data files native to the SCT. The keywords for these files are intended to track their origin, and are used only to propagate this information to the LCT files. The keywords for SCT Geometry and Irradiance Multiple Observation Files are identical.

Instrument = A unique identification of the instrument, possibly including separate optical components, e.g. ASTER SWIR. Internal blanks are allowed.

User = The name of the (one) person representing the SCT. Internal blanks are allowed.

Source_Date = The date and time of the primary SCT observational data file.

Process = the name of the software system that created this input file.

Version = The version date of the Process software that was used.

Run_Time = The data and time when this input file was created by Process. Internal blanks are allowed.

LCT Multiple Observation File Keywords

The Instrument and User keywords from the SCT Multiple Observation Files are propagated to the LCT geometry and model results Multiple Observation Files. The keywords Process and Version are modified to values for the software system that ran the model comparison. Run_Time is updated to the local date and time of the model run. One new keyword is added to the LCT model results file:

Lunar_model = Identification of the lunar model version used. This includes identification of the model coefficients files used.

The BEGIN_FREE sections generated for LCT Multiple Observation Files contain extensive explanations of the columns, including FORTRAN-style format statements and column-aligned headers.

U.S. Department of the Interior | U.S. Geological Survey | U.S.G.S. Astrogeology
Top | Home | Search | Disclaimers & Privacy | Special Printing Instructions
Send Science Questions to: tstone@usgs.gov
Send Website Questions to: webteam@astrogeology.usgs.gov
http:// www.moon-cal.org
Last Modified: Fri, 05 Dec 2014 08:33:25 -0700
- - -
The USGS is committed to providing valid and Section 508 compliant content.
If you feel that this page does not meet any of the standards, please email at webteam@astrogeology.usgs.gov.