WebGeoCalc calculations

For now only the geometry/time calculations are implemented:

Import generic WebGeoCalc calculation object:

>>> from webgeocalc import Calculation

or import specific WebGeoCalc calculation object:

>>> from webgeocalc import StateVector, AngularSeparation

Inputs examples and payloads

All WebGeoCalc calculation objects take their input attributes in underscore_case format.

>>> calc = Calculation(
...    kernels = 5,
...    times = '2012-10-19T08:24:00.000',
...    calculation_type = 'STATE_VECTOR',
...    target = 'CASSINI',
...    observer = 'SATURN',
...    reference_frame = 'IAU_SATURN',
...    aberration_correction = 'NONE',
...    state_representation = 'PLANETOGRAPHIC',
... )

Important

Calculation required parameters:
Calculation default parameters:

Note

By default, if no api option is provided, the query is sent to the WGC_URL API (if set in the global environment variables) or JPL API (if not). See API docs for details.

To query on the ESA WGC API, you need to add the ESA key to the any Calculation parameters:

>>> Calculation(
...    api = 'ESA',
...    kernels = 6,
...    times = '2014-01-01T01:23:45.000',
...    calculation_type = 'STATE_VECTOR',
...    target = '67P/CHURYUMOV-GERASIMENKO (1969 R1)',
...    observer = 'ROSETTA ORBITER',
...    reference_frame = '67P/C-G_CK',
...    aberration_correction = 'NONE',
...    state_representation = 'LATITUDINAL',
... ).api
<Api> http://spice.esac.esa.int/webgeocalc/api

3-rd party WGC are also supported, either set WGC_URL on your system (as mention before), or you can provide directly its URL to the api parameter:

>>> Calculation(
...    api = 'https://wgc.obspm.fr/webgeocalc/api',
...    kernels = 6,
...    times = '2014-01-01T01:23:45.000',
...    calculation_type = 'STATE_VECTOR',
...    target = '67P/CHURYUMOV-GERASIMENKO (1969 R1)',
...    observer = 'ROSETTA ORBITER',
...    reference_frame = '67P/C-G_CK',
...    aberration_correction = 'NONE',
...    state_representation = 'LATITUDINAL',
... ).api
<Api> https://wgc.obspm.fr/webgeocalc/api

In each cases, every new API is cached to improve the kernels loading performances.

The payload that will be submitted to the WebGeoCalc API can be retrieve with the payload attribute:

>>> calc.payload
{'kernels': [{'type': 'KERNEL_SET', 'id': 5}],
 'times': ['2012-10-19T08:24:00.000'],
 'calculationType': 'STATE_VECTOR',
 'target': 'CASSINI',
 'observer': 'SATURN',
 'referenceFrame': 'IAU_SATURN',
 'aberrationCorrection': 'NONE',
 'stateRepresentation': 'PLANETOGRAPHIC',
 'timeSystem': 'UTC',
 'timeFormat': 'CALENDAR'}

Example of StateVector calculation with multi kernels inputs (requested by name in this case), with multiple times inputs for target, observer and reference_frame requested by id:

>>> StateVector(
...    kernels = ['Solar System Kernels', 'Cassini Huygens'],
...    times = ['2012-10-19T07:00:00', '2012-10-19T09:00:00'],
...    target = -82,             # CASSINI
...    observer = 699,           # SATURN
...    reference_frame = 10016,  # IAU_SATURN
... ).payload
{'kernels': [{'type': 'KERNEL_SET', 'id': 1},
             {'type': 'KERNEL_SET', 'id': 5}],
 'times': ['2012-10-19T07:00:00', '2012-10-19T09:00:00'],
 'target': -82,
 'observer': 699,
 'referenceFrame': 10016,
 'calculationType': 'STATE_VECTOR',
 'aberrationCorrection': 'CN',
 'stateRepresentation': 'RECTANGULAR',
 'timeSystem': 'UTC',
 'timeFormat': 'CALENDAR'}

Example of AngularSeparation calculation with specific kernel_paths and multiple intervals:

>>> AngularSeparation(
...    kernel_paths = [
...         'pds/wgc/kernels/lsk/naif0012.tls',
...         'pds/wgc/kernels/spk/de430.bsp'
...    ],
...    intervals = [
...        ['2000-01-01', '2000-01-03'],
...        ['2000-02-01', '2000-02-03']
...    ],
...    time_step = 1,
...    time_step_units = 'DAYS',
...    target_1 = 'VENUS',
...    target_2 = 'MERCURY',
...    observer = 'SUN',
... ).payload
{'kernels': [{'type': 'KERNEL', 'path': 'pds/wgc/kernels/lsk/naif0012.tls'},
             {'type': 'KERNEL', 'path': 'pds/wgc/kernels/spk/de430.bsp'}],
 'intervals': [{'startTime': '2000-01-01', 'endTime': '2000-01-03'},
               {'startTime': '2000-02-01', 'endTime': '2000-02-03'}],
 'timeStep': 1,
 'timeStepUnits': 'DAYS',
 'target1': 'VENUS',
 'target2': 'MERCURY',
 'observer': 'SUN',
 'calculationType': 'ANGULAR_SEPARATION',
 'shape1': 'POINT',
 'shape2': 'POINT',
 'aberrationCorrection': 'CN',
 'timeSystem': 'UTC',
 'timeFormat': 'CALENDAR'}

