Opportunity Definition File (ODF)#

An ODF file essentially describes the geometry and geometrical conditions of a “geometrical event” (or opportunity), defined as a sequence of observations, which in turn, is defined as a series of measurements (instant acquisitions).

General structure#

Opportunity Definition File (ODF) files are in JSON format. It contains to the following members:

name (string): Free-form descriptive name of the ODF file.
author (string, optional): Name of the initial author of the ODF file.
status (string, optional): Status of the ODF file. Placeholder to help answer the question: “can it used in mission operational context?”.
description (string, optional): Description of the ODF file.
observation_type (string, optional): Mnemonic of the observation type represented by the ODF file. Allowed values are defined in the Observation Types Index File.
target (string): SPICE body name of the observed target.
observer (string, optional): SPICE body name of the observer. Always JUICE by default.
detector (string): SPICE detector name. For example: JUICE_MAJIS_VISNIR.
measurement_geometries (array): List of geometry_definition and/or odf_include JSON objects, defining measurement geometries.
observation_geometries (array): List of geometry_definition and/or odf_include JSON objects, defining observation geometries.
sequence_geometries (array): List of geometry_definition and/or odf_include JSON objects, defining sequence geometries.

`geometry_definition`#

JSON object defining a Geometry object to be computed.

name (string): Geometry class name. Allowed values are provided in Geometry Classes.
parameters (object): parameters JSON object defining the parameters to be used for computation of the Geometry object.
condition (object): condition JSON object defining the condition to be satisfied for a given Geometry.

`parameters`#

JSON object defining the parameters to be used for computation of the Geometry object. It contains a set of required members defined by the Geometry class. For example, most Geometry classes require the target and detector names.

Note

The set(s) of required parameters for a given Geometry name can be known by using the GeometryFactory.get_geometry_required_parameters() method or the gfinder_cli.geometry() function (or equivalent CLI command).

`condition`#

JSON object defining the condition to be satisfied for a given Geometry. It contains the following members:

relationalCondition (string): Relational condition.
referenceValue (number): Reference value.
adjustmentValue (number): Adjustment value.

Example without condition:

{
  "name": "Phase_Angle",
  "parameters": {
    "target": "CALLISTO"
  }
}

Example with condition:

{
  "name": "Phase_Angle",
  "parameters": {
    "target": "CALLISTO"
  },
  "condition": {
    "relationalCondition": ">",
    "referenceValue": 135,
    "adjustmentValue": 0
  }
}

`odf_include`#

JSON object defining a directive to include the list of geometry definitions from another ODF file, defined by the parent odf_include object: whether measurement_geometries, observation_geometries, or sequence_geometries. It contains the following member:

include (string): Path to an ODF file to include geometry definitions from, relative to ODF data store directory.

Important

Variables defined in the included ODF file must be present in the ODF file. See Additional members and variables.

Example:

{
  "include": "pointing/juice_target_limb_scan.json"
}

The included pointing ODF defines these two variables, which must be present in the ODF file containing an ODF inclusion.

"latitude": 0.0,
"max_incidence_angle": 90.0

Additional members and variables#

All string-type ODF JSON members can be used as a variable for use in the geometry definitions in the ODF file. The name and value of a @variable variable is respectively defined by the variable member name and value.

This allows for “parametrisation” of an ODF.

Additional members can be used as ODF variable. In the following example, in addition to target, latitude and max_incidence_angle members are used to define the Limb_Point_Direction geometry:

"target": "JUPITER"
"latitude": 0.0,
"max_incidence_angle": 90.0

{
  "name": "Limb_Point_Direction",
  "parameters": {
    "target": "@target",
    "latitude": "@latitude",
    "max_incidence_angle": "@max_incidence_angle"
  }
}

Note that ODF variables can also be used in condition JSON object. For example:

{
  "name": "Vertical_Resolution",
  "parameters": {
    "target": "@target",
    "detector": "@detector"
  },
  "condition": {
    "relationalCondition": "<",
    "referenceValue": "@max_vertical_resolution",
    "adjustmentValue": 0
  }
}

Types of ODF files#

ODF files can represent an observation type, or any sets of geometrical conditions or geometry definitions common to other ODF files, including pointing definitions.

Observation Type ODFs#

An observation-type ODF, is a particular type of ODF, which satisfies the following conditions:

it must have a observation_type member,
it must have geometrical conditions, and
it must have pointing definitions.

Master observation-type ODF files, typically contains odf_include objects and ODF variables, and act as a template to be “filled in” (or “instantiated”).

Current master observation-type ODFs are available in odf.

Common ODFs#

Common ODFs are ODF files containing a set of geometry or geometrical conditions that are can be reused by other ODF file, in particular by observation-type ODFs.

Current common ODFs are available in odf/common.

Pointing ODFs#

A pointing ODF only contains the definition of the pointing frames to be simulated: Simulated_SC_Frame and Simulated_Scan_Frame.

Example:

"measurement_geometries": [
  {
    "name": "SC_Slew_Angles",
    "parameters": {
      "x_start": 0.0,
      "y_start": 0.0
    }
  },
  {
    "name": "Simulated_SC_Frame",
    "parameters": {
      "primary_axis": "Z",
      "primary_vector": {
        "name": "Limb_Point_Direction",
        "parameters": {
          "target": "@target",
          "latitude": "@latitude",
          "max_incidence_angle": "@max_incidence_angle"
        }
      },
      "secondary_axis": "-X",
      "secondary_vector": {
        "name": "Limb_Point_Tangent_Direction",
        "parameters": {
          "target": "@target",
          "latitude":"@latitude",
          "max_incidence_angle": "@max_incidence_angle",
          "power_optimised": "True"
        }
      },
      "offset_rotations": "SC_Slew_Angles"
    }
  },
  {
    "name": "MAJIS_Scan_Angle",
    "parameters": {
      "start_angle": 0.0,
      "start_scan_rate": 0.0,
      "stop_scan_rate": 0.0,
      "method": "discrete"
    }
  },
  {
    "name": "Simulated_Scan_Frame",
    "parameters": {
      "scan_zero": [
        0.0,
        0.0,
        0.0
      ],
      "scan_rotation_angle": "MAJIS_Scan_Angle"
    }
  }
]

Current pointing ODFs are available in odf/pointing.

Opportunity Definition File (ODF)

Contents

Opportunity Definition File (ODF)#

General structure#

geometry_definition#

parameters#

condition#

odf_include#

Additional members and variables#

Types of ODF files#

Observation Type ODFs#

Common ODFs#

Pointing ODFs#

`geometry_definition`#

`parameters`#

`condition`#

`odf_include`#