{"id":27248318,"url":"https://github.com/zhiyliu/shanapy","last_synced_at":"2025-04-10T23:08:29.280Z","repository":{"id":156757828,"uuid":"429493357","full_name":"ZhiyLiu/shanapy","owner":"ZhiyLiu","description":"Anatomical shape analysis with skeletal representations (s-reps)","archived":false,"fork":false,"pushed_at":"2024-04-14T06:16:28.000Z","size":2706,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T23:08:20.844Z","etag":null,"topics":["geometry-model","non-euclidean-statistics","shape-analysis","skeletal-representation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZhiyLiu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-11-18T16:03:45.000Z","updated_at":"2023-06-19T14:24:11.000Z","dependencies_parsed_at":"2024-04-19T09:00:45.716Z","dependency_job_id":null,"html_url":"https://github.com/ZhiyLiu/shanapy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhiyLiu%2Fshanapy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhiyLiu%2Fshanapy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhiyLiu%2Fshanapy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhiyLiu%2Fshanapy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZhiyLiu","download_url":"https://codeload.github.com/ZhiyLiu/shanapy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312137,"owners_count":21082638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geometry-model","non-euclidean-statistics","shape-analysis","skeletal-representation"],"created_at":"2025-04-10T23:08:27.764Z","updated_at":"2025-04-10T23:08:29.267Z","avatar_url":"https://github.com/ZhiyLiu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"SHANAPY: SHape ANAlysis PYthon package using s-reps\n===\nThis repository is the codebase of the following articles:\n\u003e Liu, Z., Hong, J., Vicory, J., Damon, J.N. and Pizer, S.M., 2021. Fitting unbranching skeletal structures to objects. Medical image analysis, 70, p.102020.\n\n\u003e Liu, Z., Schulz, J., Taheri, M., Styner, M., Damon, J., Pizer, S. and Marron, J.S., 2022. Analysis of joint shape variation from multi-object complexes. Journal of Mathematical Imaging and Vision, pp.1-21.\n\n\u003e Liu, Z., Damon, J., Marron, J.S., and Pizer, S., 2023. Geometric and Statistical Models for Analysis of Two-Object Complexes. International Journal of Computer Vision. https://doi.org/10.1007/s11263-023-01800-2\n\n## Table of Contents\n\n1. [Introduction: what is an s-rep \u0026 why is it useful?](#intro)\n2. [Installation](#use)\n3. [Examples](#example)\n- [Initialize an s-rep](#initialize)\n- [Refine an s-rep](#refinement)\n- [Interpolate an s-rep for denser spokes](#interpolate)\n- [Fit Principal Nested Spheres (PNS) to non-Euclidean data](#pns)\n\n\u003ca name=\"intro\"\u003e\u003c/a\u003e\n\n## Introduction\n\n### What are s-reps?\n\nAn s-rep is a skeletal representation of an object. In the continuous regime, an s-rep consists of a skeleton and a radial vector field defined (based) on the skeleton.\nThough a continuous s-rep is desirable in some situations (e.g., refinement), a discrete s-rep is favorable in statistical analysis because of good correspondences across a population.\nA discrete s-rep (also referred to an s-rep in some places) consists of skeletal points, and spokes that connect the skeletal points and boundary points.\nThe skeletal points form quadrilaterals on the skeleton. A continuous skeleton is thus approximated by the combination of these quadrilaterals.\n\nThis package provides an algorithm to obtain a discrete s-rep that best fit to a 3D object.\nOften, the object of interest has a close and smooth boundary with no holes.\nThe discretized skeletal sheet sits in the near-medial place of the object. These skeletal points are sampled in a consistent way to provide good correspondences.\nAt these skeletal points, spokes are correspondingly sampled from the radial vector field. These spokes define the mapping from the skeletal geometry to the boundary geometry.\nA reader can refer to chapter 3 in the book\n\u003e K. Siddiqi and S. Pizer, Medial representations: mathematics, algorithms and applications, 2008\nfor more details about the relation between the skeletal and boundary geometry.\n\nA formal definition of an s-rep and the discretization of an s-rep can be found in the paper\n\u003e Z. Liu et al., Fitting unbranching skeletal structures to objects, Medical Image Analysis, 2021\n\n### Anatomical shape analysis with s-reps\n\nAnatomical shapes are typically obtained from segmentation of medical images. It is often problematic to use boundary geometry in analyzing a population of anatomical shapes for the following reasons.\nFirst, the boundary is often noisy, sometimes correupted (see the figure (a) below). These noise and corruptions unexpectedly draw too much attention in statistical analysis.\nTherefore, the results from analyzing boundaries can be biased and difficult to generalize to new shapes.\nSecond, it is difficult to establish good correspondences on 3D objects. There exist methods (e.g., SPHARM-PDM) producing mathematical landmarks of an object.\nHowever, the correspondences of these landmarks across a population can be not anatomically reasonable (see the figure (b) below).\n![Problems with boundary geometry](figures/problems_in_boundary_geometry.png)\n\nIn contrast, s-reps take the interior geometry of an object into consideration, making the geometric features more robust.\nThe skeleton shape and the differential properties of spokes allow us to reconstruct the boundary geometry from the skeletal geometry.\nThis reconstructed boundary is also referred to as the `implied boundary` or `onion skin` (see the figure below).\n![3D onion skins](figures/onion_skins_3d.png)\n\nS-reps provide rich anatomical shape features. A user can select appropriate features according to the data and tasks.\nThe features provided by s-reps include:\n\n(1) Geometric features of implied boundaries. S-reps can produce corruption-free smooth boundary mesh. Moreover, the implied boundary points have good correspondences across a population.\n\n(2) Radial geometry from spokes. A spoke is represented by a tuple containing (a) coordinates of the base (skeletal) point (b) a unit direction vector in $\\mathbb{R}^3$ and\n(c) a positive scalar value that indicates the spoke's length.\n\nThe workflow of using s-reps can be summarized in the following chart.\n![Flowchart](figures/srep_fitting_workflow.png)\n\nPlease cite and refer to the following papers for more details.\n\n\u003e Z. Liu et al., Non-Euclidean Analysis of Joint Variations in Multi-Object Shapes, 2021\n\n\u003e S. Pizer et al. Skeletons, Object Shape, Statistics, Frontiers in Computer Science, section Computer Vision, 2022\n\n---\n\u003ca name=\"use\"\u003e\u003c/a\u003e\n## Installation\n1. (Optional) Download [SPHARM-PDM](https://www.nitrc.org/projects/spharm-pdm) according to your platform into `third_party/spharm_bin`.\n2. Install shanapy module as follows\n```bash=\n## clone the source code\n$ cd ~\n$ git clone https://github.com/ZhiyLiu/shanapy.git\n$ cd shanapy\n\n## create \u0026 activate a virtual envirionment\n## assume the anaconda has been installed\n$ conda create -n shanapy python=3.7 anaconda\n$ source activate shanapy\n\n## install required packages (optional)\n## $ python -m pip install -r requirements.txt\n\n## install pyshanalysis\n$ python -m pip install -e .\n```\n\n---\n\n\u003ca name=\"example\"\u003e\u003c/a\u003e\n## Example\n\u003ca name=\"initialize\"\u003e\u003c/a\u003e\n### 1. Initialize and visualize a discrete s-rep for a hippocampus\n\nThe example data (a hippocampus) is provided [here](data/example_hippocampus.vtk). The example code is in [this file](shanapy/test/test_initializer.py). To run the example,\n```bash=\n## The required additional packages can be installed via pip.\n## make sure the current directory is ~/shanapy/\n$ pwd\n$ python shanapy/test/test_initializer.py\n```\nThe above commands result in a fitted s-rep the example hippocampus. Also, a visualization window should show as follows.\n![InitResult](figures/test_initializer_result.png)\n\nThe transparent surface is the boundary of the hippocampus. The white line segments are discrete spokes connecting the skeleton and the boundary.\n\n---\n\u003ca name=\"refinement\"\u003e\u003c/a\u003e\n### 2. Refine the above s-rep\n\nThe example code for the refinement is in [this file](shanapy/test/test_refiner.py). To run the example,\n```bash=\n## The required additional packages can be installed via pip.\n## make sure the current directory is ~/shanapy/\n$ pwd\n$ python shanapy/test/test_refiner.py\n```\nThe refinement yields a better fit s-rep, as shown below.\n![RefineResult](figures/refined_srep.png)\n\nThe orange line segments are from the above initial s-rep. The blue curve is the fold curve.\nThe black arrow points to a spoke that was initially longer than expected but was refined due to the refinement algorithm.\n\n---\n### \u003ca name=\"interpolate\"\u003e\u003c/a\u003e 3. Interpolate an s-rep for denser spokes\n\nThe interpolation can convert a discrete s-rep to a continuous one, based on which the implied level surfaces of radial distances can be generated. This algorithm takes in a discrete s-rep from the initialization or the refinement stage. The algorithm interpolates\n- skeletal points\n- spokes' directions\n- spokes' lengths.\n\nThe example code can be found in [this file](shanapy/test/test_interpolater.py). Run the code similar to the above example. The following figure shows the interpolated spokes on one side of a hippocampal s-rep.\n![Interpolate](figures/interpolate.png)\n\n---\n### \u003ca name=\"pns\"\u003e\u003c/a\u003e 4. Fit PNS model\n\n[PNS](https://github.com/sungkyujung/PNS) captures principal components of data distributed on a unit hypersphere. The PNS scores are taken as Euclidean representations of non-Euclidean data, which has shown notable statistical advantages (see `Pizer et al. Object Shape Representation via Skeletal Models (s-reps) and Statistical Analysis, 2019`).\n\nThe example code in [test_pns.py](shanapy/test/test_pns.py) demonstrates Euclideanizing spherical [data](https://github.com/ZhiyLiu/shanapy/raw/main/data/toy_example_small_circle.mat) (on $\\mathbb{S}^2$) via PNS and then comparing PNS components with PCA components. The [comparison](https://github.com/ZhiyLiu/shanapy/blob/main/figures/cmp_pns_pca.png) shows that PNS components are more statistically efficient. To reproduce the comparison,\n\n```bash=\n## The required additional packages can be installed via pip.\n## make sure the current directory is ~/shanapy/\n$ pwd\n$ python shanapy/test/test_pns.py\n```\n---\n## Acknowledgement\n\nThis project is adviced by Stephen M. Pizer, J. S. Marron and James N. Damon.\nJ. Hong initiates this project. J. Vicory and B. Paniagua significantly contributed to this project.\nThanks to M. Styner for providing insightful comments and experimental data.\nSpecial thanks to my great colleagues A. Krishna, M. Taheri, N. Tapp-Hughes, A. Sharma and J. Schulz for their feedback and contributions.\n\n###### tags: `Simulation` `Shape models` `Shape analysis`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhiyliu%2Fshanapy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhiyliu%2Fshanapy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhiyliu%2Fshanapy/lists"}