dcnum.feat.feat_contour.volume
==============================

.. py:module:: dcnum.feat.feat_contour.volume


Functions
---------

.. autoapisummary::

   dcnum.feat.feat_contour.volume.volume_from_contours
   dcnum.feat.feat_contour.volume.vol_revolve


Module Contents
---------------

.. py:function:: volume_from_contours(contour: list[numpy.ndarray], pos_x: numpy.ndarray, pos_y: numpy.ndarray, pixel_size: float)

   Calculate the volume of a polygon revolved around an axis

   The volume estimation assumes rotational symmetry.

   :param contour: One entry is a 2D array that holds the contour of an event
   :type contour: list of ndarrays of shape (N,2)
   :param pos_x: The x coordinate(s) of the centroid of the event(s) [µm]
   :type pos_x: float ndarray of length N
   :param pos_y: The y coordinate(s) of the centroid of the event(s) [µm]
   :type pos_y: float ndarray of length N
   :param pixel_size: The detector pixel size in µm.
   :type pixel_size: float

   :returns: **volume** -- volume in um^3
   :rtype: float ndarray

   .. rubric:: Notes

   The computation of the volume is based on a full rotation of the
   upper and the lower halves of the contour from which the
   average is then used.

   The volume is computed radially from the center position
   given by (``pos_x``, ``pos_y``). For sufficiently smooth contours,
   such as densely sampled ellipses, the center position does not
   play an important role. For contours that are given on a coarse
   grid, as is the case for deformability cytometry, the center position
   must be given.

   .. rubric:: References

   - https://de.wikipedia.org/wiki/Kegelstumpf#Formeln
   - Yields identical results to the Matlab script by Geoff Olynyk
     <https://de.mathworks.com/matlabcentral/fileexchange/36525-volrevolve>`_


.. py:function:: vol_revolve(r, z, point_scale=1.0)

   Calculate the volume of a polygon revolved around the Z-axis

   This implementation yields the same results as the volRevolve
   Matlab function by Geoff Olynyk (from 2012-05-03)
   https://de.mathworks.com/matlabcentral/fileexchange/36525-volrevolve.

   The difference here is that the volume is computed using (a much
   more approachable) implementation using the volume of a truncated
   cone (https://de.wikipedia.org/wiki/Kegelstumpf).

   .. math::

     V = \frac{h \cdot \pi}{3} \cdot (R^2 + R \cdot r + r^2)

   Where :math:`h` is the height of the cone and :math:`r` and
   ``R`` are the smaller and larger radii of the truncated cone.

   Each line segment of the contour resembles one truncated cone. If
   the z-step is positive (counter-clockwise contour), then the
   truncated cone volume is added to the total volume. If the z-step
   is negative (e.g. inclusion), then the truncated cone volume is
   removed from the total volume.

   :param r: radial coordinates (perpendicular to the z axis)
   :type r: 1d np.ndarray
   :param z: coordinate along the axis of rotation
   :type z: 1d np.ndarray
   :param point_scale: point size in your preferred units; The volume is multiplied
                       by a factor of `point_scale**3`.
   :type point_scale: float

   .. rubric:: Notes

   The coordinates must be given in counter-clockwise order,
   otherwise the volume will be negative.