Skip to content

Commit bf31a08

Browse files
loic-lbloic-lb
committed
docs: Update mkdocs configuration, add CLI and examples sections, and introduce default contouring and patching configurations.
1 parent cee43f7 commit bf31a08

File tree

7 files changed

+378
-1
lines changed

7 files changed

+378
-1
lines changed

‎config/default_contouring.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Default configuration for PrismToolBox contouring
2+
3+
# Tissue contour extraction parameters
4+
contouring:
5+
seg_level: 2 # (int) Segmentation level for the tissue contour extraction.
6+
window_avg: 30 # (int) Size of the window average for tissue extraction.
7+
window_eng: 3 # (int) Size of the window to use for computing energy for tissue extraction.
8+
thresh: 120 # (int) Threshold for the tissue extraction algorithm.
9+
area_min: 6000 # (int) Minimum area for the tissue contour.
10+
11+
# Tissue visualization parameters
12+
visualizing:
13+
vis_level: 2 # (int) Visualization level for the tissue contour extraction.
14+
number_contours: false # (bool) Plot the id number for each contour.
15+
line_thickness: 50 # (bool) Line thickness for the contour visualization.

‎config/default_patching.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Default configuration for PrismToolBox patching
2+
3+
# Patch extraction parameters
4+
patching:
5+
patch_level: 0 # (float) Level of the slide to extract patches from.
6+
patch_size: 256 # (float) Size of the patches to extract.
7+
overlap: 0 # (float) Overlap between the patches.
8+
units: ["px", "px"] # (str, str) Units for the patch size and overlap. Options are 'pixels' or 'micro' for micrometers.
9+
contours_mode: "four_pt" # (str) The mode to use for the contour checking. Possible values are center, four_pt, and four_pt_hard.
10+
rgb_threshs: [2, 240] # (int, int) The thresholds for the RGB channels (black threshold, white threshold).
11+
percentages: [0.6, 0.9] # (float, float) The percentages of pixels below/above the thresholds to consider the patch as black/white.
12+
13+
# Patch stitching parameters
14+
stitching:
15+
vis_level: 2 # (int) Level of the slide to stitch the patches at.
16+
draw_grid: false # (bool) Whether to draw a grid on the stitched image.

‎docs/api_index.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# API Reference
2+
3+
Welcome to the PrismToolBox API documentation. This section provides comprehensive reference for all modules, classes, and functions in the library.
4+
5+
## Core Modules
6+
7+
### 🔬 WSI Core (`prismtoolbox.wsicore`)
8+
9+
The core module for whole slide image handling and preprocessing.
10+
11+
**Main Classes:**
12+
- [`WSI`](reference/prismtoolbox/wsicore/wsi.md) - Primary class for WSI operations, tissue detection, patch extraction, and visualization
13+
14+
**Key Functionality:**
15+
- Slide loading and multi-resolution access
16+
- Tissue contour detection and analysis
17+
- ROI (Region of Interest) management
18+
- Patch extraction with various modes
19+
- Visualization and stitching capabilities
20+
- QuPath integration for annotations
21+
22+
---
23+
24+
### 🧠 WSI Embeddings (`prismtoolbox.wsiemb`)
25+
26+
Feature extraction and embedding generation from WSI patches.
27+
28+
**Main Classes:**
29+
- [`SlideEmbedder`](reference/prismtoolbox/wsiemb/embedder.md) - Extract embeddings from slide patches using pretrained models
30+
- [`PatchEmbedder`](reference/prismtoolbox/wsiemb/embedder.md) - Extract embeddings from patch datasets
31+
- [`EmbeddingProcessor`](reference/prismtoolbox/wsiemb/processing.md) - Process, analyze, and visualize embeddings
32+
33+
**Key Functionality:**
34+
- Model-based embeddings (ResNet, Vision Transformers, Foundation models)
35+
- Stain-based feature extraction (color deconvolution)
36+
- Cell-based feature extraction (morphological features)
37+
- Dimensionality reduction and clustering
38+
- Visualization and analysis tools
39+
40+
---
41+
42+
### 🔬 Nuclei Segmentation (`prismtoolbox.nucleiseg`)
43+
44+
Deep learning-based nuclei segmentation and analysis.
45+
46+
**Main Classes:**
47+
- [`NucleiSegmenter`](reference/prismtoolbox/nucleiseg/segmenter.md) - Segment nuclei in WSI patches using deep learning models
48+
49+
**Key Functionality:**
50+
- Multiple segmentation models (SOP, custom models)
51+
- Batch processing of slide patches
52+
- Post-processing and conflict resolution
53+
- QuPath export for visualization
54+
55+
---

