Install & Compatibility
Where this runs
tested against v1.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 9.9s
268MB installed
● package 268MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
alphashape
✓ from alphashape import alphashape
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()
alphashape --version
Debug
Known issues
gotchaUsing 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.fixAdjust the `precision` parameter in `optimizealpha` to a reasonable value based on your dataset size and acceptable performance.
affects: All versions
gotchaWhen 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`.fixManually 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`.
affects: Versions relying on older `descartes` with newer `shapely`
gotchaSpecifying 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.fixCarefully 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.
affects: All versions
gotchaUsers 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.fixEnsure 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).
affects: All versions
gotchaCapturing 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.fixThis 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.
affects: All versions
gotchaWhen processing large point clouds, `alphashape` can sometimes generate unexpected `MultiPolygon` results or geometries that deviate from the anticipated shape of the input data.fixInspect 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'alphashape'
The 'alphashape' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install alphashape'.
ImportError: cannot import name 'alphashape' from 'alphashape'
Attempting to import the 'alphashape' function incorrectly.
fixUse the correct import statement: 'from alphashape import alphashape'.
IndexError: too many indices for array: array is 0-dimensional, but 2 were indexed
The 'alphashape' function returned an unexpected geometry type, leading to an indexing error.
fixEnsure the input data is valid and check the 'alphashape' function's return type before indexing.
TypeError: 'NoneType' object is not iterable
The 'alphashape' function returned None, possibly due to an invalid alpha parameter.
fixVerify that the alpha parameter is set correctly and that the input data is appropriate for the desired alpha shape.
AttributeError: 'NoneType' object has no attribute 'intersection'
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.
fixEnsure 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.
Upgrade
Version history
1.3.1latest on PyPI · released Apr 16, 2021
Audit
Dependencies
ClickrequiredCommand-line interface.
click_logrequiredLogging for CLI.
shapelyrequiredGeometric objects manipulation.
numpyrequiredNumerical operations.
trimeshrequired3D mesh processing.
networkxrequiredGraph structures for geometric algorithms.
rtreerequiredSpatial indexing for efficient queries.
scipyrequiredScientific computing utilities.
matplotliboptionalFor plotting and visualization in examples.
descartesoptionalFor plotting Shapely geometries with Matplotlib in examples.