datagenerator.image_generation

Attributes

balanced_dataset

Classes

`ImageBuilder`	A class to build images with either geometric shapes or dinosaurs superimposed on various backgrounds,
`ImageDataset`	A dataset for images with specified configurations for image generation, supporting both balanced and imbalanced datasets.
`BalancedImageDataset`	A dataset for images where each each image consists of a background and a foreground overlay.
`ImbalancedImageDataset`	Creates Image Dataset where each image comprises of a background image an a foreground image.

Module Contents

class datagenerator.image_generation.ImageBuilder(shape_type: str = 'geometric', rotation: bool = False, color: str | Tuple[int, int, int, int] | None = None, position: str = 'center', overlay_scale: float = 0.3, background_size: Tuple[int, int] = (512, 512), default_background_imagefile: str | None = None, source: str = 'local')

A class to build images with either geometric shapes or dinosaurs superimposed on various backgrounds, including options for color customization, image rotation, and positioning of the overlay image.

A specific background image can be set as default for all generated samples.

shape_type

Specifies the type of overlay shape, either ‘geometric’ or ‘dinosaurs’.

Type:: str

rotation

If True, the overlay image will be randomly rotated.

Type:: bool

color

RGBA range (0-255) for the color of overlay shape. Used as default unless overridden.

Type:: str | tuple

position

Specifies the positioning of the overlay image on the background, either ‘center’ or ‘random’.

Type:: str

overlay_scale

The scale of the overlay image relative to the background size.

Type:: float

background_size

The size of the background image.

Type:: tuple

default_background_imagefile

Specific background image filename to use as default for all samples.

Type:: str

back_gen

An instance of BackgroundGenerator to fetch background images.

Type:: BackgroundGenerator

image_gen

The generator for overlay images, either shapes or dinosaurs.

Type:: ShapeGenerator | DinoGenerator

Initializes the ImageBuilder object with specified configurations for image generation.

Parameters:

shape_type (str) – The type of shapes to overlay (‘geometric’ or ‘dinosaurs’). Defaults to ‘geometric’.
rotation (bool) – Whether to apply random rotation to the overlay images. Defaults to False.
color (str | tuple, optional) – The color of the shape, specified by name or RGBA tuple. Defaults to None.
position (str) – The positioning of the overlay image (‘center’ or ‘random’). Defaults to ‘center’.
overlay_scale (float) – Scale of the overlay image relative to the background. Defaults to 0.3.
background_size (tuple) – The size (width, height) of the background image. Defaults to (512, 512).
default_background_imagefile (str, optional) – Specific background image filename to use as default for all samples. Defaults to None.

Raises:

ValueError – If input other than ‘geometric’ or ‘dinosaurs’ is passed to shape_type.

shape_type = 'geometric'

rotation = False

color = None

position = 'center'

overlay_scale = 0.3

background_size = (512, 512)

back_gen

default_background_imagefile = None

resize_overlay_to_background(background: PIL.Image.Image, overlay: PIL.Image.Image) → PIL.Image.Image

Resizes the overlay image to maintain its aspect ratio and fit within the specified background size, calculated based on the overlay_scale.

This method ensures that the overlay fits aesthetically with the background without distorting its original aspect ratio.

Parameters:

background (PIL.Image.Image) – The background image onto which the overlay will be placed.
overlay (PIL.Image.Image) – The overlay image to be resized.

Returns:

The resized overlay image, maintaining its original aspect ratio.

Return type:

PIL.Image.Image

img_rotation(img: PIL.Image.Image, angle: int | None = None) → PIL.Image.Image

Rotates the image by a specified angle or a random angle between 0 and 360 degrees if none is provided.

Parameters:

img (PIL.Image.Image) – The image to be rotated.
angle (int, optional) – The angle in degrees for rotation. If None, a random angle will be used. Defaults to None.

Returns:

The rotated image, resized to accommodate its new dimensions if necessary.

Return type:

PIL.Image.Image

Raises:

ValueError – If the specified angle is not within the expected range of 0-360 degrees.

overlay_pos(background_image: PIL.Image.Image, overlay_image: PIL.Image.Image) → Tuple[int, int]

Calculates the position of the overlay image on the background based on the specified position setting.

Parameters:

background_image (PIL.Image.Image) – The background image.
overlay_image (PIL.Image.Image) – The overlay image.

Returns:

A tuple (x, y) representing the top-left corner of the overlay image’s position on the background.

