Quantify 3D structures with 2 lines of code

HSC3D: A Python package to quantify three-dimensional habitat structural complexity

Package workflow

Setup environment

Install Anaconda or miniconda to your device. See more information at this link.

# choose your own virtual environment name
conda create -n hsc3d_test python=3.10 -y

conda activate hsc3d_test

Installation

pip install HSC3D

Usage

Basic usage (without volume metrics)

By default, volume metrics (convex hull and alpha shape) are disabled for faster initialization:

from HSC3D import HSC3D

# Initialize without volume metrics (default)
hsc3d = HSC3D("path/to/your/pointcloud.ply")

# Compute and plot all metrics
hsc3d.compute_all()
hsc3d.plot_all()

Including volume metrics

To compute convex hull and alpha shape volumes, use volume=True:

from HSC3D import HSC3D

# Initialize with volume metrics enabled
hsc3d = HSC3D("path/to/your/pointcloud.ply", volume=True)

# Compute and plot all metrics
hsc3d.compute_all()
hsc3d.plot_all()

Fine-grained control

You can selectively enable or disable specific volume metrics:

# Only compute convex hull (skip alpha shape)
hsc3d = HSC3D("path/to/your/pointcloud.ply", volume=True, compute_alpha_shape=False)

# Only compute alpha shape (skip convex hull)
hsc3d = HSC3D("path/to/your/pointcloud.ply", volume=True, compute_convex_hull=False)

For more examples, see sample_usage.ipynb.

Demo case study point cloud data

Citation

Please cite the following paper if you use HSC3D in your research:

Gu, Y.-F., Hu, J., Han, K., Lau, J. W. T., & Williams, G. A. (2024).
HSC3D: A Python package to quantify three-dimensional habitat structural complexity.
Methods in Ecology and Evolution, 15, 639–646.
https://doi.org/10.1111/2041-210X.14305

License

Creative Commons Attribution-NonCommercial License