visutils

Module to visualise .tiff images, label masks and results from the fitting of neural networks for remote sensing.

WGS84

WGS84 co-ordinate reference system acting as a default CRS for transformations.

Type:: CRS

de_interlace(x: Sequence[Any], f: int) → ndarray[tuple[int, ...], dtype[Any]]

Separates interlaced arrays, x at a frequency of f from each other.

Parameters:

x (Sequence[Any]) – Array of data to be de-interlaced.
f (int) – Frequency at which interlacing occurs. Equivalent to number of sources interlaced together.

Returns:

De-interlaced array. Each source array is now sequentially connected.

Return type:

ndarray[Any]

dec_extent_to_deg(shape: tuple[int, int], bounds: BoundingBox, src_crs: CRS, new_crs: CRS = CRS.from_epsg(4326), spacing: int = 32) → tuple[tuple[int, int, int, int], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]]

Gets the extent of the image with shape and with bounds in latitude, longitude of system new_crs.

Parameters:

shape (tuple[int, int]) – 2D shape of image to be used to define the extents of the composite image.
bounds (BoundingBox) – Object describing a geospatial bounding box. Must contain minx, maxx, miny and maxy parameters.
src_crs (CRS) – Source co-ordinate reference system (CRS).
new_crs (CRS) – Optional; The co-ordinate reference system (CRS) to transform to.
spacing (int) – Spacing of the lat - lon ticks.

Returns:

The corners of the image in pixel co-ordinates e.g. (0, 256, 0, 256).
The latitude extent of the image with ticks at intervals defined by spacing.
The longitude extent of the image with ticks at intervals defined by spacing.

Return type:

tuple[tuple[int, int, int, int], ndarray[float], ndarray[float]]

discrete_heatmap(data: ndarray[tuple[int, ...], dtype[int64]], classes: list[str] | tuple[str, ...], cmap_style: str | ListedColormap | None = None, block_size: int = 32) → None

Plots a heatmap with a discrete colour bar. Designed for Radiant Earth MLHub 256x256 SENTINEL images.

Parameters:

data (ndarray[int]) – 2D Array of data to be plotted as a heat map.
classes (list[str]) – Optional; List of all possible class labels.
cmap_style (str | ListedColormap) – Optional; Name or object for colour map style.
block_size (int) – Optional; Size of block image subdivision in pixels.

format_plot_names(model_name: str, timestamp: str, path: Sequence[str] | str | Path) → dict[str, Path]

Creates unique filenames of plots in a standardised format.

Parameters:

model_name (str) – Name of model. e.g. "MLP-MkVI".
timestamp (str) – Time and date to be used to identify experiment.
path (list[str] | str | Path]) – Path to the directory for storing plots as a list of strings for each level.

Returns:

Formatted filenames for plots.

Return type:

filenames (dict[str, Path])

get_mlp_cmap(cmap_style: Colormap | str | None = None, n_classes: int | None = None) → Colormap | None

Creates a cmap from query

Parameters:

cmap_style (Colormap | str) – Optional; matplotlib colourmap style to get.
n_classes (int) – Optional; Number of classes in data to assign colours to.

Returns:

If cmap_style and n_classes provided, returns a ListedColormap instance.
If cmap_style provided but no n_classes, returns a Colormap instance.
If neither arguments are provided, None is returned.

Return type:

Colormap | None

labelled_rgb_image(image: ndarray[tuple[int, ...], dtype[float64]], mask: ndarray[tuple[int, ...], dtype[int64]], bounds: BoundingBox, src_crs: CRS, path: str | Path, name: str, classes: list[str] | tuple[str, ...], cmap_style: str | ListedColormap | None = None, new_crs: CRS | None = CRS.from_epsg(4326), block_size: int = 32, alpha: float = 0.5, show: bool = True, save: bool = True, figdim: tuple[int | float, int | float] = (8.02, 10.32)) → Path

Produces a layered image of an RGB image, and it’s associated label mask heat map alpha blended on top.

Parameters:

image (ndarray[int]) – Array representing the image of shape (height x width x bands).
mask (ndarray[int]) – Ground truth mask. Should be of shape (height x width) matching image.
bounds (BoundingBox) – Object describing a geospatial bounding box. Must contain minx, maxx, miny and maxy parameters.
src_crs (CRS) – Source co-ordinate reference system (CRS).
path (str) – Path to where to save created figure.
name (str) – Name of figure. Will be used for title and in the filename.
classes (list[str]) – Optional; List of all possible class labels.
cmap_style (str | ListedColormap) – Optional; Name or object for colour map style.
new_crs (CRS) – Optional; The co-ordinate reference system (CRS) to transform to.
block_size (int) – Optional; Size of block image subdivision in pixels.
alpha (float) – Optional; Fraction determining alpha blending of label mask.
show (bool) – Optional; Show the figure when plotted.
save (bool) – Optional; Save the figure to path.
figdim (tuple[int | float, int | float]) – Optional; Figure (height, width) in inches.

Returns:

Path to figure save location.

Return type:

str

make_confusion_matrix(pred: list[int] | ndarray[tuple[int, ...], dtype[int64]], labels: list[int] | ndarray[tuple[int, ...], dtype[int64]], classes: dict[int, str], filename: str | Path | None = None, cmap_style: str = 'Blues', figsize: tuple[int, int] = (2, 2), show: bool = True, save: bool = False) → None

Creates a heat-map of the confusion matrix of the given model.

Parameters:

pred (list[int]) – Predictions made by model on test images.
labels (list[int]) – Accompanying ground truth labels for testing images.
classes (dict[int, str]) – Dictionary mapping class labels to class names.
filename (str) – Optional; Name of file to save plot to.
cmap_style (str) – Colourmap style to use in the confusion matrix.
show (bool) – Optional; Whether to show plot.
save (bool) – Optional; Whether to save plot to file.

Returns:

None

make_gif(dates: Sequence[str], images: ndarray[tuple[int, ...], dtype[Any]], masks: ndarray[tuple[int, ...], dtype[Any]], bounds: BoundingBox, src_crs: CRS, classes: list[str] | tuple[str, ...], gif_name: str, path: str | Path, cmap_style: str | ListedColormap | None = None, fps: float = 1.0, new_crs: CRS | None = CRS.from_epsg(4326), alpha: float = 0.5, figdim: tuple[int | float, int | float] = (8.02, 10.32)) → None

Wrapper to labelled_rgb_image() to make a GIF for a patch out of scenes.

Parameters:

dates (Sequence[str]) – Dates of scenes to be used as the frames in the GIF.
images (ndarray[Any]) – All the frames of imagery to make the GIF from. Leading dimension must be the same length as dates and masks.
masks (ndarray[Any]) – The masks for each frame of the GIF. Leading dimension must be the same length as dates and image.
bounds (BoundingBox) – The bounding box (in the src_crs CRS) of the patch the GIF will be of.
src_crs (CRS) – Source co-ordinate reference system (CRS).
classes (list[str]) – List of all possible class labels.
gif_name (str) – Path to and name of GIF to be made.
path (Path | str]) – Path to where to save frames of the GIF.
cmap_style (str | ListedColormap) – Optional; Name or object for colour map style.
fps (float) – Optional; Frames per second of GIF.
new_crs (CRS) – Optional; The co-ordinate reference system (CRS) to transform to.
alpha (float) – Optional; Fraction determining alpha blending of label mask.
figdim (tuple[int | float, int | float]) – Optional; Figure (height, width) in inches.

Returns:

None

make_rgb_image(image: ndarray[tuple[int, ...], dtype[float64]], block_size: int = 32, max_pixel_value: int = 255) → AxesImage

Creates an RGB image from a composition of red, green and blue bands.

Parameters:

image (ndarray[int]) – Array representing the image of shape (bands x height x width).
block_size (int) – Optional; Size of block image sub-division in pixels.
max_value (int) – Optional; The maximum pixel value in image. e.g. for 8 bit this will be 255.

Returns:

Plotted RGB image object.

Return type:

AxesImage

Plots ROC curves for each class, the micro and macro average ROC curves and accompanying AUCs.

