Histolab

Histolab

Overview

Histolab é uma biblioteca Python para processar imagens de lâminas inteiras (WSI) em patologia digital. Automatiza a detecção de tecido, extrai tiles informativos de imagens gigapixel e prepara datasets para pipelines de deep learning. A biblioteca processa múltiplos formatos de WSI, implementa segmentação sofisticada de tecido e oferece estratégias flexíveis de extração de tiles.

Instalação

uv pip install histolab

Quick Start

Fluxo básico para extrair tiles de uma imagem de lâmina inteira:

from histolab.slide import Slide
from histolab.tiler import RandomTiler

# Carregar lâmina
slide = Slide("slide.svs", processed_path="output/")

# Configurar tiler
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42
)

# Visualizar localizações dos tiles
tiler.locate_tiles(slide, n_tiles=20)

# Extrair tiles
tiler.extract(slide)

Core Capabilities

1. Gerenciamento de Lâminas

Carregar, inspecionar e trabalhar com imagens de lâminas inteiras em diversos formatos.

Operações comuns:

• Carregar arquivos WSI (SVS, TIFF, NDPI, etc.)
• Acessar metadados da lâmina (dimensões, magnificação, propriedades)
• Gerar thumbnails para visualização
• Trabalhar com estruturas de imagem piramidal
• Extrair regiões em coordenadas específicas

Classes principais: Slide

Referência: references/slide_management.md contém documentação abrangente sobre:

• Inicialização e configuração de lâminas
• Datasets de amostra integrados (próstata, ovário, mama, coração, rins)
• Acesso a propriedades e metadados da lâmina
• Geração e visualização de thumbnails
• Trabalho com níveis de pirâmide
• Fluxos de trabalho de processamento multi-lâmina

Exemplo de fluxo:

from histolab.slide import Slide
from histolab.data import prostate_tissue

# Carregar dados de amostra
prostate_svs, prostate_path = prostate_tissue()

# Inicializar lâmina
slide = Slide(prostate_path, processed_path="output/")

# Inspecionar propriedades
print(f"Dimensões: {slide.dimensions}")
print(f"Níveis: {slide.levels}")
print(f"Magnificação: {slide.properties.get('openslide.objective-power')}")

# Salvar thumbnail
slide.save_thumbnail()

2. Detecção de Tecido e Máscaras

Identificar automaticamente regiões de tecido e filtrar fundo/artefatos.

Operações comuns:

• Criar máscaras binárias de tecido
• Detectar a maior região de tecido
• Excluir fundo e artefatos
• Segmentação personalizada de tecido
• Remover anotações em caneta

Classes principais: TissueMask, BiggestTissueBoxMask, BinaryMask

Referência: references/tissue_masks.md contém documentação abrangente sobre:

• TissueMask: Segmenta todas as regiões de tecido usando filtros automatizados
• BiggestTissueBoxMask: Retorna caixa delimitadora da maior região de tecido (padrão)
• BinaryMask: Classe base para implementações de máscara personalizada
• Visualizar máscaras com locate_mask()
• Criar máscaras retangulares e máscaras personalizadas de exclusão de anotações
• Integração de máscara com extração de tiles
• Melhores práticas e resolução de problemas

Exemplo de fluxo:

from histolab.masks import TissueMask, BiggestTissueBoxMask

# Criar máscara de tecido para todas as regiões
tissue_mask = TissueMask()

# Visualizar máscara na lâmina
slide.locate_mask(tissue_mask)

# Obter array da máscara
mask_array = tissue_mask(slide)

# Usar a maior região de tecido (padrão para a maioria dos extractors)
biggest_mask = BiggestTissueBoxMask()

Quando usar cada máscara:

• TissueMask: Múltiplas seções de tecido, análise abrangente
• BiggestTissueBoxMask: Seção única de tecido principal, excluir artefatos (padrão)
• BinaryMask personalizado: ROI específica, excluir anotações, segmentação personalizada

3. Extração de Tiles

Extrair regiões menores de WSI grande usando diferentes estratégias.

Três estratégias de extração:

RandomTiler: Extrair número fixo de tiles posicionados aleatoriamente

• Melhor para: Amostrar regiões diversas, análise exploratória, dados de treinamento
• Parâmetros principais: n_tiles, seed para reprodutibilidade

