@synsci/cli-darwin-x64-baseline 1.1.77 → 1.1.78

package/bin/skills/histolab/references/filters_preprocessing.md

@@ -0,0 +1,514 @@
+# Filters and Preprocessing
+
+## Overview
+
+Histolab provides a comprehensive set of filters for preprocessing whole slide images and tiles. Filters can be applied to images for visualization, quality control, tissue detection, and artifact removal. They are composable and can be chained together to create sophisticated preprocessing pipelines.
+
+## Filter Categories
+
+### Image Filters
+Color space conversions, thresholding, and intensity adjustments
+
+### Morphological Filters
+Structural operations like dilation, erosion, opening, and closing
+
+### Composition Filters
+Utilities for combining multiple filters
+
+## Image Filters
+
+### RgbToGrayscale
+
+Convert RGB images to grayscale.
+
+```python
+from histolab.filters.image_filters import RgbToGrayscale
+
+gray_filter = RgbToGrayscale()
+gray_image = gray_filter(rgb_image)
+```
+
+**Use cases:**
+- Preprocessing for intensity-based operations
+- Simplifying color complexity
+- Input for morphological operations
+
+### RgbToHsv
+
+Convert RGB to HSV (Hue, Saturation, Value) color space.
+
+```python
+from histolab.filters.image_filters import RgbToHsv
+
+hsv_filter = RgbToHsv()
+hsv_image = hsv_filter(rgb_image)
+```
+
+**Use cases:**
+- Color-based tissue segmentation
+- Detecting pen markings by hue
+- Separating chromatic from achromatic content
+
+### RgbToHed
+
+Convert RGB to HED (Hematoxylin-Eosin-DAB) color space for stain deconvolution.
+
+```python
+from histolab.filters.image_filters import RgbToHed
+
+hed_filter = RgbToHed()
+hed_image = hed_filter(rgb_image)
+```
+
+**Use cases:**
+- Separating H&E stain components
+- Analyzing nuclear (hematoxylin) vs. cytoplasmic (eosin) staining
+- Quantifying stain intensity
+
+### OtsuThreshold
+
+Apply Otsu's automatic thresholding method to create binary images.
+
+```python
+from histolab.filters.image_filters import OtsuThreshold
+
+otsu_filter = OtsuThreshold()
+binary_image = otsu_filter(grayscale_image)
+```
+
+**How it works:**
+- Automatically determines optimal threshold
+- Separates foreground from background
+- Minimizes intra-class variance
+
+**Use cases:**
+- Tissue detection
+- Nuclei segmentation
+- Binary mask creation
+
+### AdaptiveThreshold
+
+Apply adaptive thresholding for local intensity variations.
+
+```python
+from histolab.filters.image_filters import AdaptiveThreshold
+
+adaptive_filter = AdaptiveThreshold(
+    block_size=11,      # Size of local neighborhood
+    offset=2            # Constant subtracted from mean
+)
+binary_image = adaptive_filter(grayscale_image)
+```
+
+**Use cases:**
+- Non-uniform illumination
+- Local contrast enhancement
+- Handling variable staining intensity
+
+### Invert
+
+Invert image intensity values.
+
+```python
+from histolab.filters.image_filters import Invert
+
+invert_filter = Invert()
+inverted_image = invert_filter(image)
+```
+
+**Use cases:**
+- Preprocessing for certain segmentation algorithms
+- Visualization adjustments
+
+### StretchContrast
+
+Enhance image contrast by stretching intensity range.
+
+```python
+from histolab.filters.image_filters import StretchContrast
+
+contrast_filter = StretchContrast()
+enhanced_image = contrast_filter(image)
+```
+
+**Use cases:**
+- Improving visibility of low-contrast features
+- Preprocessing for visualization
+- Enhancing faint structures
+
+### HistogramEqualization
+
+Equalize image histogram for contrast enhancement.
+
+```python
+from histolab.filters.image_filters import HistogramEqualization
+
+hist_eq_filter = HistogramEqualization()
+equalized_image = hist_eq_filter(grayscale_image)
+```
+
+**Use cases:**
+- Standardizing image contrast
+- Revealing hidden details
+- Preprocessing for feature extraction
+
+## Morphological Filters
+
+### BinaryDilation
+
+Expand white regions in binary images.
+
+```python
+from histolab.filters.morphological_filters import BinaryDilation
+
+dilation_filter = BinaryDilation(disk_size=5)
+dilated_image = dilation_filter(binary_image)
+```
+
+**Parameters:**
+- `disk_size`: Size of structuring element (default: 5)
+
+**Use cases:**
+- Connecting nearby tissue regions
+- Filling small gaps
+- Expanding tissue masks
+
+### BinaryErosion
+
+Shrink white regions in binary images.
+
+```python
+from histolab.filters.morphological_filters import BinaryErosion
+
+erosion_filter = BinaryErosion(disk_size=5)
+eroded_image = erosion_filter(binary_image)
+```
+
+**Use cases:**
+- Removing small protrusions
+- Separating connected objects
+- Shrinking tissue boundaries
+
+### BinaryOpening
+
+Erosion followed by dilation (removes small objects).
+
+```python
+from histolab.filters.morphological_filters import BinaryOpening
+
+opening_filter = BinaryOpening(disk_size=3)
+opened_image = opening_filter(binary_image)
+```
+
+**Use cases:**
+- Removing small artifacts
+- Smoothing object boundaries
+- Noise reduction
+
+### BinaryClosing
+
+Dilation followed by erosion (fills small holes).
+
+```python
+from histolab.filters.morphological_filters import BinaryClosing
+
+closing_filter = BinaryClosing(disk_size=5)
+closed_image = closing_filter(binary_image)
+```
+
+**Use cases:**
+- Filling small holes in tissue regions
+- Connecting nearby objects
+- Smoothing internal boundaries
+
+### RemoveSmallObjects
+
+Remove connected components smaller than a threshold.
+
+```python
+from histolab.filters.morphological_filters import RemoveSmallObjects
+
+remove_small_filter = RemoveSmallObjects(
+    area_threshold=500  # Minimum area in pixels
+)
+cleaned_image = remove_small_filter(binary_image)
+```
+
+**Use cases:**
+- Removing dust and artifacts
+- Filtering noise
+- Cleaning tissue masks
+
+### RemoveSmallHoles
+
+Fill holes smaller than a threshold.
+
+```python
+from histolab.filters.morphological_filters import RemoveSmallHoles
+
+fill_holes_filter = RemoveSmallHoles(
+    area_threshold=1000  # Maximum hole size to fill
+)
+filled_image = fill_holes_filter(binary_image)
+```
+
+**Use cases:**
+- Filling small gaps in tissue
+- Creating continuous tissue regions
+- Removing internal artifacts
+
+## Filter Composition
+
+### Chaining Filters
+
+Combine multiple filters in sequence:
+
+```python
+from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
+from histolab.filters.morphological_filters import BinaryDilation, RemoveSmallObjects
+from histolab.filters.compositions import Compose
+
+# Create filter pipeline
+tissue_detection_pipeline = Compose([
+    RgbToGrayscale(),
+    OtsuThreshold(),
+    BinaryDilation(disk_size=5),
+    RemoveSmallHoles(area_threshold=1000),
+    RemoveSmallObjects(area_threshold=500)
+])
+
+# Apply pipeline
+result = tissue_detection_pipeline(rgb_image)
+```
+
+### Lambda Filters
+
+Create custom filters inline:
+
+```python
+from histolab.filters.image_filters import Lambda
+import numpy as np
+
+# Custom brightness adjustment
+brightness_filter = Lambda(lambda img: np.clip(img * 1.2, 0, 255).astype(np.uint8))
+
+# Custom color channel extraction
+red_channel_filter = Lambda(lambda img: img[:, :, 0])
+```
+
+## Common Preprocessing Pipelines
+
+### Standard Tissue Detection
+
+```python
+from histolab.filters.compositions import Compose
+from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
+from histolab.filters.morphological_filters import (
+    BinaryDilation, RemoveSmallHoles, RemoveSmallObjects
+)
+
+tissue_detection = Compose([
+    RgbToGrayscale(),
+    OtsuThreshold(),
+    BinaryDilation(disk_size=5),
+    RemoveSmallHoles(area_threshold=1000),
+    RemoveSmallObjects(area_threshold=500)
+])
+```
+
+### Pen Mark Removal
+
+```python
+from histolab.filters.image_filters import RgbToHsv, Lambda
+import numpy as np
+
+def remove_pen_marks(hsv_image):
+    """Remove blue/green pen markings."""
+    h, s, v = hsv_image[:, :, 0], hsv_image[:, :, 1], hsv_image[:, :, 2]
+    # Mask for blue/green hues (common pen colors)
+    pen_mask = ((h > 0.45) & (h < 0.7) & (s > 0.3))
+    # Set pen regions to white
+    hsv_image[pen_mask] = [0, 0, 1]
+    return hsv_image
+
+pen_removal = Compose([
+    RgbToHsv(),
+    Lambda(remove_pen_marks)
+])
+```
+
+### Nuclei Enhancement
+
+```python
+from histolab.filters.image_filters import RgbToHed, HistogramEqualization
+from histolab.filters.compositions import Compose
+
+nuclei_enhancement = Compose([
+    RgbToHed(),
+    Lambda(lambda hed: hed[:, :, 0]),  # Extract hematoxylin channel
+    HistogramEqualization()
+])
+```
+
+### Contrast Normalization
+
+```python
+from histolab.filters.image_filters import StretchContrast, HistogramEqualization
+
+contrast_normalization = Compose([
+    RgbToGrayscale(),
+    StretchContrast(),
+    HistogramEqualization()
+])
+```
+
+## Applying Filters to Tiles
+
+Filters can be applied to individual tiles:
+
+```python
+from histolab.tile import Tile
+from histolab.filters.image_filters import RgbToGrayscale
+
+# Load or extract tile
+tile = Tile(image=pil_image, coords=(x, y))
+
+# Apply filter
+gray_filter = RgbToGrayscale()
+filtered_tile = tile.apply_filters(gray_filter)
+
+# Chain multiple filters
+from histolab.filters.compositions import Compose
+from histolab.filters.image_filters import StretchContrast
+
+filter_chain = Compose([
+    RgbToGrayscale(),
+    StretchContrast()
+])
+processed_tile = tile.apply_filters(filter_chain)
+```
+
+## Custom Mask Filters
+
+Integrate custom filters with tissue masks:
+
+```python
+from histolab.masks import TissueMask
+from histolab.filters.compositions import Compose
+from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
+from histolab.filters.morphological_filters import BinaryDilation
+
+# Custom aggressive tissue detection
+aggressive_filters = Compose([
+    RgbToGrayscale(),
+    OtsuThreshold(),
+    BinaryDilation(disk_size=10),  # Larger dilation
+    RemoveSmallObjects(area_threshold=5000)  # Remove only large artifacts
+])
+
+# Create mask with custom filters
+custom_mask = TissueMask(filters=aggressive_filters)
+```
+
+## Stain Normalization
+
+While histolab doesn't have built-in stain normalization, filters can be used for basic normalization:
+
+```python
+from histolab.filters.image_filters import RgbToHed, Lambda
+import numpy as np
+
+def normalize_hed(hed_image, target_means=[0.65, 0.70], target_stds=[0.15, 0.13]):
+    """Simple H&E normalization."""
+    h_channel = hed_image[:, :, 0]
+    e_channel = hed_image[:, :, 1]
+
+    # Normalize hematoxylin
+    h_normalized = (h_channel - h_channel.mean()) / h_channel.std()
+    h_normalized = h_normalized * target_stds[0] + target_means[0]
+
+    # Normalize eosin
+    e_normalized = (e_channel - e_channel.mean()) / e_channel.std()
+    e_normalized = e_normalized * target_stds[1] + target_means[1]
+
+    hed_image[:, :, 0] = h_normalized
+    hed_image[:, :, 1] = e_normalized
+
+    return hed_image
+
+normalization_pipeline = Compose([
+    RgbToHed(),
+    Lambda(normalize_hed)
+    # Convert back to RGB if needed
+])
+```
+
+## Best Practices
+
+1. **Preview filters**: Visualize filter outputs on thumbnails before applying to tiles
+2. **Chain efficiently**: Order filters logically (e.g., color conversion before thresholding)
+3. **Tune parameters**: Adjust thresholds and structuring element sizes for specific tissues
+4. **Use composition**: Build reusable filter pipelines with `Compose`
+5. **Consider performance**: Complex filter chains increase processing time
+6. **Validate on diverse slides**: Test filters across different scanners, stains, and tissue types
+7. **Document custom filters**: Clearly describe purpose and parameters of custom pipelines
+
+## Quality Control Filters
+
+### Blur Detection
+
+```python
+from histolab.filters.image_filters import Lambda
+import cv2
+import numpy as np
+
+def laplacian_blur_score(gray_image):
+    """Calculate Laplacian variance (blur metric)."""
+    return cv2.Laplacian(np.array(gray_image), cv2.CV_64F).var()
+
+blur_detector = Lambda(lambda img: laplacian_blur_score(
+    RgbToGrayscale()(img)
+))
+```
+
+### Tissue Coverage
+
+```python
+from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
+from histolab.filters.compositions import Compose
+
+def tissue_coverage(image):
+    """Calculate percentage of tissue in image."""
+    tissue_mask = Compose([
+        RgbToGrayscale(),
+        OtsuThreshold()
+    ])(image)
+    return tissue_mask.sum() / tissue_mask.size * 100
+
+coverage_filter = Lambda(tissue_coverage)
+```
+
+## Troubleshooting
+
+### Issue: Tissue detection misses valid tissue
+**Solutions:**
+- Reduce `area_threshold` in `RemoveSmallObjects`
+- Decrease erosion/opening disk size
+- Try adaptive thresholding instead of Otsu
+
+### Issue: Too many artifacts included
+**Solutions:**
+- Increase `area_threshold` in `RemoveSmallObjects`
+- Add opening/closing operations
+- Use custom color-based filtering for specific artifacts
+
+### Issue: Tissue boundaries too rough
+**Solutions:**
+- Add `BinaryClosing` or `BinaryOpening` for smoothing
+- Adjust disk_size for morphological operations
+
+### Issue: Variable staining quality
+**Solutions:**
+- Apply histogram equalization
+- Use adaptive thresholding
+- Implement stain normalization pipeline

package/bin/skills/histolab/references/slide_management.md

@@ -0,0 +1,172 @@
+# 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}")
+```