Alpha Shapes

1.3.1 verified Thu May 14 auth: no python

Alpha Shape Toolbox is a Python library for generating n-dimensional alpha shapes, which are a generalization of convex hulls used to create bounding polygons around sets of points. It offers workflows to manually define the alpha parameter or optimize its value to best fit the data. As of version 1.3.1 (released April 16, 2021), the library supports 3D input data and GeoJSON output for its command-line interface. It is actively maintained with recent updates addressing Python version compatibility.

pip install alphashape

Common errors

error ModuleNotFoundError: No module named 'alphashape' ↓

cause The 'alphashape' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install alphashape'.

error ImportError: cannot import name 'alphashape' from 'alphashape' ↓

cause Attempting to import the 'alphashape' function incorrectly.

fix

Use the correct import statement: 'from alphashape import alphashape'.

error IndexError: too many indices for array: array is 0-dimensional, but 2 were indexed ↓

cause The 'alphashape' function returned an unexpected geometry type, leading to an indexing error.

fix

Ensure the input data is valid and check the 'alphashape' function's return type before indexing.

error TypeError: 'NoneType' object is not iterable ↓

cause The 'alphashape' function returned None, possibly due to an invalid alpha parameter.

fix

Verify that the alpha parameter is set correctly and that the input data is appropriate for the desired alpha shape.

error AttributeError: 'NoneType' object has no attribute 'intersection' ↓

cause This error often occurs when the `alphashape` function, with a given alpha parameter or point set, fails to generate a valid geometric output (e.g., if the alpha value is too small, points are collinear, or too few points are provided), returning `None` instead of a `shapely` geometry. Subsequent operations on this `None` object, such as trying to perform an intersection, then fail. It can also be caused by a missing spatial index dependency like `rtree` when performing spatial operations on `shapely` geometries.

fix

Ensure your input points and alpha parameter are appropriate for forming a valid alpha shape; test with different alpha values, especially larger ones, or use alphashape.optimizealpha to find a suitable value. Additionally, install rtree (pip install rtree) if you are performing further spatial operations with shapely or geopandas on the alphashape output. Always check if the result of alphashape() is None before attempting further geometric operations.

Warnings

gotcha Using the `optimizealpha` function with extremely small precision values can lead to very slow calculations and potential resource exhaustion. It's important to balance precision needs with computational cost. ↓

fix Adjust the `precision` parameter in `optimizealpha` to a reasonable value based on your dataset size and acceptable performance.

gotcha When plotting `alphashape` results with `descartes.PolygonPatch` (which depends on `shapely`), you might encounter `TypeError: 'MultiPoint' object is not iterable` or incorrect plots. This is often due to API changes in `shapely` where `t.exterior` should be `t.exterior.coords`. ↓

fix Manually edit the `descartes/patch.py` file (around line 62) in your environment, changing `t.exterior` to `t.exterior.coords` for PolygonPatch rendering. Alternatively, consider converting the `alphashape` output to a `geojson` or `matplotlib.path.Path` object for plotting without `descartes`.

gotcha Specifying too high an `alpha` parameter can result in an overly loose bounding shape that might exclude some of the original input points, leading to an inaccurate representation of the dataset's form. ↓

fix Carefully select the `alpha` parameter. Start with a small value and gradually increase it, visualizing the output at each step, until the desired shape is achieved without losing points. The library also provides an `optimizealpha` function to help determine a suitable value.

gotcha Users have reported `IndexError: too many indices for array: array is 1-dimensional, but 2 were indexed` indicating issues with array dimension handling, particularly when passing 1D arrays where 2D are expected. ↓

fix Ensure that input point data (e.g., NumPy arrays) passed to `alphashape.alphashape` explicitly matches the expected dimensionality (e.g., `(N, 2)` or `(N, 3)` for N points in 2D or 3D).

gotcha Capturing the interior of polygons with sharp angles (e.g., 90-degree edges) can be challenging, as the alpha shape might produce undesired gaps or fail to accurately represent these features, even after tuning the `alpha` parameter. ↓

fix This is an inherent characteristic of alpha shapes. For shapes with sharp corners, consider alternative hull algorithms or preprocess your data to smooth sharp features, or experiment extensively with `alpha` values. If precise polygonal reconstruction is critical for such shapes, other geometric libraries might be more suitable.

gotcha When processing large point clouds, `alphashape` can sometimes generate unexpected `MultiPolygon` results or geometries that deviate from the anticipated shape of the input data. ↓

fix Inspect the generated `alpha_shape` object for `MultiPolygon` types. If unexpected, iterate through the individual polygons or try to simplify the input point cloud before processing. Adjusting the `alpha` parameter more carefully for dense datasets may also help.

Install

conda install alphashape

Install compatibility last tested: 2026-05-14 v1.3.1 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 1.95s 269.9M 41.4M clean

3.10 alpine (musl) - - 2.00s 269.9M 41.4M -

3.10 slim (glibc) wheel 8.9s 1.55s 254M 41.4M clean

3.10 slim (glibc) - - 1.65s 254M 41.4M -

3.11 alpine (musl) wheel - 2.84s 291.2M 49.1M clean

3.11 alpine (musl) - - 3.25s 291.2M 49.1M -

3.11 slim (glibc) wheel 8.8s 2.60s 274M 49.1M clean

3.11 slim (glibc) - - 2.68s 274M 49.1M -

3.12 alpine (musl) wheel - 2.54s 275.9M 47.5M clean

3.12 alpine (musl) - - 2.95s 275.9M 47.5M -

3.12 slim (glibc) wheel 9.0s 2.72s 258M 47.5M clean

3.12 slim (glibc) - - 3.10s 258M 47.5M -

3.13 alpine (musl) wheel - 2.39s 274.5M 48.2M clean

3.13 alpine (musl) - - 2.73s 274.4M 48.2M -

3.13 slim (glibc) wheel 9.1s 2.37s 257M 48.2M clean

3.13 slim (glibc) - - 2.90s 257M 48.2M -

3.9 alpine (musl) build_error - - - - - -

3.9 alpine (musl) - - - - - -

3.9 slim (glibc) wheel 10.0s 1.46s 259M 37.2M clean

3.9 slim (glibc) - - 1.58s 259M 37.2M -

Imports

alphashape
```
from alphashape import alphashape
```

Quickstart

This example demonstrates how to generate a 2D alpha shape from a set of points and visualize it using Matplotlib and Descartes. The `alpha` parameter controls the 'tightness' of the shape; a value of 0.0 will typically yield the convex hull.

import alphashape
import matplotlib.pyplot as plt
from descartes import PolygonPatch

# Define input points (2D example)
points = [(0., 0.), (0., 1.), (1., 1.), (1., 0.), (0.5, 0.5)]

# Define alpha parameter (0.0 often gives the convex hull)
alpha = 0.5

# Generate the alpha shape
alpha_shape = alphashape.alphashape(points, alpha)

# Initialize plot (requires matplotlib and descartes)
fig, ax = plt.subplots()

# Plot input points
ax.scatter(*zip(*points))

# Plot alpha shape
# Note: If plotting issues occur, a common fix for descartes/shapely incompatibility
# is to edit `descartes/patch.py` line 62 from `t.exterior` to `t.exterior.coords`.
ax.add_patch(PolygonPatch(alpha_shape, alpha=0.2, fc='blue', ec='black'))
ax.set_title(f'Alpha Shape (alpha={alpha})')
plt.xlabel('X-coordinate')
plt.ylabel('Y-coordinate')
plt.show()