| Name | ari3d JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Analyse Regions in 3D |
| upload_time | 2025-08-01 12:10:19 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ~=3.11 |
| license | None |
| keywords |
x-ray
imaging
data analysis
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ARI3D
## Introduction
ARI3D is an interactive workflow that lets you analyse your mineral particles in micro CT images.
It is based on the MSPacMan workflow: A Standardized and semiautomated workflow for characterization of
liberated particles in 3D X-ray micro-computed tomography images (https://doi.org/10.1016/j.powtec.2023.119159),
but extended to allow for more flexibility and usability as well as application to a wider range
of mineral particle types or even other materials.
Each workflow step is developed as an album solutions (https://album.solutions/).
The software itself can be installed via pip as a package as described below.
## Solutions
Each workflow step is executed in its own micromamba environment and hence there are will
be no compatibility issues between these.
Moreover, each step is individually callable (executable) via album.
## Installation
Please install ARI3D via pip in the following way:
Install micromamba https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html.
If the installation fails on Windows 11 try the following:
- open powershell
- run command: Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe ####this will install winget
- run command: winget install --id=Mamba.Micromamba -e ####this will install micromamba
- run command: micromamba.exe shell hook -s powershell | Out-String | Invoke-Expression
- micromamba shell init --shell powershell --root-prefix=~/.local/share/mamba #sets the path to micromamba, may need admin login
- micromamba activate
On windows systems when working with micromamba you need to have configured the policy to allow running scripts.
You can do this by running the following command in an elevated powershell:
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Install the environment(the place where the software will live) with:
```
micromamba create -n ari3d python==3.11 git -c conda-forge
```
Then execute:
```
micromamba activate ari3d
```
Now install the software via:
```
pip install ari3d
```
Now we can run the software with:
```
ari3d
```
The software automatically installs the necessary dependencies. This can take some time.
After that the main GUI should open.
Installing necessary dependencies can fail. Especially for MacOS users, the installation of the
segmentation solution can fail, as it requires a GPU and the correct CUDA version.
We recommend to use a Linux or Windows system with a GPU for the segmentation step.
## Common issues when installing:
bzip2 not available: https://github.com/mamba-org/mamba/issues/2940
"Could not resolve host: repo.anaconda.com" error: Your configuration most likely holds a commercial repository hosted
by anaconda. Probably your institution has a proxy that blocks the connection to the anaconda repository. Remove the
commercial repository from your configuration and try again.
## Uninstall
To uninstall the entire software suit do the following in your micromamba terminal (e.g. powershell or shell):
```
micromamba activate
micromamba remove -n ari3d --all
```
This will remove the environment and all installed packages and steps.
Ari3d logging is written to disk. By default Ari3d will write the logs to the `~/<USERHOME>/.ari3d` directory.
You can remove the logs by deleting this directory.
## Run the entire workflow
We provide a headless workflow that can be run in the terminal.
This workflow is realized with SnakeMake (https://snakemake.readthedocs.io/en/stable/).
To run the workflow, you need to have the mspacman workflow installed as described above.
Then you can display the help message of the workflow with:
```
ari3d-cli -h
```
We provide a docker image of the workflow that can be used to run the workflow in a container.
Due to image size (around 30 GB), we do not provide it on docker hub, but in the following link:
https://syncandshare.desy.de/index.php/s/SBi9FPnAwYcm2CE
## Install the workflow via album
We provide the ARI3D workflow as an album solution.
The solution is inside the github repository of the ARI3D project.
It installs the entire workflow, all models and all steps of the workflow.
To install the workflow via album, first install album (see https://album.solutions/installation.html).
Then you can install the ARI3D workflow with the following command:
```
git clone https://gitlab.com/ida-mdc/ari3d.git
album install ari3d
```
Then run the workflow with:
```
album run de.mdc:ari3d:0.1.0 --input INPUT_PATH --output OUTPUT_PATH
```
Where `INPUT_PATH` is the path to your input data and `OUTPUT_PATH` is the path where you want to store the output data.
## Run individual steps without GUI
When using the software without the GUI, you can use the album command line interface to run the individual steps.
Especially for the segmentation step, this is useful, as the segmentation step
can take a long time and requires special hardware (e.g. GPU).
We will describe the usage of the album command line interface exemplary for the segmentation step:
Install micromamba (https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html#linux-and-macos)
on your linux based system.
Then do the following:
Install your album base environment:
```
micromamba create -n album python==3.11 git -c conda-forge
micromamba activate album
```
Install the album software:
```
pip install album
```
Add the mspacman catalog to the album software:
```
album catalog add https://gitlab.com/ida-mdc/ari3d.git
```
Install your step with:
```
album install de.mdc:particleSeg3D-predict:0.1.0
```
Now you can look at how to execute the step with:
```
album info de.mdc:particleSeg3D-predict:0.1.0
```
A call of the step could then look like this:
```
album run de.mdc:particleSeg3D-predict:0.1.0 --input PARAMETER_VALUE --output PARAMETER_VALUE --model PARAMETER_VALUE
```
Where the PARAMETER_VALUEs are placeholders for the actual values you want to use.
Remember there is more than one parameter to set. You can see them with the info command.
## Docker Export Requirements
For full reproducibility, we provide a docker export of the ARI3D workflow.
The software utilizes PyQt6 for building the graphical user interface (GUI).
Despite the fact that the workflow is designed to run headless, the GUI is still required as a dependency.
For linux containers that requires having shared system libraries installed.
We recommend the following shared libraries to be installed in your container:
| Package | Purpose |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `tzdata` | Timezone data used by the system clock and applications to handle time zones properly. |
| `libgl1` | OpenGL rendering library – required for 3D and hardware-accelerated graphics. |
| `libglx-mesa0` | Part of the Mesa 3D Graphics Library that implements the GLX interface to connect OpenGL and the X Window System. |
| `libxkbcommon-x11-0` | Keyboard handling library that provides keyboard layout parsing and handling for X11 systems. |
| `libegl1` | Interface between rendering APIs like OpenGL ES and the native platform window system. |
| `libfontconfig1` | Font discovery and configuration library – allows Qt and other GUI libraries to locate system fonts. |
| `libglib-2.0-0` | Core low-level utility library used by GTK and Qt (through DBus or GLib-based modules). |
| `libdbus-1-3` | DBus library for inter-process communication, often used for event/message communication in Linux desktops. |
We used albums container export feature to create the docker image.
To export the container, you can use the following command:
```
album docker --solution ari3d/ --output . --install-flags="--allow-recursive" --install-deps "DEBIAN_FRONTEND=noninteractive apt install -y --no-install-recommends tzdata libgl1 libglx-mesa0 libxkbcommon-x11-0 libegl1 libfontconfig1 libglib-2.0-0 libdbus-1-3"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "ari3d",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.11",
"maintainer_email": null,
"keywords": "X-ray, imaging, data analysis",
"author": null,
"author_email": "Jan Philipp Albrecht <j.p.albrecht@fu-berlin.de>, Jose Ricardo Assuncao Godinho <jragodinho@uma.es>",
"download_url": "https://files.pythonhosted.org/packages/00/a2/68bce0db01875aba5a3752a09e284a8d93a53477b0bbb5752b2cd49dd7ba/ari3d-0.1.1.tar.gz",
"platform": null,
"description": "# ARI3D\n\n## Introduction\n\nARI3D is an interactive workflow that lets you analyse your mineral particles in micro CT images.\n\nIt is based on the MSPacMan workflow: A Standardized and semiautomated workflow for characterization of\nliberated particles in 3D X-ray micro-computed tomography images (https://doi.org/10.1016/j.powtec.2023.119159),\nbut extended to allow for more flexibility and usability as well as application to a wider range\nof mineral particle types or even other materials.\n\nEach workflow step is developed as an album solutions (https://album.solutions/).\nThe software itself can be installed via pip as a package as described below.\n\n## Solutions\n\nEach workflow step is executed in its own micromamba environment and hence there are will\nbe no compatibility issues between these.\n\nMoreover, each step is individually callable (executable) via album.\n\n## Installation\n\nPlease install ARI3D via pip in the following way:\n\nInstall micromamba https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html.\n\nIf the installation fails on Windows 11 try the following:\n\n- open powershell\n- run command: Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe ####this will install winget\n- run command: winget install --id=Mamba.Micromamba -e ####this will install micromamba\n- run command: micromamba.exe shell hook -s powershell | Out-String | Invoke-Expression\n- micromamba shell init --shell powershell --root-prefix=~/.local/share/mamba #sets the path to micromamba, may need admin login\n- micromamba activate\n\nOn windows systems when working with micromamba you need to have configured the policy to allow running scripts.\nYou can do this by running the following command in an elevated powershell:\n\n```\nSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser\n```\n\nInstall the environment(the place where the software will live) with:\n\n```\nmicromamba create -n ari3d python==3.11 git -c conda-forge\n```\n\nThen execute:\n\n```\nmicromamba activate ari3d\n```\n\nNow install the software via:\n\n```\npip install ari3d\n```\n\nNow we can run the software with:\n\n```\nari3d\n```\n\nThe software automatically installs the necessary dependencies. This can take some time.\nAfter that the main GUI should open.\n\nInstalling necessary dependencies can fail. Especially for MacOS users, the installation of the\nsegmentation solution can fail, as it requires a GPU and the correct CUDA version.\nWe recommend to use a Linux or Windows system with a GPU for the segmentation step.\n\n## Common issues when installing:\n\nbzip2 not available: https://github.com/mamba-org/mamba/issues/2940\n\n\"Could not resolve host: repo.anaconda.com\" error: Your configuration most likely holds a commercial repository hosted\nby anaconda. Probably your institution has a proxy that blocks the connection to the anaconda repository. Remove the\ncommercial repository from your configuration and try again.\n\n## Uninstall\n\nTo uninstall the entire software suit do the following in your micromamba terminal (e.g. powershell or shell):\n\n```\nmicromamba activate\nmicromamba remove -n ari3d --all\n```\n\nThis will remove the environment and all installed packages and steps.\n\nAri3d logging is written to disk. By default Ari3d will write the logs to the `~/<USERHOME>/.ari3d` directory.\nYou can remove the logs by deleting this directory.\n\n## Run the entire workflow\n\nWe provide a headless workflow that can be run in the terminal.\nThis workflow is realized with SnakeMake (https://snakemake.readthedocs.io/en/stable/).\nTo run the workflow, you need to have the mspacman workflow installed as described above.\n\nThen you can display the help message of the workflow with:\n\n```\nari3d-cli -h\n```\n\nWe provide a docker image of the workflow that can be used to run the workflow in a container.\nDue to image size (around 30 GB), we do not provide it on docker hub, but in the following link:\nhttps://syncandshare.desy.de/index.php/s/SBi9FPnAwYcm2CE\n\n## Install the workflow via album\n\nWe provide the ARI3D workflow as an album solution.\nThe solution is inside the github repository of the ARI3D project.\nIt installs the entire workflow, all models and all steps of the workflow.\n\nTo install the workflow via album, first install album (see https://album.solutions/installation.html).\n\nThen you can install the ARI3D workflow with the following command:\n\n```\ngit clone https://gitlab.com/ida-mdc/ari3d.git\nalbum install ari3d\n```\n\nThen run the workflow with:\n\n```\nalbum run de.mdc:ari3d:0.1.0 --input INPUT_PATH --output OUTPUT_PATH\n```\n\nWhere `INPUT_PATH` is the path to your input data and `OUTPUT_PATH` is the path where you want to store the output data.\n\n## Run individual steps without GUI\n\nWhen using the software without the GUI, you can use the album command line interface to run the individual steps.\n\nEspecially for the segmentation step, this is useful, as the segmentation step\ncan take a long time and requires special hardware (e.g. GPU).\nWe will describe the usage of the album command line interface exemplary for the segmentation step:\n\nInstall micromamba (https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html#linux-and-macos)\non your linux based system.\n\nThen do the following:\n\nInstall your album base environment:\n\n```\nmicromamba create -n album python==3.11 git -c conda-forge\nmicromamba activate album\n```\n\nInstall the album software:\n\n```\npip install album\n```\n\nAdd the mspacman catalog to the album software:\n\n```\nalbum catalog add https://gitlab.com/ida-mdc/ari3d.git\n```\n\nInstall your step with:\n\n```\nalbum install de.mdc:particleSeg3D-predict:0.1.0\n```\n\nNow you can look at how to execute the step with:\n\n```\nalbum info de.mdc:particleSeg3D-predict:0.1.0\n```\n\nA call of the step could then look like this:\n\n```\nalbum run de.mdc:particleSeg3D-predict:0.1.0 --input PARAMETER_VALUE --output PARAMETER_VALUE --model PARAMETER_VALUE\n```\n\nWhere the PARAMETER_VALUEs are placeholders for the actual values you want to use.\nRemember there is more than one parameter to set. You can see them with the info command.\n\n## Docker Export Requirements\n\nFor full reproducibility, we provide a docker export of the ARI3D workflow.\n\nThe software utilizes PyQt6 for building the graphical user interface (GUI).\nDespite the fact that the workflow is designed to run headless, the GUI is still required as a dependency.\n\nFor linux containers that requires having shared system libraries installed.\n\nWe recommend the following shared libraries to be installed in your container:\n\n| Package | Purpose |\n| -------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `tzdata` | Timezone data used by the system clock and applications to handle time zones properly. |\n| `libgl1` | OpenGL rendering library \u2013 required for 3D and hardware-accelerated graphics. |\n| `libglx-mesa0` | Part of the Mesa 3D Graphics Library that implements the GLX interface to connect OpenGL and the X Window System. |\n| `libxkbcommon-x11-0` | Keyboard handling library that provides keyboard layout parsing and handling for X11 systems. |\n| `libegl1` | Interface between rendering APIs like OpenGL ES and the native platform window system. |\n| `libfontconfig1` | Font discovery and configuration library \u2013 allows Qt and other GUI libraries to locate system fonts. |\n| `libglib-2.0-0` | Core low-level utility library used by GTK and Qt (through DBus or GLib-based modules). |\n| `libdbus-1-3` | DBus library for inter-process communication, often used for event/message communication in Linux desktops. |\n\nWe used albums container export feature to create the docker image.\n\nTo export the container, you can use the following command:\n\n```\nalbum docker --solution ari3d/ --output . --install-flags=\"--allow-recursive\" --install-deps \"DEBIAN_FRONTEND=noninteractive apt install -y --no-install-recommends tzdata libgl1 libglx-mesa0 libxkbcommon-x11-0 libegl1 libfontconfig1 libglib-2.0-0 libdbus-1-3\"\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Analyse Regions in 3D",
"version": "0.1.1",
"project_urls": {
"Repository": "https://gitlab.com/ida-mdc/ari3d"
},
"split_keywords": [
"x-ray",
" imaging",
" data analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a01a4cb9d891b90b70bbcf470a4f9a726e526de7840b0bd52c9a8bb9d05ef12a",
"md5": "2b039ddba9548dabf99834bbf2680d0c",
"sha256": "2e82671aeeb0b35c11aa070ad57e675e5db8feeec5395dbad2898eeb3dad6ad5"
},
"downloads": -1,
"filename": "ari3d-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b039ddba9548dabf99834bbf2680d0c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.11",
"size": 418594,
"upload_time": "2025-08-01T12:10:18",
"upload_time_iso_8601": "2025-08-01T12:10:18.144172Z",
"url": "https://files.pythonhosted.org/packages/a0/1a/4cb9d891b90b70bbcf470a4f9a726e526de7840b0bd52c9a8bb9d05ef12a/ari3d-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "00a268bce0db01875aba5a3752a09e284a8d93a53477b0bbb5752b2cd49dd7ba",
"md5": "891744ee86145a08f5b1617f73bd66a1",
"sha256": "9938f26cddb9615226e2479281accb80821e63699782c2654a3d5bab004422fc"
},
"downloads": -1,
"filename": "ari3d-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "891744ee86145a08f5b1617f73bd66a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.11",
"size": 392250,
"upload_time": "2025-08-01T12:10:19",
"upload_time_iso_8601": "2025-08-01T12:10:19.837537Z",
"url": "https://files.pythonhosted.org/packages/00/a2/68bce0db01875aba5a3752a09e284a8d93a53477b0bbb5752b2cd49dd7ba/ari3d-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 12:10:19",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ida-mdc",
"gitlab_project": "ari3d",
"lcname": "ari3d"
}