Submit payload and retrieve results

Calculation requests to the WebGeoCalc API are made in three steps:

1. The payload is submitted to the API with Calculation.submit() method, and a calculation-id is retrieved:

>>> calc.submit() 
[Calculation submit] Status: LOADING_KERNELS (id: 8750344d-645d-4e43-b159-c8d88d28aac6)

2. If the calculation status is COMPLETE, the results can be directly retrieved. Otherwise, you need to update the calculation status with Calculation.update() method:

>>> calc.update() 
[Calculation update] Status: COMPLETE (id: 8750344d-645d-4e43-b159-c8d88d28aac6)

3. When the calculation status is COMPLETE, the results are retrieved by the results attribute:

>>> calc.results  
{
    'DATE': '2012-10-19 09:00:00.000000 UTC',
    'DISTANCE': 764142.63776247,
    'SPEED': 111.54765899,
    'X': 298292.85744169,
    'Y': -651606.58468976,
    'Z': 265224.81187627,
    'D_X_DT': -98.8032491,
    'D_Y_DT': -51.73211296,
    'D_Z_DT': -2.1416539,
    'TIME_AT_TARGET': '2012-10-19 08:59:57.451094 UTC',
    'LIGHT_TIME': 2.54890548
}

Tip

It is possible to submit, update and retrieve the results at once with Calculation.run() method:

