Derived classes

Hapke Model

class HapkeModel(geometries, variant, adapter, theta_bar_scaling, b0, h)

The class HapkeModel is a representation of the Hapke’s photometric model. For more details check the scientific documentation.

There are two variants of the Hapke’s formulation, the initial 1993 version and the 2002 version. The calculation in the class are initially designed for a 4 parameters model. The class can use a adapter to adapt different variants of the model for example : the model with 3 or 6 parameters.

See : Hapke B. 1993 Theory of Reflectance and Emittance Spectroscopy. Topics in Remote Sensing. Cambridge University Press, Cambridge, UK.

See : Schmidt F. and Fernando J. 2015 Realistic uncertainties on Hapke model parameters from photometric measurement. Icarus, 260 :73 - 93, 2015.

Parameters:

geometries (ndarray of shape (n_geometries,3)) –
The matrix of geometries that will be used by the model. The shape of the Numpy array should be (n_geometries,3). The three geometric angles must be this particular order :
- At [:,0] the incidence angle (inc) also called the solar zenith angle (sza)
- At [:,1] the emergence angle (eme) also called the vertical zenith angle (vza)
- At [:,2] the phi angle (phi)
Thus the geometries matrix should look like this
```
>>> geometries
array([ [inc_0, eme_0, phi_0],
        [inc_1, eme_1, phi_1],
        [inc_2, eme_2, phi_2],
                ...
        [inc_n, eme_n, phi_n]])
```
variant (string) – The variant a the Hapke’s model among {‘1993’, ‘2002’}.
adapter (string) – This argument allows to adapt the Hapke’s model parameter number among {‘three’, ‘four’, ‘six’}.
theta_bar_scaling (float) – Value used to transform theta_bar between physical and mathematical spaces.
b0 (float) – The amplitude of the opposition effect
h (float) – The angular width of the opposition effect

Shkuratov Model

class ShkuratovModel(geometries, variant, scaling_coeffs, offset)

The class ShkuratovModel is a representation of the Shkuratov’s photometric model. For more details check the scientific documentation.

There are two variants of the Shkuratov’s formulation, the original model with 5 parameters and a reduced model with 3 parameters. The scaling_coeffs and offset arguments are to perform affine transformation between the physical space and the mathematical space, such as, \((\text{toPhysic}(x))_{1 \leq i \leq L} = (\text{scaling_coeffs}_i x_i + \text{offset}_i)_{1 \leq i \leq L}\).

Parameters:

geometries (ndarray of shape (n_geometries,3)) –
The matrix of geometries that will be used by the model. The shape of the Numpy array should be (n_geometries,3). The three geometric angles must be this particular order :
- At [:,0] the incidence angle (inc) also called the solar zenith angle (sza)
- At [:,1] the emergence angle (eme) also called the vertical zenith angle (vza)
- At [:,2] the phi angle (phi)
Thus the geometries matrix should look like this
```
>>> geometries
array([ [inc_0, eme_0, phi_0],
        [inc_1, eme_1, phi_1],
        [inc_2, eme_2, phi_2],
                ...
        [inc_n, eme_n, phi_n]])
```
variant (string) – The variant a the Hapke’s model among {‘3p’, ‘5p’}. ‘3p’ refers to the 3-parameters variant- and ‘5p’ refers to the original 5-parameters model.
scaling_coeffs (ndarray of shape (L,)) – A set of coefficients used in the transformation between physical and mathematical spaces.
offset (ndarray of shape (L,)) – A set of offsets used in the transformation between physical and mathematical spaces

External Python Model

class ExternalPythonModel(className, fileName, filePath)

The PlanetGLLiM software allows you to edit your own physical model. To do so you must provide a Python file (.py) describing your physical model as a Python class. The template of such python module is described below.

>>> # IMPORTS
>>> import numpy as np
>>>
>>> class PhysicalModel(object):
>>>    """ This is a python class defining a functional model.
>>>
>>>    This class is composed of 5 mandatory functions:
>>>        - F: the functional model F describing the physical model. F takes photometries as arguments and return reflectances
>>>        - getDimensionY: returns the dimension of Y (reflectances)
>>>        - getDimensionX: return de dimension of X (photometries)
>>>        - toPhysic: converts the X data from mathematical framework (0<X<1) to physical framework
>>>        - fromPhysic: converts the X data from physical framework to mathematical framework (0<X<1)
>>>
>>>    Note that some class constants, other functions and class constructors can be declared.
>>>
>>>    Geometries : if your physical model requires geometries as with Shkuratov, the structure and the values of the geometries
>>>        must be declared within this Python file.
>>>
>>>    See the Planet-Gllim documentation for more informations (https://gitlab.inria.fr/xllim/planet-gllim/-/wikis/home)
>>>    """
>>>
>>>    #################################################################################################
>>>    ##                          CLASS CONSTANTS (OPTIONAL)                                         ##
>>>    #################################################################################################
>>>
>>>    # Geometries of the physical model MUST be declared here - directly in the python file.
>>>
>>>
>>>    #################################################################################################
>>>    ##                          CORE FUNCTIONS (MANDATORY)                                         ##
>>>    #################################################################################################
>>>
>>>    def F(self):
>>>        pass
>>>
>>>    def getDimensionY(self):
>>>        pass
>>>
>>>    def getDimensionX(self):
>>>        pass
>>>
>>>    def toPhysic(self):
>>>        pass
>>>
>>>    def fromPhysic(self):
>>>        pass
>>>
>>>
>>>    #################################################################################################
>>>    ##                          OTHER FUNCTIONS (OPTIONAL)                                         ##
>>>    #################################################################################################
>>>
>>>    def __init__(self, *args, **kwargs):
>>>        pass
>>>
>>>    def optional_but_useful_function():
>>>        pass

If the functional model shows interest it can be added in further development in xLLiM as a built-in class to improve speed performance.

Parameters:

className (string) – The exact name of the python class.
fileName (string) – The exact name of the python module without the .py extension.
filePath (string) – The directory path of the python module.

Test Model

class TestModel

The class TestModel is low-dimensional functional model implemented in order to test the GLLiM method with simple but not trivial example. The functional F is designed so as to exhibit 2 solutions with D=9 and L=4. \(F = A ◦ G ◦ H\), where

\(A\) is a (DxL) injective matrix,

\[\begin{split}A = \frac{1}{2} \begin{pmatrix} 1 & 2 & 2 & 1 \\ 0 & 0.5 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 3 \\ 0.2 & 0 & 0 & 0 \\ 0 & -0.5 & 0 & 0 \\ -0.2 & 0 & -1 & 0 \\ -1 & 0 & 2 & 0 \\ 0 & 0 & 0 & -0.7 \end{pmatrix}\end{split}\]

\(G(x)\) = \((exp(x_1), exp(x_2), exp(x_3), exp(x_4))\) and

\(H(x)\) = \((x_1, x_2, 4(x_3-0.5)^2, x_4)\).

The resulting F is therefore non-linear and yields two solutions for each observation, denoted by xobs,1 and xobs,2 = 1 - xobs,1.