Advanced parameters

Payload

WebGeoCalc API requires JSON encoded payloads. An abstract class Payload is available to convert any python keywords values pattern into a structure dictionary that can be encoded into JSON. It also provided a mechanism to enforce some required keywords and restrict some parameter to a subset of VALID_PARAMETERS (see webgeocalc.vars).

>>> from webgeocalc.payload import Payload
>>> from webgeocalc.decorator import parameter

>>> class DerivedPayload(Payload):
...     REQUIRED = ('foo',)
...
...     @parameter
...     def foo(self, val):  # required
...         self.__foo = val
...
...     @parameter(only='AXIS')  # optional
...     def baz(self, val):
...         self.__baz = val

>>> DerivedPayload(foo='bar', baz='X').payload
{'foo': 'bar', 'baz': 'X'}
class webgeocalc.payload.Payload(**kwargs)[source]

Bases: ABC

Abstract WebGeoCalc payload abstract class.

Check if any required parameters is missing.

Raises:

CalculationRequiredAttr – If any parameter in REQUIRED is not provided.

property payload: dict

Payload parameters dict for JSON input in WebGeoCalc format.

Collect all the properties prefixed with __*.

Returns:

Payload keys and values.

Return type:

dict

Direction

Direction vectors for ANGULAR_SEPARATION and POINTING_DIRECTION can be specified as an explicit dict but it is recommended to use an explicit with Direction object:

>>> from webgeocalc.direction import Direction

>>> Direction(
...     direction_type='POSITION',
...     target='MARS',
...     shape='POINT',
...     observer='EARTH',
...     aberration_correction='LT+S',
... ).payload
{'directionType': 'POSITION',
 'target': 'MARS',
 'shape': 'POINT',
 'observer': 'EARTH',
 'aberrationCorrection': 'LT+S',
 'antiVectorFlag': False}

>>> Direction(
...     direction_type='VELOCITY',
...     target='MARS',
...     reference_frame='ITRF93',
...     observer='EARTH',
...     aberration_correction='XCN+S',
...     anti_vector_flag=True,
... ).payload
{'directionType': 'VELOCITY',
 'target': 'MARS',
 'referenceFrame': 'ITRF93',
 'observer': 'EARTH',
 'aberrationCorrection': 'XCN+S',
 'antiVectorFlag': True}

>>> Direction(
...     direction_type='VECTOR',
...     observer='EARTH',
...     direction_vector_type='REFERENCE_FRAME_AXIS',
...     direction_frame='IAU_EARTH',
...     direction_frame_axis='X',
...     aberration_correction='S',
...     anti_vector_flag=True,
... ).payload
{'directionType': 'VECTOR',
 'observer': 'EARTH',
 'directionVectorType': 'REFERENCE_FRAME_AXIS',
 'directionFrame': 'IAU_EARTH',
 'directionFrameAxis': 'X',
 'aberrationCorrection': 'S',
 'antiVectorFlag': True}

Important

Direction required parameters:

  • direction_type either POSITION, VELOCITY or VECTOR

  • observer (not required if aberration_correction is NONE and direction vector is VECTOR)

Direction POSITION required parameters:
Direction VELOCITY required parameters:
Direction VECTOR required parameters:

  • direction_vector_type either INSTRUMENT_BORESIGHT, REFERENCE_FRAME_AXIS, VECTOR_IN_INSTRUMENT_FOV, VECTOR_IN_REFERENCE_FRAME or INSTRUMENT_FOV_BOUNDARY_VECTORS

Direction vector INSTRUMENT_BORESIGHT or INSTRUMENT_FOV_BOUNDARY_VECTORS required parameters:
Direction vector REFERENCE_FRAME_AXIS required parameters:
Direction vector VECTOR_IN_INSTRUMENT_FOV required parameters:
Direction vector VECTOR_IN_REFERENCE_FRAME required parameters:
Default parameters:
class webgeocalc.direction.Direction(aberration_correction='NONE', anti_vector_flag=False, **kwargs)[source]

Bases: Payload

Webgeocalc direction object.

Parameters:
property direction_type

Type of direction.

Method used to specify a direction. Directions could be specified as the position of an object as seen from the observer, as the velocity vector of an object as seen from the observer in a given reference frame, or by providing a vector in a given reference frame.

Parameters:

direction_type (str) –

The type of direction string. One of:

  • POSITION

  • VELOCITY

  • VECTOR

Velocity depends on the reference frame in which it is expressed.

Raises:

CalculationInvalidAttr – If the value provided is invalid.

property observer

Observing body.

Parameters:

observer (str or int) – The observing body name or id from API.bodies(). Required if aberration_correction is not 'NONE' for direction vector of type 'VECTOR'.

property target

Target body.

Parameters:

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

property shape

The shape to use for the first body.

Parameters:

shape (str) –

One of:

  • POINT

  • SPHERE

Raises:

CalculationInvalidAttr – If the value provided is invalid.

property reference_frame

The reference frame name.

Parameters:

reference_frame (str) – The reference frame name.

property direction_vector_type

Direction vector type.

