Merge branch 'docs_update' into 'main'

Docs update

See merge request !62

docs/cli.md

----
-icon: fontawesome/solid/keyboard
----
-
 # 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
 

docs/gui.md

----
-icon: fontawesome/solid/window-maximize
----
-
 # Graphical User Interfaces
 
 The `qim3d` library provides a set of custom made GUIs that ease the interaction with the available tools.
@@ -21,6 +17,7 @@ The `qim3d` library provides a set of custom made GUIs that ease the interaction
 
 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
@@ -35,3 +32,7 @@ For details see [here](cli.md#qim3d-gui).
     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

 # ![qim3d logo](assets/qim3d-logo.svg){ width="256" }
 
-`qim3d` is a Python library for quantitative imaging analysis in 3D. It provides functionality for handling data, as well as tools for visualization and analysis.
+[![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` library is designed to make it easier to work with 3D imaging data in Python. It offers a range of features, including data loading and manipulation, image processing and filtering, visualization of 3D data, 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 rendering, and perform quantitative analysis on the images.
+
+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
+    ```python
+    import qim3d
+    import qim3d.processing.filters as filters
+
+    # Get data
+    vol = qim3d.examples.fly_150x256x256
+
+    # Show original
+    qim3d.viz.slices(vol, show=True)
+
+    # Create filter pipeline
+    pipeline = filters.Pipeline(
+        filters.Median(size=5),
+        filters.Gaussian(sigma=3))
+
+    # Apply pipeline
+    filtered_vol = pipeline(vol)
+
+
+    # Show filtered
+    qim3d.viz.slices(filtered_vol)
+    ```
     ![Data explorer GUI](assets/screenshots/qim3d-filters_example.png)
 
 ## Installation
@@ -15,16 +47,26 @@ After the environment is created, activate it by running:
 conda activate qim3d
 ```
 
-Install the latest stable version by using `pip`:
+
+### Install using `pip`
+
+The latest stable version can be simply installed using `pip`:
 
 ```
 pip install qim3d
 ```
-!!! warning
+
+!!! note
     Installing `qim3d` may take a bit of time due to its dependencies. Thank you for your patience!
 
+### Upgrade
+
+The library is under constant development, so make sure to keep your installation updated:
+```
+pip install --upgrade qim3d
+```
 
-## Contributing
+## 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.

docs/io.md

----
-icon: fontawesome/solid/database
----
 # 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.
 
 
+!!! Example
+    ```python
+    import qim3d
+
+    # Get some data from examples
+    vol = qim3d.examples.blobs_256x256x256
+
+    # Save in a local file
+    qim3d.io.save("blobs.tif", vol)
+
+    # Load data from file
+    loaded_vol = qim3d.io.load("blobs.tif")
+    ```
+
 ::: qim3d.io.load
     options:
         members:
-            - DataLoader
+            - load
 
 ::: qim3d.io.save
     options:
         members:
-            - DataSaver
+            - save
+
 ::: qim3d.io.downloader
     options:
         members:

docs/models.md

----
-icon: fontawesome/solid/robot
----
-
 # Machine learning models
 
 The `qim3d` library aims to ease the creation of ML models for volumetric images

docs/processing.md

+# Processing data
+
+::: qim3d.processing.filters
+    options:
+        members:
+            - 
+
+
+::: qim3d.processing.filters.Pipeline
+    options:
+        members:
+            - append
+
+

docs/releases.md

----
-icon: fontawesome/solid/bookmark
----
-
 # 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.
+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/#upgrade) so that you have the latest features!
 
+### v0.3.3 (coming soon!)
+- Introduction of `qim3d.viz.slicer` (and also `qim3d.viz.orthogonal` ) 🎉
+- Introduction of `qim3d.gui.annotation_tool` 🎉
 
 ### v0.3.2 (23/02/2024)
 

docs/stylesheets/extra.css

+/* 
+qim3d colors:
+#ff9900
+#cd4d00
+#990000
+*/
+
+
 code {
   border-radius: 6px !important;
 }
 
 
-h1 {
+.md-content h1 {
   font-size: 2.5em !important;
 }
 
-h2 {
+.md-content h2 {
   margin-top: 5em !important;
   font-size: 2em !important;
 }
 
-h3 {
+
+.md-content h3 {
   margin-top: 2em !important;
   font-size: 1.5em !important;
 } 
@@ -69,3 +78,22 @@ h3 {
 .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;
+}
\ No newline at end of file

docs/utils.md

----
-icon: fontawesome/solid/screwdriver-wrench
----
-
 # Utils
 
 A set of tools to ease managment of the system, with the common needs for large data in mind.

docs/viz.md

----
-icon: fontawesome/solid/images
----
-
 # Data visualization
 The `qim3d`libray aims to provide easy ways to explore and get insights from volumetric data. 
 
@@ -16,6 +12,26 @@ The `qim3d`libray aims to provide easy ways to explore and get insights from vol
     ![Grid of slices](assets/screenshots/viz-slices.png)
 
 
+!!! Example
+    ```python
+    import qim3d
+
+    vol = qim3d.examples.bone_128x128x128
+    qim3d.viz.slicer(vol)
+    ```
+    ![viz slicer](assets/screenshots/viz-slicer.gif)
+
+
+!!! Example
+    ```python
+    import qim3d
+
+    vol = qim3d.examples.fly_150x256x256
+    qim3d.viz.orthogonal(vol, cmap="magma")
+    ```
+    ![viz orthogonal](assets/screenshots/viz-orthogonal.gif)
+
+
 !!! Example
     ```python
     import qim3d
@@ -25,10 +41,13 @@ The `qim3d`libray aims to provide easy ways to explore and get insights from vol
     ```
     ![viz k3d](assets/screenshots/viz-k3d.png)
 
+
 ::: qim3d.viz.img
     options:
         members:
             - slices
+            - slicer
+            - orthogonal
 
 ::: qim3d.viz.k3d
     options:

mkdocs.yml

@@ -7,13 +7,16 @@ repo_name: Gitlab
 
 
 nav:
+   
   - qim3d: index.md
   - Input & Output: io.md
+  - Processing: processing.md
   - Visualization: viz.md
   - Utils: utils.md
   - GUIs: gui.md
   - ML Models: models.md
   - CLI: cli.md
+
   - Release history: releases.md
 
 theme:
@@ -24,11 +27,13 @@ theme:
   favicon: assets/qim3d-icon.svg
   features: 
     - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.sections
-    # - navigation.expand
-    # - navigation.instant
+    - navigation.expand
+    - navigation.instant
+    # - navigation.tracking
     - toc.integrate
-    - toc.follow
+    # - toc.follow
     - search.suggest
     # - content.tabs.link
     # - content.code.annotation

qim3d/gui/annotation_tool.py

+"""
+The GUI can be launched directly from the command line:
+
+```bash
+qim3d gui --annotation-tool
+```
+
+Or launched from a python script
+
+```python
+import qim3d
+
+app = qim3d.gui.annotation_tool.Interface()
+app.launch()
+```
+"""
+
 import tifffile
 import tempfile
 import os

qim3d/io/downloader.py

@@ -13,10 +13,10 @@ import outputformat as ouf
 
 
 class Downloader:
-    """Class for downloading large data files available on the QIM data repository.
+    """Class for downloading large data files available on the [QIM data repository](https://data.qim.dk/data-repository/).
 
     Attributes:
-        [folder_name] (str): folder class with the name of the folder in [https://data.qim.dk/data-repository/](https://data.qim.dk/data-repository/)
+        [folder_name] (str): folder class with the name of the folder in https://data.qim.dk/data-repository/
 
     Example:
         ```python

qim3d/io/load.py

@@ -546,11 +546,17 @@ def load(
 
     Returns:
         numpy.ndarray, numpy.memmap, h5py._hl.dataset.Dataset, nibabel.arrayproxy.ArrayProxy or tuple: The loaded volume.
+
         If 'virtual_stack' is True, returns numpy.memmap, h5py._hl.dataset.Dataset or nibabel.arrayproxy.ArrayProxy depending on file format
+        
         If 'return_metadata' is True and file format is either HDF5, NIfTI or TXRM/TXM/XRM, returns a tuple (volume, metadata).
 
     Example:
-        data = qim3d.io.load("image.tif", virtual_stack=True)
+        ```python
+        import qim3d
+
+        vol = qim3d.io.load("path/to/image.tif", virtual_stack=True)
+        ```
     """
 
     loader = DataLoader(

qim3d/io/save.py

 """
-Provides functionality for loading data from various file formats.
+Provides functionality for saving data from various file formats.
 
 
 Example:
     ```python
     import qim3d
-    img = qim3d.examples.fly_150x256x256
     
-    qim3d.io.save("img.tif", img)
+    vol = qim3d.examples.fly_150x256x256
+    
+    qim3d.io.save("fly.tif", vol)
     ```
 
     Volumes can also be saved with one file per slice:
     ```python
     import qim3d
-    img = qim3d.examples.fly_150x256x256
 
-    qim3d.io.save("slices", img, basename="fly-slices", sliced_dim=0)
+    vol = qim3d.examples.fly_150x256x256
+    
+    qim3d.io.save("slices", vol, basename="fly-slices", sliced_dim=0)
     ```
 
 """
@@ -305,8 +307,12 @@ def save(
         **kwargs: Additional keyword arguments to be passed to the DataSaver constructor
 
     Example:
-        image = qim3d.examples.blobs_256x256
-        qim3d.io.save("image.tif",image,compression=True)
+        ```python
+        import qim3d
+
+        vol = qim3d.examples.blobs_256x256x256
+        qim3d.io.save("blobs.tif", vol)
+        ```
     """
 
     DataSaver(

qim3d/utils/img.py

 import numpy as np
 
 def overlay_rgb_images(background, foreground, alpha=0.5):
-    """Overlay multiple RGB foreground onto an RGB background image using alpha blending.
+    """Overlay a RGB foreground onto an RGB background using alpha blending.
 
     Args:
         background (numpy.ndarray): The background RGB image.