Skip to main content
Tile and mega-tile specification types for WSI extraction. Defines the TileSpec and MegaTileSpec dataclasses as well as the GridLayout enum and the MegaTileRegion container. TileSpec Encapsulates tile size, stride, target resolution, and measurement unit. Used by TileExtractor. GridLayout Enum for rectangular vs. hexagonal tiling grids. MegaTileSpec Describes a mega tile — a grid of smaller tiles — including grid dimensions, per-tile specification, layout, stride, and valid-tile-ratio bounds. Used by MegaTileExtractor. MegaTileRegion Immutable container returned by the mega-tile extractor. Holds the top-left location, grid shape, per-tile RegionSpec list, tile-availability mask, and aggregate tissue statistics. Example: 
>>> from bioptimus.extraction.wsi.types import TileSpec, MegaTileSpec, GridLayout
>>> from bioptimus.io.wsi.types import Level, MeasurementUnit
>>> tile = TileSpec(
...     size=(256, 256), stride=(256, 256),
...     resolution=Level(0), unit=MeasurementUnit.PIXELS,
... )
>>> mega = MegaTileSpec(
...     megatile_shape=(5, 5), tile_spec=tile,
...     grid_layout=GridLayout.RECTANGULAR,
... )
>>> mega.num_tiles
25

​
GridLayout

class GridLayout(str, Enum)
Layout strategy for arranging tiles within a mega tile.
​
RECTANGULAR
Standard row-major rectangular grid.
​
HEXAGONAL
Offset hex grid — odd rows are shifted right by half a tile width, producing a honeycomb pattern.
Example: 
>>> GridLayout.RECTANGULAR.value
'RECTANGULAR'

​
MegaTileSpec

@dataclass(frozen=True)
class MegaTileSpec()
Defines the specification of a mega tile — a grid of smaller tiles. A mega tile groups rows × cols individual tiles into a single logical region that can be extracted from a WSI. The per-tile geometry is delegated to TileSpec.
​
megatile_shape
tuple[int, int]
Number of tiles as (rows, cols).
​
tile_spec
TileSpec
Size, stride, resolution, and unit for each individual tile.
​
grid_layout
GridLayout
Rectangular or hexagonal arrangement. Defaults to RECTANGULAR.
​
megatile_stride
tuple[int, int] | None
Stride expressed in number of tiles as (stride_rows, stride_cols). None defaults to megatile_shape (no overlap).
​
min_valid_tiles_ratio
float
Minimum fraction of tiles that must pass the tissue-mask threshold for the mega tile to be kept. Defaults to 0.5.
​
max_valid_tiles_ratio
float | None
Optional upper bound on the valid-tile fraction. None means no upper limit.
Example: 
>>> tile = TileSpec(
...     size=(256, 256), stride=(256, 256),
...     resolution=Level(0), unit=MeasurementUnit.PIXELS,
... )
>>> mega = MegaTileSpec(megatile_shape=(5, 5), tile_spec=tile)
>>> mega.rows, mega.cols
(5, 5)
>>> mega.num_tiles
25

​
megatile_shape

(rows, cols) in number of tiles

​
megatile_stride

(stride_rows, stride_cols)

​
rows

@property
def rows() -> int
Number of tile rows in the mega tile.

​
cols

@property
def cols() -> int
Number of tile columns in the mega tile.

​
num_tiles

@property
def num_tiles() -> int
Total number of tiles in the mega tile grid.

​
effective_stride

@property
def effective_stride() -> tuple[int, int]
Returns the stride, defaulting to megatile_shape when not set.
​
returns
tuple[int, int]
tuple[int, int]: (stride_rows, stride_cols) in tiles.

​
MegaTileRegion

@dataclass(frozen=True)
class MegaTileRegion()
A group of tiles forming one extracted mega tile. Returned by MegaTileExtractor.
​
location
RegionLocation
Absolute slide coordinates of the top-left corner of the mega tile.
​
megatile_spec
MegaTileSpec
The specification that produced this mega tile (grid shape, tile spec, layout, stride, and valid-ratio bounds).
​
tile_specs
List[RegionSpec]
Per-tile region specifications, ordered row-major (tile_specs[row * cols + col]).
​
tile_availability
np.ndarray
Boolean array of shape (rows, cols) indicating which tiles passed the tissue threshold.
​
valid_ratio
float
Fraction of tiles that are valid (tissue).
Example: 
>>> mega.grid_shape
(5, 5)
>>> mega.valid_ratio
0.72
>>> mega.tile_availability.sum()
18

​
grid_shape

@property
def grid_shape() -> tuple[int, int]
(rows, cols) — number of tiles in each direction.

​
grid_layout

@property
def grid_layout() -> GridLayout
Layout used during extraction.

​
rows

@property
def rows() -> int
Number of tile rows.

​
cols

@property
def cols() -> int
Number of tile columns.

​
num_valid_tiles

@property
def num_valid_tiles() -> int
Count of tiles that passed the tissue threshold.

​
num_tiles

@property
def num_tiles() -> int
Total tile slots in the grid.