docs/cli.md

+# Command line interface
+The library also includes a command line interface for easy access to some functionalities, and the convenience of using qim3d directly from your terminal. 
+
+This offers quick interactions, making it ideal for tasks that require efficiency or when certain functionalities need to run on a server. 
+
+!!! Example
+    ```bash
+    qim3d gui --data-explorer
+    ```
+    ![CLI Data Explorer](assets/screenshots/CLI-data_explorer.gif)
+
+
+## Graphical User Interfaces
+
+### `qim3d gui`
+!!! quote "Reference"
+    The GUIs available in `qim3d` are built using Gradio:
+    <https://github.com/gradio-app/gradio>
+
+    ```bibtex
+    @article{abid2019gradio,
+    title = {Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild},
+    author = {Abid, Abubakar and Abdalla, Ali and Abid, Ali and Khan, Dawood and Alfozan, Abdulrahman and Zou, James},
+    journal = {arXiv preprint arXiv:1906.02569},
+    year = {2019},
+    }
+    ```
+| Arguments | Description |
+| --------- | ----------- |
+| `--data-explorer` | Starts the Data Explorer |
+| `--iso3d` | Starts the 3D Isosurfaces visualization |
+| `--local-thickness` | Starts the Local thickness tool |
+| `--host` | Desired host for the server. By default runs on `0.0.0.0`  |
+| `--platform` | Uses the Qim platform API for a unique path and port depending on the username |
+
+
+!!! Example
+
+    Here's an example of how to open the [Data Explorer](gui.md#data_explorer)
+
+    ```
+    qim3d gui --data-explorer
+    ```
+    ``` title="Output"
+    Running on local URL:  http://127.0.0.1:7860
+    ```
+
+    In this case, the GUI will be available at `http://127.0.0.1:7860`
+
+    ![Data explorer GUI](assets/screenshots/GUI-data_explorer.png)
+
+
+!!! Example
+
+    Or for the local thickness GUI:
+
+    ```
+    qim3d gui --local-thickness --host 127.0.0.1 --platform
+    ```
+
+    ``` title="Output"
+    {'username': 'fima', 'jupyter_port': '57326', 'gradio_port': '47326'}
+
+
+    ╭────────────────────────╮
+    │ Starting gradio server │
+    ├────────────────────────╯
+    ├ Gradio
+    ├ Using port 47326
+    ╰ Running at 10.52.0.158
+
+    http://127.0.0.1:47326/gui/fima/47326/
+    INFO:     Started server process [1534019]
+    INFO:     Waiting for application startup.
+    INFO:     Application startup complete.
+    INFO:     Uvicorn running on http://127.0.0.1:47326 (Press CTRL+C to quit)
+
+    ```
+
+    In this case, the GUI will be available at `http://127.0.0.1:47326/gui/fima/47326/`
+
+    ![Local thickness GUI](assets/screenshots/GUI-local_thickness.png)
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Data visualization
+The command line interface also allows you to easily visualize data.
+
+### `qim3d viz`
+!!! quote "Reference"
+    Volumetric visualization uses K3D:
+    [Github page](https://github.com/K3D-tools/K3D-jupyter)
+
+
+It is possible to launch the k3d visualization directly from the command line.
+
+| Arguments | Description |
+| --------- | ----------- |
+| `--source` | Path to the volume file (Any image format supported by `qim3d.io.load()`) |
+| `--destination` | Path to the `html` file to be saved. By default, `k3d.html` is saved where the command is run. |
+| `--no-browser` | Do not open the file when finished. |
+
+
+
+!!! Example
+    ```
+    qim3d viz --source blobs_256x256x256.tif
+    ```
+
+    ``` title="Output"
+    Loading data from blobs_256x256x256.tif
+    Done, volume shape: (256, 256, 256)
+
+    Generating k3d plot...
+    Done, plot available at <k3d.html>
+    Opening in default browser...
+    ```
+    And a new tab will be opened in the default browser with the interactive k3d plot:
+
+    ![CLI k3d](assets/screenshots/CLI-k3d.png){ width="512" }
+
+Or an specific path for destination can be used. We can also choose to not open the browser:
+
+!!! Example
+    ```
+    qim3d viz --source blobs_256x256x256.tif --destination my_plot.html --no-browser
+    ```
+    
+    ``` title="Output"
+    Loading data from blobs_256x256x256.tif
+    Done, volume shape: (256, 256, 256)
+
+    Generating k3d plot...
+    Done, plot available at <my_plot.html>
+    ```
+
+    This writes to disk the `my_plot.html` file.
+
+## File preview
+Command line interface, which allows users to preview 3D structers or 2D images directly in command line.
+###  `qim3d preview <filename>`
+| Arguments | Description |
+| --------- | ----------- |
+| `--axis` | Specifies from which axis the slice will be taken. If the object is 2D image, then this is ignored. Defaults to 0.|
+| `--slice` | Specifies which slice will be displayed. If the number exceeds number of slices, the last one is taken. Defaults to the middle slice.|
+| `--resolution` | How many characters will be used to display the image in command line. Defaults to 80.|
+| `--absolute_values` |If values are low the image might be just black square. By default maximum value is set to 255. This flag turns this behaviour off.|
+
+!!! Example
+    ```
+    qim3d preview blobs_256x256x256.tif 
+    ```
+
+    ![CLI k3d](assets/preview/default.png){ width="512" }
+
+!!! Example
+    ```
+    qim3d preview blobs_256x256x256.tif --resolution 30
+    ```
+
+    ![CLI k3d](assets/preview/res30.png){ width="512" }
+
+!!! Example
+    ```
+    qim3d preview blobs_256x256x256.tif --resolution 50 --axis 1
+    ```
+
+    ![CLI k3d](assets/preview/axis1.png){ width="512" }
+
+!!! Example
+    ```
+    qim3d preview blobs_256x256x256.tif --resolution 50 --axis 2 --slice 0
+    ```
+
+    ![CLI k3d](assets/preview/relativeIntensity.png){ width="512" }
+
+!!! Example
+    ```
+    qim3d preview qim_logo.png --resolution 40
+    ```
+
+    ![CLI k3d](assets/preview/qimLogo.png){ width="512" }

docs/generate.md

+# Generating synthetic data
+
+The `qim3d` library provides a set of methods for generating volumes consisting of a single synthetic blob or a collection of multiple synthetic blobs. 
+
+::: qim3d.generate
+    options:
+        members:
+            - blob
+            - collection

docs/gui.md

+# Graphical User Interfaces
+
+The `qim3d` library provides a set of custom made GUIs that ease the interaction with the available tools.
+
+!!! quote "Reference"
+    The GUIs available in `qim3d` are built using Gradio:
+    <https://github.com/gradio-app/gradio>
+
+    ```bibtex
+    @article{abid2019gradio,
+    title = {Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild},
+    author = {Abid, Abubakar and Abdalla, Ali and Abid, Ali and Khan, Dawood and Alfozan, Abdulrahman and Zou, James},
+    journal = {arXiv preprint arXiv:1906.02569},
+    year = {2019},
+    }
+    ```
+
+In general, the GUIs can be launched directly from the command line. 
+For details see [here](cli.md#qim3d-gui).
+
+::: qim3d.gui.data_explorer
+    options:
+        members: False
+![Data explorer GUI](assets/screenshots/GUI-data_explorer.png)
+
+::: qim3d.gui.local_thickness
+    options:
+        members: False
+![Local thickness GUI](assets/screenshots/GUI-local_thickness.png)
+
+::: qim3d.gui.iso3d
+    options:
+        members: False
+![Iso3d GUI](assets/screenshots/GUI-iso3d.png)
+
+::: qim3d.gui.annotation_tool
+    options:
+        members: False
\ No newline at end of file

docs/index.md

+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
+
+<audio id="audio" src="assets/qim3d.mp3"></audio>
+
+<script>
+document.addEventListener("DOMContentLoaded", function() {
+  const audio = document.getElementById("audio");
+  const playButton = document.getElementById("playButton");
+
+  playButton.addEventListener("click", function() {
+    const icon = playButton.querySelector("i");
+    if (audio.paused) {
+      audio.play();
+      icon.classList.remove("fa-circle-play");
+      icon.classList.add("fa-circle-pause");
+    } else {
+      audio.pause();
+      icon.classList.remove("fa-circle-pause");
+      icon.classList.add("fa-circle-play");
+    }
+  });
+
+  audio.addEventListener("ended", function() {
+    const icon = playButton.querySelector("i");
+    icon.classList.remove("fa-circle-pause");
+    icon.classList.add("fa-circle-play");
+  });
+});
+</script>
+
+# ![qim3d logo](assets/qim3d-logo.svg){ width="25%" }
+
+[![PyPI version](https://badge.fury.io/py/qim3d.svg)](https://badge.fury.io/py/qim3d)
+[![Downloads](https://static.pepy.tech/badge/qim3d)](https://pepy.tech/project/qim3d)
+
+The **`qim3d`** (kɪm θriː diː <button id="playButton"><i class="fa-regular fa-circle-play"></i></button>)  library is designed for **Quantitative Imaging in 3D** using Python. It offers a range of features, including data loading and manipulation, image processing and filtering, data visualization, and analysis of imaging results.
+
+You can easily load and process 3D image data from various file formats, apply filters and transformations to the data, visualize the results using interactive plots and 3D volumetric rendering.
+
+Whether you are working with medical imaging data, materials science data, or any other type of 3D imaging data, `qim3d` provides a convenient and powerful set of tools to help you analyze and understand your data.
+
+!!! Example "Interactive volume slicer"
+    ```python
+    import qim3d
+
+    vol = qim3d.examples.bone_128x128x128
+    qim3d.viz.slicer(vol)
+    ```
+    ![viz slicer](assets/screenshots/viz-slicer.gif)
+
+!!! Example "Synthetic data generation"
+    ```python
+    import qim3d
+
+    # Generate synthetic collection of blobs
+    num_objects = 15
+    synthetic_collection, labels = qim3d.generate.collection(num_objects = num_objects)
+
+    # Visualize synthetic collection
+    qim3d.viz.vol(synthetic_collection)
+    ```
+    <iframe src="https://platform.qim.dk/k3d/synthetic_collection_default.html" width="100%" height="500" frameborder="0"></iframe>
+
+!!! Example "Structure tensor"
+    ```python
+    import qim3d
+
+    vol = qim3d.examples.NT_128x128x128
+    val, vec = qim3d.processing.structure_tensor(vol, visualize = True, axis = 2)
+    ```
+
+    ![structure tensor](assets/screenshots/structure_tensor_visualization.gif)
+
+## Installation
+
+### Create environment
+
+Creating a `conda` environment is not required but recommended.
+
+??? info "Miniconda installation and setup"
+
+    [Miniconda](https://docs.anaconda.com/free/miniconda/index.html) is a free minimal installer for conda. 
+
+    Here are some quick instructions to help you set up the latest Miniconda installer for your system: 
+
+    === "Windows"
+
+        The easiest way to install Miniconda on Windows is through the graphical interface installer. Follow these steps:
+
+        1. Download the installer [here](https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe).
+        2. Run the installer and follow the on-screen instructions.
+        3. When the installation finishes, open `Anaconda Prompt (miniconda3)` from the Start menu.
+        
+    
+    === "macOS"
+ 
+        The easiest way to install Miniconda on macOS is through the graphical interface installer. Follow these steps:
+
+        1. Download the correct installer for your processor version. If you are unsure about your version, check [here](https://support.apple.com/en-us/116943).
+            - For Intel processors, download [x86](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.pkg)
+            - For Apple Silicon (M1/M2/M3 etc) processors, download [arm64](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.pkg)
+
+        2. Run the installer and follow the on-screen instructions.
+        
+    === "Linux"
+        These four commands quickly and quietly install the latest 64-bit version of the installer and then clean up after themselves. To install a different version or architecture of Miniconda for Linux, change the name of the `.sh` installer in the `wget` command.
+
+        ```bash
+        mkdir -p ~/miniconda3
+        wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
+        bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+        rm -rf ~/miniconda3/miniconda.sh
+        ```
+
+        After installing, initialize your newly-installed Miniconda. The following commands initialize for bash and zsh shells:
+
+        ```bash
+        ~/miniconda3/bin/conda init bash
+        ~/miniconda3/bin/conda init zsh
+        ```
+Once you have `conda` installed, open your terminal and create a new enviroment:
+
+    conda create -n qim3d python=3.11
+
+After the environment is created, activate it by running:
+
+    conda activate qim3d
+
+Remember, if you chose to create an environment to install `qim3d`, it needs to be activated each time before using the library.
+
+### Install using `pip`
+
+The latest stable version can be simply installed using `pip`. Open your terminal and run:
+
+    pip install qim3d
+
+!!! note
+    The base installation of `qim3d` does not include deep-learning dependencies, keeping the library lighter for scenarios where they are unnecessary. If you need to use deep-learning features, you can install the additional dependencies by running: **`pip install qim3d['deep-learning']`**
+
+### Troubleshooting
+
+Here are some solutions for commonly found issues during installation and usage of `qim3d`.
+
+#### Failed building
+
+Some Windows users could face an build error during installation.
+
+??? Bug "ERROR: Failed building wheel for noise"
+    ```
+    Building wheels for collected packages: noise, outputformat, asciitree, ffmpy
+    Building wheel for noise (setup.py) ... error
+    error: subprocess-exited-with-error
+
+    × python setup.py bdist_wheel did not run successfully.
+    │ exit code: 1
+    ╰─> [14 lines of output]
+        running bdist_wheel
+        running build
+        running build_py
+        creating build
+        creating build\lib.win-amd64-cpython-311
+        creating build\lib.win-amd64-cpython-311\noise
+        copying perlin.py -> build\lib.win-amd64-cpython-311\noise
+        copying shader.py -> build\lib.win-amd64-cpython-311\noise
+        copying shader_noise.py -> build\lib.win-amd64-cpython-311\noise
+        copying test.py -> build\lib.win-amd64-cpython-311\noise
+        copying __init__.py -> build\lib.win-amd64-cpython-311\noise
+        running build_ext
+        building 'noise._simplex' extension
+        error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
+        [end of output]
+
+    note: This error originates from a subprocess, and is likely not a problem with pip.
+    ERROR: Failed building wheel for noise
+    ```
+
+This issue occurs because the system lacks the necessary tools to compile the library requirements. To resolve this, follow these steps:
+
+- Go to the [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) page and click on "Download build tools."
+- Run the installer and ensure that `Desktop development with C++` is checked. ![Windows build tools](assets/screenshots/Troubleshooting-Windows_build_tools.png)
+- Restart your computer
+- Activate your conda enviroment and run `pip install qim3d` again
+
+#### Get the latest version
+
+The library is under constant development, so make sure to keep your installation updated:
+
+    pip install --upgrade qim3d
+
+## Collaboration
+
+Contributions to `qim3d` are welcome!
+
+If you find a bug, have a feature request, or would like to contribute code, please open an issue or submit a pull request.
+
+You can find us at Gitlab:
+[https://lab.compute.dtu.dk/QIM/tools/qim3d](https://lab.compute.dtu.dk/QIM/tools/qim3d
+)
+
+This project is licensed under the [MIT License](https://lab.compute.dtu.dk/QIM/tools/qim3d/-/blob/main/LICENSE).
+
+### Contributors
+
+Below is a list of contributors to the project, arranged in chronological order of their first commit to the repository:
+
+| Author                    |   Commits | First commit |
+|:--------------------------|----------:|-------------:|
+| Felipe Delestro           |       195 | 2023-05-12   |
+| Stefan Engelmann Jensen   |        29 | 2023-06-29   |
+| Oskar Kristoffersen       |        15 | 2023-07-05   |
+| Christian Kento Rasmussen |        22 | 2024-02-01   |
+| Alessia Saccardo          |         7 | 2024-02-19   |
+| David Grundfest           |         8 | 2024-04-12   |
+| Anna Bøgevang Ekner       |         5 | 2024-04-18   |
+
+## Support
+
+The development of `qim3d` is supported by:
+
+![Novo Nordisk Foundation](https://novonordiskfonden.dk//app/uploads/NNF-INT_logo_tagline_blue_RGB_solid.png){ width="256" }

docs/io.md

+# Data input and output
+Dealing with volumetric data can be done by `qim3d` for the most common image formats available.
+
+Currently, it is possible to directly load `tiff`, `h5`, `nii`,`txm`, `vol` and common `PIL` formats using one single function.
+
+::: qim3d.io
+    options:
+        members:
+            - load
+            - save
+            - Downloader
\ No newline at end of file

docs/models.md

+# Machine learning models
+
+The `qim3d` library aims to ease the creation of ML models for volumetric images
+
+::: qim3d.models.unet
\ No newline at end of file

docs/notebooks/README.md

 # Adding notebooks
 
-Jupyter notebooks can be added to this directory, but following this guidelines:
+Jupyter notebooks can be added to this directory, but following these guidelines:
 - File size should be kept under 5MB
 - Make a clean run of the notebook before saving and pushing
 - Add descriptions of the intent and processes happening

docs/notebooks/Untitled.ipynb

+%% Cell type:code id:0b73f2d8 tags:
+
+``` python
+import qim3d
+```
+
+%% Cell type:code id:73db6886 tags:
+
+``` python
+vol = qim3d.examples.bone_128x128x128
+```
+
+%% Cell type:code id:22d86d4d tags:
+
+``` python
+qim3d.viz.orthogonal(vol)
+```
+
+%% Output
+
+    HBox(children=(interactive(children=(IntSlider(value=64, description='Z', max=127), Output()), layout=Layout(a…

docs/notebooks/annotation_tool.ipynb

-%% Cell type:markdown id: tags:
-
-# Image annotation tool
-This notebook shows how the annotation interface can be used to create masks for images
-
 %% Cell type:code id: tags:
 
 ``` python
 import qim3d
 import matplotlib.pyplot as plt
-import matplotlib as mpl
-import numpy as np
-%matplotlib inline
-```
-
-%% Cell type:code id: tags:
-
-``` python
-# Load 2D example image
-img = qim3d.examples.blobs_256x256
 
-# Display image
-plt.imshow(img)
-plt.show()
-```
-
-%% Cell type:code id: tags:
+# Load example image
+vol = qim3d.examples.bone_128x128x128
 
-``` python
 # Start annotation tool
-interface = qim3d.gui.annotation_tool.Interface()
-interface.max_masks = 4
+annotation_tool = qim3d.gui.annotation_tool.Interface()
 
 # We can directly pass the image we loaded to the interface
-interface.launch(img=img)
+app = annotation_tool.launch(vol[0], server_name="10.197.104.229")
 ```
 
 %% Cell type:code id: tags:
 
 ``` python
-# When 'prepare mask for download' is pressed once, the mask can be retrieved with the get_result() method
-mask = interface.get_result()
+annotation_tool.get_result()
 ```
 
-%% Cell type:markdown id: tags:
-
-## Check the obtained mask
-
 %% Cell type:code id: tags:
 
 ``` python
-print (f"Original image shape..: {img.shape}")
-print (f"Mask image shape......: {mask.shape}")
-print (f"\nNumber of masks: {np.max(mask)}")
-```
-
-%% Cell type:markdown id: tags:
+%matplotlib inline
+import matplotlib.pyplot as plt
+from IPython.display import clear_output
+import numpy as np
+import time
 
-## Show the masked regions
+while True:
+    clear_output(wait=True)
+    masks_dict = annotation_tool.get_result()
+    if len(masks_dict) == 0:
+        masks_dict["No mask"] = np.zeros((32,32))
 
-%% Cell type:code id: tags:
+    fig, axs = plt.subplots(1, len(masks_dict), figsize=(8,3))
 
-``` python
-%matplotlib inline
+    if len(masks_dict) == 1:
+        axs = [axs]
+    for idx, (name, mask) in enumerate(masks_dict.items()):
 
-nmasks = np.max(mask)
-fig, axs = plt.subplots(nrows=1, ncols=nmasks+2, figsize=(12,3))
+        axs[idx].imshow(mask, cmap='gray', interpolation='none')
+        axs[idx].set_title(name)
+        axs[idx].axis('off')
 
-# Show original image
-axs[0].imshow(img)
-axs[0].set_title("Original")
-axs[0].axis('off')
-
-
-# Show masks
-cmap = mpl.colormaps["rainbow"].copy()
-cmap.set_under(color='black') # Sets the background to black
-axs[1].imshow(mask, interpolation='none', cmap=cmap, vmin=1, vmax=nmasks+1)
-axs[1].set_title("Masks")
-axs[1].axis('off')
-
-# Show masked regions
-for idx in np.arange(2, nmasks+2):
-    mask_id = idx-1
-    submask = mask.copy()
-    submask[submask != mask_id] = 0
-
-    masked_img = img.copy()
-    masked_img[submask==0] = 0
-    axs[idx].imshow(masked_img)
-    axs[idx].set_title(f"Mask {mask_id}")
+    plt.tight_layout()
 
-    axs[idx].axis('off')
 
-plt.show()
+    plt.show()
+    time.sleep(2)
 ```

docs/notebooks/filters.ipynb

+%% Cell type:code id: tags:
+
+``` python
+import qim3d
+import qim3d.processing.filters as filters
+import numpy as np
+from scipy import ndimage
+```
+
+%% Cell type:code id: tags:
+
+``` python
+vol = qim3d.examples.fly_150x256x256
+```
+
+%% Cell type:markdown id: tags:
+
+## Using the filter functions directly
+
+%% Cell type:code id: tags:
+
+``` python
+### Gaussian filter
+out1_gauss = filters.gaussian(vol,3)
+# or
+out2_gauss = filters.gaussian(vol,sigma=3) # sigma is positional, but can be passed as a kwarg
+
+### Median filter
+out_median = filters.median(vol,size=5)
+```
+
+%% Cell type:markdown id: tags:
+
+## Using filter classes
+
+%% Cell type:code id: tags:
+
+``` python
+gaussian_fn = filters.Gaussian(sigma=3)
+out3_gauss = gaussian_fn(vol)
+```
+
+%% Cell type:markdown id: tags:
+
+## Using filter classes to construct a pipeline of filters
+
+%% Cell type:code id: tags:
+
+``` python
+pipeline = filters.Pipeline(
+    filters.Gaussian(sigma=3),
+    filters.Median(size=10))
+out_seq = pipeline(vol)
+```
+
+%% Cell type:markdown id: tags:
+
+Filter functions can also be appended to the sequence after defining the class instance:
+
+%% Cell type:code id: tags:
+
+``` python
+pipeline.append(filters.Maximum(size=5))
+out_seq2 = pipeline(vol)
+```
+
+%% Cell type:markdown id: tags:
+
+The filter objects are stored in the `filters` dictionary:
+
+%% Cell type:code id: tags:
+
+``` python
+print(pipeline.filters)
+```
+
+%% Output
+
+    {'0': <qim3d.processing.filters.Gaussian object at 0x7b3fbdad7bb0>, '1': <qim3d.processing.filters.Median object at 0x7b3fbdad52a0>, '2': <qim3d.processing.filters.Maximum object at 0x7b40f7d3f6d0>}

docs/notebooks/segmentation_pipeline.ipynb

+%% Cell type:markdown id: tags:
+
+# Deep learning volume segmentation
+
+Authors: Alessia Saccardo (s212246@dtu.dk) & Felipe Delestro (fima@dtu.dk)
+
+This notebook aims to demonstrate the feasibility of implementing a comprehensive deep learning segmentation pipeline solely leveraging the capabilities offered by the qim3d library. Specifically, it will highlight the utilization of the annotation tool and walk through the process of creating and training a Unet model.
+
+%% Cell type:markdown id: tags:
+
+### Imports
+
+%% Cell type:code id: tags:
+
+``` python
+import qim3d
+import numpy as np
+import os
+```
+
+%% Cell type:markdown id: tags:
+
+### Load data
+Qim3d library contains a set of example volumes which can be easily loaded using `qim3d.examples.{volume_name}`
+
+%% Cell type:code id: tags:
+
+``` python
+vol = qim3d.examples.bone_128x128x128
+```
+
+%% Cell type:markdown id: tags:
+
+To easily have an insight of how the volume looks like we can interact with it using the `slicer` function from `qim3d`
+
+%% Cell type:code id: tags:
+
+``` python
+qim3d.viz.slicer(vol)
+```
+
+%% Cell type:markdown id: tags:
+
+# Generate dataset for training
+
+In order to train the classification model, we need to create a dataset from the volume.
+
+This means that we'll need a few slices to be used for `training` and at least one for the `test`
+
+%% Cell type:markdown id: tags:
+
+The dataset for training the model is managed by `qim3d.utils.prepare_datasets` and it expects files to follow this structure:
+
+<pre>
+dataset
+├── test
+│   ├── images
+│   │   └── FileA.png
+│   └── labels
+│       └── FileA.png
+└── train
+    ├── images
+    │   ├── FileB.png
+    │   └── FileC.png
+    └── labels
+        ├── FileB.png
+        └── FileC.png
+
+
+</pre>
+
+%% Cell type:code id: tags:
+
+``` python
+# Number of slices that will be used
+ntraining = 4
+ntest = 1
+```
+
+%% Cell type:markdown id: tags:
+
+In the following cell, we get the slice indices, making sure that we're not using the same indices for training and test.
+
+%% Cell type:code id: tags:
+
+``` python
+# Create a set with all the indices
+all_idxs = set(range(vol.shape[0]))
+
+# Get indices for training data
+training_idxs = list(np.random.choice(list(all_idxs), size=ntraining))
+print(f"Slices for training data...: {training_idxs}")
+
+# Get indices for test data
+test_idxs = list(np.random.choice(list(all_idxs - set(training_idxs)), size=ntest, replace=False))
+print(f"Slices for test data.......: {test_idxs}")
+```
+
+%% Cell type:markdown id: tags:
+
+## Create folder structure
+Here we create the necessary directories
+
+%% Cell type:code id: tags:
+
+``` python
+# Base path for the training data
+base_path = os.path.expanduser("~/dataset")
+
+# Create directories
+print("Creating directories:")
+for folder_split in ["train", "test"]:
+    for folder_type in ["images", "labels"]:
+        path = os.path.join(base_path, folder_split, folder_type)
+        os.makedirs(path, exist_ok=True)
+        print(path)
+
+# Here we have the option to remove any previous files
+clean_files = True
+if clean_files:
+    for root, dirs, files in os.walk(base_path):
+        for file in files:
+            file_path = os.path.join(root, file)
+            os.remove(file_path)
+```
+
+%% Cell type:markdown id: tags:
+
+# Annotate data
+
+The following cell will generate an annotation tool for each slice that was requested.
+
+You should use the tool to drawn a mask over the structures you're willing to detect, and press the button `Update` so that the mask is saved.
+
+%% Cell type:code id: tags:
+
+``` python
+annotation_tools = {}
+for idx in training_idxs + test_idxs:
+    if idx in training_idxs:
+        subset = "training"
+    elif idx in test_idxs:
+        subset = "test"
+    annotation_tools[idx] = qim3d.gui.annotation_tool.Interface()
+    annotation_tools[idx].name_suffix = f"_{idx}"
+    print(f"Annotation for slice {idx} ({subset})")
+    annotation_tools[idx].launch(vol[idx])
+```
+
+%% Cell type:markdown id: tags:
+
+### Getting masks from the annotation tool
+The masks are stored in the annotation tool when the button `Update` is pressed
+
+Here we extract the masks and save them to disk, followign the standard needed for the DL model
+
+%% Cell type:code id: tags:
+
+``` python
+print("Saving images and masks to disk")
+for idx in training_idxs + test_idxs:
+
+    if idx in training_idxs:
+        folder_split = "train"
+
+    elif idx in test_idxs:
+        folder_split = "test"
+
+    print (f"- slice {idx} ({folder_split})")
+    mask_dict = annotation_tools[idx].get_result()
+    mask = list(mask_dict.values())[0]
+
+    # Save image
+    qim3d.io.save(os.path.join(base_path,folder_split,"images",f"{idx}.png"), vol[idx], replace=True)
+    # Save label
+    qim3d.io.save(os.path.join(base_path,folder_split,"labels",f"{idx}.png"), mask, replace=True)
+```
+
+%% Cell type:markdown id: tags:
+
+# Build Unet
+
+%% Cell type:markdown id: tags:
+
+Building and training the Unet model is straightforward using `qim3d`.
+
+We first need to instantiate the model by defying its size, which can be either *small*, *medium* or *large*.
+
+%% Cell type:code id: tags:
+
+``` python
+# defining model
+model = qim3d.models.UNet(size = 'small', dropout = 0.25)
+```
+
+%% Cell type:markdown id: tags:
+
+Then we need to decide which type of augumentation to apply to the data.
+
+The `qim3d.utils.Augmentation` allows to specify how the images should be reshaped to the appropriate size and the level of transformation to apply respectively to train, test and validation sets.
+
+The resize must be choosen between [*crop*, *reshape*, *padding*] and the level of transformation must be chosse between [*None*, *light*, *moderate*, *heavy*]. The user can also specify the mean and standard deviation values for normalizing pixel intensities.
+
+%% Cell type:code id: tags:
+
+``` python
+# defining augmentation
+aug = qim3d.utils.Augmentation(resize = 'crop', transform_train = 'light')
+```
+
+%% Cell type:markdown id: tags:
+
+Then the datasets and dataloaders are instantiated
+
+%% Cell type:code id: tags:
+
+``` python
+# datasets and dataloaders
+train_set, val_set, test_set = qim3d.utils.prepare_datasets(path = base_path,
+                                                            val_fraction = 0.5,
+                                                            model = model,
+                                                            augmentation = aug)
+
+
+train_loader, val_loader, test_loader = qim3d.utils.prepare_dataloaders(train_set,
+                                                                        val_set,
+                                                                        test_set,
+                                                                        batch_size = 1)
+```
+
+%% Cell type:markdown id: tags:
+
+The hyperparameters are defined using the function `qim3d.models.Hyperparameters` and the model can be easily trained by running the function `qim3d.utils.train_model` which returns also a plot of the losses at the end of the training if the option is selected by the user
+
+%% Cell type:markdown id: tags:
+
+# Train model
+
+%% Cell type:code id: tags:
+
+``` python
+# model hyperparameters
+hyperparameters = qim3d.models.Hyperparameters(model, n_epochs=10,
+                                               learning_rate = 5e-3, loss_function='DiceCE',
+                                               weight_decay=1e-3)
+
+# training model
+qim3d.utils.train_model(model, hyperparameters, train_loader, val_loader, plot=True)
+```
+
+%% Cell type:markdown id: tags:
+
+# Check results
+
+To compute the inference step it is just needed to run `qim3d.utils.inference`.
+
+The results can be visualize with the function `qim3d.viz.grid_pred` that shows the predicted segmentation along with a comparison between the ground truth.
+
+%% Cell type:code id: tags:
+
+``` python
+in_targ_preds_test = qim3d.utils.inference(test_set, model)
+qim3d.viz.grid_pred(in_targ_preds_test,alpha=1)
+```
+
+%% Cell type:markdown id: tags:
+
+# Compute inference on entire volume
+
+Given that the input is a volume, the goal is to perform inference on the entire volume rather than individual slices.
+
+By using the function `qim3d.utils.volume_inference` it is possible to obtain the segmentation volume output
+
+%% Cell type:code id: tags:
+
+``` python
+inference_vol = qim3d.utils.models.volume_inference(vol, model)
+qim3d.viz.slicer(inference_vol)
+```
+
+%% Cell type:markdown id: tags:
+
+We can also visualize the created mask together with the original volume
+
+%% Cell type:code id: tags:
+
+``` python
+vol_masked = qim3d.viz.vol_masked(vol, inference_vol, viz_delta=128)
+qim3d.viz.slicer(vol_masked, cmap="PiYG")
+```

docs/notebooks/structure_tensor.ipynb

+%% Cell type:code id: tags:
+
+``` python
+import qim3d
+```
+
+%% Cell type:markdown id: tags:
+
+### Structure tensor notebook
+
+%% Cell type:markdown id: tags:
+
+This notebook shows how to compute eigenvalues and eigenvectors of the **structure tensor** of a 3D volume using the `qim3d` library. The structure tensor (matrix) represents information about the local gradient directions in the volume, such that the eigenvectors represent the orientation of the structure in the volume, and the corresponding eigenvaleus indicate the magnitude.
+
+The function `qim3d.processing.structure_tensor` returns two arrays `val` and `vec` for the eigenvalues and eigenvectors, respectively.\
+By having the argument `visulize = True`, the function displays a figure of three subplots:
+
+* Slice of volume with vector field of the eigenvectors
+* Orientation histogram of the eigenvectors
+* Slice of volume with overlaying colors of the orientation
+
+For all three subplots, the colors used to visualize the orientation within the volume are from the HSV colorspace. In these visualizations, the saturation of the color corresponds to the vector component of the slicing direction (i.e. $z$-component when choosing visualization along `axis = 0`). Hence, if an orientation in the volume is orthogonal to the slicing direction, the corresponding color of the visualization will be gray.
+
+%% Cell type:markdown id: tags:
+
+### **Example:** Structure tensor of brain tissue volume
+
+%% Cell type:code id: tags:
+
+``` python
+# Import 3D volume of brain tissue
+NT = qim3d.examples.NT_128x128x128
+
+# Visuaize the 3D volume
+qim3d.viz.vol(NT)
+```
+
+%% Output
+
+
+%% Cell type:markdown id: tags:
+
+From the visualization of the full volume, it can be seen that the circular structures of the brain tissue are aligned orthogonal to the $z$-axis (`axis = 0`). By choosing to slice the volume in this direction, the structure tensor visualizations will largely be gray, since the $z$-component of the eigenvectors are close to $0$, meaning the saturation of the coloring will be close to $0$ (i.e. gray). This can be seen below.
+
+%% Cell type:code id: tags:
+
+``` python
+# Compute eigenvalues and eigenvectors of the structure tensor
+val, vec = qim3d.processing.structure_tensor(NT, visualize = True, axis = 0) # Slicing in z-direction
+```
+
+%% Output
+
+
+%% Cell type:markdown id: tags:
+
+By slicing the volume in the $x$-direction (`axis = 2`) instead, the orientation along the length of the structures in the brain tissue can be seen instead. Then the structure tensor visualizations will be largely blue, corresponding to eigenvectors along the $x$-direction with angles of $\approx \frac{\pi}{2}$ radians ($90$ degrees).
+
+%% Cell type:code id: tags:
+
+``` python
+# Compute eigenvalues and eigenvectors of the structure tensor
+val, vec = qim3d.processing.structure_tensor(NT, visualize = True, axis = 2) # Slicing in x-direction
+```
+
+%% Output
+

docs/processing.md

+# Processing data
+
+Here, we provide functionalities designed specifically for 3D image analysis and processing. From filter pipelines to structure tensor computation and blob detection, `qim3d` equips you with the tools you need to extract meaningful insights from your data.
+
+::: qim3d.processing
+    options:
+        members:
+            - blob_detection
+            - structure_tensor
+            - local_thickness
+            - get_3d_cc
+            - gaussian
+            - median
+            - maximum
+            - minimum
+            - tophat
+
+::: qim3d.processing.Pipeline
+    options:
+        members:
+            - append
+
+::: qim3d.processing.operations
+    options:
+        members:
+            - remove_background
+            - watershed
+            - fade_mask
+            - overlay_rgb_images

docs/releases.md

+# Release History
+[![PyPI version](https://badge.fury.io/py/qim3d.svg)](https://badge.fury.io/py/qim3d)
+[![Downloads](https://static.pepy.tech/badge/qim3d)](https://pepy.tech/project/qim3d)
+
+
+Below, you'll find details about the version history of `qim3d`.
+
+As the library is still in its early development stages, **there may be breaking changes** before `v1.0` without prior deprecation warnings. Therefore, it's advisable to review the release history for more information if you encounter any issues.
+
+And remember to keep your pip installation [up to date](/qim3d/#get-the-latest-version) so that you have the latest features!
+
+### v0.4.1 (30/07/2024)
+
+- Fixed issue with example volumes not being loaded
+
+### v0.4.0 (29/07/2024)
+
+- Refactored imports to use lazy loading
+- Namespace `utils` reserved for internal tools only
+- All deep-learning related functions moved to `models`
+- Running `pip install qim3d` does not install DL requirements. For those, use `pip install qim3d['deep-learning']` 
+
+
+### v0.3.9 (24/07/2024)
+
+- Loading and saving for Zarr files
+- File convertion using the CLI, including Zarr
+- Refactoring for the GUIs
+- Color visualization for structure tensor ![Color visualization for structure tensor](assets/screenshots/releases/qim3d-structure_tensor_with_colors.gif)
+- Refactoring for synthetic data generation, from `utils` to `generate`
+- Introduction of `qim3d.generate.collection` 🎉 ![Introduction of `qim3d.generate.collection`](assets/screenshots/releases/qim3d-generate_collection.gif)
+
+### v0.3.8 (20/06/2024)
+
+- Minor refactoring and bug fixes
+
+### v0.3.7 (17/06/2024)
+
+- Performance improvements when importing 
+- Refactoring for blob detection ![Refactoring for blob detection](assets/screenshots/releases/qim3d-blob_detection_refactoring.gif)
+
+
+### v0.3.6 (30/05/2024)
+
+- Refactoring for performance improvement
+- Welcome message for the CLI
+- Introduction of `qim3d.processing.fade_mask` 🎉 ![Introduction of `qim3d.processing.fade_mask`](assets/screenshots/releases/qim3d-fade_viz.gif)
+
+
+
+### v0.3.5 (27/05/2024)
+
+- Added runtime and memory usage in the documentation
+- Introduction of `qim3d.utils.generate_volume` 🎉 ![Introduction of `qim3d.utils.generate_volume`](assets/screenshots/releases/qim3d-synthetic_volume.gif)
+- CLI refactoring, adding welcome message to the user ![CLI refactoring](assets/screenshots/releases/qim3d-CLI_welcome_message.png)
+- Introduction of `preview` CLI 🎉
+
+
+### v0.3.4 (22/05/2024)
+
+- Documentation for `qim3d.viz.plot_cc`
+- Fixed issue with Annotation tool and recent Gradio versions
+- New colormap: `qim3d.viz.colormaps.qim`, showcasing the Qim colors!
+- Object separation using `qim3d.processing.operations.watershed`
+- Added option to pass `dim_order` to `vol/vgi` files
+- The 'Data Explorer' GUI now can load image sequences also
+- Warning in case user tries to load a file larger than available memory
+- Objects colormap now can enforce a `min_dist` between neighbor colors
+- It is possible to load a directory with a sequence of PIL images
+- Aspect ratio issue for k3d fixed
+
+### v0.3.3 (11/04/2024)
+
+- Introduction of `qim3d.viz.slicer` (and also `qim3d.viz.orthogonal` ) 🎉
+- Introduction of `qim3d.gui.annotation_tool` 🎉
+- Introduction of `qim3d.processing.Blob` for blob detection 🎉
+- Introduction of `qim3d.processing.local_thickness` 🎉
+- Introduction of `qim3d.processing.structure_tensor` 🎉
+- Support for loading DICOM files with `qim3d.io.load`
+- Introduction of `qim3d.processing.get_3d_cc` for 3D connected components and `qim3d.viz.plot_cc` for associated visualization 🎉
+- Introduction of `qim3d.viz.colormaps` for easy visualization of e.g. multi-label segmentation results 🎉
+- Introduction of `qim3d.processing.operations.background_removal` 🎉
+- Documentation refactoring
+- Fixed bug preventing `Data Explorer` to show files
+
+### v0.3.2 (23/02/2024)
+
+This version focus on the increased usability of the `qim3d` library
+
+- Online documentation available at [https://platform.qim.dk/qim3d](https://platform.qim.dk/qim3d)
+- Virtual stacks also available for `txm` files
+- Updated GUI launch pipeline
+- New functionalities for `qim3d.viz.slices`
+- Introduction of `qim3d.processing.filters` 🎉 
+- Introduction of `qim3d.viz.vol` 🎉 
+
+### v0.3.1 (01/02/2024)
+
+Release expanding the IO functionalities
+
+- Support for loading `vol` `nii` and `bigtiff` files
+- Data loader now supports `virtual_stack`
+- Save functionality for all file formats except `txm`
+
+### v0.3.0 (23/01/2024)
+- Introduction of qim3d CLI 🎉 
+- Introduction of memory utils 🎉 
+- Data Explorer GUI
+- Save functionality for `tif` files
+
+### v0.2.0 (18/09/2023)
+
+Includes new develoments toward the usability of the library, as well as its integration with the QIM platform.
+
+- Refactored code for the graphical interfaces
+    - For the local thicknes GUI, now it is possible to pass and receive numpy arrays instead of using the upload functionality.
+- Improved data loader
+    - Now the extensions `tif`, `h5` and `txm` are supported.
+- Added `qim3d.viz.slices` for easy slice visualization.
+- U-net model creation
+    - Model availabe from `qim3d.models.UNet`
+    - Data augmentation class at `qim3d.utils.Augmentation`
+    - Notebook with full pipeline at `docs/notebooks/Unet.ipynb`
+- Image examples accessible from `qim3d.examples`
+
+
+### v0.1.3 (17/05/2023)
+
+First stable release.
+
+- Simple Tiff data loader
+- Graphical interfaces
+    - Local thickness
+    - 3D Isosurfaces
+    - Data exploration tool
\ No newline at end of file

docs/stylesheets/extra.css

+/* 
+qim3d colors:
+#ff9900
+#cd4d00
+#990000
+*/
+
+
+code {
+  border-radius: 6px !important;
+}
+
+
+.md-content h1 {
+  font-size: 2.5em !important;
+}
+
+.md-content h2 {
+  margin-top: 5em !important;
+  font-size: 2em !important;
+}
+
+
+.md-content h3 {
+  margin-top: 2.5em !important;
+  font-size: 1.5em !important;
+} 
+
+.md-content h4 {
+  margin-top: 2em !important;
+  margin-bottom: -0.5em !important;
+
+  font-size: 1.1em !important;
+} 
+
+.md-search__form {
+  border-radius: 8px;
+}
+
+.md-search__form:hover {
+  background-color: #f0f0f0 !important;
+}
+
+.md-search__inner {
+  border-radius: 0px !important;
+}
+
+.md-nav__item .md-nav__link--active,
+.md-nav__item .md-nav__link--active code {
+  color: orange
+}
+
+.md-typeset a {
+  color: orange;
+  word-break: break-word;
+}
+
+.md-nav__link {
+  font-size: 1.0em;
+}
+
+.md-nav:first-child {
+  font-size: 2.0em;
+}
+
+
+.md-tabs__list li:last-child {
+  margin-left: auto;
+}
+
+
+.md-header__source {
+  text-align: right;
+}
+
+.md-header__title {
+  margin-left: 0px !important;
+}
+
+
+.doc-module {
+  margin-top: 128px !important;
+}
+
+.md-main{
+  margin-bottom: 256px;
+}
+
+.md-sidebar{
+  top:150px !important;
+}
+
+
+/* Colors for example box */
+
+.md-typeset .example>.admonition-title, .md-typeset .example>summary{
+  background-color: #ff990020
+}
+
+.md-typeset .example>.admonition-title:before, .md-typeset .example>summary:before {
+  background-color: #ff9900
+}
+
+.md-typeset .admonition.example, .md-typeset details.example {
+  border-color: #ff9900;
+}
+
+.md-typeset .example>.admonition-title:after, .md-typeset .example>summary:after {
+  color: #ff9900;
+}
+
+#playButton {
+  cursor: pointer;
+  margin-top: 0.05em;
+  vertical-align: middle;
+}

docs/utils.md

+# Utils
+
+A set of tools to ease managment of the system, with the common needs for large data in mind.
+
+::: qim3d.utils.system
+    options:
+      members:
+        - Memory
\ No newline at end of file

docs/version_history.md

-# Release history
-Here you can fin details about the version history of `qim3d`
-
-
-## v0.2.0 (Sept 18, 2023)
-```pip install qim3d==0.2.0```
-
-Includes new develoments toward the usability of the library, as well as its integration with the QIM platform.
-
-- Refactored code for the graphical interfaces
-    - For the local thicknes GUI, now it is possible to pass and receive numpy arrays instead of using the upload functionality.
-- Improved data loader
-    - Now the extensions `tif`, `h5` and `txm` are supported.
-- Added `qim3d.viz.slice_viz` for easy slice visualization.
-- U-net model creation
-    - Model availabe from `qim3d.models.UNet`
-    - Data augmentation class at `qim3d.utils.Augmentation`
-    - Notebook with full pipeline at `docs/notebooks/Unet.ipynb`
-- Image examples accessible from `qim3d.examples`
-
-
-## v0.1.3 (May 17, 2023)
-```pip install qim3d==0.1.3```
-
-First stable release.
-
-- Simple Tiff data loader
-- Graphical interfaces
-    - Local thickness
-    - 3D Isosurfaces
-    - Data exploration tool
\ No newline at end of file