Return type:

tuple

Raises:

ValueError – If the position attribute is not ‘center’ or ‘random’.

generate_sample(name: str | None = None, background_imagefile: str | None = None, color: str | Tuple[int, int, int, int] | None = None, contour_thickness: int = 3) → Tuple[PIL.Image.Image, int, str, PIL.Image.Image]

Generates a single image sample with a specified shape (or randomly selected if none is provided), color, and background. This method allows for specific customization of the image sample or can use default settings defined in the class. Useful for generating varied datasets for image recognition tasks.

Parameters:

name (str, optional) – The name of the shape or dinosaur to use. Randomly selects a shape if None. Defaults to None.
background_imagefile (str, optional) – Path to a specific background image file to use. Uses the class-level default if None. Defaults to None.
color (str | tuple, optional) – The color to apply to the shape, specified as a name or RGBA tuple. Uses the class-level default if None. Defaults to None.
contour_thickness (int)

Returns:

Contains the composite image (PIL.Image.Image), the numeric label representing the shape, a string label describing the shape and the gorund truth.

Return type:

tuple

class datagenerator.image_generation.ImageDataset(seed: int = 0, backgrounds: int | List[str] = 5, shapes: int | List[str] = 10, n_variants: int = 4, background_size: Tuple[int, int] = (512, 512), shape_type: str = 'geometric', position: str = 'random', overlay_scale: float = 0.3, rotation: bool = False, shape_colors: str | Tuple[int, int, int, int] | List[str | Tuple[int, int, int, int]] | None = None, shuffled: bool = True, transform: Callable | None = None, contour_thickness: int = 3, source: str = 'local')

Bases: torch.utils.data.Dataset

A dataset for images with specified configurations for image generation, supporting both balanced and imbalanced datasets.

Inherits from:: torch.utils.data.Dataset: The standard base class for defining a dataset within the PyTorch framework.

seed

Seed for random number generation to ensure reproducibility.

Type:: int

backgrounds

List of background images to use for dataset generation.

Type:: list

shapes

List of shapes to overlay on background images.

Type:: list

n_variants

Number of variations per shape-background combination, affects dataset size.

Type:: int

background_size

Dimensions (width, height) of background images.

Type:: tuple

shape_type

Type of shapes: ‘geometric’ for geometric shapes, ‘dinosaurs’ for dinosaur shapes.

Type:: str

position

Overlay position on the background (‘center’ or ‘random’).

Type:: str

overlay_scale

Scale factor for overlay relative to the background size.

Type:: float

rotation

If True, applies random rotation to overlays.

Type:: bool

shape_colors

List of default color(s) for shapes, accepts color names or RGBA tuples.

Type:: list

shuffled

If True, shuffles the dataset after generation.

Type:: bool

transform

Transformation function to apply to each image, typically converting to tensor.

Type:: callable

contour_thickness

Thickness of lines the contours are drawn with. If it is negative, the contour interiors are drawn.

Type:: int

image_builder

Instance of ImageBuilder for generating images.

Type:: ImageBuilder

samples

List to store the generated samples.

Type:: list

labels

List to store the labels.

Type:: list

fg_shapes

List to store the foreground shapes.

Type:: list

bg_labels

List to store the background labels.

Type:: list

fg_colors

List to store the foreground colors.

Type:: list

ground_truth

List to store the ground truths.

Type:: list

Initializes an ImageDataset object.

Parameters:

seed (int) – Seed for random number generation to ensure reproducibility. Defaults to 0.
backgrounds (int | list) – Number or list of specific backgrounds to use. Defaults to 5.
shapes (int | list) – Number or list of specific shapes. Defaults to 10.
n_variants (int) – Number of variations per shape-background combination, affects dataset size. Defaults to 4.
background_size (tuple) – Dimensions (width, height) of background images. Defaults to (512, 512).
shape_type (str) – ‘geometric’ for geometric shapes, ‘dinosaurs’ for dinosaur shapes. Defaults to ‘geometric’.
position (str) – Overlay position on the background (‘center’ or ‘random’). Defaults to ‘random’.
overlay_scale (float) – Scale factor for overlay relative to the background size. Defaults to 0.3.
rotation (bool) – If True, applies random rotation to overlays. Defaults to False.
shape_colors (str | tuple, optional) – Default color(s) for shapes, accepts color names or RGBA tuples. Defaults to None.
shuffled (bool) – If True, shuffles the dataset after generation. Defaults to True.
transform (callable, optional) – Transformation function to apply to each image, typically converting to tensor. Defaults to None.
contour_thickness (int) – Defaults to 3.