GridTiler: Extrair sistematicamente tiles através do tecido em padrão de grade

• Melhor para: Cobertura completa, análise espacial, reconstrução
• Parâmetros principais: pixel_overlap para janelas deslizantes

ScoreTiler: Extrair tiles mais bem classificados com base em funções de pontuação

• Melhor para: Regiões mais informativas, seleção orientada por qualidade
• Parâmetros principais: scorer (NucleiScorer, CellularityScorer, personalizado)

Parâmetros comuns:

• tile_size: Dimensões do tile (ex: (512, 512))
• level: Nível de pirâmide para extração (0 = resolução mais alta)
• check_tissue: Filtrar tiles por conteúdo de tecido
• tissue_percent: Cobertura mínima de tecido (padrão 80%)
• extraction_mask: Máscara que define a região de extração

Referência: references/tile_extraction.md contém documentação abrangente sobre:

• Explicação detalhada de cada estratégia de tiler
• Scorers disponíveis (NucleiScorer, CellularityScorer, personalizado)
• Visualização de tiles com locate_tiles()
• Fluxos de trabalho e relatórios de extração
• Padrões avançados (extração multi-nível, hierárquica)
• Otimização de desempenho e resolução de problemas

Exemplos de fluxo:

from histolab.tiler import RandomTiler, GridTiler, ScoreTiler
from histolab.scorer import NucleiScorer

# Amostragem aleatória (rápida, diversa)
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)
random_tiler.extract(slide)

# Cobertura em grade (abrangente)
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=0,
    pixel_overlap=0,
    check_tissue=True
)
grid_tiler.extract(slide)

# Seleção baseada em pontuação (mais informativa)
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    scorer=NucleiScorer(),
    level=0
)
score_tiler.extract(slide, report_path="tiles_report.csv")

Sempre fazer visualização antes de extrair:

# Visualizar localizações dos tiles na thumbnail
tiler.locate_tiles(slide, n_tiles=20)

4. Filtros e Pré-processamento

Aplicar filtros de processamento de imagem para detecção de tecido, controle de qualidade e pré-processamento.

Categorias de filtros:

Filtros de imagem: Conversões de espaço de cor, limiarização, aprimoramento de contraste

• RgbToGrayscale, RgbToHsv, RgbToHed
• OtsuThreshold, AdaptiveThreshold
• StretchContrast, HistogramEqualization

Filtros morfológicos: Operações estruturais em imagens binárias

• BinaryDilation, BinaryErosion
• BinaryOpening, BinaryClosing
• RemoveSmallObjects, RemoveSmallHoles

Composição: Encadear múltiplos filtros

• Compose: Criar pipelines de filtros

Referência: references/filters_preprocessing.md contém documentação abrangente sobre:

• Explicação detalhada de cada tipo de filtro
• Composição e encadeamento de filtros
• Pipelines comuns de pré-processamento (detecção de tecido, remoção de caneta, aprimoramento de núcleos)
• Aplicar filtros a tiles
• Filtros de máscara personalizada
• Filtros de controle de qualidade (detecção de desfoque, cobertura de tecido)
• Melhores práticas e resolução de problemas

Exemplos de fluxo:

from histolab.filters.compositions import Compose
from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
from histolab.filters.morphological_filters import (
    BinaryDilation, RemoveSmallHoles, RemoveSmallObjects
)

# Pipeline padrão de detecção de tecido
tissue_detection = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=5),
    RemoveSmallHoles(area_threshold=1000),
    RemoveSmallObjects(area_threshold=500)
])

# Usar com máscara personalizada
from histolab.masks import TissueMask
custom_mask = TissueMask(filters=tissue_detection)

# Aplicar filtros ao tile
from histolab.tile import Tile
filtered_tile = tile.apply_filters(tissue_detection)

5. Visualização

Visualizar lâminas, máscaras, localizações de tiles e qualidade de extração.

Tarefas comuns de visualização:

• Exibir thumbnails de lâminas
• Visualizar máscaras de tecido
• Visualizar localizações de tiles
• Avaliar qualidade de tiles
• Criar relatórios e figuras

Referência: references/visualization.md contém documentação abrangente sobre:

