ashp 1.5.0

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Performance
5. Interactive Dashboard
6. Roadmap
7. Contributing
8. License
9. Contact
10. Acknowledgments

About The Project

An alpha shape generalises the convex hull of a point cloud: as alpha increases, the hull is carved inward to follow the actual shape of the data — useful for concave hulls, boundary extraction, and footprint generation in 2-D and 3-D.

ashp is a maintained fork of Kenneth E. Bellock's excellent alphashape library. It keeps the original API while adding:

• A numba-accelerated circumradius core (JIT-compiled, disk-cached, parallel for large meshes) — see Performance.
• Modern uv packaging with the uv_build backend.
• An interactive Streamlit + Plotly dashboard for exploring alpha shapes.

It also works in 3-D, returning a surface mesh:

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

Prerequisites

• Python 3.13+
• uv (recommended) or pip

Installation

Add it to your project:

uv add ashp            # or: pip install ashp

Optional geopandas support:

uv add "ashp[geo]"

Or work on the project itself:

git clone https://github.com/arunoruto/ashp.git
cd ashp
uv sync                # project + test group
uv run pytest          # run the test suite

# Build the documentation (Sphinx + autoapi, with cited references):
uv run --group docs sphinx-build -b html docs/source docs/build/html

(back to top)

Usage

from ashp import alphashape, optimizealpha, select_alpha

points = [(0., 0.), (0., 1.), (1., 1.), (1., 0.),
          (0.5, 0.25), (0.5, 0.75), (0.25, 0.5), (0.75, 0.5)]

# Fixed alpha (larger = tighter / more concave; 0 = convex hull):
shape = alphashape(points, alpha=2.0)        # -> shapely geometry

# Pick alpha from the circumradius distribution — fast, outlier-robust, and the
# resulting shape stays stable as the point count changes. Works in 2-D and 3-D:
shape = alphashape(points, select_alpha(points, q=0.9))     # keep 90% of simplices
shape = alphashape(points, select_alpha(points, method="knee"))  # auto cutoff

# 'knee' finds the cutoff automatically at the knee of the sorted circumradius
# curve (the DBSCAN-eps heuristic): it drops the long edges that bridge gaps /
# holes and keeps the homogeneous local connections. alpha_knee() also returns
# the diagnostic curve.
shape = alphashape(points, select_alpha(points, method="band"))
# 'band' targets the centre of the usable alpha range — past the blob, before
# the shape fragments — and is the most point-count-stable of the selectors;
# alpha_sweep() / usable_band() expose the underlying curves and band.

# Or solve for the tightest alpha that keeps every point in one polygon.
# Note: this is a bottleneck statistic — sensitive to outliers and density:
best = optimizealpha(points)
shape = alphashape(points, best)

alphashape accepts 2-D points (returns a shapely Polygon / LineString / Point), 3-D points (returns a trimesh.Trimesh), a MultiPoint, or a geopandas.GeoDataFrame.

A small CLI is included too:

ashp input_points.geojson output_shape.geojson --alpha 2.0

(back to top)

Performance

Two hot paths were optimised relative to the original implementation:

• The per-simplex circumradius computation is JIT-compiled with numba and cached to disk, parallelising across cores for large meshes. If numba is not installed, it transparently falls back to numpy.
• The boundary reconstruction is fully vectorised for every dimension (numpy set logic for the perimeter facets in place of a per-simplex Python loop), plus bulk shapely geometry construction in 2-D instead of building shapely objects one edge at a time. Biggest effect in 2-D; 3-D/N-D get a smaller speed-up with byte-identical output.

Together these take a single 4000-point alphashape call from ~1031 ms (the original pure-Python / np.matrix implementation) to ~72 ms — roughly 14×, with bit-identical output. The first call in a fresh environment pays a one-time numba compilation cost before the cache is warm.

(back to top)

Interactive Dashboard

A Streamlit app (using Plotly) lives in apps/dashboard for exploring how alpha and the input distribution shape the result:

uv run --group dashboard streamlit run apps/dashboard/app.py

The gallery images above are produced by assets/generate_images.py (written to assets/img/):

uv run --group dashboard python assets/generate_images.py

(back to top)

Roadmap

• numba-accelerated circumradius core
• Interactive Streamlit + Plotly dashboard
• Documentation gallery image generator
• True 2-D holes (interior rings) in the reconstruction
• Interactive 3-D mesh viewer in the dashboard
• Published documentation site

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/amazing-feature)
3. Commit your Changes (git commit -m 'Add some amazing feature')
4. Push to the Branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please run uv run pytest before opening a PR.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information. Original work © Kenneth E. Bellock.

(back to top)

Contact

Mirza Arnaut - mirza.arnaut45@gmail.com

Project Link: https://github.com/arunoruto/ashp

(back to top)

Acknowledgments

• alphashape by Kenneth E. Bellock — the original project this fork is built on. All of the core alpha shape algorithm is his work; ashp only modernises packaging and accelerates the hot path.
• Edelsbrunner, Kirkpatrick & Seidel — On the shape of a set of points in the plane (1983)
• Best-README-Template
• Shields.io

(back to top)