> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bioptimus.extraction.wsi.types

Tile and mega-tile specification types for WSI extraction.

Defines the [`TileSpec`](/sdk-reference/data/tile_spec#tilespec) and [`MegaTileSpec`](/sdk-reference/extraction/wsi/types#megatilespec) dataclasses as well as the [`GridLayout`](/sdk-reference/extraction/wsi/types#gridlayout) enum and the [`MegaTileRegion`](/sdk-reference/extraction/wsi/types#megatileregion) container.

[`TileSpec`](/sdk-reference/data/tile_spec#tilespec) Encapsulates tile size, stride, target resolution, and measurement unit. Used by `TileExtractor`.

[`GridLayout`](/sdk-reference/extraction/wsi/types#gridlayout) Enum for rectangular vs. hexagonal tiling grids.

[`MegaTileSpec`](/sdk-reference/extraction/wsi/types#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`](/sdk-reference/extraction/wsi/types#megatileregion) Immutable container returned by the mega-tile extractor.  Holds the top-left location, grid shape, per-tile [`RegionSpec`](/sdk-reference/io/wsi/types#regionspec) list, tile-availability mask, and aggregate tissue statistics.

**Example**:

```python theme={null}
>>> 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

```python theme={null}
class GridLayout(str, Enum)
```

Layout strategy for arranging tiles within a mega tile.

**Attributes**:

* `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**:

```python theme={null}
>>> GridLayout.RECTANGULAR.value
'RECTANGULAR'
```

## MegaTileSpec

```python theme={null}
@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`](/sdk-reference/data/tile_spec#tilespec).

**Attributes**:

* `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**:

```python theme={null}
>>> 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

```python theme={null}
@property
def rows() -> int
```

Number of tile rows in the mega tile.

***

#### cols

```python theme={null}
@property
def cols() -> int
```

Number of tile columns in the mega tile.

***

#### num\_tiles

```python theme={null}
@property
def num_tiles() -> int
```

Total number of tiles in the mega tile grid.

***

#### effective\_stride

```python theme={null}
@property
def effective_stride() -> tuple[int, int]
```

Returns the stride, defaulting to `megatile_shape` when not set.

**Returns**:

tuple\[int, int]: `(stride_rows, stride_cols)` in tiles.

## MegaTileRegion

```python theme={null}
@dataclass(frozen=True)
class MegaTileRegion()
```

A group of tiles forming one extracted mega tile.

Returned by `MegaTileExtractor`.

**Attributes**:

* `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**:

```python theme={null}
>>> mega.grid_shape
(5, 5)
>>> mega.valid_ratio
0.72
>>> mega.tile_availability.sum()
18
```

***

#### grid\_shape

```python theme={null}
@property
def grid_shape() -> tuple[int, int]
```

`(rows, cols)` — number of tiles in each direction.

***

#### grid\_layout

```python theme={null}
@property
def grid_layout() -> GridLayout
```

Layout used during extraction.

***

#### rows

```python theme={null}
@property
def rows() -> int
```

Number of tile rows.

***

#### cols

```python theme={null}
@property
def cols() -> int
```

Number of tile columns.

***

#### num\_valid\_tiles

```python theme={null}
@property
def num_valid_tiles() -> int
```

Count of tiles that passed the tissue threshold.

***

#### num\_tiles

```python theme={null}
@property
def num_tiles() -> int
```

Total tile slots in the grid.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.