ihcinfer

Fast, patch-based IHC whole-slide inference — powered by DeepLIIF.
From IHC glass slide to cell-counting CSVs, heatmaps, and visual overlays — in one command.

中文 · What's New · Quick Start · Docs · Benchmarks

📰 What's New

v0.2.1

• 🖼️ MIRAX (.mrxs) support — tissue segmentation now suppresses black out-of-scan regions; thumbnails and overlays are cropped to the scanned bounds so tissue fills the frame.
• 🔍 Better thumbnail quality for bounded slides — OpenSlideReader exposes bounds; read_slide_thumbnail upscales before cropping when bounds are present.
• 📝 Renamed thumbnail output — WSI thumbnail is now saved as wsi_thumbnail.jpg instead of he_thumbnail.jpg.
• 🎚️ IHC background tuning — TissueSegmenter gains a black_v_thresh parameter to filter dark scanner background in IHC mode.

v0.2.0

• 🚀 Unified ihc CLI — one command for tissue_seg, patch_infer, and infer.
• 🧫 IHC Tissue Segmentation — default ihc mode optimized for immunohistochemistry backgrounds; he mode for H&E.
• ⚡ Scoring-only Fast Path — skip intermediate PIL images during WSI inference to lower memory and boost throughput.
• ⬇️ Automatic Model Download — the DeepLIIF TorchScript model is downloaded from Zenodo the first time model_dir is omitted.
• 🧩 Cross-chunk Batch Tiling — large slides are read in chunks and patches are batched across chunk boundaries for better GPU utilization.

ihcinfer is a lightweight Python library for batch immunohistochemistry (IHC) inference on SVS / KFB whole-slide images and PNG / JPEG patches. It reorganizes patch buffering, chunk tiling, tissue-mask pre-filtering, and a scoring-only fast path on top of DeepLIIF's TorchScript model, while exposing both a Python API (IHCAnalyzer) and a command-line tool (ihc).

✨ Core Features

🧑‍🔬 What Can You Do With It?

ihc infer \
  --slide_path "path/to/CD3.svs" \
  --output_dir ./ihc_outputs \
  --gpu_ids 0 \
  --batch_size 8

from ihcinfer import IHCAnalyzer
import pandas as pd

analyzer = IHCAnalyzer(gpu_ids=[0], batch_size=16)
result = analyzer.infer_wsi(
    slide_path="path/to/slide.svs",
    output_dir="./outputs",
)

df = pd.read_csv(result.csv_path)

from ihcinfer import segment_tissue

mask = segment_tissue("slide.svs", mode="ihc")
print(mask.mask.shape)

export IHCINFER_MODEL_DIR="/path/to/DeepLIIF_Latest_Model"
ihc infer --slide_path slide.svs --output_dir ./out --model_dir "$IHCINFER_MODEL_DIR"

📋 Supported Platforms & Inputs

Model: DeepLIIF TorchScript model (~3 GB). It is downloaded automatically from Zenodo the first time model_dir is omitted, or you can point to a local copy.

⚡ 30-Second Quick Start

# Install
pip install ihcinfer

# 1. Tissue segmentation (no model required)
ihc tissue_seg --input "slide.svs" --output_dir ./tissue_mask --overlay

# 2. Patch inference
ihc patch_infer --input patch.png --output_dir ./patch_outputs

# 3. Whole-slide IHC inference
ihc infer --slide_path slide.svs --output_dir ./ihc_outputs --gpu_ids 0

from ihcinfer import IHCAnalyzer

analyzer = IHCAnalyzer(
    model_dir="/path/to/DeepLIIF_Latest_Model",  # omit to auto-download
    gpu_ids=[0],
    batch_size=16,
)

result = analyzer.infer_wsi(
    slide_path="/path/to/slide.svs",
    output_dir="/path/to/output",
)

print(result.csv_path)
print(result.heatmap_path)
print(f"Region samples: {len(result.region_sample_paths) // 2}")
print(f"Patch samples: {len(result.patch_sample_dirs)}")

🐍 Python API

IHCAnalyzer is the unified entry point for most users:

from ihcinfer import IHCAnalyzer

analyzer = IHCAnalyzer(gpu_ids=[0], batch_size=16)

# Whole-slide inference
result = analyzer.infer_wsi("slide.svs", output_dir="./outputs")

# Patch inference
patch_result = analyzer.infer_patches(["p1.png", "p2.png"], output_dir="./patch_outputs")

# Tissue segmentation
mask = analyzer.segment_tissue("slide.svs", mode="ihc")

🚀 Why ihcinfer?

Test environment: 6× NVIDIA RTX 3090 / 24 GiB. Reproduction scripts are in benchmarks/.

Charts generated by benchmarks/plot_benchmarks.py from the table above.

🏗️ Pipeline Architecture

graph LR
    A[WSI: SVS / KFB] --> B[Tissue Segmentation<br/>ihc / he mode]
    B --> C[Chunked Patch Tiler]
    C --> D[DeepLIIF Batch Inference]
    D --> E[Cell Scoring]
    E --> F[CSV + Heatmap]
    E --> G[H&E Thumbnail + Overlay]
    E --> H[Region / Patch Samples]

📚 Documentation & Resources

🛠️ CLI Reference

ihc --help

# Subcommands
ihc tissue_seg --input <slide> --output_dir <dir> [--overlay] [--mode ihc|he]
ihc patch_infer --input <patch_or_dir> --output_dir <dir> [--model_dir <dir>]
ihc infer --slide_path <slide> --output_dir <dir> [--gpu_ids 0] [--batch_size 8]

🔧 Advanced Usage

from ihcinfer.inference import PatchInference, RegionInference
from ihcinfer.models import DeepLIIFModel
from ihcinfer.prep import Tiler, TissueSegmenter, segment_tissue
from ihcinfer.readers import create_reader
from ihcinfer.scoring import compute_scoring, extract_cells
from ihcinfer.outputs import build_patch_output, save_patch_output, build_heatmap

📈 Benchmarks

All numbers can be reproduced with the scripts in benchmarks/:

# Patch-level comparison (original DeepLIIF repo must be on PYTHONPATH)
PYTHONPATH=/path/to/DeepLIIF uv run python benchmarks/bench_patch_vs_original.py --device cuda:0

# Region-level comparison
PYTHONPATH=/path/to/DeepLIIF uv run python benchmarks/bench_region_inference.py

# WSI 50-patch comparison
PYTHONPATH=/path/to/DeepLIIF uv run python benchmarks/bench_wsi_50_vs_original.py

# Full IHC WSI pipeline timing
uv run python examples/infer_ihc.py \
  --slide_path /path/to/slide.svs \
  --output_dir ./ihc_outputs \
  --gpu_ids 0 --batch_size 8 \
  --patch_size 512 --region_size 2048

🤝 Contributing

Issues and PRs are welcome.

📄 License

This project is licensed under the MIT License.