{"id":26786778,"url":"https://github.com/marrlab/shapr_torch","last_synced_at":"2025-07-11T01:08:38.815Z","repository":{"id":40779371,"uuid":"465677779","full_name":"marrlab/SHAPR_torch","owner":"marrlab","description":"SHAPR: Code for \"Capturing Shape Information with Multi-Scale Topological Loss Terms for 3D Reconstruction\"","archived":false,"fork":false,"pushed_at":"2023-10-28T08:59:40.000Z","size":11684,"stargazers_count":39,"open_issues_count":0,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-28T03:06:11.698Z","etag":null,"topics":["cubical-complexes","deep-learning","image-reconstruction","persistent-homology","pytorch","segmentation","topological-data-analysis","topological-machine-learning"],"latest_commit_sha":null,"homepage":"https://shapr.topology.rocks","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marrlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-03T10:46:33.000Z","updated_at":"2025-04-29T13:17:03.000Z","dependencies_parsed_at":"2023-01-21T18:46:56.534Z","dependency_job_id":"09732b43-a6c4-4814-9e21-bfb1cd251c17","html_url":"https://github.com/marrlab/SHAPR_torch","commit_stats":{"total_commits":233,"total_committers":4,"mean_commits":58.25,"dds":"0.32188841201716734","last_synced_commit":"dc9126c4b75c95a00eb2daf9b769b3b5b7892bc3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marrlab/SHAPR_torch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSHAPR_torch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSHAPR_torch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSHAPR_torch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSHAPR_torch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marrlab","download_url":"https://codeload.github.com/marrlab/SHAPR_torch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSHAPR_torch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264703072,"owners_count":23651891,"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":["cubical-complexes","deep-learning","image-reconstruction","persistent-homology","pytorch","segmentation","topological-data-analysis","topological-machine-learning"],"created_at":"2025-03-29T12:16:53.873Z","updated_at":"2025-07-11T01:08:37.216Z","avatar_url":"https://github.com/marrlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHAPR\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"figures/SHAPR_logo.png\"  width=\"200\" /\u003e\n\u003c/p\u003e\n\n\nFor a short video introducing our topological loss function and SHAPR please see:\n\n\u003ca href=\"https://www.youtube.com/watch?v=pCfRuTtyt1w\"\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg href=\"InstantDL\" src=\"figures/youtube.png\"\nwidth=\"500\" align=\"center\"\u003e\n\u003c/p\u003e\n\u003ca\u003e\n\n## Citation\n\nIf you use this code, please consider citing our paper:\n\n```bibtex\n@inproceedings{Waibel22a,\n  author        = {Dominik J. E. Waibel and Scott Atwell and Matthias Meier and Carsten Marr and Bastian Rieck},\n  title         = {Capturing Shape Information with Multi-Scale Topological Loss Terms for 3D Reconstruction},\n  year          = {2022},\n  booktitle     = {Medical Image Computing and Computer Assisted Intervention~(MICCAI)},\n  archiveprefix = {arXiv},\n  eprint        = {2203.01703},\n  primaryclass  = {cs.CV},\n  repository    = {https://github.com/marrlab/SHAPR_torch},\n  pubstate      = {inpress},\n}\n```\n\n## Introduction\n\nReconstructing the shapes of three dimensional (3D) objects from two\ndimensional (2D) images is a task our brain constantly and unnoticeably\nperforms. Recently neural networks have been proposed to solve the same\ntask and trained to reconstruct the 3D shape of natural objects from 2D\nphotographs. An application to biomedical imaging, where the trade-off\nbetween resolution and throughput is key, is missing so far.\n\nHere, we show that deep learning can be used to predict the 3D shape of\nsingle cells and single nuclei from 2D images and thereby reconstruct\nrelevant morphological information. Our SHAPR autoencoder is trained\nwith hundreds of 3D shapes and corresponding 2D sections of red blood\ncells and differentiated induced pluripotent stem cells, and fine tuned\nwith an adversarial network inspired discriminator. We demonstrate the\npower of our approach by showing that the 3D shapes of red blood cells\ncan be reconstructed more realistically than with simpler 3D models.\nMoreover, the features extracted from the predicted 3D shapes lead to\na higher classification accuracy for six red blood cell types than the\nfeatures of the 2D image alone. Applied to human induced pluripotent\nstem cells growing in a 3D culture, we demonstrate that SHAPR is able to\nrobustly reconstruct the shape of single nuclei from a 2D slice,\nmimicking a single imaging step. Our work demonstrates that neural\nnetworks can learn to reconstruct the 3D shape of single cells and\nnuclei from 2D images. SHAPR is available as an easily installable, well\ndocumented python package. Its application allows dramatically\nincreasing throughput for the characterization of cellular and\nsubcellular structures in biomedical imaging data.\n\nFor more information, please refer to our preprint on bioRxiv \n[here](https://www.biorxiv.org/content/10.1101/2021.09.29.462353v1).\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"figures/SHAPR_architecture.png\"  width=\"400\" /\u003e\n\u003c/p\u003e\n\nSHAPR consists of a 2D encoder, which embeds 2D images into a\nlatent space, and a 3D decoder, which reconstructs 3D shapes from the latent space representation.\nTo train SHAPR we segment 3D microscopy images (we show an exemplary single red blood cell).\nWe pair a 2D segmentation with the microscopy image of the same slice to enter the encoder as input.\nDuring supervised training (Fig. 1, step 1), we minimize the reconstruction loss (see Methods),\nwhich is the sum of the Dice loss and the binary cross entropy loss between the 3D segmentations and SHAPR predictions.\nFor an input image of 64 x 64 pixels, we provide the pixel sizes for\neach layer in the gray boxes and the filter sizes on top of each box. In\nthe second step, we fine-tune SHAPR by adding a discriminator. The\ndiscriminator is trained to differentiate between SHAPR output and\nground truth segmentation and minimize the adversarial loss. It thereby\nchallenges SHAPR to output realistic 3D objects.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"figures/SHAPR_topology.png\"  width=\"400\" /\u003e\n\u003c/p\u003e\n\nGiven a predicted object and a 3D ground truth object, we calculate\ntopological features using (cubical) persistent homology, obtaining\na set of persistence diagrams. Each point in a persistence diagram\ndenotes the birth and death of a topological feature of some dimension of\nthe given object. We compare these diagrams using $\\mathcal{L}_T$, our\ntopology-based loss, and weight this with existing loss terms like binary\ncross entropy (BCE) and Dice.\n\n## Installation\n\nFork the repository.\n\n```console\n$ cd SHAPR_torch\n$ pip3 install -e .\n```\n\n### Installation using a virtual environment\n\nWe would recommend to first set a virtual environment and then install the package:\n\n```console\n$ cd SHAPR\n$ python3 -m venv .venv_shapr\n$ source .venv_shapr/bin/activate\n(.venv_shapr) $ pip3 install -e .\n```\n\nBy activating the virtual environment your shell’s prompt will be changed in order to show what virtual environment you’re using.\n\nYou can deactivate a virtual environment by:\n\n```console\n(.venv_shapr) $ deactivate\n```\n\nWe can also use the virtual environment as a kernel for Jupyter\nNotebook. First you should install `ipykernel` package when the virtual\nenvironment is **activated**:\n\n```console\n(.venv_shapr) $ pip3 install ipykernel\n```\n\nWe need to manually add our virtual environment as a kernel to Jupyter Notebook:\n\n```console\n(.venv_shapr) $ python -m ipykernel install --name=.venv_shapr\n```\n\nNow by opening the Jupyter-Notebook you have the option to select the `.venv_shapr` as the kernel.\n\n## Running SHAPR\n\nPlease find an example of how to run SHAPR from a jupyter notebook in\n`SHAPR_torch/docs/jupyter notebook/Run SHAPR from notebook.ipynb`.\n\nYou can also run SHAPR using a params.json file, which is provided in `SHAPR_torch/docs/sample/params.json`.\n\n### Setting parameters\n\nTo run SHAPR you should set the following parameters:\nSetting parameters are:\n- `path`: path to a folder that includes three subfolder of\n    1. `obj`: containing the 3D groundtruth segmentations, \n    2. `mask`: containing the 2D masks, \n    3. `image`: containing the images from which the 2D masks were segmented (e.g. brightfield).\n- `result_path`: path to a folder for saving the results of predictions.\n- `pretrained_weights_path`: path to a folder for saving and reloading pretrain model \n- `random_seed`: seed for random generator in order to keep the results reproducible.\n\nThe setting parameters are read from the `settings` object. You may\nchange the setting parameters by directly changing their default values\nin a `SHAPR_torch/params.json` file or simply package API like:\n\n```console\n\u003e from shapr import settings\n\u003e settings.path = \"a/new/path\"\n```\n\nWe have added an example of a `params.json` file to `SHAPR/docs/sample/params.json`.\nIf you want to use it, please adapt the paths to your project and copy the `params.json` to `SHAPR_torch/params.json`, then execute `SHAPR_torch/shapr/run_train_script.py`.\nYou can also print all the parameters and their values using `print`:\n\n```console\n\u003e print(settings)\n------ settings parameters ------\npath: \"path value\"\nresult_path: \"result_path value\"\npretrained_weights_path: \"pretrained_weights_path value\"\nrandom_seed: 0\n```\n\n### Running specific parts of the training loop individually\n\nYou can run the training and evaluation on the test sample by calling\nthe `run_train()` and `run_evaluation()` functions, respectively.\n\n```console\n\u003e from shapr import run_train\n\u003e run_train()\n\u003e run_evaluation()\n```\n  \n## Dataset\nPlease find the datasets used for this publication on Zenodo: https://doi.org/10.5281/zenodo.7031924\n\n### Folder structure \n\nSHAPR expects the data in the following folder structure (see sample).\nWith corresponding files having the same name. 2D microscopy images\n(64x64px) should be contained in the images folder, 2D segmentations\n(64x64px) in the mask folder and the 3D segmentation (64x64x64px) in the\nobj folder. \n\n```\npath\n├── image                 \n│   ├── 000003-num1.png\n│   │── 000004-num9.png\n│   │── 000006-num1.png\n│   │── .\n│   │── .\n│   │── .\n│   │── 059994-num1.png     \n│\n└── mask               \n│   ├── 000003-num1.png\n│   │── 000004-num9.png\n│   │── 000006-num1.png\n│   │── .\n│   │── .\n│   │── .\n│   │── 059994-num1.png    \n│\n└── obj     \n│   ├── 000003-num1.png\n│   │── 000004-num9.png\n│   │── 000006-num1.png\n│   │── .\n│   │── .\n│   │── .\n│   │── 059994-num1.png    \n```\n\n## Additional analyses\n\nNext to the SHAPR model, we also provide additional scripts that permit\nzooming into various aspects of SHAPR and persistent homology. All of\nthese scripts are to be found in the `scripts` subdirectory.\n\n### Evaluation of results\n\nTo create the evaluation plots with all errors, as shown in the paper,\nrun the `evaluation.py` script:\n\n```\n$ python -m scripts.evaluation evaluation/red-blood-cell.json\n```\n\nYou can optionally specify the `-q` option in order to skip evaluation\nmetrics that are computationally more complex to compute.\n\n### Gallery of results\n\nAfter running SHAPR, you can use the `make_gallery.py` script to create\na small gallery of all outputs. This is great for getting an overview of\nhow the model performed:\n\n```shell\n# Note that we are using a sample directory that contains ground truth\n# objects. In a realistic scenario, you would rnu this command for the\n# outputs of your own model.\n$ python -m scripts.make_gallery ../docs/sample/obj \n```\n\n### Interpolation errors\n\nTo run the analysis of the interpolation (i.e. downsampling) quality as\ndescribed in the supplementary materials, run the following command from\nthe `shapr` directory:\n\n```shell\n$ python -m scripts.analyse_interpolation -s 8 -p config/small-0D.json\n```\n\nThis will generate the interpolation/downsampling errors for a volume of\nside length `s = 8`.\n\n### Persistent homology of images\n\nTo calculate persistent homology of input images, you can use the\nfollowing script:\n\n```shell\n$ python -m scripts.calculate_persistence_diagrams ../docs/sample/obj/*.tif\n```\n\n## Contributing\n\nWe are happy about any contributions. For any suggested changes, please\nsend a pull request to the `develop` branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarrlab%2Fshapr_torch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarrlab%2Fshapr_torch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarrlab%2Fshapr_torch/lists"}