semanticlens.utils package

Submodules

semanticlens.utils.helper module

Helper functions for SemanticLens.

semanticlens.utils.helper.get_denormalization_transform(mean=tensor([0.4850, 0.4560, 0.4060]), std=tensor([0.2290, 0.2240, 0.2250]))

Return a transform to undo the normalization of an image tensor.

This function creates a composition of transforms that reverses standard ImageNet normalization, which is useful for visualization purposes.

Parameters:

• mean (torch.Tensor, optional) – Mean values used in the original normalization. Default is ImageNet means [0.485, 0.456, 0.406] for RGB channels.

• std (torch.Tensor, optional) – Standard deviation values used in the original normalization. Default is ImageNet stds [0.229, 0.224, 0.225] for RGB channels.

Returns:

A composed transform that reverses the normalization when applied to a tensor.

Return type:

torch.nn.Module

semanticlens.utils.helper.get_fallback_name(obj)

Function to get a fallback name for an object.

semanticlens.utils.helper.to_transforms_compose(instance)

Helper function to convert an ImageClassification instance to a Compose transform.

semanticlens.utils.log_setup module

Logging configuration for the SemanticLens package.

This module provides a centralized, optional configuration for colored console logging. It is designed to be non-intrusive, allowing the user of the library to enable and configure logging without interfering with their own application’s logging setup.

The primary function, setup_colored_logging, attaches a formatted handler to the top-level ‘semanticlens’ logger. By default, the library has a NullHandler to prevent “No handler found” warnings if the user does not configure logging.

Functions

setup_colored_logging

Configures a colored, stream-based logger for the package.

Example

>>> from semanticlens.utils import setup_colored_logging
>>> setup_colored_logging("DEBUG", "path-to-logs/debug.log")

class semanticlens.utils.log_setup.ColorFormatter(fmt, use_color=True)

Bases: Formatter

A custom formatter to add colors to log messages.

COLOR_MAP = {'CRITICAL': '\x1b[91m', 'DEBUG': '\x1b[90m', 'ERROR': '\x1b[91m', 'INFO': '\x1b[92m', 'WARNING': '\x1b[38;5;208m'}

RESET_SEQ = '\x1b[0m'

__init__(fmt, use_color=True)

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

format(record)

Format the specified record as text.

semanticlens.utils.log_setup.setup_colored_logging(log_level='INFO', file_path=None)

Configures a colored logger for the ‘semanticlens’ package.

semanticlens.utils.render module

Image visualization utilities for semantic analysis and heatmap rendering.

semanticlens.utils.render.crop_and_mask_images(data_batch, heatmaps, rf=False, alpha=0.4, vis_th=0.02, crop_th=0.01, kernel_size=51)

Crop and adjust images based on heatmaps.

This function processes a batch of images by applying Gaussian blur to their corresponding heatmaps, cropping the images based on the filtered heatmaps, and converting them to RGB format.

Parameters:

• data_batch (list or array-like) – Batch of input images to be processed.

• heatmaps (list or array-like) – Corresponding attention heatmaps for each image in the batch.

• rf (bool, optional) – Receptive field flag (currently unused), by default False.

• alpha (float, optional) – Alpha blending parameter, must be between [0, 1], by default 0.4.

• vis_th (float, optional) – Visibility threshold, must be between [0, 1), by default 0.02.

• crop_th (float, optional) – Cropping threshold for determining crop boundaries, must be between [0, 1), by default 0.01.

• kernel_size (int, optional) – Size of the Gaussian blur kernel, by default 51.

Returns:

List of processed PIL Images in RGB format, cropped according to their respective heatmaps.

Return type:

list

Raises:

• ValueError – If alpha is not between [0, 1].

• ValueError – If vis_th is not between [0, 1).

• ValueError – If crop_th is not between [0, 1).

Notes

The function applies Gaussian blur to normalize heatmaps, determines crop boundaries based on the crop threshold, and converts the final images to RGB format for visualization.

semanticlens.utils.render.mystroke(img, size, color='black')

Apply a stroke effect to an image by detecting edges and drawing ellipses around them. This function creates a stroke effect by first finding edges in the input image, then drawing filled ellipses at edge locations to create an outline effect. The original image is then pasted on top of the stroke layer.

Parameters:

• img (PIL.Image.Image) – The input image to apply the stroke effect to. Must be a PIL Image object.

• size (int) – The radius of the ellipses used to create the stroke effect. Larger values create thicker strokes.

• color (str, optional) – The color of the stroke effect. Accepts “black” for dark strokes or any other value for white strokes. Default is “black”.

Returns:

A new image with the stroke effect applied. The returned image maintains the same mode and dimensions as the input image.

Return type:

PIL.Image.Image

Notes