>>> calc.run()  
[Calculation submit] Status: LOADING_KERNELS (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
[Calculation update] Status: COMPLETE (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
{'DATE': '2012-10-19 09:00:00.000000 UTC',
 'DISTANCE': 764142.63776247,
 'SPEED': 111.54765899,
 'X': 298292.85744169,
 'Y': -651606.58468976,
 'Z': 265224.81187627,
 'D_X_DT': -98.8032491,
 'D_Y_DT': -51.73211296,
 'D_Z_DT': -2.1416539,
 'TIME_AT_TARGET': '2012-10-19 08:59:57.451094 UTC',
 'LIGHT_TIME': 2.54890548}

Generic calculation

class webgeocalc.Calculation(api='', time_system='UTC', time_format='CALENDAR', verbose=True, **kwargs)[source]

Bases: object

Webgeocalc calculation object.

Parameters

  • api (str or webgeocalc.Api, optional) – WebGeoCalc API endpoint. By default, if no api option is provided, the query is sent to the WGC_URL API (if set in the global environment variables) or JPL_API (if not). Keyword are also accepted (JPL and ESA). Custom 3-rd party endpoints can be used (with their URL or as a custom webgeocalc.api.Api).

  • time_system (str, optional) – See: time_system

  • time_format (str, optional) – See: time_format

  • verbose (bool, optional) – Verbose calculation phase during submit(), update() and run().

Other Parameters
Raises
property payload

Calculation payload parameters dict for JSON input in WebGeoCalc format.

Returns

Payload keys and values.

Return type

dict

Example

>>> Calculation(
...    kernels = 'Cassini Huygens',
...    times = '2012-10-19T08:24:00.000',
...    calculation_type = 'STATE_VECTOR',
...    target = 'CASSINI',
...    observer = 'SATURN',
...    reference_frame = 'IAU_SATURN',
...    aberration_correction = 'NONE',
...    state_representation = 'PLANETOGRAPHIC',
... ).payload  # noqa: E501
{'kernels': [{'type': 'KERNEL_SET', 'id': 5}], 'times': ['2012-10-19T08:24:00.000'], ...}
submit()[source]

Submit calculation parameters and get calculation id and phase.

Raises

CalculationAlreadySubmitted – If the calculation was already submitted (to avoid duplicated submissions).

Example

>>> calc.submit()  # noqa: E501  
[Calculation submit] Phase: QUEUED | POSITION: 6 (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
>>> calc.id        
'8750344d-645d-4e43-b159-c8d88d28aac6'
>>> calc.phase     
'QUEUED | POSITION: 6'
resubmit()[source]

Reset calculation id and re-submit the calculation.

See: submit().

cancel()[source]

Cancels calculation if already submitted.

update()[source]

Update calculation phase phase.

Example

>>> calc.update()  # noqa: E501  
[Calculation update] Phase: QUEUED | POSITION: 3 (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
>>> calc.update()  # noqa: E501  
[Calculation update] Phase: STARTING (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
>>> calc.update()  # noqa: E501  
[Calculation update] Phase: LOADING_KERNELS (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
>>> calc.update()  # noqa: E501  
[Calculation update] Phase: CALCULATING (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
>>> calc.update()  
[Calculation update] Phase: COMPLETE (id: 8750344d-645d-4e43-b159-c8d88d28aac6)
property results

Gets the results of a calculation, if its phase is COMPLETE.

Returns

Calculation results as dict based on output columns. If multiple times or intervals are used, the value of the dict will be an array. See examples.

Return type

dict

Raises

CalculationNotCompleted – If calculation phase is not COMPLETE.

Examples

>>> calc.results     
{'DATE': '2012-10-19 09:00:00.000000 UTC',
 'DISTANCE': 764142.63776247,
 'SPEED': 111.54765899,
 'X': 298292.85744169,
 'Y': -651606.58468976,
 'Z': 265224.81187627,
 'D_X_DT': -98.8032491,
 'D_Y_DT': -51.73211296,
 'D_Z_DT': -2.1416539,
 'TIME_AT_TARGET': '2012-10-19 08:59:57.451094 UTC',
 'LIGHT_TIME': 2.54890548}

>>> ang_sep = AngularSeparation(
...     kernel_paths = ['pds/wgc/kernels/lsk/naif0012.tls', 'pds/wgc/kernels/spk/de430.bsp'],
...     times = ['2012-10-19T08:24:00.000', '2012-10-19T09:00:00.000'],
...     target_1 = 'VENUS',
...     target_2 = 'MERCURY',
...     observer = 'SUN',
...     verbose = False,
... )  # noqa: E501
>>> ang_sep.submit()      
>>> ang_sep.results       
{'DATE': ['2012-10-19 08:24:00.000000 UTC', '2012-10-19 09:00:00.000000 UTC'],
 'ANGULAR_SEPARATION': [175.17072258, 175.18555938]}
run(timeout=30, sleep=1)[source]

Submit, update and retrive calculation results at once.

See: submit(), update() and results.

Parameters

  • timeout (int, optional) – Auto-update time out (in seconds).

  • sleep (int, optional) – Sleep duration (in seconds) between each update.

Raises

CalculationTimeOut – If calculation reach the timeout duration.

calculation_type[source]

The type of calculation to perform.

Parameters

calculation_type (str) –

One of the following:

  • STATE_VECTOR

  • ANGULAR_SEPARATION

  • ANGULAR_SIZE

  • SUB_OBSERVER_POINT

  • SUB_SOLAR_POINT

  • ILLUMINATION_ANGLES

  • SURFACE_INTERCEPT_POINT

  • OSCULATING_ELEMENTS

  • FRAME_TRANSFORMATION

  • TIME_CONVERSION

  • GF_COORDINATE_SEARCH

  • GF_ANGULAR_SEPARATION_SEARCH

  • GF_DISTANCE_SEARCH

  • GF_SUB_POINT_SEARCH

  • GF_OCCULTATION_SEARCH

  • GF_TARGET_IN_INSTRUMENT_FOV_SEARCH

  • GF_SURFACE_INTERCEPT_POINT_SEARCH

  • GF_RAY_IN_FOV_SEARCH

Note

This parameters will be auto-filled for specific calculation sub-classes.

Raises

CalculationInvalidAttr – If the value provided is invalid.

kernels[source]

Add kernel sets.

Parameters

kernels (str, int, [str or/and int]) –

Kernel set(s) to be used for the calculation:

[{'type': 'KERNEL_SET', 'id': 5}, ...]

kernel_paths[source]

Add path for individual kernel paths.

Parameters

kernel_paths (str, [str]) –

Kernel path(s) to be used for the calculation:

[{'type': 'KERNEL', 'path': 'pds/wgc/kernels/lsk/naif0012.tls'}, ...]

times[source]

Calculation input times.

Parameters

times (str or [str]) – String or array of strings representing the time points that should be used in the calculation.

Raises

CalculationConflictAttr – Either this parameter or the py:attr:intervals parameter must be supplied.

intervals[source]

Calculation input intervals.

Parameters

intervals ([str, str] or {'startTime': str, 'endTime': str} or [interval, ..]) –

An array of objects with startTime and endTime parameters, representing the time intervals used for the calculation.

Warning

Either this parameter or the times parameter must be supplied.

Raises

  • CalculationInvalidAttr – If :py:attr:intervals` input format is invalid. For example, if :py:attr:intervals` is provided an dict, startTime and endTime must be present.

  • CalculationUndefinedAttr – If this parameter is used, time_step must also be supplied.

time_step[source]

Time step for intervals.

Parameters

time_step (int) – Number of steps parameter used for time series or geometry finder calculations.

Raises

  • CalculationConflictAttr – If times attribute is supplied.

  • CalculationUndefinedAttr – If time_step_units is not supplied.

time_step_units[source]

Time step units.

Parameters

time_step_units (str) –

One of the following:

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

  • EQUAL_INTERVALS

Raises

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationConflictAttr – If times attribute is supplied.

  • CalculationUndefinedAttr – If time_step is not supplied.

time_system[source]

Time System.

Parameters

time_system (str) –

One of the following:

  • UTC

  • TDB

  • TDT

  • SPACECRAFT_CLOCK

Raises

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationUndefinedAttr – If SPACECRAFT_CLOCK is selected, but sclk_id attribute is not provided.

time_format[source]

Time format input.

Parameters

time_format (str) –

One of the following:

  • CALENDAR

  • JULIAN

  • SECONDS_PAST_J2000

  • SPACECRAFT_CLOCK_TICKS

  • SPACECRAFT_CLOCK_STRING

Raises

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationRequiredAttr – If time_system is not provided.

  • CalculationIncompatibleAttr – If CALENDAR, JULIAN or SECONDS_PAST_J2000 is selected but time_system attribute is not in UTC, TDB or TDT, or SPACECRAFT_CLOCK_STRING or SPACECRAFT_CLOCK_TICKS is selected but time_system attribute is not SPACECRAFT_CLOCK.

sclk_id[source]

Spacecraft clock kernel id.

Parameters

sclk_id (int) – Spacecraft clock kernel id.

Raises

  • CalculationRequiredAttr – If time_system is not provided.

  • CalculationIncompatibleAttr – If time_system is not SPACECRAFT_CLOCK.

output_time_system[source]

The time system for results output times.

Parameters

output_time_system (str) –

One of the following:

  • UTC

  • TDB

  • TDT

  • SPACECRAFT_CLOCK

Raises

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationUndefinedAttr – If SPACECRAFT_CLOCK is selected, but output_sclk_id attribute is not provided.

output_time_format[source]

The time format for the result output times.

Parameters

output_time_format (str) –

One of the following:

  • CALENDAR

  • CALENDAR_YMD

  • CALENDAR_DOY

  • JULIAN

  • SECONDS_PAST_J2000

  • SPACECRAFT_CLOCK_STRING

  • SPACECRAFT_CLOCK_TICKS

  • CUSTOM

Warning

If CUSTOM is selected, then output_time_custom_format must also be provided.

Raises

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationRequiredAttr – If output_time_system is not provided.

  • CalculationIncompatibleAttr – If CALENDAR_YMD, CALENDAR_DOY, JULIAN, SECONDS_PAST_J2000 or CUSTOM is selected but outputTimeSystem is not in TDB, TDT or UTC, or SPACECRAFT_CLOCK_STRING or SPACECRAFT_CLOCK_TICKS is selected but output_time_system is not SPACECRAFT_CLOCK.

output_time_custom_format[source]

A SPICE timout() format string.

Parameters

output_time_custom_format (str) – A SPICE timout() format string.

Raises
output_sclk_id[source]

The output spacecraft clock kernel id.

Parameters

output_sclk_id (int) – Spacecraft clock kernel id.

Raises
target[source]

Target body.

Parameters

target (str or int) – The target body name or id from API.bodies().

target_frame[source]

The target body-fixed reference frame name.

Parameters

target_frame (str) – Reference frame name.

target_1[source]

The target body the first body.

Parameters

target_1 (str) – Target body name or id.

target_2[source]

The target body the second body.

Parameters

target_2 (str) – Target body name or id.

shape_1[source]

The shape to use for the first body.

Parameters

shape_1 (str) –

One of:

  • POINT

  • SPHERE

Raises

CalculationInvalidAttr – If the value provided is invalid.

shape_2[source]

The shape to use for the second body.

Parameters

shape_2 (str) –

One of:

  • POINT

  • SPHERE

Raises

CalculationInvalidAttr – If the value provided is invalid.

observer[source]

The observing body.

Parameters

observer (str or int) – The oberving body name or id from API.bodies().

reference_frame[source]

The reference frame.

Parameters

reference_frame (str or int) – The reference frame name or id from API.frames().

frame_1[source]

The first reference frame.

Parameters

frame_1 (str or int) – The reference frame name or id from API.frames().

frame_2[source]

The second reference frame.

Parameters

frame_2 (str or int) – The reference frame name or id from API.frames().

orbiting_body[source]

The SPICE orbiting body.

Parameters

orbiting_body (str or int) – SPICE body name or id for the orbiting body.

center_body[source]

The SPICE body center of motion.

Parameters

center_body (str or int) – SPICE body name or id for the body that is the center of motion.

aberration_correction[source]

SPICE aberration correction.

Parameters

aberration_correction (str) –

The SPICE aberration correction string. One of:

  • NONE

  • LT

  • LT+S

  • CN

  • CN+S

  • XLT

  • XLT+S

  • XCN

  • XCN+S

Raises

CalculationInvalidAttr – If the value provided is invalid.

state_representation[source]

State representation.

Parameters

state_representation (str) –

One of:

  • RECTANGULAR

  • RA_DEC

  • LATITUDINAL (planetocentric)

  • PLANETODETIC

  • PLANETOGRAPHIC

  • CYLINDRICAL

  • SPHERICAL

Raises

CalculationInvalidAttr – If the value provided is invalid.

time_location[source]

The frame for the input times.

Parameters

time_location (str) –

One of:

  • FRAME1

  • FRAME2

Raises

CalculationInvalidAttr – If the value provided is invalid.

Warning

NAIF API docs:

`Only needed if aberrationCorrection is not NONE.`

Required even when aberration_correction is NONE.

orientation_representation[source]

The representation of the result transformation.

Parameters

orientation_representation (str) –

Orientation result transformation. One of:

  • EULER_ANGLES

  • ANGLE_AND_AXIS

  • SPICE_QUATERNION

  • OTHER_QUATERNION

  • MATRIX_ROW_BY_ROW

  • MATRIX_FLAGGED

  • MATRIX_ALL_ONE_ROW

Raises

CalculationInvalidAttr – If the value provided is invalid.

axis_1[source]

The first axis for Euler angle rotation.

Parameters

axis_1 (str) – Axis name. See: axis().

axis_2[source]

The second axis for Euler angle rotation.

Parameters

axis_3 (str) – Axis name. See: axis().

axis_3[source]

The third axis for Euler angle rotation.

Parameters

axis_3 (str) – Axis name. See: axis().

axis(name, val)[source]

Axis for Euler angle rotation.

Parameters

  • name (str) –

    Axis name. One of:

    • X

    • Y

    • Z

  • val (float) – Value on the axis.

Returns

Value on the axis.

Return type

float

Raises
angular_units[source]

The angular units.

Parameters

angular_units (str) –

The angular units used for the angle of rotation. One of:

  • deg

  • rad

Raises
angular_velocity_representation[source]

Angular velocity representation.

Parameters

angular_velocity_representation (str) –

The representation of angular velocity in the output. One of:

  • NOT_INCLUDED

  • VECTOR_IN_FRAME1

  • VECTOR_IN_FRAME2

  • EULER_ANGLE_DERIVATIVES

  • MATRIX

Raises

CalculationInvalidAttr – If the value provided is invalid.

angular_velocity_units[source]

The units for the angular velocity.

Parameters

angular_velocity_units (str) –

One of:

  • deg/s

  • rad/s

  • RPM

  • Unitary (ie, Unit vector)

Raises
coordinate_representation[source]

Coordinate Representation.

Parameters

coordinate_representation (str) –

One of:

  • LATITUDINAL (planetocentric)

  • PLANETODETIC

  • PLANETOGRAPHIC

Raises

CalculationInvalidAttr – If the value provided is invalid.

latitude[source]

Latitude of the surface point.

Parameters

latitude (float) – Latitude angle (in degrees).

Raises

CalculationInvalidValue – If latitude not in [-90, +90] range.

longitude[source]

Longitude of the surface point.

Parameters

longitude (float) – Longitude angle (in degrees).

Raises

CalculationInvalidValue – If longitude not in [-180, +180] range.

sub_point_type[source]

Sub-observer point.

Parameters

sub_point_type (str) –

The method of finding the sub-observer point, as in the SPICE subpnt() API call. One of:

  • Near point: ellipsoid

  • Intercept: ellipsoid

  • NADIR/DSK/UNPRIORITIZED

  • INTERCEPT/DSK/UNPRIORITIZED

Raises

CalculationInvalidAttr – If the value provided is invalid.

direction_vector_type[source]

Type of ray’s direction vector.

Parameters

direction_vector_type (str) –

Type of vector to be used as the ray direction. One of:

  • INSTRUMENT_BORESIGHT (the instrument boresight vector)

  • INSTRUMENT_FOV_BOUNDARY_VECTORS (the instrument field-of-view boundary vectors)

  • REFERENCE_FRAME_AXIS (an axis of the specified reference frame)

  • VECTOR_IN_INSTRUMENT_FOV (a vector in the reference frame of the specified instrument)

  • VECTOR_IN_REFERENCE_FRAME (a vector in the specified reference frame)

Raises
direction_instrument[source]

Direction imnstrument.

Parameters

direction_instrument (str or int) – The instrument name or id.

Raises

  • CalculationUndefinedAttr – If direction_vector_type is not provided.

  • CalculationIncompatibleAttr – If direction_vector_type not in INSTRUMENT_BORESIGHT, INSTRUMENT_FOV_BOUNDARY_VECTORS or VECTOR_IN_INSTRUMENT_FOV.

direction_frame[source]

Direction vector reference frame.

Parameters

direction_frame (str) – The vector’s reference frame name.

Raises
direction_frame_axis[source]

The vector’s reference frame axis name.

Parameters

direction_frame (str) –

The vector’s reference frame axis. One of:

  • X

  • Y

  • Z

Raises

  • CalculationUndefinedAttr – If direction_vector_type is not provided.

  • CalculationIncompatibleAttr – If direction_vector_type is not REFERENCE_FRAME_AXIS.

  • CalculationInvalidAttr – If the value provided is invalid.

direction_vector(axis, val)[source]

Direction vector coordinate.

Parameters

  • axis (str) – Axis name.

  • val (float) – Value on the axis.

Raises
direction_vector_x[source]

The X ray’s direction vector coordinate.

Parameters

direction_vector_x (float) – Direction x-coordinate. See direction_vector().

direction_vector_y[source]

The Y ray’s direction vector coordinate.

Parameters

direction_vector_y (float) – Direction y-coordinate. See direction_vector().

direction_vector_z[source]

The Z ray’s direction vector coordinate.

Parameters

direction_vector_z (float) – Direction z-coordinate. See direction_vector().

direction_vector_ra[source]

The right-ascenssion ray’s direction vector coordinate.

Parameters

direction_vector_ra (float) – Direction RA-coordinate. See direction_vector().

direction_vector_dec[source]

The declination ray’s direction vector coordinate.

Parameters

direction_vector_dec (float) – Direction DEC-coordinate. See direction_vector().

State Vector

Calculates the position of one body relative to another, calculated in a desired reference frame:

>>> StateVector(
...    kernels = 5,
...    times = '2012-10-19T09:00:00',
...    target = 'CASSINI',
...    observer = 'SATURN',
...    reference_frame = 'IAU_SATURN',
...    verbose = False,
... ).run()
{'DATE': '2012-10-19 09:00:00.000000 UTC',
 'DISTANCE': 764142.63776247,
 'SPEED': 111.54765899,
 'X': 298292.85744169,
 'Y': -651606.58468976,
 'Z': 265224.81187627,
 'D_X_DT': -98.8032491,
 'D_Y_DT': -51.73211296,
 'D_Z_DT': -2.1416539,
 'TIME_AT_TARGET': '2012-10-19 08:59:57.451094 UTC',
 'LIGHT_TIME': 2.54890548}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.StateVector(aberration_correction='CN', state_representation='RECTANGULAR', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

State vector calculation.

Calculates the position of one body relative to another, calculated in a desired reference frame.

Parameters
Other Parameters
Raises

CalculationRequiredAttr – If target, observer and reference_frame are not provided.

Angular Separation

Calculates the angular separation of two bodies as seen by an observer body.

>>> AngularSeparation(
...     kernel_paths = ['pds/wgc/kernels/lsk/naif0012.tls',
...                     'pds/wgc/kernels/spk/de430.bsp'],
...     times = '2012-10-19T08:24:00.000',
...     target_1 = 'VENUS',
...     target_2 = 'MERCURY',
...     observer = 'SUN',
...     verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC', 'ANGULAR_SEPARATION': 175.17072258}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.AngularSeparation(shape_1='POINT', shape_2='POINT', aberration_correction='CN', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Angular separation calculation.

Calculates the angular separation of two bodies as seen by an observer body.

Parameters
Other Parameters

  • kernels (str, int, [str or/and int]) – See: kernels

  • kernel_paths (str, [str]) – See: kernel_paths

  • times (str or [str]) – See: times

  • intervals ([str, str] or {‘startTime’: str, ‘endTime’: str} or [interval, …]) – See: intervals

  • time_step (int) – See: time_step

  • time_step_units (str) – See: time_step_units

  • time_system (str) – See: time_system

  • time_format (str) – See: time_format

  • target_1 (str or int) – See: target_1

  • target_2 (str or int) – See: target_2

  • observer (str or int) – See: observer

Raises

CalculationRequiredAttr – If target_1, target_2 and observer are not provided.

Angular Size

Calculates the angular size of a target as seen by an observer.

>>> AngularSize(
...     kernels = 5,
...     times = '2012-10-19T08:24:00.000',
...     target = 'ENCELADUS',
...     observer = 'CASSINI',
...     aberration_correction = 'CN+S',
...     verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC', 'ANGULAR_SIZE': 0.03037939}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.AngularSize(aberration_correction='CN', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Angular size calculation.

Calculates the angular size of a target as seen by an observer.

Parameters

aberration_correction (str, optional) – See: aberration_correction

Other Parameters

  • kernels (str, int, [str or/and int]) – See: kernels

  • kernel_paths (str, [str]) – See: kernel_paths

  • times (str or [str]) – See: times

  • intervals ([str, str] or {‘startTime’: str, ‘endTime’: str} or [interval, …]) – See: intervals

  • time_step (int) – See: time_step

  • time_step_units (str) – See: time_step_units

  • time_system (str) – See: time_system

  • time_format (str) – See: time_format

  • target (str or int) – See: target

  • observer (str or int) – See: observer

Raises

CalculationRequiredAttr – If target and observer are not provided.

Frame Transformation

Calculate the transformation from one reference frame (Frame 1) to another reference frame (Frame 2).

>>> FrameTransformation(
...     kernels = 5,
...     times = '2012-10-19T08:24:00.000',
...     frame_1 = 'IAU_SATURN',
...     frame_2 = 'IAU_ENCELADUS',
...     aberration_correction = 'NONE',
...     verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC',
 'ANGLE3': -20.58940104,
 'ANGLE2': 0.01874004,
 'ANGLE1': 0.00136319,
 'AV_X': 9.94596495e-07,
 'AV_Y': -7.23492228e-08,
 'AV_Z': -0.00634331,
 'AV_MAG': 0.00634331}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.FrameTransformation(aberration_correction='CN', time_location='FRAME1', orientation_representation='EULER_ANGLES', axis_1='X', axis_2='Y', axis_3='Z', angular_units='deg', angular_velocity_representation='VECTOR_IN_FRAME1', angular_velocity_units='deg/s', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Frame transforme calculation.

Calculate the transformation from one reference frame (Frame 1) to another reference frame (Frame 2).

Parameters
Other Parameters

  • kernels (str, int, [str or/and int]) – See: kernels

  • kernel_paths (str, [str]) – See: kernel_paths

  • times (str or [str]) – See: times

  • intervals ([str, str] or {‘startTime’: str, ‘endTime’: str} or [interval, …]) – See: intervals

  • time_step (int) – See: time_step

  • time_step_units (str) – See: time_step_units

  • time_system (str) – See: time_system

  • time_format (str) – See: time_format

  • frame_1 (str or int) – See: frame_1

  • frame_2 (str or int) – See: frame_2

Raises

Illumination Angles

Calculate the emission, phase and solar incidence angles at a point on a target as seen from an observer.

>>> IlluminationAngles(
...    kernels = 5,
...    times = '2012-10-19T08:24:00.000',
...    target = 'ENCELADUS',
...    target_frame = 'IAU_ENCELADUS',
...    observer = 'CASSINI',
...    aberration_correction = 'CN+S',
...    latitude = 0.0,
...    longitude = 0.0,
...    verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC',
 'INCIDENCE_ANGLE': 24.78527742,
 'EMISSION_ANGLE': 25.56007298,
 'PHASE_ANGLE': 1.00079007,
 'OBSERVER_ALTITUDE': 967668.02765637,
 'TIME_AT_POINT': '2012-10-19 08:23:56.772207 UTC',
 'LIGHT_TIME': 3.2277931,
 'LTST': '13:15:59'}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.IlluminationAngles(shape_1='ELLIPSOID', coordinate_representation='LATITUDINAL', aberration_correction='CN', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Illumination angles calculation.

Calculate the emission, phase and solar incidence angles at a point on a target as seen from an observer.

Parameters
Other Parameters

  • kernels (str, int, [str or/and int]) – See: kernels

  • kernel_paths (str, [str]) – See: kernel_paths

  • times (str or [str]) – See: times

  • intervals ([str, str] or {‘startTime’: str, ‘endTime’: str} or [interval, …]) – See: intervals

  • time_step (int) – See: time_step

  • time_step_units (str) – See: time_step_units

  • time_system (str) – See: time_system

  • time_format (str) – See: time_format

  • target (str or int) – See: target

  • target_frame (str or int) – See: target_frame

  • observer (str or int) – See: observer

  • latitude (str or int) – See: latitude

  • longitude (str or int) – See: longitude

Raises

Sub Solar Point

Calculates the sub-solar point on a target as seen from an observer.

>>> SubSolarPoint(
...     kernels = 5,
...     times = '2012-10-19T08:24:00.000',
...     target = 'ENCELADUS',
...     target_frame = 'IAU_ENCELADUS',
...     observer = 'CASSINI',
...     aberration_correction = 'CN+S',
...     verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC',
 'X': 234.00550655,
 'Y': -77.32612213,
 'Z': 67.42916937,
 'SUB_POINT_RADIUS': 255.50851089,
 'OBSERVER_ALTITUDE': 967644.15493281,
 'INCIDENCE_ANGLE': 4.49798357e-15,
 'EMISSION_ANGLE': 0.99611862,
 'PHASE_ANGLE': 0.99611862,
 'TIME_AT_POINT': '2012-10-19 08:23:56.772287 UTC',
 'LIGHT_TIME': 3.22771347}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.SubSolarPoint(sub_point_type='Near point: ellipsoid', aberration_correction='CN', state_representation='RECTANGULAR', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Sub-solar point calculation.

Calculates the sub-solar point on a target as seen from an observer.

Parameters
Other Parameters

  • kernels (str, int, [str or/and int]) – See: kernels

  • kernel_paths (str, [str]) – See: kernel_paths

  • times (str or [str]) – See: times

  • intervals ([str, str] or {‘startTime’: str, ‘endTime’: str} or [interval, …]) – See: intervals

  • time_step (int) – See: time_step

  • time_step_units (str) – See: time_step_units

  • time_system (str) – See: time_system

  • time_format (str) – See: time_format

  • target (str or int) – See: target

  • target_frame (str or int) – See: target_frame

  • observer (str or int) – See: observer

Raises

Sub Observer Point

Calculate the sub-observer point on a target as seen from an observer.

>>> SubObserverPoint(
...     kernels = 5,
...     times = '2012-10-19T08:24:00.000',
...     target = 'ENCELADUS',
...     target_frame = 'IAU_ENCELADUS',
...     observer = 'CASSINI',
...     aberration_correction = 'CN+S',
...     verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC',
 'X': 232.5831733,
 'Y': -81.40386728,
 'Z': 67.35505213,
 'SUB_POINT_RADIUS': 255.45689491,
 'OBSERVER_ALTITUDE': 967644.11734179,
 'INCIDENCE_ANGLE': 0.99586304,
 'EMISSION_ANGLE': 1.66981544e-12,
 'PHASE_ANGLE': 0.99586304,
 'TIME_AT_POINT': '2012-10-19 08:23:56.772287 UTC',
 'LIGHT_TIME': 3.22771334,
 'LTST': '11:58:49'}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.SubObserverPoint(sub_point_type='Near point: ellipsoid', aberration_correction='CN', state_representation='RECTANGULAR', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Sub-observer point calculation.

Calculate the sub-observer point on a target as seen from an observer.

Parameters
Other Parameters

  • kernels (str, int, [str or/and int]) – See: kernels

  • kernel_paths (str, [str]) – See: kernel_paths

  • times (str or [str]) – See: times

  • intervals ([str, str] or {‘startTime’: str, ‘endTime’: str} or [interval, …]) – See: intervals

  • time_step (int) – See: time_step

  • time_step_units (str) – See: time_step_units

  • time_system (str) – See: time_system

  • time_format (str) – See: time_format

  • target (str or int) – See: target

  • target_frame (str or int) – See: target_frame

  • observer (str or int) – See: observer

Raises

CalculationRequiredAttr – If target, target_frame and observer are not provided.

Surface Intercept Point

Calculate the intercept point of a vector or vectors on a target as seen from an observer.

>>> SurfaceInterceptPoint(
...     kernels = 5,
...     times = '2012-10-14T00:00:00',
...     target = 'SATURN',
...     target_frame = 'IAU_SATURN',
...     observer = 'CASSINI',
...     direction_vector_type = 'INSTRUMENT_BORESIGHT',
...     direction_instrument = 'CASSINI_ISS_NAC',
...     aberration_correction = 'NONE',
...     state_representation = 'LATITUDINAL',
...     verbose = False,
... ).run()
{'DATE': '2012-10-14 00:00:00.000000 UTC',
 'LONGITUDE': 98.7675609,
 'LATITUDE': -38.69027976,
 'INTERCEPT_RADIUS': 57739.95803153,
 'OBSERVER_ALTITUDE': 1831047.67987589,
 'INCIDENCE_ANGLE': 123.05323675,
 'EMISSION_ANGLE': 5.8567773,
 'PHASE_ANGLE': 123.77530312,
 'TIME_AT_POINT': '2012-10-14 00:00:00.000000 UTC',
 'LIGHT_TIME': 6.10771763,
 'LTST': '20:03:06'}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.SurfaceInterceptPoint(shape_1='ELLIPSOID', direction_vector_type='INSTRUMENT_BORESIGHT', aberration_correction='CN', state_representation='RECTANGULAR', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Surface intercept point calculation.

Calculate the intercept point of a vector or vectors on a target as seen from an observer.

Parameters
Other Parameters
Raises

Osculating Elements

Calculate the osculating elements of the orbit of a target body around a central body. The orbit may be elliptical, parabolic, or hyperbolic.

>>> OsculatingElements(
...     kernels = [1,5],
...     times = '2012-10-19T08:24:00.000',
...     orbiting_body = 'CASSINI',
...     center_body = 'SATURN',
...     verbose = False,
... ).run()
{'DATE': '2012-10-19 08:24:00.000000 UTC',
 'PERIFOCAL_DISTANCE': 474789.03917271,
 'ECCENTRICITY': 0.70348463,
 'INCLINATION': 38.18727034,
 'ASCENDING_NODE_LONGITUDE': 223.98123058,
 'ARGUMENT_OF_PERIAPSE': 71.59474487,
 'MEAN_ANOMALY_AT_EPOCH': 14.65461204,
 'ORBITING_BODY_RANGE': 753794.65101401,
 'ORBITING_BODY_SPEED': 8.77222231,
 'PERIOD': 2067101.2236748,
 'CENTER_BODY_GM': 37931207.49865224}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.OsculatingElements(reference_frame='J2000', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Osculating elements calculation.

Calculate the osculating elements of the orbit of a target body around a central body.

The orbit may be elliptical, parabolic, or hyperbolic.

Parameters

reference_frame (str, optional) – See: reference_frame

Other Parameters
Raises

CalculationRequiredAttr – If orbiting_body and center_body are not provided.

Time Conversion

Convert times from one time system or format to another.

>>> TimeConversion(
...     kernels = 5,
...     times = '1/1729329441.04',
...     time_system = 'SPACECRAFT_CLOCK',
...     time_format = 'SPACECRAFT_CLOCK_STRING',
...     sclk_id = -82,
...     verbose = False,
... ).run()
{'DATE': '1/1729329441.004', 'DATE2': '2012-10-19 08:24:02.919085 UTC'}

Important

Calculation required parameters:
Default parameters:
class webgeocalc.TimeConversion(output_time_system='UTC', output_time_format='CALENDAR', **kwargs)[source]

Bases: webgeocalc.calculation.Calculation

Time conversion calculation.

Convert times from one time system or format to another.

Parameters

  • output_time_system (str, optional) – See: output_time_system

  • output_time_format (str, optional) – See: output_time_format

Other Parameters