Histolab

Quando usar

Use o Histolab para inspecionar metadados de WSI (Whole Slide Images), identificar tecido, extrair blocos de imagem e padronizar a coloração H&E. Suas máscaras e pontuações são heurísticas de processamento de imagem; elas não diagnosticam câncer, contam células individuais ou estabelecem a qualidade da imagem.

Instalação

O Histolab 0.7.0 continua sendo a versão publicada mais recente na data da revisão. Seus restrições de lançamento exigem Python <3.12, NumPy <=1.24.4, scikit-image <0.19.4, SciPy <1.10.1, Pillow <11 e openslide-python 1.3.1. Mantenha essa pilha isolada de ambientes científicos modernos. O Windows não é suportado por esta versão do Histolab.

Instale o OpenSlide nativo para o seu sistema, então crie um ambiente dedicado (Python 3.10 foi testado):

uv venv --python 3.10 .venv-histolab
uv pip install --python .venv-histolab/bin/python 'histolab==0.7.0' pooch matplotlib
.venv-histolab/bin/python -c 'import openslide; print(openslide.__library_version__)'

No macOS com Homebrew, brew install openslide instala a biblioteca nativa. Se o binding mais antigo do Python não conseguir encontrá-la, execute o Python com o caminho da biblioteca definido imediatamente antes do início do Python:

env DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix openslide)/lib" .venv-histolab/bin/python -c 'import openslide; print(openslide.__library_version__)'

pooch é opcional para exemplos remotos. Comece com um slide local ou com o pequeno exemplo empacotado cmu_small_region; outras funções de exemplo podem baixar centenas de megabytes. A extração exata de mpp também precisa de large-image e um plugin de origem correspondente; consulte gerenciamento de slides.

Fluxo de trabalho

1. Inspecione slide.dimensions, slide.levels (uma lista) e slide.level_dimensions(level) (um método). Verifique ambos os eixos MPP nos metadados.
2. Selecione o campo de visão físico e a resolução de pixel; os números de nível não são intercambiáveis entre scanners. Preserve os limites de coordenadas do nível 0.
3. Escolha TissueMask para todas as seções de tecido ou BiggestTissueBoxMask para a caixa delimitadora da maior seção. Inspecione a máscara em sua resolução real.
4. Configure um tiler e visualize com a mesma máscara passada para extração. Os métodos de visualização retornam uma imagem Pillow; salve ou exiba esse valor de retorno.
5. Extraia para um diretório distinto por slide/por estratégia. Conte os arquivos salvos, inspecione blocos representativos e retenha parâmetros, IDs de origem e flags de QC.
6. Divida os conjuntos de dados por paciente antes da atribuição de blocos de treinamento/validação/teste. Ajuste os alvos de normalização de coloração apenas nos dados de treinamento e valide em scanners mantidos fora do conjunto de treinamento. Uma semente reproduz a amostragem; ela não impede o vazamento de pacientes.

Início rápido

Ilustrativo para um slide fornecido pelo usuário; o mesmo caminho da API é testado com pequenas fixtures locais. n_tiles é um limite superior, não uma promessa de 100 blocos válidos.

from pathlib import Path
from histolab.slide import Slide
from histolab.masks import TissueMask
from histolab.tiler import RandomTiler

output = Path("output/random_tiles")
output.mkdir(parents=True, exist_ok=True)
slide = Slide("slide.svs", processed_path=output)
mask = TissueMask()
slide.locate_mask(mask).save(output / "mask_preview.png")

tiler = RandomTiler(
    tile_size=(512, 512), n_tiles=100, level=0, seed=42,
    check_tissue=True, tissue_percent=80.0, prefix="random_",
)
tiler.locate_tiles(slide, extraction_mask=mask).save(output / "tile_preview.png")
tiler.extract(slide, extraction_mask=mask)
print("[OK] Saved tiles:", len(list(output.glob("random_tile_*.png"))))

extraction_mask pertence a extract() e locate_tiles(), não ao construtor do tiler. locate_tiles() não tem argumento n_tiles. A visualização executa a seleção de blocos novamente, portanto, pode ser custosa; use um tiler pequeno separado para exploração inicial, então visualize a configuração final antes de confirmar uma execução grande.

Escolha uma estratégia

Para grades, o passo em cada eixo é o tamanho do bloco menos pixel_overlap; positivo

…