Learning Generative Models of the Geometry and Topology of Tree-like 3D Objects

This is an example code for the paper "Learning Generative Models of the Geometry and Topology of Tree-like 3D Objects" by Guan Wang, Hamid Laga, and Anuj Srivastava.

In this paper, we develop a novel mathematical framework for representing, comparing, and computing geodesic deformations between the shapes of tree-like 3D objects, such as neuronal and botanical trees. Details could be found in our project website.

How to use the code

• compile DynamicProgrammingQ.c using mex command in matlab: mex DynamicProgrammingQ.c

• run eg1_geodesic_botanTrees.m to compute the geodesic between a pair of botancial trees

• run eg1_mean_botanTrees.m to compute the mean shape for a group of botancial trees

• run eg1_modesAndSamples_botanTrees.m to compute the principal variance mode and random samples for a group of botancial trees

• The same operations apply to neuronal trees. Run files named as eg2_xxxx.m

Python distance and visualization utilities

• Install Python deps from python_distance/requirements.txt.
• Compute distance for sample pairs:
  • python -m python_distance.examples.eg2_distance_neuron
• Run MATLAB-vs-Python parity check and report absolute/relative error:
  • python -m python_distance.examples.compare_neuron_with_matlab
  • If MATLAB is not on PATH, pass a known MATLAB value manually:
    • python -m python_distance.examples.compare_neuron_with_matlab --matlab-energy <value>
• Generate MATLAB baseline JSON for neuron parity tests:
  • python -m python_distance.examples.generate_neuron_matlab_baseline

Visualization CLIs:

• Single tree:
  • python -m python_distance.examples.visualize_single_tree --domain neuron --index 22 --save /tmp/tree.png --no-show
• Pair with distance:
  • python -m python_distance.examples.visualize_distance_pair --domain botan --file1 Acer_saccharum_y1.txtskl --file2 Eucalyptus_yilgarnensis_4.txtskl --save /tmp/pair.png --no-show
• Geodesic-style sequence with bbox diagnostics:
  • python -m python_distance.examples.visualize_geodesic_sequence --domain neuron --idx1 27 --idx2 25 --steps 7 --save /tmp/geod.png --no-show

Folder statistics CLI:

• Summarize a folder of trees (count, geometry, branching, wire length, density, etc.):
  • python -m python_distance.examples.summarize_tree_folder_stats --domain neuron --output-json /tmp/neuron_stats.json

The 3D model rendering part is adapted from this MatlabRenderToolbox by Jing Ren.

Comments

• This work is an extension and generalization of Duncan's work, which focused on simple 2D tree-shaped objects.

• A key component of this work is Square Root Velocity Functions (SRVF), which is used to carry out elastic analysis of curves. The description and relevant codes on SRVF could be found at this website.

Other related publications

• ‪Statistical shape analysis of simplified neuronal trees‬ by Adam Duncan, Eric Klassen, Anuj Srivastava

• Statistical analysis and modeling of the geometry and topology of plant roots by Guan Wang, Hamid Laga, Jinyuan Jia, Stanley J. Miklavcic, Anuj Srivastava

License

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. For any commercial uses or derivatives, please contact us (wangguan12621@gmail.com, H.Laga@murdoch.edu.au, anuj@stat.fsu.edu).

Citation

If you use the code, please make sure you cite:

@article{wang2023statistical,
  title={Learning Generative Models of the Geometry and Topology of Tree-like 3D Objects},
  author={Wang, Guan and Laga, Hamid and Srivastava, Anuj},
  journal={arXiv preprint arXiv:2110.08693},
  year={2023}
}