• Exibição e salvamento de thumbnail de lâmina
• Visualização de máscara com locate_mask()
• Visualização de localização de tiles com locate_tiles()
• Exibir tiles extraídos e criar mosaicos
• Avaliação de qualidade (distribuição de pontuações, tiles superiores vs inferiores)
• Visualização multi-lâmina
• Visualização de efeito de filtro
• Exportar figuras e relatórios PDF em alta resolução
• Visualização interativa em notebooks Jupyter

Exemplos de fluxo:

import matplotlib.pyplot as plt
from histolab.masks import TissueMask

# Exibir thumbnail de lâmina
plt.figure(figsize=(10, 10))
plt.imshow(slide.thumbnail)
plt.title(f"Lâmina: {slide.name}")
plt.axis('off')
plt.show()

# Visualizar máscara de tecido
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Visualizar localizações de tiles
tiler = RandomTiler(tile_size=(512, 512), n_tiles=50)
tiler.locate_tiles(slide, n_tiles=20)

# Exibir tiles extraídos em grade
from pathlib import Path
from PIL import Image

tile_paths = list(Path("output/tiles/").glob("*.png"))[:16]
fig, axes = plt.subplots(4, 4, figsize=(12, 12))
axes = axes.ravel()

for idx, tile_path in enumerate(tile_paths):
    tile_img = Image.open(tile_path)
    axes[idx].imshow(tile_img)
    axes[idx].set_title(tile_path.stem, fontsize=8)
    axes[idx].axis('off')

plt.tight_layout()
plt.show()

Typical Workflows

Workflow 1: Exploratory Tile Extraction

Amostragem rápida de regiões diversas de tecido para análise inicial.

from histolab.slide import Slide
from histolab.tiler import RandomTiler
import logging

# Ativar logging para rastreamento de progresso
logging.basicConfig(level=logging.INFO)

# Carregar lâmina
slide = Slide("slide.svs", processed_path="output/random_tiles/")

# Inspecionar lâmina
print(f"Dimensões: {slide.dimensions}")
print(f"Níveis: {slide.levels}")
slide.save_thumbnail()

# Configurar tiler aleatório
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)

# Visualizar localizações
random_tiler.locate_tiles(slide, n_tiles=20)

# Extrair tiles
random_tiler.extract(slide)

Workflow 2: Comprehensive Grid Extraction

Cobertura completa de tecido para análise de lâmina inteira.

from histolab.slide import Slide
from histolab.tiler import GridTiler
from histolab.masks import TissueMask

# Carregar lâmina
slide = Slide("slide.svs", processed_path="output/grid_tiles/")

# Usar TissueMask para todas as seções de tecido
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Configurar tiler em grade
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=1,  # Usar nível 1 para extração mais rápida
    pixel_overlap=0,
    check_tissue=True,
    tissue_percent=70.0
)

# Visualizar grade
grid_tiler.locate_tiles(slide)

# Extrair todos os tiles
grid_tiler.extract(slide, extraction_mask=tissue_mask)

Workflow 3: Quality-Driven Tile Selection

Extrair tiles mais informativos baseado em densidade de núcleos.

from histolab.slide import Slide
from histolab.tiler import ScoreTiler
from histolab.scorer import NucleiScorer
import pandas as pd
import matplotlib.pyplot as plt

# Carregar lâmina
slide = Slide("slide.svs", processed_path="output/scored_tiles/")

# Configurar score tiler
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    scorer=NucleiScorer(),
    check_tissue=True
)

# Visualizar tiles superiores
score_tiler.locate_tiles(slide, n_tiles=15)

# Extrair com relatório
score_tiler.extract(slide, report_path="tiles_report.csv")

# Analisar pontuações
report_df = pd.read_csv("tiles_report.csv")
plt.hist(report_df['score'], bins=20, edgecolor='black')
plt.xlabel('Pontuação do Tile')
plt.ylabel('Frequência')
plt.title('Distribuição de Pontuações de Tiles')
plt.show()

Workflow 4: Multi-Slide Processing Pipeline

Processar coleção inteira de lâminas com parâmetros consistentes.

from pathlib import Path
from histolab.slide import Slide
from histolab.tiler import RandomTiler
import logging

logging.basicConfig(level=logging.INFO)

# Configurar tiler uma vez
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    seed=42,
    check_tissue=True
)

# Processar todas as lâminas
slide_dir = Path("slides/")
output_base = Path("output/")

