datagenerator.foregrounds

Classes

ForegroundGenerator	Abstract base class for generating overlay images (e.g., geometric shapes, dinosaurs) with customizable colors.
GeometricShapeGenerator	Generates images of geometric shapes with customizable colors.
DinosaurShapeGenerator	Generates and manipulates images of dinosaurs with customizable colors.

Module Contents

class datagenerator.foregrounds.ForegroundGenerator

Bases: abc.ABC

Abstract base class for generating overlay images (e.g., geometric shapes, dinosaurs) with customizable colors.

This class sets up common attributes and methods for its subclasses to generate images with specific characteristics and colors. Subclasses are expected to implement the get_shape method, providing a way to create and retrieve images with optional color overlays.

shape_names

Names of available shapes or dinosaurs. Populated by subclasses based on their specific image types.

Type:

list

Initializes a ForegroundGenerator object.

_colors_rgba: Dict[str, Tuple[int, int, int, int]]

_data_path: str

validate_color(color: str | Tuple[int, int, int, int]) → Tuple[int, int, int, int]

Validates and returns the RGBA value for a given color name or tuple.

Parameters:

color (str | tuple) – The color specified as a name or RGBA tuple.

Returns:

The RGBA tuple corresponding to the specified color.

Return type:

tuple

Raises:

ValueError – If input color is a value that is not supported.

apply_color_fill(image: PIL.Image.Image, color: Tuple[int, int, int, int] | None) → PIL.Image.Image

Applies a color fill to an overlay shape while preserving transparency.

If a color is provided, apply it to the non-transparent parts of the image, effectively changing the shape’s color while keeping the background transparent.

Parameters:

• image (PIL.Image.Image) – Original PIL.Image.Image object of a shape.

• color (tuple | NoneType) – RGBA tuple to apply as the new color.

Returns:

A new PIL Image object with the color applied.

Return type:

PIL.Image.Image

get_data_path() → str

Determines the path for storing downloaded data, locating the ‘data’ directory at a fixed level above this script’s location in the directory hierarchy.

This function calculates an absolute path to a ‘data’ directory intended to reside a few levels above the directory containing this script. It ensures the ‘data’ directory exists, creating it if necessary. This approach allows for a consistent data storage location relative to the script’s position in the project structure, facilitating access across different environments and setups.

Returns:

The absolute path to the ‘data’ directory, ensuring it is consistently located relative to the

script’s position in the project’s directory hierarchy.

Return type:

str

abstract get_shape(name: str | None = None, color: str | Tuple[int, int, int, int] | None = None) → Tuple[PIL.Image.Image, str]

Abstract method to generate and return an image of a specific overlay type (shape or dinosaur) in a specified color.

Subclasses must implement this method to create images according to their specialization (geometric shapes or dinosaurs) and optionally apply a color overlay based on the provided color parameter.

Parameters:

• name (str, optional) – The name of the specific shape or dinosaur to generate. Defaults to a random selection if None.

• color (str | tuple, optional) – The color to apply to the image. It can be a color name or an RGBA tuple. Defaults to no color overlay if None.

Returns:

A tuple with the PIL.Image.Image object of the generated foreground with the applied color overlay,

and the name of the generated foreground.

Return type:

tuple[PIL.Image.Image, str]

class datagenerator.foregrounds.GeometricShapeGenerator(size: int = 200)

Bases: ForegroundGenerator

Generates images of geometric shapes with customizable colors.

This class provides functionality to generate images of various geometric shapes, such as circles, ellipses, rectangles, and polygons with a specified number of sides, each with a specified or default color. Shapes are drawn on a transparent background.

Inherits from:

ForegroundGenerator: The base class for generating foreground images.

size

The size of the square image in pixels. Defaults to 200.

Type:

int

shape_names

List of all possible shape names to be drawn.

Type:

list

shape_id_map

Maps an integer to each name in shape_names list

Type:

dict

Initializes a GeometricShapeGenerator object.

size: int = 200