‎docs/cli/preprocessing.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# CLI Reference: Preprocessing
2+
3+
The PrismToolBox CLI provides useful preprocessing capabilities for whole slide images through the `ptb preprocessing` command.
4+
5+
## Overview
6+
7+
The preprocessing module includes two main commands:
8+
9+
1. **`contouring`**: Extract tissue contours from whole slide images
10+
2. **`patching`**: Extract patches from slides using tissue contours
11+
12+
## Installation
13+
14+
Make sure you have PrismToolBox installed:
15+
16+
```bash
17+
# Basic installation
18+
pip install prismtoolbox
19+
```
20+
21+
## Global Options
22+
23+
All preprocessing commands support these global options:
24+
25+
- `--verbose, -v`: Increase verbosity (can be used multiple times: `-v`, `-vv`)
26+
- `--help`: Show help message
27+
28+
## Commands
29+
30+
### `ptb preprocessing contouring`
31+
32+
Extract tissue contours from whole slide images.
33+
34+
#### Usage
35+
36+
```bash
37+
ptb preprocessing contouring [OPTIONS] SLIDE_DIRECTORY RESULTS_DIRECTORY
38+
```
39+
40+
#### Arguments
41+
42+
- **`SLIDE_DIRECTORY`**: Path to the directory containing the slide files
43+
- **`RESULTS_DIRECTORY`**: Path to the directory where the results will be saved
44+
45+
#### Options
46+
47+
| Option | Type | Description | Default |
48+
|--------|------|-------------|---------|
49+
| `--engine` | `str` | Engine for reading slides (`openslide`, `tiffslide`). | `openslide` |
50+
| `--annotations-directory` | `str | None` | Path to annotations directory | `None` |
51+
| `--contours-exts` | `list[str]` | File extensions for contour annotations (`geojson`, `pickle`) | `[pickle]` |
52+
| `--config-file` | `str` | Path to configuration file | `None` |
53+
| `--visualize` | `bool` | Visualize the extracted contours | `False` |
54+
55+
#### Configuration File
56+
57+
You can use a YAML configuration file to specify tissue extraction and visualization parameters:
58+
59+
```yaml
60+
--8<-- "./config/default_contouring.yaml"
61+
```
62+
63+
#### Examples
64+
65+
```bash
66+
# Basic contour extraction
67+
ptb preprocessing contouring slides/ results/
68+
69+
# With visualization
70+
ptb preprocessing contouring slides/ results/ --visualize
71+
72+
# Using custom configuration
73+
ptb preprocessing contouring slides/ results/ --config-file custom_config.yaml
74+
75+
# With annotations and multiple output formats
76+
ptb preprocessing contouring slides/ results/ --annotations-directory annotations/ --contours-exts pickle geojson --visualize
77+
```
78+
79+
### `ptb preprocessing patching`
80+
81+
Extract patches from slides using tissue contours.
82+
83+
#### Usage
84+
85+
```bash
86+
ptb preprocessing patching [OPTIONS] SLIDE_DIRECTORY RESULTS_DIRECTORY
87+
```
88+
89+
#### Arguments
90+
91+
- **`SLIDE_DIRECTORY`**: Path to the directory containing the slide files
92+
- **`RESULTS_DIRECTORY`**: Path to the directory where the results will be saved
93+
94+
#### Options
95+
96+
| Option | Type | Description | Default |
97+
|--------|------|-------------|---------|
98+
| `--contours-directory` | `str | None` | Path to directory containing contour annotations | `None` |
99+
| `--engine` | `str` | Engine for reading slides | `openslide` |
100+
| `--mode` | `str` | Extraction mode (`contours`, `roi`, `all`) | `contours` |
101+
| `--patch-exts` | `list[str]` | File extensions for patches (`h5`, `geojson`) |`[h5]` |
102+
| `--config-file` | `str | None` | Path to configuration file | `None` |
103+
104+
#### Configuration File
105+
106+
Example configuration for patch extraction:
107+
108+
```yaml
109+
--8<-- "./config/default_patching.yaml"
110+
```
111+
112+
#### Examples
113+
114+
```bash
115+
# Basic patch extraction
116+
ptb preprocessing patching slides/ results/ --contours-directory results/contours/
117+
118+
# With custom configuration
119+
ptb preprocessing patching slides/ results/ --contours-directory results/contours/ --config-file patch_config.yaml
120+
121+
# Extract patches in multiple formats
122+
ptb preprocessing patching slides/ results/ --contours-directory results/contours/ --patch-exts h5 geojson
123+
```
124+
125+
## Complete Workflow Example
126+
127+
Here's a complete example of processing a dataset:
128+
129+
```bash
130+
# Step 1: Extract tissue contours with visualization
131+
ptb preprocessing contouring slides/ results/ --visualize --config-file tissue_config.yaml
132+
133+
# Step 2: Extract patches from the contours
134+
ptb preprocessing patching slides/ results/ --contours-directory results/contours/ --config-file patch_config.yaml --patch-exts geojson
135+
136+
# Results will be saved in:
137+
# - results/contours/ (tissue contours)
138+
# - results/contoured_images/ (visualizations)
139+
# - results/patches_256_ovelap_0/ (extracted patches)
140+
# - results/stitched_images_256_ovelap_0/ (patch visualizations)
141+
```
142+
143+
## Error Handling
144+
145+
Common issues and solutions:
146+
147+
### Missing Dependencies
148+
149+
```bash
150+
Error: Segmentation features require additional dependencies.
151+
Please install with: pip install prismtoolbox[seg]
152+
```
153+
154+
**Solution**: Install the required dependencies:
155+
```bash
156+
pip install prismtoolbox[seg,emb]
157+
```
158+
159+
### Configuration File Issues
160+
161+
```bash
162+
Warning: Incomplete tissue extraction parameters in config file
163+
```
164+
165+
**Solution**: Ensure your configuration file contains all required parameters for each section.
166+
167+
### File Path Issues
168+
169+
```bash
170+
Error: No valid config file found. Using default parameters.
171+
```
172+
173+
**Solution**: Check that your configuration file path is correct and the file exists.
174+
175+
## Tips and Best Practices
176+
177+
1. **Start with visualization**: Use `--visualize` flag to check if tissue detection works correctly
178+
2. **Test with small datasets**: Process a few slides first to validate your parameters
179+
3. **Use configuration files**: Store your parameters in YAML files for reproducibility
180+
4. **Monitor output**: Use verbose mode (`-v` or `-vv`) to see detailed processing information