The function uses PIL’s FIND_EDGES filter to detect edges and creates semi-transparent ellipses (opacity 180/255) for the stroke effect. Black strokes use RGBA(0, 0, 0, 180) and white strokes use RGBA(255, 255, 255, 180).

semanticlens.utils.render.vis_lighten_img_border(data_batch, heatmaps, rf=False, alpha=0.4, vis_th=0.02, crop_th=0.01, kernel_size=51)

Visualize images with lightened borders based on relevance heatmaps.

This function creates visualizations by lightening regions with low relevance scores, making high-relevance areas more prominent. It can optionally crop images to focus on relevant regions and applies Gaussian blur for smoothing.

Parameters:

• data_batch (torch.Tensor) – Batch of input images of shape (batch_size, channels, height, width).

• heatmaps (torch.Tensor) – Relevance heatmaps of shape (batch_size, height, width).

• rf (bool, default=False) – Whether to crop images to the receptive field of relevant regions.

• alpha (float, default=0.4) – Blending factor for lightening low-relevance regions. Must be in [0, 1].

• vis_th (float, default=0.02) – Visibility threshold for determining relevant regions. Must be in [0, 1).

• crop_th (float, default=0.01) – Cropping threshold for receptive field cropping. Must be in [0, 1).

• kernel_size (int, default=51) – Kernel size for Gaussian blur smoothing of heatmaps.

Returns:

List of processed PIL Images with lightened borders and optional cropping.

Return type:

list of PIL.Image

Raises:

• ValueError – If alpha is not in [0, 1], vis_th not in [0, 1), or crop_th not in [0, 1).

• AssertionError – If no masking or cropping is applied to any image in the batch, which may indicate issues with thresholds or heatmaps.

Examples

>>> import torch
>>> data = torch.randn(2, 3, 224, 224)
>>> heatmaps = torch.randn(2, 224, 224)
>>> images = vis_lighten_img_border(data, heatmaps, alpha=0.3)
>>> len(images)
2
>>> type(images[0])
<class 'PIL.Image.Image'>

semanticlens.utils.render.vis_opaque_img_border(data_batch, heatmaps, rf=True, alpha=0.4, vis_th=0.02, crop_th=0.01, kernel_size=51)

Visualize Dark Image Border.

Draws reference images. The function lowers the opacity in regions with relevance lower than max(relevance)*vis_th. In addition, the reference image can be cropped where relevance is less than max(relevance)*crop_th by setting ‘rf’ to True.

Parameters:

• data_batch (torch.Tensor) – original images from dataset without FeatureVisualization.preprocess() applied to it

• heatmaps (torch.Tensor) – output heatmap tensor of the CondAttribution call

• rf (boolean) – Computes the CRP heatmap for a single neuron and hence restricts the heatmap to the receptive field. The amount of cropping is further specified by the ‘crop_th’ argument.

• alpha (between [0 and 1]) – Regulates the transparency in low relevance regions.

• vis_th (between [0 and 1)) – Visualization Threshold: Increases transparency in regions where relevance is smaller than max(relevance)*vis_th

• crop_th (between [0 and 1)) – Cropping Threshold: Crops the image in regions where relevance is smaller than max(relevance)*crop_th. Cropping is only applied, if receptive field ‘rf’ is set to True.

• kernel_size (scalar) – Parameter of the torchvision.transforms.functional.gaussian_blur function used to smooth the CRP heatmap.

Returns:

image – If ‘rf’ is True, reference images have different shapes.

Return type:

list of PIL.Image objects

Module contents

Utility modules for semantic analysis and visualization.

This package provides utility functions and classes for activation caching, image rendering, and visualization tasks used throughout the SemanticLens library.

Modules

activation_caching

Tools for caching and managing neural network activations.

render

Image visualization and rendering utilities for semantic analysis.

semanticlens.utils.get_denormalization_transform(mean=tensor([0.4850, 0.4560, 0.4060]), std=tensor([0.2290, 0.2240, 0.2250]))

Return a transform to undo the normalization of an image tensor.

This function creates a composition of transforms that reverses standard ImageNet normalization, which is useful for visualization purposes.

Parameters:

• mean (torch.Tensor, optional) – Mean values used in the original normalization. Default is ImageNet means [0.485, 0.456, 0.406] for RGB channels.

• std (torch.Tensor, optional) – Standard deviation values used in the original normalization. Default is ImageNet stds [0.229, 0.224, 0.225] for RGB channels.

Returns:

A composed transform that reverses the normalization when applied to a tensor.

Return type:

torch.nn.Module

semanticlens.utils.get_fallback_name(obj)

Function to get a fallback name for an object.

semanticlens.utils.setup_colored_logging(log_level='INFO', file_path=None)

Configures a colored logger for the ‘semanticlens’ package.

semanticlens.utils.to_transforms_compose(instance)

Helper function to convert an ImageClassification instance to a Compose transform.