Skip to main content
WSI Mega-Tile Extraction Module. This module provides the MegaTileExtractor class, which groups individual tile positions from a Whole Slide Image into mega tiles — fixed- size grids of rows × cols tiles. It builds on the tile-level tissue filtering from TileExtractor and adds a second filtering stage: only mega tiles where the fraction of tissue-positive tiles falls within a configurable [min_valid_tiles_ratio, max_valid_tiles_ratio] band are kept. The class follows the same scikit-learn–style lifecycle as TileExtractor:
  1. Configure — instantiate with a MegaTileSpec, optional tissue mask, and threshold.
  2. Fit — call fit with an open WSIReader.
  3. Extract — call extract (or the shortcut fit_extract). Results are stored in megatile_regions_ and also returned.
  4. Export — call to_csv or to_json to persist the results.
Typical usage example:

​
MegaTileExtractor

Extracts mega tiles (grids of tiles) from a WSI, filtered by tissue. A mega tile is a rectangular or hexagonal grid of individual tiles. Extraction proceeds in two stages:
  1. Tile-level filtering — a binary tissue mask and mask_threshold determine which individual tile positions contain sufficient tissue.
  2. Mega-tile-level filtering — only mega tiles where the fraction of valid (tissue-positive) tiles falls within [min_valid_tiles_ratio, max_valid_tiles_ratio] are retained.
The extractor follows the same lifecycle as TileExtractor: Or via method chaining: Configuration attributes (set at init):
Attributes:
  • megatile_spec MegaTileSpec - Mega-tile grid shape, per-tile spec, layout, stride, and valid-ratio bounds.
  • mask np.ndarray | None - Binary tissue mask.
  • mask_provider TissueMaskProvider | None - Per-slide mask generator.
  • mask_threshold float | None - Per-tile tissue fraction threshold.
  • save_mask bool - Whether to store per-tile masks.
  • max_megatiles int | None - Optional cap on returned mega tiles. Fitted attributes (populated by fit / extract):
Attributes:
  • source_ WSIReader - Bound WSI reader.
  • slide_name_ str - Stem of the slide filename.
  • megatile_regions_ List[MegaTileRegion] - Extracted mega tiles.

​
fit

Binds the extractor to an open WSI reader. Stores the reader and slide name. If a mask_provider is set, its generate method is called to create a per-slide tissue mask.
​
An open WSI reader.
Returns:
  • MegaTileExtractor - self for method chaining.
Example:

​
extract

Extracts mega-tile regions from a WSI. The method operates in five stages:
  1. Reference-level setup — as in TileExtractor.
  2. Mask scaling — resize tissue mask to the reference level.
  3. Tile-spec scaling — convert tile dimensions to reference-level pixels.
  4. Per-tile tissue evaluation — build an integral image and compute the tissue fraction for every candidate tile position.
  5. Mega-tile grouping — slide a rows × cols window (in tile units) across the tile grid, collect per-tile validity, and filter by [min_valid_tiles_ratio, max_valid_tiles_ratio].
Results are stored in megatile_regions_ and returned.
​
An open WSI reader. When given, the extractor is fitted automatically. Otherwise fit must have been called.
Returns:
  • List[MegaTileRegion] - Mega-tile regions that pass filtering.
Raises:
  • RuntimeError - If no source is provided and fit has not been called.
Example:

​
fit_extract

Convenience method: fit + extract in one call.
​
An open WSI reader.
Returns:
  • List[MegaTileRegion] - Extracted mega-tile regions.
Example:

​
to_csv

Saves mega-tile metadata to a CSV file named after the slide. Each row represents one tile within a mega tile. Mega-tile–level columns (megatile_index, megatile_top, etc.) allow grouping.
​
Destination directory (created if needed).
​
Override the stored regions. Defaults to megatile_regions_.
Returns:
  • Path - Path of the written CSV file.
Raises:
  • RuntimeError - If no regions are available.
Example:

​
to_json

Saves mega-tile metadata to a JSON file named after the slide. The output is a JSON array of mega-tile objects, each containing the mega-tile location, grid info, valid ratio, and a nested tiles array with per-tile metadata.
​
Destination directory (created if needed).
​
Override the stored regions.
​
JSON pretty-printing indent.
Returns:
  • Path - Path of the written JSON file.
Raises:
  • RuntimeError - If no regions are available.
Example: