/ Skeleton Refinement

The documentation of the Plant Imager project can be found here: https://docs.romi-project.eu/plant_imager/

The API documentation of the skeleton_refinement library can be found here: https://romi.github.io/skeleton_refinement/

About

This library is intended to provide the implementation of a skeleton refinement method published here:

Chaudhury A. and Godin C. (2020) Skeletonization of Plant Point Cloud Data Using Stochastic Optimization Framework. Front. Plant Sci. 11:773. DOI: 10.3389/fpls.2020.00773.

This is a part of the implementation of the stochastic registration algorithm based on the following paper: Myronenko A. and Song X. (2010) Point set registration: Coherent Point drift. IEEE Transactions on Pattern Analysis and Machine Intelligence. 32 (2): 2262-2275. DOI: 10.1109/TPAMI.2010.46. arXiv PDF.

The library is based on the Python implementation of the paper in pycpd package. GitHub sources. PyPi package.

Installation

We strongly advise creating isolated environments to install the ROMI libraries.

We often use conda as an environment and Python package manager. If you do not yet have miniconda3 installed on your system, have a look here.

The skeleton_refinement package is available from the romi-eu channel.

Existing conda environment

To install the skeleton_refinement conda package in an existing environment, first activate it, then proceed as follows:

conda install skeleton_refinement -c romi-eu

New conda environment

To install the skeleton_refinement conda package in a new environment, here named romi, proceed as follows:

conda create -n romi skeleton_refinement -c romi-eu

Installation from sources

To install this library, clone the repo and use pip to install it and the required dependencies. Again, we strongly advise creating a conda environment.

All this can be done as follows:

git clone https://github.com/romi/skeleton_refinement.git
cd skeleton_refinement
conda create -n skeleton_refinement 'python =3.10' ipython
conda activate skeleton_refinement  # do not forget to activate your environment!
python -m pip install -e .  # install the sources

Note that the -e option is to install the skeleton_refinement sources in "developer mode". That is, if you make changes to the source code of skeleton_refinement you will not have to pip install it again.

Usage

Example dataset

First, we download an example dataset from Zenodo, named real_plant_analyzed, to play with:

wget https://zenodo.org/records/10379172/files/real_plant_analyzed.zip
unzip real_plant_analyzed.zip -d /tmp

It contains:

• a plant point cloud under PointCloud_1_0_1_0_10_0_7ee836e5a9/PointCloud.ply
• a plant skeleton under CurveSkeleton__TriangleMesh_0393cb5708/CurveSkeleton.json
• a plant tree graph under TreeGraph__False_CurveSkeleton_c304a2cc71/TreeGraph.p

CLI

You may use the refine_skeleton CLI to refine a given skeleton using the original point cloud:

export DATA_PATH="/tmp/real_plant_analyzed"
refine_skeleton \
  ${DATA_PATH}/PointCloud_1_0_1_0_10_0_7ee836e5a9/PointCloud.ply \
  ${DATA_PATH}/CurveSkeleton__TriangleMesh_0393cb5708/CurveSkeleton.json \
  ${DATA_PATH}/optimized_skeleton.txt

Python API

Here is a minimal example of how to use the skeleton_refinement library in Python:

from skeleton_refinement.stochastic_registration import perform_registration
from skeleton_refinement.io import load_json, load_ply

pcd = load_ply("/tmp/real_plant_analyzed/PointCloud_1_0_1_0_10_0_7ee836e5a9/PointCloud.ply")
skel = load_json("/tmp/real_plant_analyzed/CurveSkeleton__TriangleMesh_0393cb5708/CurveSkeleton.json", "points")
# Perform stochastic optimization
refined_skel = perform_registration(pcd, skel)

import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(projection='3d')
ax.scatter(*pcd.T, marker='.', color='black')
ax.scatter(*skel.T, marker='o', color='r')
ax.scatter(*refined_skel.T, marker='o', color='b')
ax.set_aspect('equal')
plt.show()

Detailed documentation of the Python API is available here: https://romi.github.io/skeleton_refinement/reference.html

Git LFS & package data

Large binary assets (e.g., point‑cloud files) are stored with Git Large File Storage (LFS). To make sure you have the required data locally, follow the steps below.

1. Install Git LFS (once per machine)

# macOS (Homebrew)
brew install git-lfs

# Ubuntu/Debian
sudo apt-get install git-lfs

# Windows (Chocolatey)
choco install git-lfs

After installation, run the global initializer:

git lfs install

(You only need to run git lfs install the first time you use LFS on a machine.)

2. Pull (or refresh) LFS data after cloning or after a git pull

If you already have the repository cloned and want to make sure all LFS objects are present:

git lfs pull            # Downloads only the missing LFS objects
# or, to fetch *all* LFS blobs for every branch/tag:
git lfs fetch --all
git lfs checkout        # Replace pointers with real files

3. Verify that large files are present

git lfs ls-files

You should see a list of tracked files with their SHA‑256 hashes, confirming that the real content is on disk.

Developers & contributors

Adding new large files

If you add a new large file, LFS should handle that. Let's assume you want to add a PLY point-cloud:

git lfs track "*.ply"   # Example for point‑cloud files
git commit -m "Add a new large point‑cloud file via Git LFS"
git push

Git LFS will automatically upload the file to the LFS storage associated with the repository.

Unitary tests

Some tests are defined in the tests directory. We use nose2 to call them as follows:

nose2 -v -C

Conda packaging

The repository provides a conda_build GitHub Actions workflow (.github/workflows/conda.yml).
It runs automatically when a new release is published or can be triggered manually from the Actions tab.

Build a conda package locally

Start by installing the required conda-build & anaconda-client conda packages in the base environment as follows:

conda install -n base conda-build anaconda-client

To build the skeleton_refinement conda package locally, from the root directory of the repository and the base conda environment, run:

conda build conda/recipe/ -c conda-forge --user romi-eu

If you need to inspect the rendered recipe before building, you can render it with:

conda render conda/recipe/

The official documentation for conda-render can be found here.

Upload a conda package

To upload the built package, you need a valid account (here romi-eu) on anaconda.org & to log ONCE with anaconda login, then:

anaconda upload ~/miniconda3/conda-bld/linux-64/skeleton_refinement*.tar.bz2 --user romi-eu

Clean builds

To clean the source and build intermediates:

conda build purge

To clean ALL the built packages & build environments:

conda build purge-all

PyPi packaging

The repository includes a GitHub Actions workflow (.github/workflows/pip_build.yml) that builds the package and publishes it to PyPI automatically on each release.

Build the distribution

The GitHub Actions workflow builds the package using python -m build, generating both source (sdist) and wheel (bdist_wheel) archives in the dist/ folder.

You can run the same command locally:

python -m build

Publish to PyPI

For releases, the workflow uses the trusted publishing action pypa/gh-action-pypi-publish to upload the artifacts from dist/ to PyPI.

If you need to publish manually, you can use twine:

twine upload dist/*

Note: Ensure that the pypi environment in your GitHub repository is configured with a valid PyPI API token (or use the built‑in trusted publishing mechanism).