.. _plugin-bsdf-ocean_grasp:

(GRASP) Oceanic reflection model (:monosp:`ocean-grasp`)
-------------------------------------------------------------

.. pluginparameters::
 :extra-rows: 8

 * - wavelength
   - |float|
   - :math:`k \in [200, 4000]` nm.
   - Specifies the wavelength at which to evaluate the oceanic reflectance.

 * - wind_speed
   - |spectrum| or |texture|
   - :math:`k \in [0, 37.54]` m/s.
   - Specifies the wind speed at which to evaluate the oceanic reflectance
     (Default: :monosp:`0.1 m/s`).

 * - eta, k
   - |spectrum| or |texture|
   - Real and imaginary components of the water's index of refraction.
     (Default: :monosp:`1.33, 0.`)

 * - ext_ior
   - |spectrum| or |texture|
   - Exterior index of refraction specified numerically or using a known
     material name. Note that the complex component is assumed to be 0
     (Default: 1.000277).

 * - water_body_reflectance
   - |spectrum| or |texture|
   - Diffuse reflectance of radiations that entered and exited the water body.
     (Default: 0.).

 * - component
   - |int|
   - Debug: specifies which component of the oceanic reflection model to evaluate.
     Default: 0 Component 0 is used to evaluate the total oceanic reflectance.
     Component 1 evaluates the whitecap reflectance. Component 2 evaluates the sun
     glint reflectance. Component 3 evaluates the underlight reflectance.
     Component 4 evaluates the whitecap and underlight reflectance together.

This plugin implements the oceanic reflection model originally detailed in
cite:`Litvinov2024AerosolSurfaceCharacterization`. Note that this model
is monochromatic.

For the fundamental formulae defining the oceanic reflectance model, please
refer to the Eradiate Scientific Handbook.

Note that this material is one-sided---that is, observed from the
back side, it will be completely black. If this is undesirable,
consider using the ``twosided`` BSDF adapter plugin.
The following snippet describes an oceanic surface material with monochromatic
parameters:

.. tab-set-code::

    .. code-block:: python

        "type": "ocean_grasp",
        "wavelength": 550,
        "wind_speed": 10,
        "eta": 1.33,
        "k": 0.,
        "ext_ior": 1.0,
        "water_body_reflectance": 0.02,
        "component": 0,

    .. code-block:: xml

        <bsdf type="ocean_grasp">
            <float name="wavelength" value="550"/>
            <float name="wind_speed" value="10"/>
            <float name="eta" value="1.33"/>
            <float name="k" value="0."/>
            <float name="ext_ior" value=1.0/>
            <float name="water_body_reflectance" value=0.02/>
            <int name="component" value="0"/>
        </bsdf>