tbccsi: Tile based classification on cell segmented images

tbccsi is a Python-based tool for processing Whole Slide Images (WSI) in pathology. It handles the tiling of massive slide files (including SVS, TIFF, and VSI formats) and runs inference models to generate predictions.

Features

• Multi-format Support: Natively reads .svs (OpenSlide), .tiff (TiffFile), and .vsi (SlideIO).
• Smart Tiling: Automatically detects tissue regions to avoid processing empty background tiles.
• CLI Interface: Easy-to-use command line interface built with Typer.
• Efficient: Supports high-performance reading and optional on-the-fly extraction.

Installation

1. System Dependencies

You must install the OpenSlide C library before installing the Python bindings.

• Ubuntu/Debian:

  sudo apt-get install openslide-tools
  

* **macOS (Homebrew):**
```bash
brew install openslide

• Windows: Download binaries from openslide.org.

2. Python Dependencies

Clone the repository and install the requirements.

git clone [https://github.com/IlyaLab/tbccsi.git](https://github.com/IlyaLab/tbccsi.git)
cd tbccsi
pip install -r requirements.txt
pip install .  # Install the package to register the 'tbccsi' command

Ensure your requirements.txt includes: slideio, openslide-python, tifffile, typer, pandas, numpy, Pillow, tqdm.

Usage

The tool is run via the command line using the tbccsi command with two main subcommands: tile and pred.

1. Tiling (tile)

The tile command scans a whole slide image, detects tissue regions, and generates a coordinate CSV file. It can optionally save the actual image tiles to disk.

Basic Usage (Generate Coordinates Only):

tbccsi tile --slide-path "/path/to/slide.vsi" --output-dir "./output" --sample-id "Sample_001"

Save Extracted Tile Images: Add the --save-tiles flag to write .png files to disk.

tbccsi tile --slide-path "/path/to/slide.svs" --output-dir "./output" --sample-id "Sample_001" --save-tiles

Arguments:

• --slide-path: Path to the input WSI file (.svs, .vsi, .tiff).
• --output-dir: Directory where results (CSV and/or tiles) will be saved.
• --sample-id: Unique identifier for the sample (used in filenames).
• --tile-size: (Optional) Size of tiles in pixels (default: 224).
• --save-tiles / --no-save-tiles: Whether to save actual images to disk (default: False).

---

2. Prediction (pred)

The pred command runs inference on the generated tiles.

Usage:

tbccsi pred --tile-file "./output/Sample_001_common_tiling.csv" --model-path "./models/my_model.pth" --output-file "./results.csv"

Arguments:

• --tile-file: Path to the CSV file generated by the tile command.
• --model-path: Path to the trained model file.
• --output-file: Path to save prediction results.

Supported Formats

Extension	Backend	Notes
.svs	OpenSlide	Standard Aperio format.
.tiff / .tif	TiffFile	Supports OME-TIFF and flat TIFFs.
.vsi	SlideIO	New: Olympus CellSens format. Requires slideio.

Project Structure

tbccsi/
├── main.py          # Entry point for the Typer CLI
├── wsi_tiler.py     # Core tiling logic (WSITiler, VSISlide)
├── inference.py     # Prediction logic
├── requirements.txt # Python dependencies
├── pyproject.toml   # Project configuration
└── README.md

Troubleshooting

**Error: OpenSlideUnsupportedFormatError**

• Ensure the file is not corrupted.
• If using .vsi, ensure slideio is installed properly, as OpenSlide does not support VSI.

Error: DllNotFoundException (Windows)

• Ensure the OpenSlide bin directory is added to your system PATH.