> ## 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.

# types

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

```pycon 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.

<ParamField body="RECTANGULAR">
  Standard row-major rectangular grid.
</ParamField>

<ParamField body="HEXAGONAL">
  Offset hex grid — odd rows are shifted right by half a tile width, producing a honeycomb pattern.
</ParamField>

**Example**:

```pycon 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`.

<ParamField body="megatile_shape" type="tuple[int, int]">
  Number of tiles as `(rows, cols)`.
</ParamField>

<ParamField body="tile_spec" type="TileSpec">
  Size, stride, resolution, and unit for each individual tile.
</ParamField>

<ParamField body="grid_layout" type="GridLayout">
  Rectangular or hexagonal arrangement. Defaults to `RECTANGULAR`.
</ParamField>

<ParamField body="megatile_stride" type="tuple[int, int] | None">
  Stride expressed in **number of tiles** as `(stride_rows, stride_cols)`. `None` defaults to `megatile_shape` (no overlap).
</ParamField>

<ParamField body="min_valid_tiles_ratio" type="float">
  Minimum fraction of tiles that must pass the tissue-mask threshold for the mega tile to be kept.  Defaults to `0.5`.
</ParamField>

<ParamField body="max_valid_tiles_ratio" type="float | None">
  Optional upper bound on the valid-tile fraction.  `None` means no upper limit.
</ParamField>

**Example**:

```pycon 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.

<ResponseField name="returns" type="tuple[int, int]">
  tuple\[int, int]: `(stride_rows, stride_cols)` in tiles.
</ResponseField>

## MegaTileRegion

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

A group of tiles forming one extracted mega tile.

Returned by `MegaTileExtractor`.

<ParamField body="location" type="RegionLocation">
  Absolute slide coordinates of the top-left corner of the mega tile.
</ParamField>

<ParamField body="megatile_spec" type="MegaTileSpec">
  The specification that produced this mega tile (grid shape, tile spec, layout, stride, and valid-ratio bounds).
</ParamField>

<ParamField body="tile_specs" type="List[RegionSpec]">
  Per-tile region specifications, ordered row-major (`tile_specs[row * cols + col]`).
</ParamField>

<ParamField body="tile_availability" type="np.ndarray">
  Boolean array of shape `(rows, cols)` indicating which tiles passed the tissue threshold.
</ParamField>

<ParamField body="valid_ratio" type="float">
  Fraction of tiles that are valid (tissue).
</ParamField>

**Example**:

```pycon 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.