.. _sensor-mpdistant:

Multi-pixel distant radiancemeter sensor (:monosp:`mpdistant`)
--------------------------------------------------------------

.. pluginparameters::

 * - to_world
   - |transform|
   - Sensor-to-world transformation matrix.

 * - direction
   - |vector|
   - Alternative (and exclusive) to ``to_world``. Direction orienting the
     sensor's reference hemisphere.

 * - 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.

 * - target_radius
   - |float|
   - *Optional.* If a point target is used, setting this parameter to a positive
     value will turn the sensor into a distant radiometer with a fixed field of
     view defined as the cross section of a sphere of radius ``target_radius``
     and centered at ``target``. Otherwise, the single point ``target`` is
     targeted.

 * - srf
   - |spectrum|
   - Sensor Response Function that defines the
     :ref:`spectral sensitivity <explanation_srf_sensor>` of the sensor
     (Default: :monosp:`none`)

This sensor plugin implements a distant directional sensor which records
radiation leaving the scene in a given direction. It records the spectral
radiance leaving the scene in the specified direction. In its default version,
it is the adjoint to the ``directional`` emitter.

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.

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

If the film size is larger than 1×1, film coordinates are mapped to the (u,v)
coordinates of the target shape.

.. 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 non-default
   targeting strategy.