Parameters:

direction_vector_type (str) –

The direction vector type string. One of:

  • INSTRUMENT_BORESIGHT

  • REFERENCE_FRAME_AXIS

  • VECTOR_IN_INSTRUMENT_FOV

  • VECTOR_IN_REFERENCE_FRAME

  • INSTRUMENT_FOV_BOUNDARY_VECTORS (*)

(*) only for PointingDirection calculation.

Raises:

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationRequiredAttr – If this parameter is INSTRUMENT_BORESIGHT, VECTOR_IN_INSTRUMENT_FOV or INSTRUMENT_FOV_BOUNDARY_VECTORS but direction_instrument is not provided.

  • CalculationRequiredAttr – If this parameter is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME but direction_frame is not provided.

  • CalculationRequiredAttr – If this parameter is REFERENCE_FRAME_AXIS but direction_frame_axis is not provided.

property direction_instrument

The instrument direction.

Required only if direction_vector_type is INSTRUMENT_BORESIGHT, VECTOR_IN_INSTRUMENT_FOV or INSTRUMENT_FOV_BOUNDARY_VECTORS.

Parameters:

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

Raises:

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

property direction_frame

The vector’s reference frame name.

Required only if direction_vector_type is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.

Parameters:

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

Raises:

CalculationIncompatibleAttr – If direction_vector_type is not in REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.

property direction_frame_axis

The direction vector frame axis.

Required only if direction_vector_type is REFERENCE_FRAME_AXIS.

Parameters:

direction_frame_axis (str) –

The direction frame axis string. One of:

  • X

  • Y

  • Z

Raises:

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationIncompatibleAttr – If direction_vector_type is not REFERENCE_FRAME_AXIS.

  • CalculationInvalidAttr – If the value provided is invalid.

property direction_vector_x

The X direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_x, direction_vector_y, and direction_vector_z must be provided.

Parameters:

direction_vector_x (float) – The X direction vector coordinate value.

property direction_vector_y

The Y direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_x, direction_vector_y, and direction_vector_z must be provided.

Parameters:

direction_vector_y (float) – The Y direction vector coordinate value.

property direction_vector_z

The Z direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_x, direction_vector_y, and direction_vector_z must be provided.

Parameters:

direction_vector_z (float) – The Z direction vector coordinate value.

property direction_vector_ra

The right ascension direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_ra and direction_vector_dec must be provided.

Parameters:

direction_vector_ra (float) – The right ascension direction vector coordinate value.

property direction_vector_dec

The declination direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_ra and direction_vector_dec must be provided.

Parameters:

direction_vector_dec (float) – The declination direction vector coordinate value.

property direction_vector_az

The azimuth direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_az, direction_vector_el, azccw_flag and elplsz_flag must be provided.

Parameters:

direction_vector_az (float) – The azimuth direction vector coordinate value.

property direction_vector_el

The elevation direction vector coordinate.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_az, direction_vector_el, azccw_flag and elplsz_flag must be provided.

Parameters:

direction_vector_el (float) – The elevation vector coordinate value.

property azccw_flag

Flag indicating how azimuth is measured.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_az, direction_vector_el, azccw_flag and elplsz_flag must be provided.

Parameters:

azccw_flag (bool) – Flag indicating how azimuth is measured.

Raises:

  • CalculationUndefinedAttr – If direction_vector_az is not provided.

  • CalculationInvalidAttr – If the value provided is invalid.

property elplsz_flag

Flag indicating how elevation is measured.

If direction_vector_type is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of direction_vector_az, direction_vector_el, azccw_flag and elplsz_flag must be provided.

Parameters:

elplsz_flag (bool) – ag indicating how elevation is measured.

Raises:

  • CalculationUndefinedAttr – If direction_vector_el is not provided.

  • CalculationInvalidAttr – If the value provided is invalid.

property aberration_correction

SPICE aberration correction.

Parameters:

aberration_correction (str) –

The SPICE aberration correction string.

For POSITION or VELOCITY, one of:

  • NONE

  • LT

  • LT+S

  • CN

  • CN+S

  • XLT

  • XLT+S

  • XCN

  • XCN+S

For VECTOR, light time correction is applied to the rotation from the vector frame to J2000, while stellar aberration corrections apply to the vector direction. One of:

  • NONE

  • LT

  • CN

  • XLT

  • XCN

  • S

  • XS

Raises:

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationRequiredAttr – If this DIRECTION_TYPE is VECTOR and ABERRATION_CORRECTION is NONE but observer is not provided.

property anti_vector_flag

Anti-vector flag.

Parameters:

anti_vector_flag (bool) –

True if the anti-vector shall be used for the direction, and False otherwise.

In type POSITION, required when the target shape is POINT (default). If provided when the target shape is SPHERE, it must be set to false, i.e., using anti-vector direction is not supported for target bodies modeled as spheres.

Raises:

  • CalculationInvalidAttr – If the value provided is invalid.

  • CalculationInvalidAttr – If this direction_type is POSITION and SHAPE is SPHERE but observer is not provided.