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 [source]
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_weights
np.ndarray
The weights produced by
visualime.lime.weigh_segments()
: A one-dimensional array of length num_of_segments.- segment_mask
np.ndarray
The mask generated by
visualime.lime.create_segments()
: An array of shape (image_width, image_height).- coverage
float
, 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_segments
int
, optional The number of segments to select. Either num_of_segments or coverage must be specified.
- min_coverage
float
, 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_coverage
float
, 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_segments
int
, 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_segments
int
, 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.
- segment_weights
- 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 [source]
Generate a semi-transparent overlay with selected segments colored.
- Parameters:
- segment_mask
np.ndarray
The mask generated by
visualime.lime.create_segments()
: An array of shape (image_width, image_height).- segments_to_color
np.ndarray
orlist
ofints
An array that contains the integer segment numbers of the segments to color. Usually obtained through
visualime.visualize.select_segments()
.- color
str
orint
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.
- opacity
float
The opacity of the overlay as a number between 0.0 (fully transparent) and 1.0 (fully opaque).
- segment_mask
- 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 [source]
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:
- overlay
np.ndarray
The output of
visualime.visualize.generate_overlay()
: An array of shape (image_width, image_height, 4) representing an RGBA image.- segment_mask
np.ndarray
The mask generated by
visualime.lime.create_segments()
: An array of shape (image_width, image_height).- segment_weights
np.ndarray
The weights produced by
visualime.lime.weigh_segments()
: A one-dimensional array of length num_of_segments.- segments_to_color
np.ndarray
orlist
ofints
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_opacity
float
, default 1.0 The maximum opacity of the overlay as a number between 0.0 and 1.0.
- overlay
- 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 [source]
Scale the overlay to a given size.
- Parameters:
- overlay
np.ndarray
The output of
visualime.visualize.generate_overlay()
: An array of shape (image_width, image_height, 4) representing an RGBA image.- shape
tuple
ofints
The size to scale the overlay to.
- overlay
- 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 [source]
Mark the boundaries of the segments in the image.
- Parameters:
- image
np.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_mask
np.ndarray
The mask generated by
visualime.lime.create_segments()
: An array of shape (image_width, image_height).- color
str
orint
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.
- opacity
float
, default 1.0 The opacity of the boundaries as a number between 0.0 and 1.0.
- image
- Returns:
np.ndarray
An array of shape (image_width, image_height, 3) representing an RGB image.
- visualime.visualize.smooth_weights(segment_weights: ndarray) ndarray [source]
Smooth the segment_weights by applying the sigmoid function.
- Parameters:
- segment_weights
np.ndarray
The weights produced by
visualime.lime.weigh_segments()
: A one-dimensional array of length num_of_segments.
- segment_weights
- Returns:
np.ndarray
A smoothed copy of the segment_weights.