.. _plugin-sensor-mdistant:

Multi distant radiance meter (:monosp:`mdistant`)
-------------------------------------------------

.. pluginparameters::

 * - directions
   - |string|
   - Comma-separated list of directions in which the sensors are pointing in
     world coordinates.
   - —

 * - target
   - |point| or nested :paramtype:`shape` plugin
   - *Optional.* Define the ray target sampling strategy.
     If this parameter is unset, ray target points are sampled uniformly on
     the cross section of the scene's bounding sphere.
     If a |point| is passed, rays will target it.
     If a shape plugin is passed, ray target points will be sampled from its
     surface.
   - —

 * - ray_offset
   - |float|
   - *Optional.* Define the ray origin offsetting policy.
     If this parameter is unset, ray origins are positioned at a far distance
     from the target. If a value is set, rays are offset by the corresponding
     distance.
   - —

This sensor plugin aggregates an arbitrary number of distant directional sensors
which records the spectral radiance leaving the scene in specified directions.
It is the aggregation of multiple :monosp:`distant` sensors.

By default, ray target points are sampled from the cross section of the scene's
bounding sphere. The ``target`` parameter can be set to restrict ray target
sampling to a specific subregion of the scene. The recorded radiance is averaged
over the targeted geometry.

Ray origins are positioned outside of the scene's geometry.

.. warning::

   If this sensor is used with a targeting strategy leading to rays not hitting
   the scene's geometry (*e.g.* default targeting strategy), it will pick up
   ambient emitter radiance samples (or zero values if no ambient emitter is
   defined). Therefore, it is almost always preferable to use a nondefault
   targeting strategy.

.. important::

   This sensor must be used with a film with size (`N`, 1), where `N` is the
   number of aggregated sensors, and is best used with a default :monosp:`box`
   reconstruction filter.