.. _plugin-volume-sphericalcoordsvolume:

Mapping to spherical coordinates (:monosp:`sphericalcoordsvolume`)
------------------------------------------------------------------

.. pluginparameters::

 * - volume
   - |volume|
   - Nested volume plugin whose data is to be mapped to spherical coordinates.
   - —

 * - rmin
   - |float|
   - Radius for the inner limit of the spherical shell, relative to the unit
     sphere. Default: 0
   - —

 * - rmax
   - |float|
   - Radius for the outer limit of the spherical shell, relative to the unit
     sphere. Default: 1
   - —

 * - fillmin
   - |float|
   - Constant value to return for points such that :math:`r < r_\mathrm{min}`.
     Default: 0
   - —

 * - fillmax
   - |float|
   - Constant value to return for points such that :math:`r_\mathrm{max} < r`.
     Default: 0
   - —

 * - to_world
   - |transform|
   - Specifies an optional 4x4 transformation matrix that will remap local
     spherical coordinates from the unit sphere (which covers the [-1, 1]³ cube)
     to world coordinates.
   - —

This plugin addresses volume data in spherical coordinates. In practice, it
maps the texture coordinates of a nested volume plugin to the unit sphere using
the following correspondance:

.. math::

    x \in [0, 1] & \leftrightarrow r \in [r_\mathrm{min}, r_\mathrm{max}] \\
    y \in [0, 1] & \leftrightarrow \theta \in [0, \pi] \\
    z \in [0, 1] & \leftrightarrow \phi \in [-\pi, \pi]

where :math:`r` is the radius of the considered point in the unit sphere.
For angles, the default mathematical convention is used:
:math:`\theta` is the zenith angle with respect to the :math:`+Z` unit vector,
and :math:`\phi` is the azimuth angle with respect to the :math:`(+X, +Z)`
plane.

.. note::

    When using this plugin with a nested ``gridvolume``, the data layout
    remains unchanged (*i.e.* zyxc will be interpreted as φθrc).