Images

Module for managing images

Image

A class representing an image.

Attributes:

Name	Type	Description
_path	Path	The path to the image file.
_value_array	ndarray	Numpy array containing pixel values. If available, it can be accessed with Image.value.
_width	int	The width of the image in pixels.
_height	int	The height of the image in pixels.
_exif_data	dict	The EXIF metadata of the image, if available.
_date_time	datetime	The date and time the image was taken, if available.

date: str property

Returns the date and time of the image in a string format. If the information is not available in the EXIF metadata, it returns None.

Returns:

Type	Description
str	str or None: The date and time of the image in the format "YYYY:MM:DD HH:MM:SS", or None if not available.

exif: dict property

exif Returns the exif of the image

Returns:

Name	Type	Description
dict	dict	Dictionary containing Exif information

extension: str property

Returns the extension of the image

height: int property

Returns the height of the image

name: str property

Returns the name of the image (including extension)

parent: str property

Path to the parent folder of the image

path: str property

Path of the image

stem: str property

Returns the name of the image (excluding extension)

time: str property

time Returns the time of the image from exif as a string

value: np.ndarray property

Returns the image (pixel values) as numpy array

width: int property

Returns the width of the image

__init__(path, image=None)

init Create Image object

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	path to the image	required
image	ndarray	Numpy array containing pixel values. If provided, they are stored in self._value_array and they are accessible from outside the class with Image.value. Defaults to None.	None

extract_patch(limits)

Extract a patch from the image.

Parameters:

Name	Type	Description	Default
limits	List[int]	A list containing the bounding box coordinates [xmin, ymin, xmax, ymax].	required

Returns:

Type	Description
ndarray	np.ndarray: The image patch extracted from the image.

get_datetime()

Returns the date and time of the image in a string format. If the information is not available in the EXIF metadata, it returns None.

Returns:

Name	Type	Description
datetime	datetime	The date and time of the image as datetime object

get_intrinsics_from_exif()

Constructs the camera intrinsics from exif tag.

Equation: focal_px=max(w_px,h_px)*focal_mm / ccdw_mm

Note

References for this functions can be found:

• https://github.com/colmap/colmap/blob/e3948b2098b73ae080b97901c3a1f9065b976a45/src/util/bitmap.cc#L282
• https://openmvg.readthedocs.io/en/latest/software/SfM/SfMInit_ImageListing/
• https://photo.stackexchange.com/questions/40865/how-can-i-get-the-image-sensor-dimensions-in-mm-to-get-circle-of-confusion-from # noqa: E501

Returns:

Name	Type	Description
K	ndarray	intrinsics matrix (3x3 numpy array).

read_exif()

Reads the Exchangeable image file format (EXIF) metadata of an image file and stores them in a dictionary.

This function reads the EXIF data of an image file using the exifread library, and then stores the metadata in a dictionary. The image path is specified by the _path attribute of the Image object.

If no EXIF data is available for the image, an error message will be logged.

If the EXIF data contains the image size information, this function extracts the width and height of the image from the EXIF data and stores them in the _width and _height attributes of the Image object.

If the image size information is not available in the EXIF data, this function tries to load the image file and obtain the image size from the Numpy array. If the image size cannot be obtained from either the EXIF data or the Numpy array, a runtime error is raised.

Returns:

Type	Description
None	None

read_image(col=True, resize=[-1], crop=None)

Wrapper around the function read_image to be a class method.

undistort_image(K, dist, out_path=None)

Wrapper around OpenCV's cv2.undistort function to undistort the image.

Parameters:

Name	Type	Description	Default
K	ndarray	Camera intrinsic matrix.	required
dist	ndarray	Camera distortion coefficients.	required
out_path	str	Path for writing the undistorted image to disk. If out_path is None, undistorted image is not saved to disk. Defaults to None.	None

Returns:

Type	Description
ndarray	np.ndarray: Undistorted image as a numpy array.

ImageList

__init__(data_dir, image_ext=None, recursive=False)

Initialize a new ImageList object by specifying the directory containing image files.

Parameters:

Name	Type	Description	Default
data_dir	Union[str, Path]	A string or Path object specifying the directory path containing image files.	required
image_ext	Union[str, List[str]]	A string or list of strings specifying the image file extensions to search for. Defaults to None, which searches for all file types.	None
recursive	bool	Whether to search for image files recursively in subdirectories. Defaults to False.	False
case_sensitive	bool	Whether to search for image files with case sensitivity. Defaults to False.	required

Example:

from pathlib import Path from impreproc.images import ImageList data_dir = Path("/path/to/image/directory") image_list = ImageList(data_dir, image_ext=["jpg", "png"], recursive=True)

TODO

Fix case-sensitive search in Linux environments.

latlonalt_from_exif(exif)

Extracts the latitude, longitude, and altitude from the given EXIF data.

Parameters:

Name	Type	Description	Default
exif	dict	The EXIF data from which to extract the latitude, longitude, and altitude.	required

Returns:

Name	Type	Description
tuple	tuple	A tuple containing the latitude (float), longitude (float), and altitude (float).

Raises:

Type	Description
AssertionError	If the latitude or longitude reference is not North or East, respectively, or if the altitude reference is not WGS84.

read_image(path, color=True, resize=[-1], crop=None)

Reads image with OpenCV and returns it as a NumPy array.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path of the image.	required
color	bool	Whether to read the image as color (RGB) or grayscale. Defaults to True.	True
resize	List[int]	If not [-1], image is resized at [width, height] dimensions. Defaults to [-1].	[-1]
crop	List[int]	If not None, a List containing the bounding box for cropping the image as [xmin, xmax, ymin, ymax]. Defaults to None.	None

Returns:

Type	Description
ndarray	np.ndarray: The image as a NumPy array.

read_image_list(data_dir, image_ext=None, recursive=False)

Returns a list of Path objects for all image files in a directory.

Parameters:

Name	Type	Description	Default
data_dir	Union[str, Path]	A string or Path object specifying the directory path containing image files.	required
image_ext	Union[str, List[str]]	A string or list of strings specifying the image file extensions to search for. Defaults to None, which searches for all file types.	None
recursive	bool	Whether to search for image files recursively in subdirectories. Defaults to False.	False

Returns:

Type	Description
List[Path]	[Path]: A list of Path objects for all image files found in the specified directory with the specified file extensions and name pattern.

Raises:

Type	Description
AssertionError	If the specified directory path is not valid.
AssertionError	If the specified image extension is not a string or list of strings with three characters each.

TODO

Implement custom name patterns. Removed case_sensitive option for now as Windows is case-insensitive by default and the current algorithm dupicated the files when reading the file list. Need to find a way to make it work on both Windows and Linux.