shape_names: List[str] = ['circle', 'ellipse', 'triangle', 'square', 'rectangle', 'pentagon', 'hexagon', 'heptagon',...

shape_id_map: Dict[str, int]

geometric_shapes() → Dict[str, Callable[[], PIL.Image.Image]]

Provides a dictionary of lambdas for generating geometric shapes.

Returns:

A dictionary mapping shape names to lambdas that generate shape images.

Return type:

dict

calculate_ngon_vertices(center_x: int, center_y: int, radius: float, sides: int) → List[Tuple[float, float]]

Calculates the vertices of a regular polygon.

Given the center coordinates, radius, and number of sides, this method calculates the vertices of a regular polygon centered at the given point.

Parameters:

• center_x (int) – The x-coordinate of the polygon’s center.

• center_y (int) – The y-coordinate of the polygon’s center.

• radius (float) – The radius of the circumcircle of the polygon.

• sides (int) – The number of sides (and vertices) of the polygon.

Returns:

A list of vertices, where each vertex is a tuple (x, y).

Return type:

list[tuple]

make_ngon(sides: int) → PIL.Image.Image

Generates an image of a regular polygon with a specified number of sides.

Parameters:

sides (int) – The number of sides of the polygon.

Returns:

A PIL.Image.Image object containing the drawn polygon.

Return type:

PIL.Image.Image

make_rectangle() → PIL.Image.Image

Generates an image of a rectangle.

Returns:

A PIL.Image.Image object containing the drawn rectangle.

Return type:

PIL.Image.Image

make_circle() → PIL.Image.Image

Generates an image of a circle.

Returns:

A PIL.Image.Image object containing the drawn circle.

Return type:

PIL.Image.Image

make_ellipse() → PIL.Image.Image

Generates an image of an ellipse.

Returns:

An image object containing the drawn ellipse.

Return type:

PIL.Image.Image

get_shape(name: str | None = None, color: str | Tuple[int, int, int, int] | None = None) → Tuple[PIL.Image.Image, str]

Retrieves and returns an image of a specified geometric shape in a specified color.

If no shape name is specified, a shape is randomly selected from the available shapes. The specified color can be a color name or an RGBA tuple. If no color is specified, the shape is generated in black by default.

Parameters:

• name (str, optional) – The name of the shape to generate. Defaults to a random shape if None.

• color (str | tuple, optional) – The color of the shape, specified as a color name or RGBA tuple. Defaults to black if None or invalid.

Returns:

A tuple containing an PIL.Image.Image object containing the drawn shape,

and the name of the generated shape.

Return type:

tuple[PIL.Image.Image, str]

class datagenerator.foregrounds.DinosaurShapeGenerator(meta_data_source: str = 'local')

Bases: ForegroundGenerator

Generates and manipulates images of dinosaurs with customizable colors.

This class fetches dinosaur images with transparent backgrounds from Wikimedia Commons, enabling the generation of images for supervised learning datasets. It supports customizing the color of dinosaurs post-download.

dino_meta_data

Metadata for the fetched dinosaur images.

Type:

list

dino_dict

Maps dinosaur names to their Image objects.

Type:

dict

shape_names

List of all dinosaur names that we can use for sampling.

Type:

list

shape_id_map

Maps an integer to each name in shape_names list

Type:

dict

Initializes a DinosaurShapeGenerator object and downloads dinosaur images for local use.

Downloads images from Wikimedia Commons and prepares them for generating datasets, storing them locally for efficient access.

_url = 'https://commons.wikimedia.org/wiki/Category:Dinosaurs_on_transparent_background'

_data_folder

meta_data_source = 'local'

dino_meta_data

dino_dict

shape_names = []

shape_id_map

clean_dino_name_from_URL(url: str) → str

Extracts and cleans the dinosaur name from a given URL.

Parses the URL to extract the dinosaur name, removing URL encoding and invalid filename characters.

Parameters:

url (str) – URL containing the dinosaur name.

Returns:

Cleaned dinosaur name suitable for filenames.

Return type:

str

dino_image_metadata(meta_data_source: str) → List[Dict[str, str | int]]

Fetches metadata for dinosaur images from the specified URL.

Returns:

A list of dictionaries, each containing metadata for a dinosaur image.

Return type:

list[dict]

load_dino_image(url: str, save_path: str) → PIL.Image.Image | None

Downloads a dinosaur image from a URL and saves it locally.

Parameters:

• url (str) – URL of the image to be downloaded.

• save_path (str) – Local file path to save the downloaded image.

Returns:

The downloaded PIL.Image.Image object, or None if the download fails.

Return type:

PIL.Image.Image | NoneType

load_all_dinos() → None

Loads all available dinosaur images into memory from the local storage.

Ensures that images are downloaded based on metadata if they are not already present locally, making them readily available in memory for image generation.

get_shape(name: str | None = None, color: str | Tuple[int, int, int, int] | None = None) → Tuple[PIL.Image.Image, str]

Retrieves a dinosaur image by name with an optional color overlay.

If no name is specified, selects a dinosaur randomly. Optionally applies a color to the dinosaur image before returning.

Parameters:

• name (str, optional) – Name of the dinosaur. Selects randomly if None. Defaults to None.

• color (str | tuple, optional) – color to apply. Uses predefined or RGBA tuple. Defaults to None.

Returns:

A tuple containing the colored PIL.Image.Image object of the dinosaur and its name.

Return type:

tuple[PIL.Image.Image, str]