ari3d 0.1.5

Analyse Regions in 3D

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.

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

After that, restart your powershell.

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
• run command: micromamba shell init --shell powershell --root-prefix=~/.local/share/mamba # sets the path to micromamba, may need admin login
• run command: micromamba activate

Install the environment(the place where the software will live) with:

micromamba create -n ari3d python==3.11 git imagecodecs -c conda-forge

After that, restart your powershell.

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.

The workflow steps ARI3D employs are installed to disk. By default ARI3D will write to the ~/<USERHOME>/.ari3d directory. You can remove the installation 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_dir INPUT_PATH --project_dir OUTPUT_PATH --parameters_file PARAMETERS_FILE 

Where INPUT_PATH is the path to your input data and OUTPUT_PATH is the path where you want to store the output data. PARAMETERS_FILE is a json file that contains the parameters for the workflow.

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.

Run the docker container

To run the docker container, you need to have docker installed on your system. You can then run the container with the following command:

docker load -i de.mdc_ari3d_<X.X.X>_image.tar
docker run -it --rm -v /path/to/your/input:/input -v /path/to/your/output:/output de.mdc_ari3d_<X.X.X> --input_dir /input --project_dir /output --parameters_file /input/parameters.json --gpus all

Where /path/to/your/input is the path to your input data on your system and /path/to/your/output is the path where you want to store the output data on your system. This call assumes parameters.json is in the input directory. It further assumes you have a GPU available. If you do not have a GPU, remove the --gpus all flag.

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:

cd ari3d
album docker --solution . --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"