.. _volume:

====================================
 Calculating the volume of a vessel
====================================

As we have seen, the simplest method for calculating the volume of a
solid of revolution is by dividing the rotating shape into smaller
pieces.

This method has however one major flaw that limits its adoption for
archaeological purposes, namely it cannot be used to calculate the
capacity of a vessel that has a convex interior surface.

.. todo:: Insert a representative picture here.

For this reason, Kotyle uses a more advanced technique, based on
Pappus's centroid theorem.


Pappus's centroid theorem
=========================

In mathematics, Pappus's centroid theorem is either of two related
theorems dealing with the surface areas and volumes of surfaces and
solids of revolution.

The second theorem states that the volume V of a solid of revolution
generated by rotating a plane figure F about an external axis is equal
to the product of the area A of F and the distance d traveled by its
geometric centroid.

.. math::

   V = A d

For more details, see Wikipedia_ (which is also the source for the two
paragraphs above).

.. _Wikipedia: http://en.wikipedia.org/wiki/Pappus's_centroid_theorem

Implementing Pappus's centroid theorem
======================================

According to the above definition, the required data to compute the
volume are:

- the area of the plane figure
- the distance of its centroid from the rotation axis

.. todo:: Insert picture here (Matplotlib screenshot is fine)

Both geometric operations are not trivial for non-standard polygons,
so we use the Shapely_ Python library to perform them. Shapely can be
easily integrated with Matplotlib_ to plot both the profile and the
geometric centroid.

.. _Shapely: http://trac.gispython.org/lab/wiki/Shapely
.. _Matplotlib: http://matplotlib.sourceforge.net/