.. _sec-user_guide-conventions: Conventions in Eradiate ======================= Eradiate aims at building bridges between scientific communities. In some cases, this can however lead to difficult situations due to identical expressions or names having a different meaning depending on context. For concepts, Eradiate has a :ref:`glossary `; for other things bound to a convention (*e.g.* the practical definition of angles used in spherical coordinates), this page should settle things. Local coordinate definition --------------------------- .. only:: not latex .. margin:: .. figure:: ../../fig/cartesian-coordinate-system.svg :width: 100% Internally, Eradiate and its radiometric kernel Mitsuba use Cartesian coordinates to locate scene objects. When relevant, during scene construction, the X, Y and Z axes are mapped to the local East, North and up directions at the origin location. .. only:: latex .. image:: ../../fig/cartesian-coordinate-system.png Note that this does not mean that Eradiate always uses an East, North, up (ENU) coordinate system: this is only relevant when planetary curvature can be neglected. Spherical coordinates --------------------- .. only:: not latex .. margin:: .. figure:: ../../fig/spherical-coordinate-system.svg :width: 100% Internally, Eradiate also uses the spherical coordinate system with the ISO 80000-2:2019 convention :cite:`ISO201980000QuantitiesUnits` (commonly used in physics) where: * :math:`r`, denotes the radial distance whose magnitude is a positive number; * :math:`\theta \in [0, \pi]` rad, *i.e.* :math:`[0, 180]°`, denotes the *zenith angle*, a.k.a. the colatitude, polar angle, normal angle or inclination angle, which measures the angular distance to the local zenith; * :math:`\varphi \in [0, 2\pi[` rad, *i.e.* :math:`[0, 360[°`, denotes the *azimuth angle*, defined with the X axis as its references and incremented counter-clockwise. .. only:: latex .. image:: ../../fig/spherical-coordinate-system.png Local illumination and viewing angle definition ----------------------------------------------- The directions to the Sun and sensor are specified in the :math:`(\theta, \varphi)` space. In our convention, it follows that: * the Sun is considered to be at the zenith when :math:`\theta_\mathrm{s} = 0°`; * the sensor is considered to point towards the nadir when :math:`\theta_\mathrm{v} = 0°`. The azimuth angle :math:`\varphi` is defined following the right-hand rule using the local vertical, with its origin aligned with the local X axis (pointing towards East). We name this convention "East right". Other conventions are frequently used in Earth observation applications, and Eradiate therefore provides utility components to handle the conversion automatically. .. _sec-user_guide-conventions-azimuth: Azimuth definition conventions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. admonition:: Summary Eradiate works internally with the *East right* convention, which aligns the 0° azimuth with the X axis and orients azimuth values counter-clockwise. If you work with geophysical data, chances are that you will prefer the *North left* convention, which aligns the 0° with the Y axis and increments azimuth values clockwise. For convenience, Eradiate defines a set of azimuth definition conventions, exposed to the user through a dedicated interface. All azimuth angle conventions are defined, using the aforementioned East right convention as a reference, by: * an `offset` value, which defines the direction with which the azimuth origin is aligned (incremented counter-clockwise); * an `orientation`, which defines azimuth angles are counted positively clockwise or counter-clockwise (after applying the offset). The offset is expressed in angle units (internally, radian) and the most common values are aliased by the orientation corresponding to cardinal points on maps in the Western tradition. The two possible orientations are named after the right-hand rule: "right" is counter-clockwise and corresponds to the + sign; "left" is clockwise and corresponds to the - sign. .. only:: not latex .. list-table:: Eradiate's built-in azimuth conventions. :align: center :header-rows: 1 :stub-columns: 1 :widths: 1 4 4 * - - Right - Left * - East - .. image:: ../../fig/azimuth-east_right.svg - .. image:: ../../fig/azimuth-east_left.svg * - North - .. image:: ../../fig/azimuth-north_right.svg - .. image:: ../../fig/azimuth-north_left.svg * - West - .. image:: ../../fig/azimuth-west_right.svg - .. image:: ../../fig/azimuth-west_left.svg * - South - .. image:: ../../fig/azimuth-south_right.svg - .. image:: ../../fig/azimuth-south_left.svg .. only:: latex .. list-table:: Eradiate's built-in azimuth conventions. :align: center :header-rows: 1 :stub-columns: 1 :widths: auto * - - Right - Left * - East - .. image:: ../../fig/azimuth-east_right.png - .. image:: ../../fig/azimuth-east_left.png * - North - .. image:: ../../fig/azimuth-north_right.png - .. image:: ../../fig/azimuth-north_left.png * - West - .. image:: ../../fig/azimuth-west_right.png - .. image:: ../../fig/azimuth-west_left.png * - South - .. image:: ../../fig/azimuth-south_right.png - .. image:: ../../fig/azimuth-south_left.png Objects and functions taking angular parameters provide, when relevant, an option to specify which convention is used. Manual conversion can be performed using the :func:`eradiate.frame.transform_azimuth` function. Principal plane orientation --------------------------- Unless told otherwise, Eradiate indexes principal plane data using a signed zenith angle in the [-90°, 90°] range, with the positive half-plane containing the illumination direction. From this follows: .. important:: *On principal plane plots, the illumination is located to the right.*