173 lines
4.6 KiB
Markdown
173 lines
4.6 KiB
Markdown
# Slide Management
|
|
|
|
## Overview
|
|
|
|
The `Slide` class is the primary interface for working with whole slide images (WSI) in histolab. It provides methods to load, inspect, and process large histopathology images stored in various formats.
|
|
|
|
## Initialization
|
|
|
|
```python
|
|
from histolab.slide import Slide
|
|
|
|
# Initialize a slide with a WSI file and output directory
|
|
slide = Slide(processed_path="path/to/processed/output",
|
|
slide_path="path/to/slide.svs")
|
|
```
|
|
|
|
**Parameters:**
|
|
- `slide_path`: Path to the whole slide image file (supports multiple formats: SVS, TIFF, NDPI, etc.)
|
|
- `processed_path`: Directory where processed outputs (tiles, thumbnails, etc.) will be saved
|
|
|
|
## Loading Sample Data
|
|
|
|
Histolab provides built-in sample datasets from TCGA for testing and demonstration:
|
|
|
|
```python
|
|
from histolab.data import prostate_tissue, ovarian_tissue, breast_tissue, heart_tissue, kidney_tissue
|
|
|
|
# Load prostate tissue sample
|
|
prostate_svs, prostate_path = prostate_tissue()
|
|
slide = Slide(prostate_path, processed_path="output/")
|
|
```
|
|
|
|
Available sample datasets:
|
|
- `prostate_tissue()`: Prostate tissue sample
|
|
- `ovarian_tissue()`: Ovarian tissue sample
|
|
- `breast_tissue()`: Breast tissue sample
|
|
- `heart_tissue()`: Heart tissue sample
|
|
- `kidney_tissue()`: Kidney tissue sample
|
|
|
|
## Key Properties
|
|
|
|
### Slide Dimensions
|
|
```python
|
|
# Get slide dimensions at level 0 (highest resolution)
|
|
width, height = slide.dimensions
|
|
|
|
# Get dimensions at specific pyramid level
|
|
level_dimensions = slide.level_dimensions
|
|
# Returns tuple of (width, height) for each level
|
|
```
|
|
|
|
### Magnification Information
|
|
```python
|
|
# Get base magnification (e.g., 40x, 20x)
|
|
base_mag = slide.base_mpp # Microns per pixel at level 0
|
|
|
|
# Get all available levels
|
|
num_levels = slide.levels # Number of pyramid levels
|
|
```
|
|
|
|
### Slide Properties
|
|
```python
|
|
# Access OpenSlide properties dictionary
|
|
properties = slide.properties
|
|
|
|
# Common properties include:
|
|
# - slide.properties['openslide.objective-power']: Objective power
|
|
# - slide.properties['openslide.mpp-x']: Microns per pixel in X
|
|
# - slide.properties['openslide.mpp-y']: Microns per pixel in Y
|
|
# - slide.properties['openslide.vendor']: Scanner vendor
|
|
```
|
|
|
|
## Thumbnail Generation
|
|
|
|
```python
|
|
# Get thumbnail at specific size
|
|
thumbnail = slide.thumbnail
|
|
|
|
# Save thumbnail to disk
|
|
slide.save_thumbnail() # Saves to processed_path
|
|
|
|
# Get scaled thumbnail
|
|
scaled_thumbnail = slide.scaled_image(scale_factor=32)
|
|
```
|
|
|
|
## Slide Visualization
|
|
|
|
```python
|
|
# Display slide thumbnail with matplotlib
|
|
import matplotlib.pyplot as plt
|
|
|
|
plt.figure(figsize=(10, 10))
|
|
plt.imshow(slide.thumbnail)
|
|
plt.title(f"Slide: {slide.name}")
|
|
plt.axis('off')
|
|
plt.show()
|
|
```
|
|
|
|
## Extracting Regions
|
|
|
|
```python
|
|
# Extract region at specific coordinates and level
|
|
region = slide.extract_region(
|
|
location=(x, y), # Top-left coordinates at level 0
|
|
size=(width, height), # Region size
|
|
level=0 # Pyramid level
|
|
)
|
|
```
|
|
|
|
## Working with Pyramid Levels
|
|
|
|
WSI files use a pyramidal structure with multiple resolution levels:
|
|
- Level 0: Highest resolution (native scan resolution)
|
|
- Level 1+: Progressively lower resolutions for faster access
|
|
|
|
```python
|
|
# Check available levels
|
|
for level in range(slide.levels):
|
|
dims = slide.level_dimensions[level]
|
|
downsample = slide.level_downsamples[level]
|
|
print(f"Level {level}: {dims}, downsample: {downsample}x")
|
|
```
|
|
|
|
## Slide Name and Path
|
|
|
|
```python
|
|
# Get slide filename without extension
|
|
slide_name = slide.name
|
|
|
|
# Get full path to slide file
|
|
slide_path = slide.scaled_image
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Always specify processed_path**: Organize outputs in dedicated directories
|
|
2. **Check dimensions before processing**: Large slides can exceed memory limits
|
|
3. **Use appropriate pyramid levels**: Extract tiles at levels matching your analysis resolution
|
|
4. **Preview with thumbnails**: Use thumbnails for quick visualization before heavy processing
|
|
5. **Monitor memory usage**: Level 0 operations on large slides require significant RAM
|
|
|
|
## Common Workflows
|
|
|
|
### Slide Inspection Workflow
|
|
```python
|
|
from histolab.slide import Slide
|
|
|
|
# Load slide
|
|
slide = Slide("slide.svs", processed_path="output/")
|
|
|
|
# Inspect properties
|
|
print(f"Dimensions: {slide.dimensions}")
|
|
print(f"Levels: {slide.levels}")
|
|
print(f"Magnification: {slide.properties.get('openslide.objective-power', 'N/A')}")
|
|
|
|
# Save thumbnail for review
|
|
slide.save_thumbnail()
|
|
```
|
|
|
|
### Multi-Slide Processing
|
|
```python
|
|
import os
|
|
from pathlib import Path
|
|
|
|
slide_dir = Path("slides/")
|
|
output_dir = Path("processed/")
|
|
|
|
for slide_path in slide_dir.glob("*.svs"):
|
|
slide = Slide(slide_path, processed_path=output_dir / slide_path.stem)
|
|
# Process each slide
|
|
print(f"Processing: {slide.name}")
|
|
```
|