brails.types.image_set module

This module contains classes for managing and manipulating sets of image.

Classes:

Image: A class to represent an individual image.
ImageSet: A class for handling collections of images.

`Image`(filename[, properties])	Represents an image and its associated metadata.
`ImageSet`()	A collection of Image objects.

class brails.types.image_set.Image(filename, properties=None)

Bases: object

Represents an image and its associated metadata.

To import the Image class, use:

from brails.types.image_set import Image

Parameters:

filename (str) – The name of the file containing the image.
properties (dict) – A dictionary containing metadata or properties related to the image, such as camera settings, location, or depth maps.

hash_image()

Generate a unique hash for image based on its filename and properties.

This method concatenates the image’s filename and its associated properties, converts them to strings, and computes an MD5 hash. The resulting hexadecimal string can be used for efficient duplicate detection, for example, to identify identical images with the same filenames and attributes.

Returns:: Hexadecimal string representing the MD5 hash of the image.
Return type:: str

Example

>>> image1 = Image(
...     filename='roof_001.jpg',
...     properties={'resolution': '1024x768', 'format': 'JPEG'}
... )
>>> image2 = Image(
...     filename='roof_002.jpg',
...     properties={'resolution': '1024x768', 'format': 'JPEG'}
... )
>>> hash1 = image1.hash_image()
>>> print(hash1)
30e317bf41042c6f1d20d66599234139
>>> hash2 = image2.hash_image()
>>> print(hash2)
b03f805070d9fbcc9fc82fa217f16b90
>>> hash1 == hash2
False

print_info()

Print the image filename and properties.

If no properties are set, only the filename will be printed.

Examples

>>> img = Image('gstrt_4769427063_-12213443753.jpg')
>>> img.print_info()
filename: 'gstrt_4769427063_-12213443753.jpg'

>>> img.update_properties({'width': 640, 'height': 480})
>>> img.print_info()
filename: 'gstrt_4769427063_-12213443753.jpg'
properties: {'width': 640, 'height': 480}

update_filename(filename)

Update the filename for the image.

Parameters:: filename (str) – New filename for the image.

Example

>>> img = Image('building.jpg')
>>> img.update_filename('gstrt_4769427063_-12213443753.jpg')
>>> img.filename
'gstrt_4769427063_-12213443753.jpg'

update_properties(additional_properties)

Update image properties.

Parameters:: additional_properties (Dict[str, Any]) – Key-value pairs to update image properties.

Example

>>> img = Image(
...     'gstrt_4769427063_-12213443753.jpg',
...     {'width': 640}
... )
>>> img.update_properties({'height': 480, 'cam_elevation': 12.1})
>>> img.properties
{'width': 640, 'height': 480, 'cam_elevation': 12.1}

class brails.types.image_set.ImageSet

Bases: object

A collection of Image objects.

The ImageSet class can be imported using the syntax below:

from brails.types.image_set import ImageSet

Parameters:

dir_path (str) – Path to the directory containing image files.
images (Dict[Union[str, int], Image]) – Dictionary of Image objects keyed by user-defined identifiers.

add_image(image_id, image)

Add an image to the image set.

Parameters:

image_id (Union[str, int]) – Unique key to identify the image in the set.
image (Image) – The image instance to be added.

Returns:

True if the image was successfully added. False if the image_id already exists in the image set.

Return type:

bool

Raises:

TypeError – If image is not an instance of the Image class.

Examples

>>> img_set = ImageSet()
>>> img1 = Image(
...     'building_front.jpg',
...     {'width': 1920, 'height': 1080}
... )
>>> img_set.add_image(1, img1)
True

>>> img2 = Image('street_view.png')
>>> img_set.add_image(1, img2)  # Duplicate key
Image with id 1 already exists. Image was not added.
False

combine(imageset_to_combine, key_map=None)

Combine two ImageSet objects into a new merged ImageSet, avoiding duplicate images.

Images are compared using their hashed pixel or metadata representation. Duplicate images (identical data) are skipped. Images from imageset2 can have their keys remapped using key_map, and any resulting key conflicts are automatically resolved by assigning new unique IDs.

Parameters:

imageset_to_combine (ImageSet) – The ImageSet whose images will be merged into this ImageSet.
key_map (dict, optional) – A dictionary mapping original keys from imageset_to_combine to new keys in the merged ImageSet. Example: {"img_01": "new_img_A", "img_02": "new_img_B"}. If not provided, keys are used as-is.

Returns:

A mapping from each original key in imageset_to_combine to its final key in the combined image set (after applying key_map and resolving duplicates or key conflicts).

Return type:

dict

Example

The following example demonstrates how two ImageSet objects are merged. The base image set initially contains one image ('img_01'). The secondary set has two images: one unique ('fileB.jpg') and one duplicate of the existing file ('fileA.jpg'). A key mapping is provided so 'img_02' in the secondary set becomes 'img_04' in the merged set.

Please note that, after combining the two sets, only the unique image ('fileB.jpg') is added with the new key 'img_04'. The final inventory contains two images, 'img_01' and 'img_04', confirming that 1) the merge successfully preserved unique entries, and 2) resolved key conflicts automatically.

>>> base_set = ImageSet()
>>> _ = base_set.add_image('img_01', Image('fileA.jpg'))
>>> other_set = ImageSet()
>>> _ = other_set.add_image('img_02', Image('fileB.jpg'))
>>> _ = other_set.add_image('img_03', Image('fileA.jpg'))
>>> key_map = {'img_02': 'img_04', 'img_03': 1}
>>> merged_keys = base_set.combine(other_set, key_map)
>>> print(merged_keys)
{'img_02': 'img_04'}
>>> base_set.print_info()
Directory:
Total number of images: 2
List of Images
----------------
- key: img_01, filename: fileA.jpg
- key: img_04, filename: fileB.jpg

get_image(key)

Retrieve an image by key.

Parameters:: key (Union[str, int]) – Identifier for the image.
Returns:: The Image if found; otherwise, None.
Return type:: Optional[Image]

Examples

>>> img_set = ImageSet()
>>> img_in = Image('roof_detail.jpg')
>>> img_set.add_image('main', img_in)
True

>>> img_out = img_set.get_image('main')
>>> img_out.filename
'roof_detail.jpg'

print_info()

Print information about the image set.

Displays:

The directory path (if set).
The number of images in the set.
The key, filename, and any properties for each image.

Examples

>>> img_set = ImageSet()
>>> img1 = Image('north_building.jpg')
>>> img2 = Image(
...     'east_building.jpg',
...     {'location': (36.0142, -75.6679)}
... )
>>> img_set.add_image('north_view', img1)
>>> img_set.add_image('east_view', img2)
True
>>> img_set.print_info()
Directory:
Total number of images: 2
List of Images
----------------
- key: north_view, filename: north_building.jpg
- key: east_view, filename: east_building.jpg,
properties: {'location': (36.0142, -75.6679)}

remove_image(image_id)

Remove an image from the image set.

Parameters:: image_id (Union[str, int]) – Unique key to identify the image in the set.
Returns:: True if image was removed, False otherwise.
Return type:: bool

Example

>>> img_set = ImageSet()
>>> img1 = Image(
...     'east_building.jpg',
...     {'width': 1920, 'height': 1080}
... )
>>> img_set.add_image('img1', img1)
True
>>> img_set.remove_image('img1')
True
>>> len(img_set)
0

set_directory(path_to_dir, include_existing_images=False, limited_to_extension_types=None)

Set the image directory and optionally load existing images.

Parameters:

path_to_dir (str) – Path to the directory containing image files.
include_existing_images (bool) – If True, add existing image files in the directory to the set using numeric keys starting at 1.
limited_to_extension_types (Optional[List[str]]) – If provided, only include files whose extensions match one of the allowed types (e.g., ['.jpg', '.png']).

Returns:

True if the directory exists and was set; False if the directory does not exist.

Return type:

bool

Examples

Assuming the path /data/images exists:

>>> img_set = ImageSet()
>>> img_set.set_directory(
...     '/data/images',
...     include_existing_images=True,
...     limited_to_extension_types=['.jpg', '.png']
)
True

Assuming the path /DOES-NOT-EXIST does not exist:

>>> img_set.set_directory('/DOES-NOT-EXIST')
Warning: the specified path /DOES-NOT-EXIST is not a valid
directory
False