Preprocessing¶
alhena.preprocess contains the image-geometry operations applied before the encoder.
prepare_tiles() resamples input tiles to ALHENA's model resolution and maps them to the
224 × 224 canvas. Without a declared resolution, tiles are resized to the canvas as they are, so
nothing is padded or cropped. describe_geometry() and plan_resample() report the
corresponding transformation from image shapes alone.
Padding
An input field smaller than the model field of view is centered and padded with white
pixels. pad_fraction records the affected fraction of the model canvas.
Cropping
An input field larger than the model field of view is center-cropped. crop_fraction
records the fraction of the resampled field discarded outside the model canvas.
See Geometry for interpretation and recommended tile sizes.
What normalization means here
normalize_tile() applies fixed channel normalization; it does not perform stain
normalization.
prepare_tiles(images, mpp=None, target_mpp=REFERENCE_MPP, progress=None)
Prepare tiles for the encoder.
With mpp declared, tiles are resampled to target_mpp and center-cropped or padded to the
model input size, so the field of view is physical; without it, they are resized to the input
size as they are, with a warning. A tile source carrying a resolution declares it itself, and an
mpp more than MPP_TOLERANCE from it is refused. Tiles are read one at a time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
images
|
ndarray | Sequence[ndarray]
|
An |
required |
mpp
|
float | None
|
Microns per pixel of the tiles. Defaults to the resolution a tile source carries. |
None
|
target_mpp
|
float
|
Microns per pixel to resample to. |
REFERENCE_MPP
|
progress
|
bool | None
|
Whether to report progress on standard error. None follows
|
None
|
Returns:
| Type | Description |
|---|---|
Tensor
|
An |
ResampleInfo
|
reach it. |
Raises:
| Type | Description |
|---|---|
AlhenaValueError
|
If there are no tiles, or |
GeometryError
|
If a tile is not uint8 RGB or holds no pixel. |
describe_geometry(mpp, tile_size_px=INPUT_SIZE, median_nucleus_area_px=None, target_mpp=REFERENCE_MPP)
Describe the physical geometry a set of tiles presents to the model.
Read from shapes alone, it agrees with prepare_tiles on pad_fraction and crop_fraction,
both zero without a declared resolution. A crop discarding more than CROP_WARNING_FRACTION of
each field is a note of the report; the pad is reported, not noted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mpp
|
float | None
|
Microns per pixel of the tiles, refused where |
required |
tile_size_px
|
int
|
Side of the tiles, in pixels. |
INPUT_SIZE
|
median_nucleus_area_px
|
float | None
|
Median nucleus area in the tiles, in square pixels, used to report how many tokens a typical nucleus spans. |
None
|
target_mpp
|
float
|
Microns per pixel the model reads at. |
REFERENCE_MPP
|
Returns:
| Type | Description |
|---|---|
GeometryReport
|
A record of the field of view, the microns one token covers, the share of the canvas the |
GeometryReport
|
tiles pad with white, the share of each field the center crop discards, and any geometry |
GeometryReport
|
concern. |
Raises:
| Type | Description |
|---|---|
AlhenaValueError
|
If a resolution is not positive or exceeds |
plan_resample(source_size, mpp=None, target_mpp=REFERENCE_MPP)
Return what prepare_tiles would do to tiles of a given size, touching no pixel.
Every field agrees with the record prepare_tiles returns for tiles of that size. A scale
leaving no pixels is reported as a canvas of pure pad, where prepare_tiles refuses it, and a
resolution finer than MIN_MICROSCOPE_MPP is described without a warning.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_size
|
tuple[int, int]
|
Height and width of the tiles as they arrive. |
required |
mpp
|
float | None
|
Microns per pixel of the tiles. Without one, tiles are resized to the input size as they are, so nothing is padded and nothing is cropped. |
None
|
target_mpp
|
float
|
Microns per pixel to resample to. |
REFERENCE_MPP
|
Returns:
| Type | Description |
|---|---|
ResampleInfo
|
The record |
Raises:
| Type | Description |
|---|---|
AlhenaValueError
|
If a resolution is not positive or exceeds |
Return the per-channel lookup table mapping a byte value to its normalized float.
The reciprocal is taken in float32, as in the distillation, rather than in double and cast, which rounds differently.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mean
|
Sequence[float]
|
Per-channel mean, on the unit scale. |
IMAGE_MEAN
|
std
|
Sequence[float]
|
Per-channel standard deviation, on the unit scale. |
IMAGE_STD
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A |
Normalize one RGB tile and return it in channel-first layout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
A (H, W, 3) uint8 RGB tile. |
required |
lut
|
ndarray | None
|
A table from |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A (3, H, W) float32 array. |
Raises:
| Type | Description |
|---|---|
GeometryError
|
If the tile is not (H, W, 3) uint8. |
Resample a tile by a scale factor, preserving its aspect ratio.
Bilinear, or averaged over pixel area past a twofold shrink, where bilinear would alias fine texture.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
A |
required |
scale
|
float
|
Multiplier applied to both sides. A value above one enlarges. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
The resampled tile. |
Raises:
| Type | Description |
|---|---|
GeometryError
|
If the scale would collapse the tile to nothing. |
fit_to_size(image, size=INPUT_SIZE)
Center-crop or pad a tile to a square of the given side.
Padding uses white, the background of an H&E section.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
A (H, W, 3) uint8 RGB tile. |
required |
size
|
int
|
Side of the output square. |
INPUT_SIZE
|
Returns:
| Type | Description |
|---|---|
ndarray
|
The fitted tile, whether it was padded, whether it was cropped, and how many pixels of |
bool
|
the output came from padding rather than from the tile. |
module-attribute
¶
Opening of the warning raised where no tile resolution is declared, to match it in a filter.
Next: Cells and pooling