eyepy.core.annotations

EyeBscanLayerAnnotation(eyevolumelayerannotation, index)

Layer annotation for a single B-scan.

Parameters:

Name	Type	Description	Default
eyevolumelayerannotation	EyeVolumeLayerAnnotation	EyeVolumeLayerAnnotation object	required
index	int	Index of the B-scan	required

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def __init__(self, eyevolumelayerannotation: EyeVolumeLayerAnnotation,
             index: int) -> None:
    """Layer annotation for a single B-scan.

    Args:
        eyevolumelayerannotation: EyeVolumeLayerAnnotation object
        index: Index of the B-scan

    Returns:
        None
    """
    self.eyevolumelayerannotation = eyevolumelayerannotation
    self.volume = eyevolumelayerannotation.volume
    self.index = index

data property writable

Layer heights.

knots property writable

Knots parameterizing the layer heights.

name property writable

Name of the layer annotation.

EyeBscanSlabAnnotation(eyevolumeslabannotation, index)

Slab annotation for a single B-scan.

Parameters:

Name	Type	Description	Default
eyevolumeslabannotation	EyeVolumeSlabAnnotation	EyeVolumeSlabAnnotation object	required
index	int	Index of the B-scan	required

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def __init__(self, eyevolumeslabannotation: EyeVolumeSlabAnnotation,
             index: int) -> None:
    """Slab annotation for a single B-scan.

    Args:
        eyevolumeslabannotation: EyeVolumeSlabAnnotation object
        index: Index of the B-scan

    Returns:
        None
    """
    self.eyevolumeslabannotation = eyevolumeslabannotation
    self.volume = eyevolumeslabannotation.volume
    self.index = index

mask property writable

Mask of the slab in the B-scan.

name property writable

Name of the slab annotation.

EyeEnfacePixelAnnotation(enface, data=None, meta=None, **kwargs)

Pixel annotation for an enface image.

Parameters:

Name	Type	Description	Default
enface	EyeEnface	EyeEnface object	required
data	Optional[NDArray[bool_]]	Pixel annotation data	None
meta	Optional[dict]	Metadata	None
**kwargs	Any	Additional metadata specified as keyword arguments	{}

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def __init__(
    self,
    enface: EyeEnface,
    data: Optional[npt.NDArray[np.bool_]] = None,
    meta: Optional[dict] = None,
    **kwargs: Any,
) -> None:
    """Pixel annotation for an enface image.

    Args:
        enface: EyeEnface object
        data: Pixel annotation data
        meta: Metadata
        **kwargs: Additional metadata specified as keyword arguments

    Returns:
        None
    """
    self.enface = enface

    if data is None:
        self.data = np.full(self.enface.shape,
                            fill_value=False,
                            dtype=bool)
    else:
        self.data = data

    if meta is None:
        self.meta = kwargs
    else:
        self.meta = meta
        self.meta.update(**kwargs)

    if 'name' not in self.meta:
        self.meta['name'] = 'Pixel Annotation'

name property writable

Name of the pixel annotation.

EyeVolumeLayerAnnotation(volume, data=None, meta=None, **kwargs)

Layer annotation for a single layer in an EyeVolume.

Parameters:

Name	Type	Description	Default
volume	EyeVolume	EyeVolume object	required
data	Optional[NDArray[float64]]	2D array of shape (n_bscans, bscan_width) holding layer height values	None
meta	Optional[dict]	dict with additional meta data	None
**kwargs	Any	additional meta data specified as parameters	{}

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def __init__(
    self,
    volume: EyeVolume,
    data: Optional[npt.NDArray[np.float64]] = None,
    meta: Optional[dict] = None,
    **kwargs: Any,
) -> None:
    """Layer annotation for a single layer in an EyeVolume.

    Args:
        volume: EyeVolume object
        data: 2D array of shape (n_bscans, bscan_width) holding layer height values
        meta: dict with additional meta data
        **kwargs: additional meta data specified as parameters

    Returns:
        None
    """
    self.volume = volume
    if data is None:
        self.data = np.full((volume.size_z, volume.size_x), np.nan)
    else:
        self.data = data

    if meta is None:
        self.meta = kwargs
    else:
        self.meta = meta
        self.meta.update(**kwargs)

    # knots is a dict layername: list of curves where every curve is a list of knots
    if 'knots' not in self.meta:
        self.meta['knots'] = defaultdict(lambda: [])
    elif type(self.meta['knots']) is dict:
        self.meta['knots'] = defaultdict(lambda: [], self.meta['knots'])

    if 'name' not in self.meta:
        self.meta['name'] = 'Layer Annotation'

    self.meta['current_color'] = config.layer_colors[self.name]

knots property

Knots parameterizing the layer.

name property writable

Layer name.

layer_indices()

Returns pixel indices of the layer in the volume.

While the layer is stored as the offset from the bottom of the OCT volume, some applications require layer discretized to voxel positions. This method returns the layer as indices into the OCT volume.

The indices can be used for example to create layer maps for semantic segmentation.

import matplotlib.pyplot as plt
import numpy as np
import eyepy as ep

eye_volume = ep.data.load("drusen_patient")
rpe_annotation = eye_volume.layers["RPE"]
rpe_indices = rpe_annotation.layer_indices()
rpe_map = np.zeros(eye_volume.shape)
rpe_map[rpe_indices] = 1
plt.imshow(rpe_map[0]) # (1)

1. Visualize layer map for the first B-scan

Returns:

Type	Description
tuple[ndarray, ndarray, ndarray]	A tuple with indices for the layers position in the volume - Tuple[bscan_indices, row_indices, column_indices]

Source code in src/eyepy/core/annotations.py

def layer_indices(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
    """Returns pixel indices of the layer in the volume.

    While the layer is stored as the offset from the bottom of the OCT volume, some applications require
    layer discretized to voxel positions. This method returns the layer as indices into the OCT volume.

    The indices can be used for example to create layer maps for semantic segmentation.

    ```python
    import matplotlib.pyplot as plt
    import numpy as np
    import eyepy as ep

    eye_volume = ep.data.load("drusen_patient")
    rpe_annotation = eye_volume.layers["RPE"]
    rpe_indices = rpe_annotation.layer_indices()
    rpe_map = np.zeros(eye_volume.shape)
    rpe_map[rpe_indices] = 1
    plt.imshow(rpe_map[0]) # (1)
    ```

    1.  Visualize layer map for the first B-scan

    Returns:
        A tuple with indices for the layers position in the volume - Tuple[bscan_indices, row_indices, column_indices]
    """
    layer = self.data[:, np.newaxis, :]
    nan_indices = np.isnan(layer)
    row_indices = np.rint(layer).astype(int)[~nan_indices]
    x = np.ones(layer.shape)
    x[nan_indices] = 0
    bscan_indices, _, col_indices = np.nonzero(x)
    return (bscan_indices, row_indices, col_indices)

EyeVolumePixelAnnotation(volume, data=None, meta=None, radii=(1.5, 2.5), n_sectors=(1, 4), offsets=(0, 45), center=None, **kwargs)

Pixel annotation for an EyeVolume.

Parameters:

Name	Type	Description	Default
volume	EyeVolume	EyeVolume object	required
data	Optional[NDArray[bool_]]	3D array of shape (n_bscans, bscan_height, bscan_width) holding boolean pixel annotations	None
meta	Optional[dict]	dict with additional meta data	None
radii	Iterable[float]	radii for quantification on circular grid	(1.5, 2.5)
n_sectors	Iterable[int]	number of sectors for quantification on circular grid	(1, 4)
offsets	Iterable[int]	offsets from x axis for first sector, for quantification on circular grid	(0, 45)
center	Optional[tuple[float, float]]	center of circular grid for quantification	None
**kwargs	Any	additional meta data specified as parameters	{}

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def __init__(
    self,
    volume: EyeVolume,
    # Type hint for an optional boolean numpy array
    data: Optional[npt.NDArray[np.bool_]] = None,
    meta: Optional[dict] = None,
    radii: Iterable[float] = (1.5, 2.5),
    n_sectors: Iterable[int] = (1, 4),
    offsets: Iterable[int] = (0, 45),
    center: Optional[tuple[float, float]] = None,
    **kwargs: Any,
) -> None:
    """Pixel annotation for an EyeVolume.

    Args:
        volume: EyeVolume object
        data: 3D array of shape (n_bscans, bscan_height, bscan_width) holding boolean pixel annotations
        meta: dict with additional meta data
        radii: radii for quantification on circular grid
        n_sectors: number of sectors for quantification on circular grid
        offsets: offsets from x axis for first sector, for quantification on circular grid
        center: center of circular grid for quantification
        **kwargs: additional meta data specified as parameters

    Returns:
        None
    """
    self.volume = volume

    if data is None:
        self.data = np.full(self.volume.shape,
                            fill_value=False,
                            dtype=bool)
    else:
        self.data = data

    self._masks = None
    self._quantification = None

    if meta is None:
        self.meta = kwargs
    else:
        self.meta = meta
        self.meta.update(**kwargs)

    self.meta.update(
        **{
            'radii': radii,
            'n_sectors': n_sectors,
            'offsets': offsets,
            'center': center,
        })

    if 'name' not in self.meta:
        self.meta['name'] = 'Voxel Annotation'

center property writable

Center of circular grid for quantification.

enface property

Transformed projection of the annotation to the enface plane.

masks property

Masks for quantification on circular grid.

Returns:

Type	Description
dict[str, ndarray]	A dictionary of masks with the keys being the names of the masks.

n_sectors property writable

Number of sectors for quantification on circular grid.

name property writable

Annotation name.

offsets property writable

Offsets from x axis for first sector, for quantification on circular grid.

projection property

Projection of the annotation to the enface plane.

quantification property

Quantification of the annotation on the specified circular grid.

Returns:

Type	Description
dict[str, Union[float, str]]	A dictionary of quantifications with the keys being the names of the regions.

radii property writable

Radii for quantification on circular grid.

plot(ax=None, region=np.s_[:, :], cmap='Reds', vmin=None, vmax=None, cbar=True, alpha=1)

Plot the annotation on the enface plane.

Parameters:

Name	Type	Description	Default
ax	Optional[Axes]	matplotlib axes object	None
region	Union[slice, tuple[slice, slice]]	region of the enface projection to plot	s_[:, :]
cmap	Union[str, Colormap]	colormap	'Reds'
vmin	Optional[float]	minimum value for colorbar	None
vmax	Optional[float]	maximum value for colorbar	None
cbar	bool	whether to plot a colorbar	True
alpha	float	alpha value for the annotation	1

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def plot(
    self,
    ax: Optional[plt.Axes] = None,
    region: Union[slice, tuple[slice, slice]] = np.s_[:, :],
    cmap: Union[str, mpl.colors.Colormap] = 'Reds',
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cbar: bool = True,
    alpha: float = 1,
) -> None:
    """Plot the annotation on the enface plane.

    Args:
        ax: matplotlib axes object
        region: region of the enface projection to plot
        cmap: colormap
        vmin: minimum value for colorbar
        vmax: maximum value for colorbar
        cbar: whether to plot a colorbar
        alpha: alpha value for the annotation

    Returns:
        None
    """
    enface_projection = self.enface

    ax = plt.gca() if ax is None else ax

    if vmin is None:
        vmin = 1
    if vmax is None:
        vmax = max([enface_projection.max(), vmin])

    enface_crop = enface_projection[region]
    visible = np.zeros(enface_crop.shape)
    visible[np.logical_and(vmin <= enface_crop, enface_crop <= vmax)] = 1

    if cbar:
        divider = make_axes_locatable(ax)
        cax = divider.append_axes('right', size='5%', pad=0.05)
        plt.colorbar(
            cm.ScalarMappable(colors.Normalize(vmin=vmin, vmax=vmax),
                              cmap=cmap),
            cax=cax,
        )

    ax.imshow(
        enface_crop,
        alpha=visible * alpha,
        cmap=cmap,
        vmin=vmin,
        vmax=vmax,
    )

plot_quantification(ax=None, region=np.s_[:, :], alpha=0.5, vmin=None, vmax=None, cbar=True, cmap='YlOrRd')

Plot circular grid quantification of the annotation (like ETDRS)

Parameters:

Name	Type	Description	Default
ax	Optional[Axes]	Matplotlib axes to plot on	None
region	Union[slice, tuple[slice, slice]]	Region to plot	s_[:, :]
alpha	float	Alpha value of the mask	0.5
vmin	Optional[float]	Minimum value for the colorbar	None
vmax	Optional[float]	Maximum value for the colorbar	None
cbar	bool	Whether to plot a colorbar	True
cmap	Union[str, Colormap]	Colormap to use	'YlOrRd'

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def plot_quantification(
    self,
    ax: Optional[plt.Axes] = None,
    region: Union[slice, tuple[slice, slice]] = np.s_[:, :],
    alpha: float = 0.5,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cbar: bool = True,
    cmap: Union[str, mpl.colors.Colormap] = 'YlOrRd',
) -> None:
    """Plot circular grid quantification of the annotation (like ETDRS)

    Args:
        ax: Matplotlib axes to plot on
        region: Region to plot
        alpha: Alpha value of the mask
        vmin: Minimum value for the colorbar
        vmax: Maximum value for the colorbar
        cbar: Whether to plot a colorbar
        cmap: Colormap to use

    Returns:
        None
    """

    ax = plt.gca() if ax is None else ax

    mask_img = np.zeros(self.volume.localizer.shape, dtype=float)[region]
    visible = np.zeros_like(mask_img)
    for mask_name in self.masks.keys():
        mask_img += (self.masks[mask_name][region] *
                     self.quantification[mask_name + ' [mm³]'])
        visible += self.masks[mask_name][region]

    vmin = mask_img[visible.astype(int)].min() if vmin is None else vmin
    vmax = max([mask_img.max(), vmin]) if vmax is None else vmax

    if cbar:
        divider = make_axes_locatable(ax)
        cax = divider.append_axes('right', size='5%', pad=0.05)
        plt.colorbar(
            cm.ScalarMappable(colors.Normalize(vmin=vmin, vmax=vmax),
                              cmap=cmap),
            cax=cax,
        )

    ax.imshow(
        mask_img,
        alpha=visible * alpha,
        cmap=cmap,
        vmin=vmin,
        vmax=vmax,
    )

EyeVolumeSlabAnnotation(volume, meta=None, **kwargs)

Parameters:

Name	Type	Description	Default
volume	EyeVolume	An EyeVolume object	required
meta	Optional[dict]	dict with additional meta data	None
**kwargs	Any	additional meta data as keyword arguments	{}

Source code in src/eyepy/core/annotations.py

def __init__(
    self,
    volume: EyeVolume,
    meta: Optional[dict] = None,
    **kwargs: Any,
) -> None:
    """

    Args:
        volume: An EyeVolume object
        meta: dict with additional meta data
        **kwargs: additional meta data as keyword arguments
    """
    self.volume = volume
    self._mask = None

    if meta is None:
        self.meta = kwargs
    else:
        self.meta = meta
        self.meta.update(**kwargs)

    # Set default values if not provided
    if 'name' not in self.meta:
        self.meta['name'] = 'OCTA Slab'

    # Ensure layer references are present
    if 'top_layer' not in self.meta:
        self.meta['top_layer'] = None
    if 'bottom_layer' not in self.meta:
        self.meta['bottom_layer'] = None

bottom_layer property writable

Bottom layer name/acronym.

enface property

Transformed projection of the annotation to the enface plane.

mask property

Mask of the slab in the volume.

name property writable

Slab name.

projection property

Projection of the data within the slab mask to the enface plane.

top_layer property writable

Top layer name/acronym.

apply_contrast(enface, contrast)

Apply contrast to the enface projection.

Source code in src/eyepy/core/annotations.py

def apply_contrast(self, enface: np.ndarray, contrast: float) -> np.ndarray:
    """Apply contrast to the enface projection."""
    if contrast <= 0:
        logger.warning(f'Invalid contrast value: {contrast}. Using default contrast of 4.')
        contrast = 4

    return np.clip(enface / contrast, 0, 1.0)

plot(ax=None, region=np.s_[:, :], cmap='Greys_r', vmin=None, vmax=None, cbar=False, alpha=1, contrast=None, par=None, transform=False, **kwargs)

Plot the annotation on the enface plane.

Parameters:

Name	Type	Description	Default
ax	Optional[Axes]	matplotlib axes object	None
region	Union[slice, tuple[slice, slice]]	region of the enface projection to plot	s_[:, :]
cmap	Union[str, Colormap]	colormap	'Greys_r'
vmin	Optional[float]	minimum value for colorbar	None
vmax	Optional[float]	maximum value for colorbar	None
cbar	bool	whether to plot a colorbar	False
alpha	float	alpha value for the annotation	1
contrast	Union[int, Literal['auto']]	contrast value for the annotation	None
par	bool	whether to apply Projection Artifact Removal (PAR) to the enface projection	None
transform	bool	whether to apply the localizer transform to the enface projection	False

Returns:

Type	Description
None	None

Source code in src/eyepy/core/annotations.py

def plot(
    self,
    ax: Optional[plt.Axes] = None,
    region: Union[slice, tuple[slice, slice]] = np.s_[:, :],
    cmap: Union[str, mpl.colors.Colormap] = 'Greys_r',
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cbar: bool = False,
    alpha: float = 1,
    contrast: Union[int, Literal['auto']] = None,
    par: bool = None,
    transform: bool = False,
    **kwargs
) -> None:
    """Plot the annotation on the enface plane.

    Args:
        ax: matplotlib axes object
        region: region of the enface projection to plot
        cmap: colormap
        vmin: minimum value for colorbar
        vmax: maximum value for colorbar
        cbar: whether to plot a colorbar
        alpha: alpha value for the annotation
        contrast: contrast value for the annotation
        par: whether to apply Projection Artifact Removal (PAR) to the enface projection
        transform: whether to apply the localizer transform to the enface projection

    Returns:
        None
    """
    if par is None:
        par = SLAB_PROJECTION_DEFAULTS.get(self.name, {}).get('PAR', False)

    enface_projection = self.enface(par) if transform else self.projection(par)

    if contrast is None:
        contrast = SLAB_PROJECTION_DEFAULTS.get(self.name, {}).get('contrast', 'auto')
    if contrast == 'auto':
        contrast = self.iqr_contrast(self.projection(par), kwargs.get('factor', 1.5))
    elif not isinstance(contrast, (int, float)) or contrast <= 0:
        logger.warning(
            f'Invalid contrast value: {contrast}. Using default contrast of 4.')
        contrast = 4
    else:
        contrast = int(contrast)

    enface_crop = self.apply_contrast(enface_projection[region], contrast)

    ax = plt.gca() if ax is None else ax

    if vmin is None:
        vmin = 0
    if vmax is None:
        vmax = np.nanmax([np.nanmax(enface_crop), vmin])

    visible = np.zeros(enface_crop.shape)
    visible[np.logical_and(vmin < enface_crop, enface_crop <= vmax)] = 1

    if cbar:
        divider = make_axes_locatable(ax)
        cax = divider.append_axes('right', size='5%', pad=0.05)
        plt.colorbar(
            cm.ScalarMappable(colors.Normalize(vmin=vmin, vmax=vmax),
                              cmap=cmap),
            cax=cax,
        )

    ax.imshow(
        enface_crop,
        alpha=visible * alpha,
        cmap=cmap,
        vmin=vmin,
        vmax=vmax,
    )