gdf2inst

Converts a GeoDataFrame to an instance segmentation raster mask.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	GeoDataFrame to convert to an instance segmentation mask.	required
xoff	int	X offset. This is used to translate the geometries in the GeoDataFrame to burn the geometries in correctly to the raster mask.	0
yoff	int	Y offset. This is used to translate the geometries in the GeoDataFrame to burn the geometries in correctly to the raster mask.	0
width	int	Width of the output. This should match with the underlying image width. If None, the width will be calculated from the input gdf.	None
height	int	Height of the output. This should match with the underlying image height. If None, the height will be calculated from the input gdf.	None
reset_index	bool	Whether to reset the index of the output GeoDataFrame.	False
id_col	str	If provided, the column name to use for the instance IDs. If None, the index of the GeoDataFrame will be used as instance IDs. Ignored if reset_index is set to True.	None

Returns:

Type	Description
GeoDataFrame	np.ndarray: Instance segmentation mask of the input gdf. Shape (height, width).

Examples:

>>> from histolytics.data import hgsc_cancer_nuclei
>>> from histolytics.utils.raster import gdf2inst
>>> from skimage.measure import label
>>> from skimage.color import label2rgb
>>> import matplotlib.pyplot as plt
>>>
>>> nuc = hgsc_cancer_nuclei()
>>> # Convert the GeoDataFrame to an instance segmentation raster
>>> nuc_raster = gdf2inst(nuc, xoff=0, yoff=0, width=1500, height=1500)
>>> # Visualize the instance segmentation raster and the GeoDataFrame
>>> fig, ax = plt.subplots(1, 2, figsize=(8, 4))
>>> ax[0].imshow(label2rgb(label(nuc_raster), bg_label=0))
>>> ax[0].set_axis_off()
>>> nuc.plot(column="class_name", ax=ax[1])
>>> ax[1].set_axis_off()
>>> fig.tight_layout()

Source code in src/histolytics/utils/raster.py

def gdf2inst(
    gdf: gpd.GeoDataFrame,
    xoff: int = 0,
    yoff: int = 0,
    width: int = None,
    height: int = None,
    reset_index: bool = False,
    id_col: str = None,
) -> gpd.GeoDataFrame:
    """Converts a GeoDataFrame to an instance segmentation raster mask.

    Parameters:
        gdf (gpd.GeoDataFrame):
            GeoDataFrame to convert to an instance segmentation mask.
        xoff (int):
            X offset. This is used to translate the geometries in the GeoDataFrame to
            burn the geometries in correctly to the raster mask.
        yoff (int):
            Y offset. This is used to translate the geometries in the GeoDataFrame to
            burn the geometries in correctly to the raster mask.
        width (int):
            Width of the output. This should match with the underlying image width.
            If None, the width will be calculated from the input gdf.
        height (int):
            Height of the output. This should match with the underlying image height.
            If None, the height will be calculated from the input gdf.
        reset_index (bool):
            Whether to reset the index of the output GeoDataFrame.
        id_col (str):
            If provided, the column name to use for the instance IDs. If None, the index
            of the GeoDataFrame will be used as instance IDs. Ignored if `reset_index`
            is set to True.

    Returns:
        np.ndarray:
            Instance segmentation mask of the input gdf. Shape (height, width).

    Examples:
        >>> from histolytics.data import hgsc_cancer_nuclei
        >>> from histolytics.utils.raster import gdf2inst
        >>> from skimage.measure import label
        >>> from skimage.color import label2rgb
        >>> import matplotlib.pyplot as plt
        >>>
        >>> nuc = hgsc_cancer_nuclei()
        >>> # Convert the GeoDataFrame to an instance segmentation raster
        >>> nuc_raster = gdf2inst(nuc, xoff=0, yoff=0, width=1500, height=1500)
        >>> # Visualize the instance segmentation raster and the GeoDataFrame
        >>> fig, ax = plt.subplots(1, 2, figsize=(8, 4))
        >>> ax[0].imshow(label2rgb(label(nuc_raster), bg_label=0))
        >>> ax[0].set_axis_off()
        >>> nuc.plot(column="class_name", ax=ax[1])
        >>> ax[1].set_axis_off()
        >>> fig.tight_layout()
    ![out](../../img/gdf2inst.png)
    """
    if gdf.empty:
        try:
            return np.zeros((int(height), int(width)), dtype=np.int32)
        except TypeError:
            raise TypeError(
                "Input gdf is empty, trying to return an empty mask but height and width"
                " are not provided. Cannot infer the output shape."
            )

    xmin, ymin, xmax, ymax = gdf.total_bounds
    xoff = xoff - xmin
    yoff = yoff - ymin

    if width is None:
        width = int(xmax - xmin)
    if height is None:
        height = int(ymax - ymin)

    geoms = gdf.geometry.translate(xoff=-xmin - xoff, yoff=-ymin - yoff)

    if reset_index:
        labels = range(len(gdf))
    else:
        if id_col is not None:
            labels = gdf[id_col].values
        else:
            labels = gdf.index.values

    image_shape = (int(height), int(width))
    shapes = list(zip(geoms, labels))
    out_mask = rasterize(
        shapes,
        out_shape=image_shape,
        fill=0,
        dtype=np.int32,
    )

    return out_mask