diff --git a/docs/assets/screenshots/CLI-data_explorer.gif b/docs/assets/screenshots/CLI-data_explorer.gif
new file mode 100644
index 0000000000000000000000000000000000000000..72d468e8e0692d2aff8e8e0bb6b308f00655c83c
Binary files /dev/null and b/docs/assets/screenshots/CLI-data_explorer.gif differ
diff --git a/docs/assets/screenshots/qim3d-filters_example.png b/docs/assets/screenshots/qim3d-filters_example.png
index 3a138e386262efd85c3c8fa945e11c0f85b3745a..e58b32eb27b4f903e200c71b0c6a5b91f128a245 100644
Binary files a/docs/assets/screenshots/qim3d-filters_example.png and b/docs/assets/screenshots/qim3d-filters_example.png differ
diff --git a/docs/assets/screenshots/viz-orthogonal.gif b/docs/assets/screenshots/viz-orthogonal.gif
new file mode 100644
index 0000000000000000000000000000000000000000..eade0759bc4e3c040843cc19fa7ab89e36196f2c
Binary files /dev/null and b/docs/assets/screenshots/viz-orthogonal.gif differ
diff --git a/docs/assets/screenshots/viz-slicer.gif b/docs/assets/screenshots/viz-slicer.gif
new file mode 100644
index 0000000000000000000000000000000000000000..ec3dc2d60b7d74c193943c1a244725b1d22db9ae
Binary files /dev/null and b/docs/assets/screenshots/viz-slicer.gif differ
diff --git a/docs/cli.md b/docs/cli.md
index cae00a8ff1f6b2e157608e92cee6f09d73067de9..c45d7036f64b8bf77423bd77c27ed04c0481bcf1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,12 +1,14 @@
----
-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
+ ```
+ 
+
## Graphical User Interfaces
diff --git a/docs/gui.md b/docs/gui.md
index c8e06f66b5a66f054e3d3be5a8232fcba9ec81b8..5401cb85bd40f32e9d74fadfc531c3fa0dec8879 100644
--- a/docs/gui.md
+++ b/docs/gui.md
@@ -1,7 +1,3 @@
----
-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
+
+::: qim3d.gui.annotation_tool
+ options:
+ members: False
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index d040de0a677cd31e55924b5442f9dca86c989847..35e20390f2dd52f7513c12fa9041e9e83f9accb0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,8 +1,40 @@
# { 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.
+[](https://badge.fury.io/py/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)
+ ```
+ 
## 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.
diff --git a/docs/io.md b/docs/io.md
index 3d7ba7305f565f2221466e90284dd4f5884e2c79..3d15f97b206949d26a314edc9a8ec065a4c18b09 100644
--- a/docs/io.md
+++ b/docs/io.md
@@ -1,21 +1,33 @@
----
-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:
diff --git a/docs/models.md b/docs/models.md
index 4553f6f2cda74b93d5e2656538de20bfcd2354ea..17d5367551887b589cf1bdb837df019d1a65eeef 100644
--- a/docs/models.md
+++ b/docs/models.md
@@ -1,7 +1,3 @@
----
-icon: fontawesome/solid/robot
----
-
# Machine learning models
The `qim3d` library aims to ease the creation of ML models for volumetric images
diff --git a/docs/processing.md b/docs/processing.md
new file mode 100644
index 0000000000000000000000000000000000000000..8d4117079b22f17329dc5f8babf6ea027ba4254b
--- /dev/null
+++ b/docs/processing.md
@@ -0,0 +1,14 @@
+# Processing data
+
+::: qim3d.processing.filters
+ options:
+ members:
+ -
+
+
+::: qim3d.processing.filters.Pipeline
+ options:
+ members:
+ - append
+
+
diff --git a/docs/releases.md b/docs/releases.md
index 5713b599a492484364f07f4f6114c40f4de23b35..e029f4ad88c5c56fd7db4a8b199a51b57e6316cc 100644
--- a/docs/releases.md
+++ b/docs/releases.md
@@ -1,13 +1,17 @@
----
-icon: fontawesome/solid/bookmark
----
-
# Release History
+[](https://badge.fury.io/py/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)
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 18412ac7c5c27dd3380eaf79a4fc6cdbbb421eaa..ba35334e9ec9ce511401849f4ea207e947499321 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -1,21 +1,30 @@
+/*
+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;
-}
+}
.md-search__form {
border-radius: 8px;
@@ -68,4 +77,23 @@ 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
diff --git a/docs/utils.md b/docs/utils.md
index 3d4d38ec27688d3fe17ad3c8bf97c28c53101120..f86074f1b190446ad487521be309c3aa17515761 100644
--- a/docs/utils.md
+++ b/docs/utils.md
@@ -1,7 +1,3 @@
----
-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.
diff --git a/docs/viz.md b/docs/viz.md
index d13bbba5b44b70fea1e5e10617bf5252ce9c4fec..2cf4090324cec92191527575ca7edf2b85cf6d62 100644
--- a/docs/viz.md
+++ b/docs/viz.md
@@ -1,7 +1,3 @@
----
-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
+!!! Example
+ ```python
+ import qim3d
+
+ vol = qim3d.examples.bone_128x128x128
+ qim3d.viz.slicer(vol)
+ ```
+ 
+
+
+!!! Example
+ ```python
+ import qim3d
+
+ vol = qim3d.examples.fly_150x256x256
+ qim3d.viz.orthogonal(vol, cmap="magma")
+ ```
+ 
+
+
!!! Example
```python
import qim3d
@@ -25,10 +41,13 @@ The `qim3d`libray aims to provide easy ways to explore and get insights from vol
```
+
::: qim3d.viz.img
options:
members:
- slices
+ - slicer
+ - orthogonal
::: qim3d.viz.k3d
options:
diff --git a/mkdocs.yml b/mkdocs.yml
index 5c4532c22dc30272ca15099f3f0f9b13e5e5b9d0..5db3cae466759add3f7058f2ff389cb65be0dff8 100644
--- a/mkdocs.yml
+++ b/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
diff --git a/qim3d/gui/annotation_tool.py b/qim3d/gui/annotation_tool.py
index a096ae539ff051da8c6a1208ed758452d4b2474e..591f96d085b17b9ded972244fd72020357af1b4d 100644
--- a/qim3d/gui/annotation_tool.py
+++ b/qim3d/gui/annotation_tool.py
@@ -1,3 +1,20 @@
+"""
+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
diff --git a/qim3d/io/downloader.py b/qim3d/io/downloader.py
index b98e07e89246849e279e978910402ff671f41e12..a57871dd294e51977bc52266c3d97f26130aa312 100644
--- a/qim3d/io/downloader.py
+++ b/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
diff --git a/qim3d/io/load.py b/qim3d/io/load.py
index a761d3283ba7b87774210d82a1c6a29de4537827..3df15287e88588928041e401595a05a04579c7ef 100644
--- a/qim3d/io/load.py
+++ b/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).
+
+ 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(
diff --git a/qim3d/io/save.py b/qim3d/io/save.py
index e6c706a4b3b6bc71af077d9b9d32f58d3a54baaa..04cb72d392ec5ec35a8cfd44fbc40e2285bb2583 100644
--- a/qim3d/io/save.py
+++ b/qim3d/io/save.py
@@ -1,21 +1,23 @@
"""
-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
+
+ vol = qim3d.examples.fly_150x256x256
- qim3d.io.save("slices", img, basename="fly-slices", sliced_dim=0)
+ 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(
diff --git a/qim3d/utils/img.py b/qim3d/utils/img.py
index f485c13eeee0b9a61a95d59231575d60a769e0a8..347e4cc2ecbc1176ca4fc663884f7febbfc93598 100644
--- a/qim3d/utils/img.py
+++ b/qim3d/utils/img.py
@@ -1,7 +1,7 @@
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.
diff --git a/qim3d/viz/img.py b/qim3d/viz/img.py
index 3cf4e0ca0611cfcb30e02bfd7dd4ddd1b8204b4a..9ac1f29f502af066a701aeb489426872d9b4cb0c 100644
--- a/qim3d/viz/img.py
+++ b/qim3d/viz/img.py
@@ -412,9 +412,12 @@ def slicer(
slicer_obj (widgets.interactive): The interactive widget for visualizing slices of a 3D volume.
Example:
- vol_path = '/my_vol_path/my_vol.tif'
- vol = qim3d.io.load(vol_path)
- slicer(vol, axis = 1)
+ ```python
+ import qim3d
+
+ vol = qim3d.examples.bone_128x128x128
+ qim3d.viz.slicer(vol, cmap="magma")
+ ```
"""
# Create the interactive widget
@@ -468,9 +471,12 @@ def orthogonal(
orthogonal_obj (widgets.HBox): The interactive widget for visualizing orthogonal slices of a 3D volume.
Example:
- vol_path = '/my_vol_path/my_vol.tif'
- vol = qim3d.io.load(vol_path)
- orthogonal(vol)
+ ```python
+ import qim3d
+
+ vol = qim3d.examples.bone_128x128x128
+ qim3d.viz.orthogonal(vol)
+ ```
"""
z_slicer = slicer(
diff --git a/qim3d/viz/k3d.py b/qim3d/viz/k3d.py
index 1d3e712f33083d725a53d4b3ee5c8dcea0d6bb55..83fd50d190162216a24bb38c6d0d2767688f6b1b 100644
--- a/qim3d/viz/k3d.py
+++ b/qim3d/viz/k3d.py
@@ -24,7 +24,7 @@ def vol(img, show=True, save=False):
Returns:
k3d.plot: If show is False, returns the K3D plot object.
- Examples:
+ Example:
```python
import qim3d
vol = qim3d.examples.bone_128x128x128
@@ -32,6 +32,13 @@ def vol(img, show=True, save=False):
# shows the volume inline
qim3d.viz.vol(vol)
+ ```
+
+ Example:
+ ```python
+ import qim3d
+ vol = qim3d.examples.bone_128x128x128
+
# saves html plot to disk
plot = qim3d.viz.vol(vol, show=False, save="plot.html")
```