‎docs/index.md‎

Lines changed: 101 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,105 @@ hide:
55
- path
66
---
77

8-
# PrismToolBox Usage Guide
8+
# PrismToolBox Documentation
9+
10+
**PrismToolBox** is a comprehensive Python library for histopathology image analysis, providing powerful tools for processing whole slide images (WSI), feature extraction, and nuclei segmentation.
11+
12+
## 🔬 What is PrismToolBox?
13+
14+
PrismToolBox is designed for researchers and practitioners working with digital pathology images. It offers a complete pipeline for:
15+
16+
- **WSI Preprocessing**: Handle tissue contouring, patch extraction, and visualization
17+
- **Feature Extraction**: Extract embeddings from pretrained models from slide or patch datasets
18+
- **Nuclei Segmentation**: Advanced deep learning models for cell detection and segmentation
19+
20+
## 🛠️ Installation
21+
22+
### Basic Installation
23+
24+
```bash
25+
pip install prismtoolbox
26+
```
27+
28+
### Installation with Optional Dependencies
29+
```bash
30+
pip install prismtoolbox[emb, seg]
31+
```
32+
33+
### Development Installation
34+
35+
```bash
36+
git clone https://github.com/gustaveroussy/PrismToolBox.git
37+
cd PrismToolBox
38+
pip install -e .
39+
```
40+
41+
## 🚀 Key Features
42+
43+
### Core Modules
44+
45+
- **`wsicore`**: Core functionality for WSI handling and preprocessing
46+
- **`wsiemb`**: Feature extraction
47+
- **`nucleiseg`**: Deep learning-based nuclei segmentation
48+
49+
### Command Line Interface
50+
51+
PrismToolBox comes with a powerful CLI that makes it easy to process large datasets:
52+
53+
```bash
54+
# Use the CLI
55+
ptb --help
56+
```
57+
58+
## 📋 Quick Start
59+
60+
### Python API
61+
62+
```python
63+
from prismtoolbox import WSI
64+
65+
# Initialize the reader
66+
WSI_object = WSI(slide_path="path_to_your_slide", engine="openslide")
67+
68+
# Extract tissue contours
69+
params_detect_tissue = {"seg_level": 2, "window_avg": 30, "window_eng": 3, "thresh": 120, "area_min": 6e3}
70+
71+
WSI_object.detect_tissue(**params_detect_tissue)
72+
73+
# Extract patches and save them as jpg images
74+
params_patches = {"patch_size": 256, "patch_level": 0, "overlap": 0, "contours_mode": "four_pt"}
75+
76+
WSI_object.extract_patches(**params_patches)
77+
WSI_object.save_patches("path_to_folder", file_format="jpg")
78+
```
79+
80+
### Command Line Interface
81+
82+
```bash
83+
# Extract tissue contours
84+
ptb preprocessing contouring slides/ results/ --visualize
85+
86+
# Extract patches
87+
ptb preprocessing patching slides/ results/ --contours-directory results/contours/
88+
```
89+
90+
## 📚 Documentation Structure
91+
92+
- **[API Reference](api_index.md)**: Detailed documentation of all classes and functions
93+
- **[CLI Reference](cli/preprocessing.md)**: Complete guide to the command-line interface
94+
- **[Examples](examples/index.md)**: Practical examples and tutorials
95+
96+
## 🤝 Contributing
97+
98+
We welcome contributions! Please see our [contribution guidelines](https://github.com/gustaveroussy/PrismToolBox/blob/main/CONTRIBUTING.md) for more information.
99+
100+
## 📄 License
101+
102+
This project is licensed under the BSD-3-Clause license - see the [LICENSE](https://github.com/gustaveroussy/prismtoolbox/blob/master/LICENSE) file for details.
103+
104+
## 🔗 Links
105+
106+
- [GitHub Repository](https://github.com/gustaveroussy/PrismToolBox)
107+
- [PyPI Package](https://pypi.org/project/prismtoolbox/)
108+
- [Issue Tracker](https://github.com/gustaveroussy/PrismToolBox/issues)
9109

0 commit comments

Comments
 (0)