for slide_path in slide_dir.glob("*.svs"):
    print(f"\nProcessando: {slide_path.name}")

    # Criar diretório de saída específico da lâmina
    output_dir = output_base / slide_path.stem
    output_dir.mkdir(parents=True, exist_ok=True)

    # Carregar e processar lâmina
    slide = Slide(slide_path, processed_path=output_dir)

    # Salvar thumbnail para revisão
    slide.save_thumbnail()

    # Extrair tiles
    tiler.extract(slide)

    print(f"Concluído: {slide_path.name}")

Workflow 5: Custom Tissue Detection and Filtering

Tratar lâminas com artefatos, anotações ou coloração incomum.

from histolab.slide import Slide
from histolab.masks import TissueMask
from histolab.tiler import RandomTiler
from histolab.filters.compositions import Compose
from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
from histolab.filters.morphological_filters import (
    BinaryDilation, RemoveSmallObjects, RemoveSmallHoles
)

# Definir pipeline de filtros personalizado para remoção agressiva de artefatos
aggressive_filters = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=10),
    RemoveSmallHoles(area_threshold=5000),
    RemoveSmallObjects(area_threshold=3000)  # Remover artefatos maiores
])

# Criar máscara personalizada
custom_mask = TissueMask(filters=aggressive_filters)

# Carregar lâmina e visualizar máscara
slide = Slide("slide.svs", processed_path="output/")
slide.locate_mask(custom_mask)

# Extrair com máscara personalizada
tiler = RandomTiler(tile_size=(512, 512), n_tiles=100)
tiler.extract(slide, extraction_mask=custom_mask)

Best Practices

Slide Loading and Inspection

1. Sempre inspecionar propriedades da lâmina antes do processamento
2. Salvar thumbnails para revisão visual rápida
3. Verificar níveis de pirâmide e dimensões
4. Verificar se a lâmina contém tecido usando thumbnails

Tissue Detection

1. Visualizar máscaras com locate_mask() antes da extração
2. Usar TissueMask para múltiplas seções, BiggestTissueBoxMask para seções únicas
3. Personalizar filtros para colorações específicas (H&E vs IHC)
4. Tratar anotações em caneta com máscaras personalizado
5. Testar máscaras em lâminas diversas

Tile Extraction

1. Sempre visualizar com locate_tiles() antes de extrair
2. Escolher tiler apropriado:
   • RandomTiler: Amostragem e exploração
   • GridTiler: Cobertura completa
   • ScoreTiler: Seleção orientada por qualidade
3. Definir limiar tissue_percent apropriado (70-90% típico)
4. Usar seeds para reprodutibilidade em RandomTiler
5. Extrair em nível de pirâmide apropriado para resolução de análise
6. Ativar logging para datasets grandes

Performance

1. Extrair em níveis inferiores (1, 2) para processamento mais rápido
2. Usar BiggestTissueBoxMask em vez de TissueMask quando apropriado
3. Ajustar tissue_percent para reduzir tentativas de tile inválido
4. Limitar n_tiles para exploração inicial
5. Usar pixel_overlap=0 para grades não sobrepostas

Quality Control

1. Validar qualidade de tiles (verificar desfoque, artefatos, foco)
2. Revisar distribuições de pontuação para ScoreTiler
3. Inspecionar tiles com maior e menor pontuação
4. Monitorar estatísticas de cobertura de tecido
5. Filtrar tiles extraídos por métricas de qualidade adicionais se necessário

Common Use Cases

Training Deep Learning Models

• Extrair datasets balanceados usando RandomTiler em múltiplas lâminas
• Usar ScoreTiler com NucleiScorer para focar em regiões ricas em células
• Extrair em resolução consistente (nível 0 ou nível 1)
• Gerar relatórios CSV para rastreamento de metadados de tiles

Whole Slide Analysis

• Usar GridTiler para cobertura completa de tecido
• Extrair em múltiplos níveis de pirâmide para análise hierárquica
• Manter relações espaciais com posições em grade
• Usar pixel_overlap para abordagens de janela deslizante

Tissue Characterization

• Amostrar regiões diversas com RandomTiler
• Quantificar cobertura de tecido com máscaras
• Extrair informações específicas de coloração com decomposição HED
• Comparar padrões de tecido entre lâminas

Quality Assessment

