"TWO_DIRECTIONS" feature in AngularSeparation

.github/workflows/release.yml

@@ -2,7 +2,7 @@ name: Release
 
 env:
   PACKAGE: webgeocalc
-  PYTHON: 3.8
+  PYTHON: 3.11
 
 on:
   push:

.pylintrc

@@ -571,4 +571,4 @@ min-public-methods=2
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "Exception".
-overgeneral-exceptions=Exception
+overgeneral-exceptions=builtins.Exception

docs/cli.rst

@@ -250,6 +250,36 @@ Here is the list of all the calculation entry points available on the CLI:
 - ``wgc-time-conversion``
 - ``wgc-gf-coordinate-search``
 
+.. hint::
+
+    If you need to provide a :py:class:`~webgeocalc.direction.Direction`
+    (eg. an :py:class:`~webgeocalc.AngularSeparation` calculation with ``TWO_DIRECTIONS``).
+    You need to encapsulate the nested parameters into single (``'``) or double (``"``) quotes
+    separated with spaces:
+
+    .. code:: bash
+
+        $ wgc-angular-separation --dry-run \
+                                --kernels 5 \
+                                --times 2012-10-19T08:24:00 \
+                                --spec_type TWO_DIRECTIONS \
+                                --direction_1 "direction_type=POSITION target=SUN shape=POINT observer='CASSINI'" \
+                                --direction_2 'direction_type=VECTOR direction_vector_type=REFERENCE_FRAME_AXIS direction_frame="CASSINI_RPWS_EDIPOLE" direction_frame_axis=Z'
+
+        API: https://wgc2.jpl.nasa.gov:8443/webgeocalc/api
+        Payload:
+        {
+            kernels: [{'type': 'KERNEL_SET', 'id': 5}],
+            times: ['2012-10-19T08:24:00.000'],
+            direction1: {'directionType': 'POSITION', 'target': 'SUN', 'shape': 'POINT', 'observer': 'CASSINI', 'aberrationCorrection': 'NONE', 'antiVectorFlag': False},
+            direction2: {'directionType': 'VECTOR', 'directionVectorType': 'REFERENCE_FRAME_AXIS', 'directionFrame': 'CASSINI_RPWS_EDIPOLE', 'directionFrameAxis': 'Z', 'aberrationCorrection': 'NONE', 'antiVectorFlag': False},
+            calculationType: ANGULAR_SEPARATION,
+            specType: TWO_DIRECTIONS,
+            timeSystem: UTC,
+            timeFormat: CALENDAR,
+        }
+
+
 All the calculation entry point accept an optional ``api`` attribute
 to submit the query to a custom endpoint.
 If ``WGC_URL`` global environment variable is defined,

docs/index.rst

@@ -95,6 +95,7 @@ Documentation
 
    api
    calculation
+   params
    cli
 
 .. important::

docs/params.rst

@@ -0,0 +1,131 @@
+Advanced parameters
+===================
+
+Payload
+--------
+
+.. currentmodule:: webgeocalc.payload
+
+WebGeoCalc API requires JSON encoded payloads. An abstract class :py: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 :py:mod:`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'}
+
+.. autoclass:: webgeocalc.payload.Payload
+
+Direction
+---------
+
+.. currentmodule:: webgeocalc.direction
+
+Direction vectors for ``ANGULAR_SEPARATION`` and ``POINTING_DIRECTION`` can be specified as
+an explicit :py:type:`dict` but it is recommended to use an explicit with :py:class:`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:
+        - :py:attr:`~Direction.direction_type` either ``POSITION``, ``VELOCITY`` or ``VECTOR``
+        - :py:attr:`~Direction.observer` (not required if :py:attr:`aberration_correction` is ``NONE``
+          and :py:attr:`~Direction.direction vector` is ``VECTOR``)
+
+    Direction ``POSITION`` required parameters:
+        - :py:attr:`~Direction.target`
+        - :py:attr:`~Direction.shape`
+
+    Direction ``VELOCITY`` required parameters:
+        - :py:attr:`~Direction.target`
+        - :py:attr:`~Direction.reference_frame`
+
+    Direction ``VECTOR`` required parameters:
+        - :py:attr:`~Direction.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`` required parameters:
+        - :py:attr:`~Direction.direction_instrument`
+
+    Direction ``VECTOR + REFERENCE_FRAME_AXIS`` required parameters:
+        - :py:attr:`~Direction.direction_frame`
+        - :py:attr:`~Direction.direction_frame_axis`
+
+    Direction ``VECTOR + VECTOR_IN_INSTRUMENT_FOV`` required parameters:
+        - :py:attr:`~Direction.direction_instrument`
+        - :py:attr:`~Direction.direction_vector_x`, :py:attr:`~Direction.direction_vector_y` and :py:attr:`~Direction.direction_vector_z`
+          or :py:attr:`~Direction.direction_vector_ra` and :py:attr:`~Direction.direction_vector_dec`
+          or :py:attr:`~Direction.direction_vector_az`, :py:attr:`~Direction.direction_vector_el`, :py:attr:`~Direction.azccw_flag`
+          and :py:attr:`~Direction.elplsz_flag`,
+
+    Default parameters:
+        - :py:attr:`~Direction.aberration_correction`: ``NONE``
+        - :py:attr:`~Direction.anti_vector_flag`: ``False``
+
+
+.. autoclass:: Direction