radioviz.tools.crop_utils

Shared utilities for crop-based tools.

This module contains common data structures and overlay renderers used by manual and automatic cropping tools.

Functions

draw_crop_overlay(overlay, axes)

Draw a crop overlay on a Matplotlib axes.

draw_highlight_crop_overlay(overlay, axes)

Draw a highlighted crop overlay on a Matplotlib axes.

Classes

CropResult(label, overlay_label, image, extents)

Container for the outcome of a cropping operation.

RectangleExtent(xmin, xmax, ymin, ymax)

Represent a rectangular extent with integer coordinates.
class radioviz.tools.crop_utils.CropResult(label: str, overlay_label: str, image: ndarray, extents: tuple[float, float, float, float])[source]

Bases: object

Container for the outcome of a cropping operation.

It stores the label associated with the crop, the cropped image data, an overlay label, and the geometric extents of the crop in the original image.

extents: tuple[float, float, float, float]

The crop extents expressed as (xmin, xmax, ymin, ymax).

image: ndarray

The cropped image as a NumPy array.

label: str

Human‑readable label for the crop.

overlay_label: str

Short label for overlay annotations.

class radioviz.tools.crop_utils.RectangleExtent(xmin: float, xmax: float, ymin: float, ymax: float)[source]

Bases: object

Represent a rectangular extent with integer coordinates.

The class stores the minimum and maximum column (x) and row (y) positions of a rectangle and provides utility methods for conversion, padding, scaling and normalisation.

add_padding(padding: int) → None[source]

Expand the rectangle by a symmetric padding.

Parameters:

padding (int) – Number of pixels (or units) to add on each side.

expand(x_pad: float, y_pad: float) → tuple[float, float, float, float][source]

Return a padded extent without mutating the instance.

Parameters:

  • x_pad (float) – Horizontal padding to apply to xmin and xmax.

  • y_pad (float) – Vertical padding to apply to ymin and ymax.

Returns:

(xmin - x_pad, xmax + x_pad, ymin - y_pad, ymax + y_pad).

Return type:

tuple[float, float, float, float]

classmethod from_bbox(minr: int, minc: int, maxr: int, maxc: int) → RectangleExtent[source]

Create a RectangleExtent from bounding‑box coordinates.

Parameters:

  • minr (int) – Minimum row (y‑coordinate) of the bounding box (inclusive).

  • minc (int) – Minimum column (x‑coordinate) of the bounding box (inclusive).

  • maxr (int) – Maximum row (y‑coordinate) of the bounding box (inclusive).

  • maxc (int) – Maximum column (x‑coordinate) of the bounding box (inclusive).

Returns:

New RectangleExtent instance.

Return type:

RectangleExtent

classmethod from_extent(xmin: float, xmax: float, ymin: float, ymax: float) → RectangleExtent[source]

Create a RectangleExtent directly from extent values.

Parameters:

  • xmin (float) – Minimum column (x) coordinate (inclusive).

  • xmax (float) – Maximum column (x) coordinate (inclusive).

  • ymin (float) – Minimum row (y) coordinate (inclusive).

  • ymax (float) – Maximum row (y) coordinate (inclusive).

Returns:

New RectangleExtent instance.

Return type:

RectangleExtent

normalize(x_max: int, y_max: int) → None[source]

Clamp the rectangle to stay within the image bounds.

Parameters:

  • x_max (int) – Maximum allowed x‑coordinate (width‑1).

  • y_max (int) – Maximum allowed y‑coordinate (height‑1).

scale_factor(factor: int) → None[source]

Scale the rectangle coordinates by an integer factor.

Parameters:

factor (int) – Multiplicative factor applied to all four coordinates.

xmax: float

The maximum x‑coordinate (inclusive).

xmin: float

The minimum x‑coordinate (inclusive).

ymax: float

The maximum y‑coordinate (inclusive).

ymin: float

The minimum y‑coordinate (inclusive).

radioviz.tools.crop_utils.draw_crop_overlay(overlay: OverlayModel, axes: Axes) → list[Artist][source]

Draw a crop overlay on a Matplotlib axes.

The function creates a matplotlib.patches.Rectangle using the geometry and style defined in the provided OverlayModel, adds it to axes, and attaches an matplotlib.text.Annotation showing the overlay label.

Parameters:

  • overlay (OverlayModel) – Overlay model containing geometry, style and label.

  • axes (matplotlib.axes.Axes) – Matplotlib axes on which to draw the overlay.

Returns:

List containing the created rectangle patch and annotation artist.

Return type:

list[matplotlib.artist.Artist]

radioviz.tools.crop_utils.draw_highlight_crop_overlay(overlay: OverlayModel, axes: Axes) → list[Artist][source]

Draw a highlighted crop overlay on a Matplotlib axes.

If the supplied overlay does not already have the role Highlight, it is converted to that role before delegating to draw_crop_overlay().

Parameters:

  • overlay (OverlayModel) – Overlay model to be highlighted.

  • axes (matplotlib.axes.Axes) – Matplotlib axes on which to draw the highlighted overlay.

Returns:

List of Matplotlib artists created by the underlying draw call.

Return type:

list[matplotlib.artist.Artist]