seed = 0

n_variants = 4

image_builder

backgrounds

shapes

shape_colors

transform

samples = []

labels = []

fg_shapes = []

bg_labels = []

fg_colors = []

ground_truth = []

shuffled = True

contour_thickness = 3

_validate_n_variants(n_variants: int) → int

Validates that the number of variants per shape-background combination is a positive integer.

The n_variants parameter controls how many different versions of each shape-background combination are generated, varying elements such as position and possibly color if specified. This allows for diverse training data in image recognition tasks, improving the model’s ability to generalize from different perspectives and conditions.

Parameters:: n_variants (int) – The number of variations per shape-background combination to generate.
Returns:: The validated number of variants.
Return type:: int
Raises:: ValueError – If n_variants is not an integer or is less than or equal to zero.

_prepare_shapes(shape_type: str, shapes: int | List[str], source: str) → List[str]

Prepares a list of shapes or dinosaurs based on the input and the specified shape type.

This method processes the input to generate a list of specific shapes or dinosaur names. If a numerical input is provided, it selects that many random shapes/dinosaurs from the available names. If a list is provided, it directly uses those specific names.

Parameters:

shape_type (str) – Specifies the type of overlay image, either ‘geometric’ or ‘dinosaurs’.
shapes (int | list) – Number or list of specific shape names. If an integer is provided, it indicates how many random shapes or dinosaurs to select.

Returns:

A list of shape names or dinosaur names to be used as overlays.

Return type:

list

Raises:

ValueError – If the shapes input is neither an integer nor a list, or if the shape_type is not recognized as ‘geometric’ or ‘dinosaurs’.

_prepare_backgrounds(backgrounds: int | List[str]) → List[str]

Prepares background images based on the input.

This method helps to either randomly select a set number of background images from the available pool or validate and use a provided list of specific background filenames.

If a numerical value is provided, selects that many random backgrounds. If a list is provided, validates and uses those specific backgrounds.

Parameters:: backgrounds (int | list) – Number of random backgrounds to select or a list of specific background filenames.
Returns:: A list of background filenames to be used in the dataset.
Return type:: list
Raises:: ValueError – If the input is neither an integer nor a list, or if any specified background filename is not found in the available backgrounds.

Prepares shape colors by validating input against available colors.

If no valid colors are provided, a default color is selected. Accepts single or multiple colors.

Parameters:: shape_colors (int | str | tuple | list) – Specifies how many random colors to select or provides specific color(s). Can be a single color name, RGBA tuple, or list of names/tuples.
Returns:: A list of validated RGBA tuples representing the colors.
Return type:: list
Raises:: ValueError – If input is invalid or colors are not found in the available color dictionary. Details about the invalid input are provided in the error message.

generate_samples() → None: Placeholder method for generating the samples either for balanced or imbalanced datasets.

shuffle_dataset() → None

Randomly shuffles the dataset samples and corresponding labels to ensure variety in training and evaluation phases.

Raises:: ValueError – If the dataset is empty and shuffling is not possible.

__len__() → int

Returns thet number of samples in the dataset.

Returns:: number of samples contained by the dataset.
Return type:: int

__getitem__(idx: int) → Tuple[torch.Tensor, int, Dict[str, str | torch.Tensor | PIL.Image.Image]]

Retrieves an image and its label by index.

The image is transformed into a tensor if a transform is applied.

Parameters:: idx (int) – Index of the sample to retrieve.
Returns:: A tuple containing the transformed image tensor, label, a dict of other attributes.
Return type:: tuple

_re_label() → None: Re-labels the dataset labels with integer indices.

static show_image(img_tensor: torch.Tensor) → None

Displays an image given its tensor representation.

Parameters:: img_tensor (torch.Tensor) – The image tensor to display.

property default_metric: Callable

The default metric for evaluating the performance of explanation methods applied to this dataset.

For this dataset, the default metric is the mask ratio metric that is constructed based on the ground truth and context. Mask ratio is defined as the ratio of absolute attribution score that lies within the foreground and the image.

Returns:

A class that wraps around the default metric to be instantiated: within the pipeline.

Return type:

type

class datagenerator.image_generation.BalancedImageDataset(*args: Any, **kwargs: Any)

