DOC: Convex Hull areas are actually perimeters for 2-dimensional input

[ljwolf]

In scipy.spatial.ConvexHull, convex hulls expose an area and volume attribute. These are built on top of QHull. A user who computes a convex hull on 2-dimensional data will be surprised to find QHull's definitions of volume and area are dimension-dependent.

In 2-d, the convex hull is a polygon. Its surface is the edges of a polygon. So in 2-d, the 'area' is the length of the polygon's edges, while the 'volume' is the area of the polygon. (source)

So, convex_hull.area returns the perimeter of a shape in 2-d and the area of the shape in 3-d. In order for you to get the area of a 2-d convex hull, you need to use convex_hull.volume.

I would think it's appropriate to force volume to zero and area to Qhull's volume so that area has a consistent meaning across 2d and 3d+ for other packages (like shapely). Otherwise, we should modify the docstrings to read:

area : float
    Surface area of the convex hull when input dimension > 2. 
    When input is 2-dimensional, this is the perimeter of the convex hull. 

    .. versionadded:: 0.17.0
volume : float
    Volume of the convex hull when input dimension > 2. 
    When input is 2-dimensional, this is the area of the convex hull

    .. versionadded:: 0.17.0

Let me know what's preferred & I can submit a fix.

Reproducing code example:

import numpy
from scipy import spatial
import geopandas # for expected behavior

triangle = numpy.array([[0,0],[0,1],[1,0]])
square = numpy.array([[0,0], 
                           [0,1], 
                           [1,1,], 
                           [1,0]])
triangle_df = geopandas.GeoDataFrame(geometry=geopandas.points_from_xy(*triangle.T))

triangle_chull = spatial.ConvexHull(triangle)
triangle_chull_shapely = triangle_df.unary_union.convex_hull

triangle_chull.points[triangle_chull.vertices] # looks correct

assert triangle_chull_shapely.area == .5 * 1 * 1 # passes
assert triangle_chull.area == .5 * 1 * 1 # fails

Scipy/Numpy/Python version information:

I'm on scipy 1.4.1, numpy 1.18.1, and Python 3.8.2

[sjsrey]

I think going for the consistent defn across dimensions is the way to go.

[pmla]

These are generalized surface areas and volumes, sometimes called "n-dimensional areas" and "n-dimensional volumes". This could be made clearer in the docstring. The description you provided from the QHull FAQ is very clear.

[tylerjereddy]

+1 to making the documentation clearer rather than changing behavior, which could also break a fair bit of user code.

[ljwolf]

Sure, sounds good. Submitted in #12296. Thanks!

[tylerjereddy]

Fixed by the cross-linked merged PR, closing, thanks.