Adapted from Scikit-learn’s example at: https://scikit-learn.org/stable/auto_examples/model_selection/plot_roc.html

Parameters:

probs (list | ndarray[int]) – Array of probabilistic predicted classes from model where each sample should have a list of the predicted probability for each class.
labels (list | ndarray[int]) – List of corresponding ground truth labels.
class_names (dict[int, str]) – Dictionary mapping class labels to class names.
colours (dict[int, str]) – Dictionary mapping class labels to colours.
micro (bool) – Optional; Whether to compute and plot the micro average ROC curves.
macro (bool) – Optional; Whether to compute and plot the macro average ROC curves.
filename (str | Path) – Optional; Name of file to save plot to.
save (bool) – Optional; Whether to save the plots to file.
show (bool) – Optional; Whether to show the plots.

Returns:

None

Using TSNE Clustering, visualises the embeddings from a model.

Parameters:

embeddings (Any) – Embeddings from a model.
bounds (Sequence[BoundingBox] | ndarray[BoundingBox]) – # noqa: E501 Array of objects describing a geospatial bounding box. Must contain minx, maxx, miny and maxy parameters.
task_name (str) – Name of the task that the samples are from.
title (str) – Optional; Title of plot.
show (bool) – Optional; Whether to show plot.
save (bool) – Optional; Whether to save plot to file.
filename (str) – Optional; Name of file to save plot to.
cache_dir (str | Path) – Optional; Path to the directory to load the cached dataset from. Defaults to None (so will create dataset from scratch).

Returns:

None

plot_history(metrics: dict[str, Any], filename: str | Path | None = None, save: bool = True, show: bool = False) → None

Plots model history based on metrics supplied.

Parameters:

metrics (dict[str, Any]) – Dictionary containing the names and results of the metrics by which model was assessed.
filename (str) – Optional; Name of file to save plot to.
show (bool) – Optional; Whether to show plot.
save (bool) – Optional; Whether to save plot to file.

Returns:

None

Orchestrates the creation of various plots from the results of a model fitting.

Parameters:

plots (dict[str, bool]) – Dictionary defining which plots to make.
x (list[list[int]] | ndarray[ndarray[int]]) – Optional; List of images supplied to the model.
y (list[list[int]] | ndarray[ndarray[int]]) – Optional; List of corresponding ground truth labels.
z (list[list[int]] | ndarray[ndarray[int]]) – Optional; List of predicted label masks.
metrics (dict[str, Any]) – Optional; Dictionary containing a log of various metrics used to assess the performance of a model.
ids (list[str]) – Optional; List of IDs defining the origin of samples to the model. Maybe either patch IDs or scene tags.
task_name (str) – Optional; Name of task that samples are from.
index (ndarray[int] | ndarray[BoundingBox]) – Optional; Array of objects describing a geospatial bounding box for each sample or a sequence of indexes.
probs (list[float] | ndarray[float]) – Optional; Array of probabilistic predicted classes from model where each sample should have a list of the predicted probability for each class.
embeddings (ndarray[Any]) – Embeddings from the model to visualise with TSNE clustering.
class_names (dict[int, str]) – Optional; Dictionary mapping class labels to class names.
colours (dict[int, str]) – Optional; Dictionary mapping class labels to colours.
save (bool) – Optional; Save the plots to file.
show (bool) – Optional; Show the plots.
model_name (str) – Optional; Name of model. e.g. MLP-MkVI.
timestamp (str) – Optional; Time and date to be used to identify experiment. If not specified, the current date-time is used.
results_dir (list[str] | str | Path) – Optional; Path to the directory for storing plots.

Notes

save==True, show==False regardless of input for plots made for each sample such as PvT or Mask plots.

Returns:: None

plot_subpopulations(class_dist: list[tuple[int, int]], class_names: dict[int, str] | None = None, cmap_dict: dict[int, str] | None = None, filename: str | Path | None = None, save: bool = True, show: bool = False) → None

Creates a pie chart of the distribution of the classes within the data.

Parameters:

class_dist (list[tuple[int, int]]) – Modal distribution of classes in the dataset provided.
class_names (dict[int, str]) – Optional; Dictionary mapping class labels to class names.
cmap_dict (dict[int, str]) – Optional; Dictionary mapping class labels to class colours.
filename (str) – Optional; Name of file to save plot to.
show (bool) – Optional; Whether to show plot.
save (bool) – Optional; Whether to save plot to file.

Returns:

None

prediction_plot(sample: dict[str, Any], sample_id: str, classes: dict[int, str], src_crs: CRS, new_crs: CRS = CRS.from_epsg(4326), path: str = '', cmap_style: str | ListedColormap | None = None, exp_id: str | None = None, fig_dim: tuple[int | float, int | float] | None = None, block_size: int = 32, show: bool = True, save: bool = True, fn_prefix: str | Path | None = None) → None

Produces a figure containing subplots of the predicted label mask, the ground truth label mask and a reference RGB image of the same patch.

Parameters:

sample (dict[str, Any]) – Dictionary holding the "image", ground truth ("mask") and predicted ("prediction") masks and the bounding box for this sample.
sample_id (str) – ID for the sample.
classes (dict[int, str]) – Dictionary mapping class labels to class names.
src_crs (CRS) – Existing co-ordinate system of the image.
new_crs (CRS) – Optional; Co-ordinate system to convert image to and use for labelling.
exp_id (str) – Optional; Unique ID for the experiment run that predictions and labels come from.
block_size (int) – Optional; Size of block image sub-division in pixels.
cmap_style (str | ListedColormap) – Optional; Name or object for colour map style.
show (bool) – Optional; Show the figure when plotted.
save (bool) – Optional; Save the figure to file to fn_prefix.
fig_dim (tuple[float, float]) – Optional; Figure (height, width) in inches.
fn_prefix (str | Path) – Optional; Common filename prefix (including path to file) for all plots of this type from this experiment. Appended with the sample ID to give the filename to save the plot to.

Returns:

None

seg_plot(z: list[int] | ndarray[tuple[int, ...], dtype[Any]], y: list[int] | ndarray[tuple[int, ...], dtype[Any]], ids: list[str], index: Sequence[Any] | ndarray[tuple[int, ...], dtype[Any]], data_dir: Path | str, dataset_params: dict[str, Any], classes: dict[int, str], colours: dict[int, str], fn_prefix: str | Path | None, x: list[int] | ndarray[tuple[int, ...], dtype[Any]] | None = None, frac: float = 0.05, fig_dim: tuple[int | float, int | float] | None = (9.3, 10.5), model_name: str = '', path: str = '', max_pixel_value: int = 255, cache_dir: str | Path | None = None) → None

Custom function for pre-processing the outputs from image segmentation testing for data visualisation.

Parameters:

z (list[float]) – Predicted segmentation masks by the network.
y (list[float]) – Corresponding ground truth masks.
ids (list[str]) – Corresponding patch IDs for the test data supplied to the network.
bounds (list[BoundingBox] | ndarray[BoundingBox]) – Array of objects describing a geospatial bounding box. Must contain minx, maxx, miny and maxy parameters.
task_name (str) – Name of the task that samples are from.
classes (dict[int, str]) – Dictionary mapping class labels to class names.
colours (dict[int, str]) – Dictionary mapping class labels to colours.
fn_prefix (str | Path) – Common filename prefix (including path to file) for all plots of this type from this experiment to use.
frac (float) – Optional; Fraction of patch samples to plot.
fig_dim (tuple[float, float]) – Optional; Figure (height, width) in inches.
cache_dir (str | Path) – Optional; Path to the directory to load the cached dataset from. Defaults to None (so will create dataset from scratch).

Returns:

None

stack_rgb(image: ndarray[tuple[int, ...], dtype[float64]], max_value: int = 255) → ndarray[tuple[int, ...], dtype[float64]]

Stacks together red, green and blue image bands to create a RGB array.

Parameters:

image (ndarray[float]) – Image of separate channels to be normalised and reshaped into stacked RGB image.
max_value (int) – Optional; The maximum pixel value in image. e.g. for 8 bit this will be 255.

Returns:

Normalised and stacked red, green, blue arrays into RGB array.

Return type:

ndarray[float]