Bases: ImageDataset

A dataset for images where each each image consists of a background and a foreground overlay.

This ‘balanced’ dataset ensures that each combination of background (bg), foreground (fg), and foreground color (fg_color) appears the same number of times across the dataset, making it ideal for machine learning models that benefit from uniform exposure to all feature combinations.

Inherits all parameters from ImageDataset, and introduces no additional parameters, but it overrides the behavior to ensure balance in the dataset composition.

Inherits from:: ImageDataset: Standard dataset that contains images with backgorunds and foregrounds.

Initializes a BalancedImageDataset with the same parameters as ImageDataset, ensuring each combination of background, foreground, and color appears uniformly across the dataset.

After initialization, it automatically generates the samples and shuffles them if the ‘shuffled’ attribute is True.

Parameters:

*args – Additional arguments passed to the superclass initializer.
**kwargs – Additional keyword arguments passed to the superclass initializer.

generate_samples() → None

Generates a balanced set of image samples by uniformly distributing each combination of background, foreground shape, and color.

Iterates over each background, each shape, and each color to create the specified number of variants per combination. Each generated image is stored in the ‘samples’ list, with corresponding labels in ‘labels’, and other metadata like foreground shapes, background labels, and foreground colors stored in their respective lists.

Raises:: ValueError – If there is an issue with image generation parameters or overlay combinations.

class datagenerator.image_generation.ImbalancedImageDataset(backgrounds: int | List[str] = 5, shapes: int | List[str] = 3, n_variants: int = 100, shape_colors: str | Tuple[int, int, int, int] = 'red', imbalance: float = 0.8, **kwargs: Any)

Bases: ImageDataset

Creates Image Dataset where each image comprises of a background image an a foreground image.

Background images, type of foreground, color of foreground as well as other parameters can be specified.

Imbalance refers to the fact users can specify the percentage of dominant (bg, fg) pair vs other pair.

Inherits from:: ImageDataset: Standard dataset that contains images with backgorunds and foregrounds.

imbalance

The proportion of samples that should favor a particular background per shape. Should be within the range (0.0 to 1.0) inclusive.

Type:: float

Initializes an ImbalancedImageDataset object with specified parameters, focusing on creating dataset variations based on an imbalance parameter that dictates the dominance of certain shape-background pairs.

Parameters:

backgrounds (int | list) – The number or list of specific background filenames. Defaults to 5.
shapes (int | list) – The number or list of specific shapes. Defaults to 3.
n_variants (int) – Number of variations per shape-background combination, affects dataset size. Defaults to 100.
shape_colors (str | tuple) – The default color for all shapes in the dataset. Defaults to ‘red’.
imbalance (float) – The proportion (0.0 to 1.0) of samples that should favor a particular background per shape. Defaults to 0.8.
**kwargs – Additional keyword arguments passed to the superclass initializer.

imbalance

_prepare_shape_color(shape_colors: str | Tuple[int, int, int, int] | None) → List[Tuple[int, int, int, int]]

Prepares a single shape color based on the input.

Selects a random color if None is provided, validates a provided color string or RGBA tuple.

Parameters:: shape_colors (str | tuple | NoneType) – A specific color name, RGBA tuple, or None to select a random color.
Returns:: A list containing a single validated RGBA tuple representing the color.
Return type:: list
Raises:: ValueError – If the input is invalid or if the color name is not found in the predefined color dictionary.

_validate_imbalance(imbalance: float) → float

Validates that the imbalance parameter is a float between 0.0 and 1.0 inclusive, or None.

Ensures that the dataset can properly reflect the desired level of imbalance, adjusting for the number of variants and available backgrounds.

Parameters:: imbalance (float | NoneType) – The imbalance value to validate. If None is given as input, then the argument will be treated as 0.3.
Returns:: The validated imbalance value.
Return type:: float
Raises:: ValueError – If the imbalance is not within the inclusive range [0.0, 1.0] or if the imbalance settings are not feasible with the current settings of n_variants and backgrounds.

generate_samples() → None

Generates a set of image samples with overlay shapes or dinosaurs on backgrounds, considering imbalance.

Depending on the ‘imbalance’ parameter, this method either:

Allocates a specific fraction (defined by ‘imbalance’) of the samples for each shape to a particular background, with the remainder distributed among the other backgrounds.
Assigns all samples for a shape to a single background (imbalance = 1.0).

datagenerator.image_generation.balanced_dataset