Generating visual explanations (visualime.visualize)

visualime.visualize.select_segments(segment_weights: ndarray, segment_mask: ndarray, coverage: float | None = None, num_of_segments: int | None = None, min_coverage: float = 0.0, max_coverage: float = 1.0, min_num_of_segments: int = 0, max_num_of_segments: int | None = None) → ndarray

Select the segments to color.

Segments are selected in the order of descending weight until the desired coverage or num_of_segments is reached. Exactly one of these parameters has to be specified when calling the function.

Parameters:

segment_weightsnp.ndarray

The weights produced by visualime.lime.weigh_segments(): A one-dimensional array of length num_of_segments.

segment_masknp.ndarray

The mask generated by visualime.lime.create_segments(): An array of shape (image_width, image_height).

coveragefloat, optional

The coverage of the selected segments relative to the area of the image. Either coverage or num_of_segments must be specified.

A warning will be given if reaching the coverage threshold requires selection of all segments.

num_of_segmentsint, optional

The number of segments to select. Either num_of_segments or coverage must be specified.

min_coveragefloat, default 0.0

The minimum coverage of the selected segments relative to the area of the image. If the specified num_of_segments does not reach this coverage, additional segments will be selected until this minimum coverage is reached.

A warning will be given if reaching the coverage threshold requires selection of all segments.

max_coveragefloat, default 1.0

The maximum coverage of the selected segments relative to the area of the image. If the specified num_of_segments exceeds this coverage, segments will be removed from the selection until the coverage is below this maximum.

At least one segment will be returned even if the maximum coverage is exceeded. In this case, a warning will be given.

min_num_of_segmentsint, default 0

The minimum number of segments to select. Even if the specified coverage is reached with fewer segments, at least this minimum number of segments are returned.

max_num_of_segmentsint, optional

The maximum number of segments to select. Even if more segments would be required to reach the specified coverage, at most this maximum number of segments are returned.

Returns:

np.ndarray

A one-dimensional array that contains the selected segment indices.

Notes

To select the segments with the lowest weights, pass the segment_weights array with negative sign:

>>> select_segments(segment_weights=-segment_weights, ...)

visualime.visualize.generate_overlay(segment_mask: ndarray, segments_to_color: ndarray | List[int], color: str | Tuple[int, int, int], opacity: float) → ndarray

Generate a semi-transparent overlay with selected segments colored.

Parameters:

segment_masknp.ndarray

The mask generated by visualime.lime.create_segments(): An array of shape (image_width, image_height).

segments_to_colornp.ndarray or list of ints

An array that contains the integer segment numbers of the segments to color. Usually obtained through visualime.visualize.select_segments().

colorstr or int 3-tuple (RGB)

The color for the segments. Can be given as a color name or an RGB tuple.

Color names are parsed through PIL.ImageColor.getrgb(). To obtain a list of available color names, run:

>>> from PIL.ImageColor import colormap, getrgb
>>> for name, code in colormap.items(): print(name, getrgb(code))

Note that while it is possible to pass an RGBA tuple, only the RGB values will be considered. The alpha channel is controlled exclusively via the opacity parameter.

opacityfloat

The opacity of the overlay as a number between 0.0 (fully transparent) and 1.0 (fully opaque).

Returns:

np.ndarray

An array of shape (image_width, image_height, 4) representing an RGBA image.

visualime.visualize.scale_opacity(overlay: ndarray, segment_mask: ndarray, segment_weights: ndarray, segments_to_color: ndarray | List[int], relative_to: Literal['max'] | float = 'max', exponent: float = 1.0, max_opacity: float = 1.0) → ndarray

Set the opacity of each segment according to its weight.

Segments with a higher (absolute) weight will be more opaque than segments with a lower weight.

Parameters:

overlaynp.ndarray

The output of visualime.visualize.generate_overlay(): An array of shape (image_width, image_height, 4) representing an RGBA image.

segment_masknp.ndarray

The mask generated by visualime.lime.create_segments(): An array of shape (image_width, image_height).

segment_weightsnp.ndarray

The weights produced by visualime.lime.weigh_segments(): A one-dimensional array of length num_of_segments.

segments_to_colornp.ndarray or list of ints

An array that contains the integer segment numbers of the segments to color. Usually obtained through visualime.visualize.select_segments().

relative_to{float, “max”}, default “max”

The relative weight to consider the maximum weight when determining the opacity of a segment.

Can either be a number between 0.0 (exclusive) and 1.0, with 1.0 corresponding to the maximum weight that is theoretically possible for a segment.

Alternatively, if set to “max” (the default), the maximum absolute weight of any segment is considered as the maximum value. Note that for this calculation, all segments are considered, even if they are not included in segments_to_color.

exponent: int, default 1.0

The exponent used when calculating the opacity of a given segment.

A segment’s opacity is calculated as (segment_weight/reference)**exponent, where segment_weight is the normalized weight of the segment.

The default value for the exponent is 1.0, resulting in linear scaling of the opacity. An exponent smaller than 1.0 gives more emphasis to smaller weights, while an exponent larger than 1.0 gives more emphasis to larger weights.

max_opacityfloat, default 1.0

The maximum opacity of the overlay as a number between 0.0 and 1.0.

Returns:

np.ndarray

An array of shape (image_width, image_height, 4) representing an RGBA image.

Note that this function does not modify the original overlay but returns a new array.

visualime.visualize.scale_overlay(overlay: ndarray, shape: Tuple[int, int]) → ndarray

Scale the overlay to a given size.

Parameters:

overlaynp.ndarray

The output of visualime.visualize.generate_overlay(): An array of shape (image_width, image_height, 4) representing an RGBA image.

shapetuple of ints

The size to scale the overlay to.

Returns:

np.ndarray

An array of shape (image_width, image_height, 4) representing an RGBA image.

Note that this function does not modify the original overlay but returns a new array.

visualime.visualize.mark_boundaries(image: ndarray, segment_mask: ndarray, color: str | Tuple[int, int, int] = 'red', opacity: float = 1.0) → ndarray

Mark the boundaries of the segments in the image.

Parameters:

imagenp.ndarray

The image to mark the boundaries of the segments in. The image must be an array of shape (image_width, image_height, 3). The image will be modified in-place.

segment_masknp.ndarray

The mask generated by visualime.lime.create_segments(): An array of shape (image_width, image_height).

colorstr or int 3-tuple (RGB), default “red”

The color for the boundaries. Can be given as a color name or an RGB tuple.

Color names are parsed through PIL.ImageColor.getrgb(). To obtain a list of available color names, run:

>>> from PIL.ImageColor import colormap, getrgb
>>> for name, code in colormap.items(): print(name, getrgb(code))

Note that while it is possible to pass an RGBA tuple, only the RGB values will be considered, the opacity will be determined by the opacity parameter.

opacityfloat, default 1.0

The opacity of the boundaries as a number between 0.0 and 1.0.

Returns:

np.ndarray

An array of shape (image_width, image_height, 3) representing an RGB image.

visualime.visualize.smooth_weights(segment_weights: ndarray) → ndarray

Smooth the segment_weights by applying the sigmoid function.

Parameters:

segment_weightsnp.ndarray

The weights produced by visualime.lime.weigh_segments(): A one-dimensional array of length num_of_segments.

Returns:

np.ndarray

A smoothed copy of the segment_weights.