The PIDF general information fields occur within the PIDF delimiter brackets and outside any of the PIDF internal structure blocks. They can be placed anywhere within the PIDF file but are generally nested in a group at or near the top of the definition.
PIDF sensor definition block has the generalized form:
float version = ENTRY; string institution = "ENTRY"; string project = "ENTRY"; string mission = "ENTRY"; string experiment = "ENTRY"; string instrument = "ENTRY"; string vinst = "ENTRY"; int plot_avail_flag = ENTRY; int data_type_mask = ENTRY; int instrument_dep = ENTRY; float scan_min = ENTRY; float scan_max = ENTRY; float theta_min = ENTRY; float theta_max = ENTRY; float phi_min = ENTRY; float phi_max = ENTRY; float mass_min = ENTRY; float mass_max = ENTRY; float charge_min = ENTRY; float charge_max = ENTRY; float energy_min = ENTRY; float energy_max = ENTRY; float freq_min = ENTRY; float freq_max = ENTRY; char cyclic = 'ENTRY'; int blocking = ENTRY; char sen_type = 'ENTRY';
Not all of the above fields need be present in any PIDF defintion. Only those which are applicable to the measurements being defined need be included. Default values are supplied for any unspecified field. The fields can be included in the PIDF in any order.
The PIDF version number which currently stands a 2.0. This is a place holder field not currently used by the UDF generic PIDF interface software. It is intended to convey the current PIDF format to the interface software and would be used if format changes were made which would require the software to recognize added features. It is not intended to indicate user revisions, additions, or deletions in any of the PIDF definition field values. It is a float field which if not specified is set to 2.0.
An abbreviation of or acronym for the institution(s) responsible for the measurements contained in the UDF definition. This is a string field which if not specified is set to a NULL string.
The project acronym of the UDF definition associated with the PIDF. This is an string field which if not specified is set to a NULL.
The mission acronym of the UDF definition associated with the PIDF. This is a string field which if not specified is set to a NULL.
The experiment acronym of the UDF definition associated with the PIDF. This is a string field which if not specified is set to a NULL.
The instrument acronym of the UDF definition associated with the PIDF. This is a string field which if not specified is set to a NULL.
string instrument = "ENTRY";
The virtual instrument acronym of the UDF definition associated with the PIDF. This is a string field which if not specified is set to a NULL.
A bit mask which indicates the different types of plots which are applicable for the defined measurements. Some programs use this field to block a user from importing the data into plots formats for which it may not be applicable.
Each bit in the entry field represents a plot format. A bit value of 1 indicates an acceptable plot classification. The bit definitions are listed below with bit 0 being the LSB bit.
| BIT | DEFINITION |
|---|---|
| 0 | Measurements can make use of scalar plots (line plots, histograms, etc.). Data with dimensions greater than 1 will need to be collapsed. |
| 1 | Measurements are 2D or higher but have no angular dependence. The data is plottable in spectrogram format. |
| 2 | Measurements are 2D or higher with angular dependence. This adds plot types such as intensity-angle and contour plots to those available to the data defined under bit 1. |
| 3 | Measurements are image data mappable onto a generalized sphere such as images of the Earth. The PIDF should contain an image information block. |
The plot_avail_flag field can be specified either in HEX or as an integer. Hex specifications must start as 0x. This is an int which if not specified is ste to 1 (bit 0 set).
Defines the data blocks present in the PIDF definition. The various blocks are each represented by one of the bits in the PIDF entry. Bits are set to 1 if the data block is present and 0 otherwise. Bit 0 in the field is the LSB. This PIDF field is used by interface applications to determine what blocks of measurements need to be displayed to a user. Note that this field does not indicate what types of measurements are contained with the UDF. It is entirely possible for example for all of the UDF ancillary data set measurements to be listed under the PIDF Sensor block and for there to be no PIDF ANCILLARY DATA SET block defined.
The bit definitions for the field are listing below.
| BIT | DEFINITION |
|---|---|
| 0 | Quality Information Block is present. Since all UDF definitions contain a set of associated data quality flags, this block is generally always present in the PIDF. |
| 1 | Mode Information Block is present. A Mode information block should be contained in the PIDF if the VIDF Number of Status Bytes field for the UDF definition is non-zero. |
| 2 | Ancillary Information Block is present. |
| 3 | Scan Information Block is present. A Scan information block should be contained in the PIDF if the VIDF Data Storage Format field is 0, 1 or 3. |
| 4 | Sensor Information Block is present. There should always be a Sensor information block with a PIDF since each UDF definition requires the presence of at least one sensor type measurement. |
| 5 | Pitch Angle Information block is present. A Pitch Ancle information block should be contained in the PIDF if the VIDF Pitch Angle Defined>/a> field is set to 1. |
| 6 | Spin Angle Information block is present. |
The data_type_mask field can be specified either in HEX or as an integer. Hex specifications must start as 0x. This is an int field which if not specified is set to 1 (bit 0 set).
Defines any function dependency associated with the measurements defined under the PIDF sensor information block. Only scan and phase data are automatically returned within the UDF. Any other dependencies must be obtained through the VIDF, generally by using one or more of the VIDF constant definitions.
The various dependencies are each represented by one of the bits in the PIDF entry. Bits are set to 1 if the dependency exists and 0 otherwise. Bit 0 in the field is the LSB. This field is used by programs primarily to determine when multi-dimensional data is present and what comprises the different dimensions.
The bit definitions for the field are listing below.
| BIT | DEFINITION |
|---|---|
| 0 | The UDF sensor data is an array of measurements. UDF array data have an associated array index auromatically returned with them which is is defined in the PIDF Scan Information Block. |
| 1 | The UDF sensor data has a theta (elevation) dependency. The VIDF file associated with the UDF definition has either a constant field holding an elevation for each sensor ( Constant Id 1) or constant definitions from which the elevation range covered by each sensor ( Constant Ids of 4 and 5) can be derived. |
| 2 | The UDF sensor data has a phase (azimuth) dependency. This data is returned with each UDF measurement. |
| 3 | The UDF sensor data has a mass dependency. The VIDF file associated with the UDF definition has either a constant field holding a mass for each sensor (Constant Id 11) or constant definitions from which the mass range covered by each sensor (Constant Ids of 12 and 13) can be derived. |
| 4 | The UDF sensor data has a charge dependency. The VIDF file associated with the UDF definition has either a constant field holding a charge for each sensor (Constant Id 15) or constant definitions from which the charge range covered by each sensor (Constant Ids of 16 and 17) can be derived. |
| 5 | The UDF sensor data has a energy dependency. The VIDF file associated with the UDF definition has either a constant field holding a energy for each sensor (Constant Id 19) or constant definitions from which the energy range covered by each sensor (Constant Ids of 20 and 21) can be derived. |
| 6 | The UDF sensor data has a frequency dependency. The VIDF file associated with the UDF definition has either a constant field holding a frequency for each sensor ( Constant Id 23) or constant definitions from which the frequency range covered by each sensor ( Constant Ids of 24 and 25) can be derived. |
When a specific dependency, for example energy, is handled through the returned scan index array it should not be listed listed under the energy dependence bit in the instrument_dep field.
The instrument_dep field can be specified either in HEX or as an integer. Hex specifications must start as 0x. This is an int which if not specified is set to 0.
Defines a reasonable minimum scan value when a scan dependency is indicated in the instrument_dep field. It is not a particularly useful field as it does not specify the units which the minimum value is given in. When such information is needed, it is better obtained from the minimum and maximum values given in the definition structure of the unit selected.
This is a float field which if not specified is set to 0.0.
Defines a reasonable maximum scan value when a scan dependency is indicated in the instrument_dep field. It is not a particularly useful field as it does not specify the units which the maximum value is given in. When such information is needed, it is better obtained from the minimum and maximum values given in the definition structure of the unit selected.
This is a float field which if not specified is set to 0.0.
Defines the minimum theta value when a theta (elevation) dependency is indicated in the instrument_dep field. The specification is made in degrees and must lie between 0 and 180.
This is a float field which if not specified is set to 0.0.
Defines the maximum theta value when a theta (elevation) dependency is indicated in the instrument_dep field. The specification is made in degrees and must lie between 0 and 180.
This is a float field which if not specified is set to 0.0.
Defines the minimum phi value when a phi (azimuth) dependency is indicated in the instrument_dep field. The specification is made in degrees and must lie between 0 and 360.
This is a float field which if not specified is set to 0.0.
Defines the maximum phi value when a phi (azimuth) dependency is indicated in the instrument_dep field. The specification is made in degrees and must lie between 0 and 360.
This is a float field which if not specified is set to 0.0.
Defines the minimum mass value when a mass dependency is indicated in the instrument_dep field. The specification is made in amu.
This is a float field initially defaulted to 0.0. It has the form:
float mass_min = ENTRY;
Defines the maximum mass value when a mass dependency is indicated in the instrument_dep field. The specification is made in amu.
This is a float field which if not specified is set to 0.0.
Defines the minimum charge value when a charge dependency is indicated in the instrument_dep field. The specification is made in terms of the proton charge.
This is a float field which if not specified is set to 0.0.
Defines the maximum charge value when a charge dependency is indicated in the instrument_dep field. The specification is made in terms of the proton change.
This is a float field which if not specified is set to 0.0.
Defines the minimum energy value when a energy dependency is indicated in the instrument_dep field. The specification is made in eV.
This is a float field which if not specified is set to 0.0.
Defines the maximum energy value when a energy dependency is indicated in the instrument_dep field. The specification is made in eV.
This is a float field which if not specified is set to 0.0.
Defines the minimum freq value when a freq dependency is indicated in the instrument_dep field. The specification is made in Hz.
This is a float field which if not specified is set to 0.0.
Defines the maximum freq value when a freq dependency is indicated in the instrument_dep field. The specification is made in Hz.
This is a float field which if not specified is set to 0.0.
Defines whether the phi dependence associated with a measurement when the instrument_dep field indicates a phi dependency, is cyclic or non-cyclic. A 'Y' specification indicates that phi is cyclic and an 'N' specification indicates that phi is non-cyclic.
This is a char field which if not specified is set to 'N'.
Defines the method to use when initially positioning the file pointer in the UDF data file. Valid values are listed below. The ROUTINE column lists the UDF routine used to position the file pointer.
| VALUE | ROUTINE | DEFINITION |
|---|---|---|
| 0 | file_pos | File descriptor is positioned at the measurement which is closest to the requested start time. |
| 1 | FilePosRec | File descriptor is positioned at the start of the data record which is closest to or contains the requested start time. Useful when the UDF definition contains images blocked on the data records. |
| 2 | start_image | File descriptor is positioned to the start on an image. This option has meaning only when the UDF is defined to contain a scanline indicator in the first ancillary data set. Scanline 0 indicated the start of an image. |
This is a int field which if not specified is set to 0.
Defines the storage format used for the UDF sensor data. This field is needed only when the format is 3 (matrix format).
The field has defined values of 'S', 'V' or 'M' depending on whether the UDF sensor measurement are Scalar, Vector or Matrix measurements respectively. It is a char field which if not specified is set to 'S'.
The following are examples of fully functional PIDF general information blocks. The entries are shown within the overall PIDF definition braces which would occur only once within the PIDF file.
pidf v2_IMHACCUM {
$*********************************************************************
float version = 2.0; $ version
string institution = "APL"; $ institute
string project = "IMAGE"; $ project
string mission = "IMAGE-1"; $ mission
string experiment = "HENA"; $ experiment
string instrument = "HENASCI"; $ instrument
string vinst = "IMHACCUM"; $ vinst
$*********************************************************************
int plot_avail_flag = 0x1; $ plot avail
int data_type_mask = 0x13; $ Sen/Scn/Cal/M/Q
int instrument_dep = 0; $ avg over
$*********************************************************************
}
pidf v2_IMES0IMG {
$*********************************************************************
float version = 2.0; $ version
string institution = "UofAriz"; $ institute
string project = "IMAGE"; $ project
string mission = "IMAGE-1"; $ mission
string experiment = "EUV"; $ experiment
string instrument = "EUVSCI"; $ instrument
string vinst = "IMES0IMG"; $ vinst
$*********************************************************************
int plot_avail_flag = 0x05; $ plot avail
int data_type_mask = 0x1D; $ Sen/Scn/Cal/M/Q
int instrument_dep = 0x05; $ avg over
int blocking = 1; $ data rec blocking
float scan_min = 0.0; $ scan minimum
float scan_max = 50.0; $ scan minimum
float phi_min = 0.0; $ phi minimum
float phi_max = 360.0; $ phi minimum
char cyclic = 'Y'; $ phi is cyclic
char sen_type = 'V'; $ Vector Data
$*********************************************************************
};