Skip to content

Commit d5380fe

Browse files
BaptisteCecconiseignovert
BaptisteCecconi
and
seignovert
authored
"TWO_DIRECTIONS" feature in AngularSeparation (#11)
* Add `TWO_DIRECTIONS` implementation in `AngularSeparation` and `wgc-angular-separation` cli. * Add `Payload` and `Directions` classes * Bump python min version to 3.11 * Bump requests version (closes #9) --------- Co-authored-by: Benoit Seignovert <benoit.seignovert@univ-nantes.fr>
1 parent 66797da commit d5380fe

22 files changed

+2354
-358
lines changed

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: Release
22

33
env:
44
PACKAGE: webgeocalc
5-
PYTHON: 3.8
5+
PYTHON: 3.11
66

77
on:
88
push:

‎.pylintrc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -571,4 +571,4 @@ min-public-methods=2
571571

572572
# Exceptions that will emit a warning when being caught. Defaults to
573573
# "Exception".
574-
overgeneral-exceptions=Exception
574+
overgeneral-exceptions=builtins.Exception

‎docs/calculation.rst‎

Lines changed: 187 additions & 127 deletions
Large diffs are not rendered by default.

‎docs/cli.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -250,6 +250,36 @@ Here is the list of all the calculation entry points available on the CLI:
250250
- ``wgc-time-conversion``
251251
- ``wgc-gf-coordinate-search``
252252
253+
.. hint::
254+
255+
If you need to provide a :py:class:`~webgeocalc.direction.Direction`
256+
(eg. an :py:class:`~webgeocalc.AngularSeparation` calculation with ``TWO_DIRECTIONS``).
257+
You need to encapsulate the nested parameters into single (``'``) or double (``"``) quotes
258+
separated with spaces:
259+
260+
.. code:: bash
261+
262+
$ wgc-angular-separation --dry-run \
263+
--kernels 5 \
264+
--times 2012-10-19T08:24:00 \
265+
--spec_type TWO_DIRECTIONS \
266+
--direction_1 "direction_type=POSITION target=SUN shape=POINT observer='CASSINI'" \
267+
--direction_2 'direction_type=VECTOR direction_vector_type=REFERENCE_FRAME_AXIS direction_frame="CASSINI_RPWS_EDIPOLE" direction_frame_axis=Z'
268+
269+
API: https://wgc2.jpl.nasa.gov:8443/webgeocalc/api
270+
Payload:
271+
{
272+
kernels: [{'type': 'KERNEL_SET', 'id': 5}],
273+
times: ['2012-10-19T08:24:00.000'],
274+
direction1: {'directionType': 'POSITION', 'target': 'SUN', 'shape': 'POINT', 'observer': 'CASSINI', 'aberrationCorrection': 'NONE', 'antiVectorFlag': False},
275+
direction2: {'directionType': 'VECTOR', 'directionVectorType': 'REFERENCE_FRAME_AXIS', 'directionFrame': 'CASSINI_RPWS_EDIPOLE', 'directionFrameAxis': 'Z', 'aberrationCorrection': 'NONE', 'antiVectorFlag': False},
276+
calculationType: ANGULAR_SEPARATION,
277+
specType: TWO_DIRECTIONS,
278+
timeSystem: UTC,
279+
timeFormat: CALENDAR,
280+
}
281+
282+
253283
All the calculation entry point accept an optional ``api`` attribute
254284
to submit the query to a custom endpoint.
255285
If ``WGC_URL`` global environment variable is defined,

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ Documentation
9595

9696
api
9797
calculation
98+
params
9899
cli
99100

100101
.. important::

‎docs/params.rst‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
Advanced parameters
2+
===================
3+
4+
Payload
5+
--------
6+
7+
.. currentmodule:: webgeocalc.payload
8+
9+
WebGeoCalc API requires JSON encoded payloads. An abstract class :py:class:`Payload` is
10+
available to convert any python keywords values pattern into a structure dictionary that
11+
can be encoded into JSON. It also provided a mechanism to enforce some required keywords
12+
and restrict some parameter to a subset of ``VALID_PARAMETERS``
13+
(see :py:mod:`webgeocalc.vars`).
14+
15+
>>> from webgeocalc.payload import Payload
16+
>>> from webgeocalc.decorator import parameter
17+
18+
>>> class DerivedPayload(Payload):
19+
... REQUIRED = ('foo',)
20+
...
21+
... @parameter
22+
... def foo(self, val): # required
23+
... self.__foo = val
24+
...
25+
... @parameter(only='AXIS') # optional
26+
... def baz(self, val):
27+
... self.__baz = val
28+
29+
30+
>>> DerivedPayload(foo='bar', baz='X').payload
31+
{'foo': 'bar', 'baz': 'X'}
32+
33+
.. autoclass:: webgeocalc.payload.Payload
34+
35+
Direction
36+
---------
37+
38+
.. currentmodule:: webgeocalc.direction
39+
40+
Direction vectors for ``ANGULAR_SEPARATION`` and ``POINTING_DIRECTION`` can be specified as
41+
an explicit :py:type:`dict` but it is recommended to use an explicit with :py:class:`Direction`
42+
object:
43+
44+
>>> from webgeocalc.direction import Direction
45+
46+
>>> Direction(
47+
... direction_type='POSITION',
48+
... target='MARS',
49+
... shape='POINT',
50+
... observer='EARTH',
51+
... aberration_correction='LT+S',
52+
... ).payload
53+
{'directionType': 'POSITION',
54+
'target': 'MARS',
55+
'shape': 'POINT',
56+
'observer': 'EARTH',
57+
'aberrationCorrection': 'LT+S',
58+
'antiVectorFlag': False}
59+
60+
>>> Direction(
61+
... direction_type='VELOCITY',
62+
... target='MARS',
63+
... reference_frame='ITRF93',
64+
... observer='EARTH',
65+
... aberration_correction='XCN+S',
66+
... anti_vector_flag=True,
67+
... ).payload
68+
{'directionType': 'VELOCITY',
69+
'target': 'MARS',
70+
'referenceFrame': 'ITRF93',
71+
'observer': 'EARTH',
72+
'aberrationCorrection': 'XCN+S',
73+
'antiVectorFlag': True}
74+
75+
>>> Direction(
76+
... direction_type='VECTOR',
77+
... observer='EARTH',
78+
... direction_vector_type='REFERENCE_FRAME_AXIS',
79+
... direction_frame='IAU_EARTH',
80+
... direction_frame_axis='X',
81+
... aberration_correction='S',
82+
... anti_vector_flag=True,
83+
... ).payload
84+
{'directionType': 'VECTOR',
85+
'observer': 'EARTH',
86+
'directionVectorType': 'REFERENCE_FRAME_AXIS',
87+
'directionFrame': 'IAU_EARTH',
88+
'directionFrameAxis': 'X',
89+
'aberrationCorrection': 'S',
90+
'antiVectorFlag': True}
91+
92+
.. important::
93+
94+
Direction required parameters:
95+
- :py:attr:`~Direction.direction_type` either ``POSITION``, ``VELOCITY`` or ``VECTOR``
96+
- :py:attr:`~Direction.observer` (not required if :py:attr:`aberration_correction` is ``NONE``
97+
and :py:attr:`~Direction.direction vector` is ``VECTOR``)
98+
99+
Direction ``POSITION`` required parameters:
100+
- :py:attr:`~Direction.target`
101+
- :py:attr:`~Direction.shape`
102+
103+
Direction ``VELOCITY`` required parameters:
104+
- :py:attr:`~Direction.target`
105+
- :py:attr:`~Direction.reference_frame`
106+
107+
Direction ``VECTOR`` required parameters:
108+
- :py:attr:`~Direction.direction_vector_type` either
109+
``INSTRUMENT_BORESIGHT``, ``REFERENCE_FRAME_AXIS``, ``VECTOR_IN_INSTRUMENT_FOV``,
110+
``VECTOR_IN_REFERENCE_FRAME`` or ``INSTRUMENT_FOV_BOUNDARY_VECTORS``
111+
112+
Direction ``VECTOR + INSTRUMENT_BORESIGHT`` required parameters:
113+
- :py:attr:`~Direction.direction_instrument`
114+
115+
Direction ``VECTOR + REFERENCE_FRAME_AXIS`` required parameters:
116+
- :py:attr:`~Direction.direction_frame`
117+
- :py:attr:`~Direction.direction_frame_axis`
118+
119+
Direction ``VECTOR + VECTOR_IN_INSTRUMENT_FOV`` required parameters:
120+
- :py:attr:`~Direction.direction_instrument`
121+
- :py:attr:`~Direction.direction_vector_x`, :py:attr:`~Direction.direction_vector_y` and :py:attr:`~Direction.direction_vector_z`
122+
or :py:attr:`~Direction.direction_vector_ra` and :py:attr:`~Direction.direction_vector_dec`
123+
or :py:attr:`~Direction.direction_vector_az`, :py:attr:`~Direction.direction_vector_el`, :py:attr:`~Direction.azccw_flag`
124+
and :py:attr:`~Direction.elplsz_flag`,
125+
126+
Default parameters:
127+
- :py:attr:`~Direction.aberration_correction`: ``NONE``
128+
- :py:attr:`~Direction.anti_vector_flag`: ``False``
129+
130+
131+
.. autoclass:: Direction

0 commit comments

Comments
 (0)