• Identificar regiões de foco ótimo com ScoreTiler
• Detectar artefatos usando máscaras e filtros personalizados
• Avaliar qualidade de coloração em coleção de lâminas
• Sinalizar lâminas problemáticas para revisão manual

Dataset Curation

• Usar ScoreTiler para priorizar tiles informativos
• Filtrar tiles por porcentagem de tecido
• Gerar relatórios com pontuações de tiles e metadados
• Criar datasets estratificados entre lâminas e tipos de tecido

Troubleshooting

No tiles extracted

• Reduzir limiar tissue_percent
• Verificar se a lâmina contém tecido (verificar thumbnail)
• Garantir que extraction_mask capture regiões de tecido
• Verificar se tile_size é apropriado para resolução da lâmina

Many background tiles

• Ativar check_tissue=True
• Aumentar limiar tissue_percent
• Usar máscara apropriada (TissueMask vs BiggestTissueBoxMask)
• Personalizar filtros de máscara para melhor detecção de tecido

Extraction very slow

• Extrair em nível de pirâmide inferior (nível=1 ou 2)
• Reduzir n_tiles para RandomTiler/ScoreTiler
• Usar RandomTiler em vez de GridTiler para amostragem
• Usar BiggestTissueBoxMask em vez de TissueMask

Tiles have artifacts

• Implementar máscaras personalizadas de exclusão de anotações
• Ajustar parâmetros de filtro para remoção de artefatos
• Aumentar limiar de remoção de objetos pequenos
• Aplicar filtragem de qualidade pós-extração

Inconsistent results across slides

• Usar mesma seed para RandomTiler
• Normalizar coloração com filtros de pré-processamento
• Ajustar tissue_percent por qualidade de coloração
• Implementar personalização de máscara específica da lâmina

Resources

Essa skill inclui documentação de referência detalhada no diretório references/:

references/slide_management.md

Guia abrangente para carregar, inspecionar e trabalhar com imagens de lâminas inteiras:

• Inicialização e configuração de lâminas
• Datasets de amostra integrados
• Propriedades e metadados de lâminas
• Geração e visualização de thumbnails
• Trabalho com níveis de pirâmide
• Fluxos de trabalho de processamento multi-lâmina
• Melhores práticas e padrões comuns

references/tissue_masks.md

Documentação completa sobre detecção e mascaramento de tecido:

• Classes TissueMask, BiggestTissueBoxMask, BinaryMask
• Como funcionam os filtros de detecção de tecido
• Personalizar máscaras com cadeias de filtros
• Visualizar máscaras
• Criar máscaras retangulares personalizadas e máscaras de exclusão de anotações
• Integração com extração de tiles
• Melhores práticas e resolução de problemas

references/tile_extraction.md

Explicação detalhada das estratégias de extração de tiles:

• Comparação RandomTiler, GridTiler, ScoreTiler
• Scorers disponíveis (NucleiScorer, CellularityScorer, personalizado)
• Parâmetros comuns e específicos de estratégia
• Visualização de tiles com locate_tiles()
• Fluxos de trabalho e relatórios CSV
• Padrões avançados (multi-nível, hierárquico)
• Otimização de desempenho
• Resolução de problemas comuns

references/filters_preprocessing.md

Referência completa de filtros e guia de pré-processamento:

• Filtros de imagem (conversão de cor, limiarização, contraste)
• Filtros morfológicos (dilatação, erosão, abertura, fechamento)
• Composição e encadeamento de filtros
• Pipelines comuns de pré-processamento
• Aplicar filtros a tiles
• Filtros de máscara personalizada
• Filtros de controle de qualidade
• Melhores práticas e resolução de problemas

references/visualization.md

Guia abrangente de visualização:

• Exibição e salvamento de thumbnail de lâmina
• Técnicas de visualização de máscara
• Visualização de localização de tiles
• Exibir tiles extraídos e criar mosaicos
• Visualizações de avaliação de qualidade
• Comparação multi-lâmina
• Visualização de efeito de filtro
• Exportar figuras em alta resolução e PDFs
• Visualização interativa em notebooks Jupyter

Padrão de uso: Arquivos de referência contêm informações detalhadas para suportar fluxos de trabalho descritos neste documento de skill principal. Carregar arquivos de referência específicos conforme necessário para orientação de implementação detalhada, resolução de problemas ou recursos avançados.