| Name | shapeaxiflo JSON |
| Version |
0.0.3
JSON |
| download |
| home_page | |
| Summary | Shape Analysis Exploration and Interpretability |
| upload_time | 2023-11-06 19:57:15 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
shape
analysis
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ShapeAXI
Welcome to the official documentation for **ShapeAXI**. Dive into the cutting-edge framework designed for comprehensive shape analysis.
---
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Experiments & Results](#experiments--results)
- [Explainability](#explainability)
- [Contribute](#contribute)
- [FAQs](#faqs)
- [License](#license)
---
## Introduction
**ShapeAXI** is a state-of-the-art shape analysis framework that harnesses a multi-view approach. This approach is adept at capturing 3D objects from a variety of viewpoints and analyzing them through 2D Convolutional Neural Networks (CNNs).
---
## Installation
### Installation of shapeaxi
```bash
pip install shapeaxi
```
### Installation of pytorch3d
For this installation, we are going to use a variable, {YOURVERSION}, because this installation is specific to each computer configuration.
- First, you need to know your python version (3.8, 3.9)
- Second, you need to know your CUDA version with this command line :
```bash
nvcc --version
```
It will print something like this :
```bash
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2022 NVIDIA Corporation
Built on Tue_Mar__8_18:18:20_PST_2022
Cuda compilation tools, release 11.6, V11.6.124
Build cuda_11.6.r11.6/compiler.31057947_0
```
Then, you have to edit {YOURVERSION} by using your python and CUDA version.
For example, if you are using python 3.9 and CUDA 11.4,
```bash
{YOURVERSION} = py38_cu114
```
The first part is *py* and your python version without the point.
The second part is *cu* and your CUDA version without the point.
Finally, run this line by adding your editing {YOURVERSION},
```bash
pip install --no-index --no-cache-dir pytorch3d -f https://dl.fbaipublicfiles.com/pytorch3d/packaging/wheels/{YOURVERSION}_pyt1110/download.html
```
Finally, check the installation,
```bash
pip show pytorch3d
```
### Requirements:
```bash
# Command to install ShapeAXI
git clone https://github.com/DCBIA-OrthoLab/ShapeAXI.git
cd ShapeAXI
pip install -r requirements.txt
```
## Usage
### Basic Usage:
To get started with **ShapeAXI**, follow the steps below:
#### Example CSV File
Your input CSV file should be structured as follows:
| surf | class |
|--------------------------------------|--------|
| path/to/shape1.vtk | class1 |
| path/to/shape2.stl | class2 |
| path/to/shape3.obj | class1 |
| ... | ... |
- **surf**: This column holds the file paths to the 3D shape objects. The tool supports the formats `.vtk`, `.stl`, and `.obj`.
- **class**: This column indicates the class of the 3D object.
### Running ShapeAXI
To use ShapeAXI, execute the `saxi_folds.py` script:
```bash
python saxi_folds.py --csv your_data.csv --compute_scale_factor 1 --surf_column surf --class_column class --subdivision_level 2 --batch_size 8 --out output_dir/
```
Ensure you replace `your_data.csv` with the correct path to your specific CSV file.
```
usage: saxi_folds.py [-h] --csv CSV [--folds FOLDS] [--valid_split VALID_SPLIT] [--group_by GROUP_BY] [--nn NN] [--surf_column SURF_COLUMN] [--class_column CLASS_COLUMN] [--compute_scale_factor COMPUTE_SCALE_FACTOR] [--mount_point MOUNT_POINT]
[--num_workers NUM_WORKERS] [--base_encoder BASE_ENCODER] [--base_encoder_params BASE_ENCODER_PARAMS] [--hidden_dim HIDDEN_DIM] [--radius RADIUS] [--subdivision_level SUBDIVISION_LEVEL] [--image_size IMAGE_SIZE] [--lr LR] [--epochs EPOCHS]
[--batch_size BATCH_SIZE] [--patience PATIENCE] [--log_every_n_steps LOG_EVERY_N_STEPS] [--tb_dir TB_DIR] [--tb_name TB_NAME] [--neptune_project NEPTUNE_PROJECT] [--neptune_tags NEPTUNE_TAGS] [--target_layer TARGET_LAYER] [--fps FPS] [--out OUT]
Automatically train and evaluate a N fold cross-validation model for Shape Analysis Explainability and Interpretability
options:
-h, --help show this help message and exit
Split:
--csv CSV CSV with columns surf,class
--folds FOLDS Number of folds
--valid_split VALID_SPLIT
Number of folds
--group_by GROUP_BY GroupBy criteria in the CSV. For example, SubjectID in case the same subjects has multiple timepoints/data points and the subject must belong to the same data split
Train:
--nn NN Type of neural network for training
--surf_column SURF_COLUMN
Surface column name
--class_column CLASS_COLUMN
Class column name
--compute_scale_factor COMPUTE_SCALE_FACTOR
Compute a global scale factor for all shapes in the population.
--mount_point MOUNT_POINT
Dataset mount directory
--num_workers NUM_WORKERS
Number of workers for loading
--base_encoder BASE_ENCODER
Base encoder for the feature extraction
--base_encoder_params BASE_ENCODER_PARAMS
Base encoder parameters that are passed to build the feature extraction
--hidden_dim HIDDEN_DIM
Hidden dimension for features output. Should match with output of base_encoder. Default value is 512
--radius RADIUS Radius of icosphere
--subdivision_level SUBDIVISION_LEVEL
Subdivision level for icosahedron
--image_size IMAGE_SIZE
Image resolution size
--lr LR, --learning-rate LR
Learning rate
--epochs EPOCHS Max number of epochs
--batch_size BATCH_SIZE
Batch size
--patience PATIENCE Patience for early stopping
--log_every_n_steps LOG_EVERY_N_STEPS
Log every n steps
--tb_dir TB_DIR Tensorboard output dir
--tb_name TB_NAME Tensorboard experiment name
--neptune_project NEPTUNE_PROJECT
Neptune project
--neptune_tags NEPTUNE_TAGS
Neptune tags
Explainability group:
--target_layer TARGET_LAYER
Target layer for explainability
--fps FPS Frames per second
Output:
--out OUT Output
```
#### Workflow:
1. On running `saxi_folds.py`, the tool will:
- Generate the necessary N folds.
- Handle the training, validation, and testing.
2. The tool then produces:
- A confusion matrix.
- ROC curves.
- Explainability maps for each shape in the dataset.
## Experiments & Results
**ShapeAXI** has been rigorously tested across multiple domains. Below is a summary of our key experiments:
### Condyles Classification
- **Categories**: Healthy vs. Degenerative states
- **Accuracy**: ~79.78%
### Cleft Patients Severity Classification
- **Classes**: Severity levels 0 to 3
- **Accuracy**: ~81.58%
---
## Explainability
In **ShapeAXI**, we prioritize transparency and understanding. The explainability feature of our framework offers heat-maps which grant insights into its classification rationale.
https://github.com/DCBIA-OrthoLab/ShapeAXI/assets/7086191/120b0095-5f2d-4f0d-b650-a0587a33e067
https://github.com/DCBIA-OrthoLab/ShapeAXI/assets/7086191/2c635250-624f-4cce-b150-4d5507b398b4
---
## Contribute
We welcome community contributions to **ShapeAXI**. For those keen on enhancing this tool, please adhere to the steps below:
1. **Fork** the repository.
2. Create your **feature branch** (`git checkout -b feature/YourFeature`).
3. Commit your changes (`git commit -am 'Add some feature'`).
4. Push to the branch (`git push origin feature/YourFeature`).
5. Open a **pull request**.
For a comprehensive understanding of our contribution process, consult our [Contribution Guidelines](path/to/contribution_guidelines.md).
---
Of course! Here are some general FAQ entries tailored for a tool/framework like ShapeAXI:
## FAQs
### What is ShapeAXI?
**Answer:** ShapeAXI is an innovative shape analysis framework that employs a multi-view approach, rendering 3D objects from varied perspectives and analyzing them using 2D Convolutional Neural Networks (CNNs).
---
### How do I install and set up ShapeAXI?
**Answer:** Detailed installation and setup instructions can be found in the 'Installation' section of our documentation. Simply follow the steps mentioned, and you should have ShapeAXI up and running in no time.
---
### Can I use ShapeAXI for my own datasets?
**Answer:** Absolutely! ShapeAXI is designed to be versatile. You can use it on a wide variety of shape datasets. Ensure your data is in the required format as outlined in the 'Usage' section.
---
### How does ShapeAXI handle explainability?
**Answer:** ShapeAXI offers a unique approach to explainability, providing heat-maps for each class across every shape. These visualizations provide insights into the underlying object characteristics and the classification rationale.
---
### Are there any known limitations of ShapeAXI?
**Answer:** Like all models and frameworks, ShapeAXI has its constraints. It is optimized for the datasets and tasks it has been trained and tested on. While it offers versatility across a range of datasets, results may vary based on the quality and type of data. We continually work on refining and improving ShapeAXI to overcome any limitations.
---
### How can I contribute to ShapeAXI's development?
**Answer:** We welcome contributions! Please refer to the 'Contribute' section of our documentation for guidelines on how you can contribute.
---
### Who do I contact for technical support or questions about ShapeAXI?
**Answer:** For technical support or any questions, please create a new issue in our GitHub repository.
---
### Will there be future updates to ShapeAXI?
**Answer:** Yes, we plan on continuously improving and expanding ShapeAXI based on user feedback, new research, and technological advancements. Stay tuned to our repository for updates.
---
## License
**ShapeAXI** is under the [APACHE 2.0](LICENSE) license.
---
**ShapeAXI Team**: For further details, inquiries, or suggestions, feel free to [contact us](mailto:juan_prieto@med.unc.edu).
##################----TEETH----##################
import utils
from vtk.util.numpy_support import vtk_to_numpy, numpy_to_vtk
import nrrd
#################################################
Raw data
{
"_id": null,
"home_page": "",
"name": "shapeaxiflo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Shape Analysis",
"author": "",
"author_email": "juanprietob <juanprietob@gmail.com>, FlorianDAVAUX <florian.davaux@cpe.fr>",
"download_url": "https://files.pythonhosted.org/packages/ef/88/a61bd904c609801186e3cbcb24718ac5486022ffa06011e6b9e878401c43/shapeaxiflo-0.0.3.tar.gz",
"platform": null,
"description": "# ShapeAXI\n\nWelcome to the official documentation for **ShapeAXI**. Dive into the cutting-edge framework designed for comprehensive shape analysis.\n\n---\n\n## Table of Contents\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Experiments & Results](#experiments--results)\n- [Explainability](#explainability)\n- [Contribute](#contribute)\n- [FAQs](#faqs)\n- [License](#license)\n\n---\n\n## Introduction\n\n**ShapeAXI** is a state-of-the-art shape analysis framework that harnesses a multi-view approach. This approach is adept at capturing 3D objects from a variety of viewpoints and analyzing them through 2D Convolutional Neural Networks (CNNs).\n\n---\n\n## Installation\n\n### Installation of shapeaxi\n```bash\npip install shapeaxi\n```\n\n### Installation of pytorch3d \n\nFor this installation, we are going to use a variable, {YOURVERSION}, because this installation is specific to each computer configuration.\n- First, you need to know your python version (3.8, 3.9)\n- Second, you need to know your CUDA version with this command line :\n```bash\nnvcc --version\n```\nIt will print something like this : \n```bash\nnvcc: NVIDIA (R) Cuda compiler driver\nCopyright (c) 2005-2022 NVIDIA Corporation\nBuilt on Tue_Mar__8_18:18:20_PST_2022\nCuda compilation tools, release 11.6, V11.6.124\nBuild cuda_11.6.r11.6/compiler.31057947_0\n```\nThen, you have to edit {YOURVERSION} by using your python and CUDA version. \nFor example, if you are using python 3.9 and CUDA 11.4, \n```bash\n{YOURVERSION} = py38_cu114\n```\nThe first part is *py* and your python version without the point. \nThe second part is *cu* and your CUDA version without the point.\n\nFinally, run this line by adding your editing {YOURVERSION}, \n```bash\npip install --no-index --no-cache-dir pytorch3d -f https://dl.fbaipublicfiles.com/pytorch3d/packaging/wheels/{YOURVERSION}_pyt1110/download.html\n```\n\nFinally, check the installation,\n```bash\npip show pytorch3d\n```\n\n### Requirements:\n\n```bash\n# Command to install ShapeAXI\ngit clone https://github.com/DCBIA-OrthoLab/ShapeAXI.git\ncd ShapeAXI\npip install -r requirements.txt\n```\n\n## Usage\n\n### Basic Usage:\n\nTo get started with **ShapeAXI**, follow the steps below:\n\n\n#### Example CSV File\n\nYour input CSV file should be structured as follows:\n\n| surf | class |\n|--------------------------------------|--------|\n| path/to/shape1.vtk | class1 |\n| path/to/shape2.stl | class2 |\n| path/to/shape3.obj | class1 |\n| ... | ... |\n\n\n- **surf**: This column holds the file paths to the 3D shape objects. The tool supports the formats `.vtk`, `.stl`, and `.obj`.\n- **class**: This column indicates the class of the 3D object.\n\n### Running ShapeAXI\n\nTo use ShapeAXI, execute the `saxi_folds.py` script:\n\n```bash\npython saxi_folds.py --csv your_data.csv --compute_scale_factor 1 --surf_column surf --class_column class --subdivision_level 2 --batch_size 8 --out output_dir/\n```\n\nEnsure you replace `your_data.csv` with the correct path to your specific CSV file. \n\n```\nusage: saxi_folds.py [-h] --csv CSV [--folds FOLDS] [--valid_split VALID_SPLIT] [--group_by GROUP_BY] [--nn NN] [--surf_column SURF_COLUMN] [--class_column CLASS_COLUMN] [--compute_scale_factor COMPUTE_SCALE_FACTOR] [--mount_point MOUNT_POINT]\n [--num_workers NUM_WORKERS] [--base_encoder BASE_ENCODER] [--base_encoder_params BASE_ENCODER_PARAMS] [--hidden_dim HIDDEN_DIM] [--radius RADIUS] [--subdivision_level SUBDIVISION_LEVEL] [--image_size IMAGE_SIZE] [--lr LR] [--epochs EPOCHS]\n [--batch_size BATCH_SIZE] [--patience PATIENCE] [--log_every_n_steps LOG_EVERY_N_STEPS] [--tb_dir TB_DIR] [--tb_name TB_NAME] [--neptune_project NEPTUNE_PROJECT] [--neptune_tags NEPTUNE_TAGS] [--target_layer TARGET_LAYER] [--fps FPS] [--out OUT]\n\nAutomatically train and evaluate a N fold cross-validation model for Shape Analysis Explainability and Interpretability\n\noptions:\n -h, --help show this help message and exit\n\nSplit:\n --csv CSV CSV with columns surf,class\n --folds FOLDS Number of folds\n --valid_split VALID_SPLIT\n Number of folds\n --group_by GROUP_BY GroupBy criteria in the CSV. For example, SubjectID in case the same subjects has multiple timepoints/data points and the subject must belong to the same data split\n\nTrain:\n --nn NN Type of neural network for training\n --surf_column SURF_COLUMN\n Surface column name\n --class_column CLASS_COLUMN\n Class column name\n --compute_scale_factor COMPUTE_SCALE_FACTOR\n Compute a global scale factor for all shapes in the population.\n --mount_point MOUNT_POINT\n Dataset mount directory\n --num_workers NUM_WORKERS\n Number of workers for loading\n --base_encoder BASE_ENCODER\n Base encoder for the feature extraction\n --base_encoder_params BASE_ENCODER_PARAMS\n Base encoder parameters that are passed to build the feature extraction\n --hidden_dim HIDDEN_DIM\n Hidden dimension for features output. Should match with output of base_encoder. Default value is 512\n --radius RADIUS Radius of icosphere\n --subdivision_level SUBDIVISION_LEVEL\n Subdivision level for icosahedron\n --image_size IMAGE_SIZE\n Image resolution size\n --lr LR, --learning-rate LR\n Learning rate\n --epochs EPOCHS Max number of epochs\n --batch_size BATCH_SIZE\n Batch size\n --patience PATIENCE Patience for early stopping\n --log_every_n_steps LOG_EVERY_N_STEPS\n Log every n steps\n --tb_dir TB_DIR Tensorboard output dir\n --tb_name TB_NAME Tensorboard experiment name\n --neptune_project NEPTUNE_PROJECT\n Neptune project\n --neptune_tags NEPTUNE_TAGS\n Neptune tags\n\nExplainability group:\n --target_layer TARGET_LAYER\n Target layer for explainability\n --fps FPS Frames per second\n\nOutput:\n --out OUT Output\n```\n\n#### Workflow:\n\n1. On running `saxi_folds.py`, the tool will:\n - Generate the necessary N folds.\n - Handle the training, validation, and testing.\n\n2. The tool then produces:\n - A confusion matrix.\n - ROC curves.\n - Explainability maps for each shape in the dataset.\n\n## Experiments & Results\n\n**ShapeAXI** has been rigorously tested across multiple domains. Below is a summary of our key experiments:\n\n### Condyles Classification\n\n- **Categories**: Healthy vs. Degenerative states\n- **Accuracy**: ~79.78%\n\n\n\n\n### Cleft Patients Severity Classification\n\n- **Classes**: Severity levels 0 to 3\n- **Accuracy**: ~81.58%\n\n\n\n---\n\n## Explainability\n\nIn **ShapeAXI**, we prioritize transparency and understanding. The explainability feature of our framework offers heat-maps which grant insights into its classification rationale.\n\nhttps://github.com/DCBIA-OrthoLab/ShapeAXI/assets/7086191/120b0095-5f2d-4f0d-b650-a0587a33e067\n\nhttps://github.com/DCBIA-OrthoLab/ShapeAXI/assets/7086191/2c635250-624f-4cce-b150-4d5507b398b4\n\n---\n\n## Contribute\n\nWe welcome community contributions to **ShapeAXI**. For those keen on enhancing this tool, please adhere to the steps below:\n\n1. **Fork** the repository.\n2. Create your **feature branch** (`git checkout -b feature/YourFeature`).\n3. Commit your changes (`git commit -am 'Add some feature'`).\n4. Push to the branch (`git push origin feature/YourFeature`).\n5. Open a **pull request**.\n\nFor a comprehensive understanding of our contribution process, consult our [Contribution Guidelines](path/to/contribution_guidelines.md).\n\n---\n\nOf course! Here are some general FAQ entries tailored for a tool/framework like ShapeAXI:\n\n## FAQs\n\n### What is ShapeAXI?\n\n**Answer:** ShapeAXI is an innovative shape analysis framework that employs a multi-view approach, rendering 3D objects from varied perspectives and analyzing them using 2D Convolutional Neural Networks (CNNs).\n\n---\n\n### How do I install and set up ShapeAXI?\n\n**Answer:** Detailed installation and setup instructions can be found in the 'Installation' section of our documentation. Simply follow the steps mentioned, and you should have ShapeAXI up and running in no time.\n\n---\n\n### Can I use ShapeAXI for my own datasets?\n\n**Answer:** Absolutely! ShapeAXI is designed to be versatile. You can use it on a wide variety of shape datasets. Ensure your data is in the required format as outlined in the 'Usage' section.\n\n---\n\n### How does ShapeAXI handle explainability?\n\n**Answer:** ShapeAXI offers a unique approach to explainability, providing heat-maps for each class across every shape. These visualizations provide insights into the underlying object characteristics and the classification rationale.\n\n---\n\n### Are there any known limitations of ShapeAXI?\n\n**Answer:** Like all models and frameworks, ShapeAXI has its constraints. It is optimized for the datasets and tasks it has been trained and tested on. While it offers versatility across a range of datasets, results may vary based on the quality and type of data. We continually work on refining and improving ShapeAXI to overcome any limitations.\n\n---\n\n### How can I contribute to ShapeAXI's development?\n\n**Answer:** We welcome contributions! Please refer to the 'Contribute' section of our documentation for guidelines on how you can contribute.\n\n---\n\n### Who do I contact for technical support or questions about ShapeAXI?\n\n**Answer:** For technical support or any questions, please create a new issue in our GitHub repository.\n\n---\n\n### Will there be future updates to ShapeAXI?\n\n**Answer:** Yes, we plan on continuously improving and expanding ShapeAXI based on user feedback, new research, and technological advancements. Stay tuned to our repository for updates.\n\n---\n\n## License\n\n**ShapeAXI** is under the [APACHE 2.0](LICENSE) license.\n\n---\n\n**ShapeAXI Team**: For further details, inquiries, or suggestions, feel free to [contact us](mailto:juan_prieto@med.unc.edu).\n\n\n\n##################----TEETH----##################\nimport utils\nfrom vtk.util.numpy_support import vtk_to_numpy, numpy_to_vtk\nimport nrrd\n#################################################\n",
"bugtrack_url": null,
"license": "",
"summary": "Shape Analysis Exploration and Interpretability",
"version": "0.0.3",
"project_urls": {
"Source Code": "https://github.com/DCBIA-OrthoLab/ShapeAXI/"
},
"split_keywords": [
"shape",
"analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc823b7fd22882e1dff027122846c5fe35704cdec5cd47fea31d498687d28af8",
"md5": "ffd13cf8a316e09e704186ec8d382f0e",
"sha256": "901f1ff321415c1e8782d5da06fd5af6794c672489702dc5072a47d8d8b8b927"
},
"downloads": -1,
"filename": "shapeaxiflo-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffd13cf8a316e09e704186ec8d382f0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 65871,
"upload_time": "2023-11-06T19:57:12",
"upload_time_iso_8601": "2023-11-06T19:57:12.711101Z",
"url": "https://files.pythonhosted.org/packages/fc/82/3b7fd22882e1dff027122846c5fe35704cdec5cd47fea31d498687d28af8/shapeaxiflo-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ef88a61bd904c609801186e3cbcb24718ac5486022ffa06011e6b9e878401c43",
"md5": "a03c45a76154e064d7a8e03b6c8068ec",
"sha256": "183a0a9020b8b9e0651fc41c885bd730d573f062a67b2def2dcf8d84c24cf5aa"
},
"downloads": -1,
"filename": "shapeaxiflo-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "a03c45a76154e064d7a8e03b6c8068ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 67584245,
"upload_time": "2023-11-06T19:57:15",
"upload_time_iso_8601": "2023-11-06T19:57:15.442724Z",
"url": "https://files.pythonhosted.org/packages/ef/88/a61bd904c609801186e3cbcb24718ac5486022ffa06011e6b9e878401c43/shapeaxiflo-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-06 19:57:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DCBIA-OrthoLab",
"github_project": "ShapeAXI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "shapeaxiflo"
}
