mapreader.load.images

Classes

MapImages

Class to manage a collection of image paths and construct image objects.

Module Contents

class mapreader.load.images.MapImages(path_images=None, file_ext=None, tree_level='parent', parent_path=None, **kwargs)

Class to manage a collection of image paths and construct image objects.

Parameters:

path_images (str or None, optional) – Path to the directory containing images (accepts wildcards). By default, None (no images will be loaded).
file_ext (str or None, optional) – The file extension of the image files to be loaded, ignored if file types are specified in path_images (e.g. with "./path/to/dir/*png"). By default None.
tree_level (str, optional) – Level of the image hierarchy to construct. The value can be "parent" (default) and "patch".
parent_path (str or None, optional) – Path to parent images (if applicable), by default None.
**kwargs (dict, optional) – Keyword arguments to pass to the _images_constructor() method.

path_images

List of paths to the image files.

Type:: list

images

A dictionary containing the constructed image data. It has two levels of hierarchy, "parent" and "patch", depending on the value of the tree_level parameter.

Type:: dict

images

parents

patches

georeferenced = False

check_georeferencing()

add_metadata(metadata, index_col=0, delimiter=',', usecols=None, tree_level='parent', ignore_mismatch=False)

Add metadata information to the images dictionary property.

Parameters:

metadata (str or pathlib.Path or pandas.DataFrame or geopandas.GeoDataFrame) – Path to a CSV/TSV/etc, Excel or JSON/GeoJSON file or a pandas DataFrame or geopandas GeoDataFrame.
index_col (int or str, optional) –
Column to use as the index when reading the file and converting into a panda.DataFrame. Accepts column indices or column names. By default 0 (first column).

Only used if a CSV/TSV file path is provided as the metadata parameter. Ignored if usecols parameter is passed.
delimiter (str, optional) –
Delimiter used in the csv file, by default ",".

Only used if a csv file path is provided as the metadata parameter.
usecols (list, optional) – List of columns indices or names to add to MapImages. If None is passed, all columns will be used. By default None.
tree_level (str, optional) – Determines which images dictionary ("parent" or "patch") to add the metadata to, by default "parent".
ignore_mismatch (bool, optional) – Whether to error if metadata with mismatching information is passed. By default False.

Raises:

ValueError –

If metadata is not a valid file path, pandas DataFrame or geopandas GeoDataFrame.

If ‘name’ or ‘image_id’ is not one of the columns in the metadata.

Return type:

None

Notes

Your metadata file must contain an column which contains the image IDs (filenames) of your images. This should have a column name of either name or image_id.

Existing information in your MapImages object will be overwritten if there are overlapping column headings in your metadata file/dataframe.

show_sample(num_samples=6, tree_level='patch', random_seed=42, **kwargs)

Display a sample of images from a particular level in the image hierarchy.

Parameters:

num_samples (int, optional) – The number of images to display. Default is 6.
tree_level (str, optional) – The level of the hierarchy to display images from, which can be "patch" or "parent". By default “patch”.
random_seed (int, optional) – The random seed to use for reproducibility. Default is 42.
**kwargs (dict, optional) – Additional keyword arguments to pass to matplotlib.pyplot.figure().

Returns:

The figure generated

Return type:

matplotlib.Figure

list_parents()

Return list of all parents

Return type:: list[str]

list_patches()

Return list of all patches

Return type:: list[str]

add_shape(tree_level='parent', tqdm_kwargs=None)

Add a shape to each image in the specified level of the image hierarchy.

Parameters:

tree_level (str, optional) – The level of the hierarchy to add shapes to, either "parent" (default) or "patch".
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

Notes

The method runs _add_shape_id() for each image present at the tree_level provided.

add_coords_from_grid_bb(verbose=False, tqdm_kwargs=None)

Add coordinates to parent images using grid bounding boxes.

Parameters:

verbose (bool, optional) – Whether to print verbose outputs. By default, False.
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Raises:

ValueError – If no grid bounding box found for a parent image.

Return type:

None

infer_parent_coords_from_patches(verbose=False, tqdm_kwargs=None)

Infers parent coordinates from patches.

Parameters:

verbose (bool, optional) – Whether to print verbose outputs. By default, False
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

add_coord_increments(verbose=False, tqdm_kwargs=None)

Adds coordinate increments to each image at the parent level.

Parameters:

verbose (bool, optional) – Whether to print verbose outputs, by default False.
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

Notes

The method runs _add_coord_increments_id() for each image present at the parent level, which calculates pixel-wise delta longitude (dlon) and delta latitude (dlat) for the image and adds the data to it.

add_patch_coords(verbose=False, tqdm_kwargs=None)

Add coordinates to all patches in patches dictionary.

Parameters:

verbose (bool, optional) – Whether to print verbose outputs. By default, False
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

add_patch_polygons(verbose=False, tqdm_kwargs=None)

Add polygon to all patches in patches dictionary.

Parameters:

verbose (bool, optional) – Whether to print verbose outputs. By default, False
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

add_center_coord(tree_level='patch', verbose=False, tqdm_kwargs=None)

Adds center coordinates to each image at the specified tree level.

Parameters:

tree_level (str, optional) – The tree level where the center coordinates will be added. It can be either "parent" or "patch" (default).
verbose (bool, optional) – Whether to print verbose outputs, by default False.
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

Notes

The method runs _add_center_coord_id() for each image present at the tree_level provided, which calculates central longitude and latitude (center_lon and center_lat) for the image and adds the data to it.

add_parent_polygons(verbose=False, tqdm_kwargs=None)

Add polygon to all parents in parents dictionary.

Parameters:

verbose (bool, optional) – Whether to print verbose outputs. By default, False
tqdm_kwargs (dict, optional) – Additional keyword arguments to pass to the tqdm progress bar. By default, None.

Return type:

None

patchify_all(method='pixel', patch_size=100, tree_level='parent', path_save=None, skip_blank_patches=False, add_to_parents=True, square_cuts=False, resize_factor=False, output_format='png', rewrite=False, verbose=False, overlap=0)

Patchify all images in the specified tree_level and (if add_to_parents=True) add the patches to the MapImages instance’s images dictionary.

Parameters:

method (str, optional) – Method used to patchify images, choices between "pixel" (default) and "meters" or "meter".
patch_size (int, optional) – Number of pixels/meters in both x and y to use for slicing, by default 100.
tree_level (str, optional) – Tree level, choices between "parent" or "patch, by default "parent".
path_save (str, optional) – Directory to save the patches. If None, will be set as f”patches_{patch_size}_{method}” (e.g. “patches_100_pixel”). By default None.
skip_blank_patches (bool) – If True, any patch that only contains 0 values will be skipped, by default False. Uses PIL.Image().get_bbox().
add_to_parents (bool, optional) – If True, patches will be added to the MapImages instance’s images dictionary, by default True.
square_cuts (bool, optional) – If True, all patches will have the same number of pixels in x and y, by default False.
resize_factor (bool, optional) – If True, resize the images before patchifying, by default False.
output_format (str, optional) – Format to use when writing image files, by default "png".
rewrite (bool, optional) – If True, existing patches will be rewritten, by default False.
verbose (bool, optional) – If True, progress updates will be printed throughout, by default False.
overlap (int, optional) – Fractional overlap between patches, by default 0.

Return type:

None

calc_pixel_stats(parent_id=None, calc_mean=True, calc_std=True, verbose=False)

Calculate the mean and standard deviation of pixel values for all channels of all patches of a given parent image. Store the results in the MapImages instance’s images dictionary.

Parameters:

parent_id (str or None, optional) – The ID of the parent image to calculate pixel stats for. If None, calculate pixel stats for all parent images. By default, None
calc_mean (bool, optional) – Whether to calculate mean pixel values. By default, True.
calc_std (bool, optional) – Whether to calculate standard deviation of pixel values. By default, True.
verbose (bool, optional) – Whether to print verbose outputs. By default, False.

Return type:

None

Notes

Pixel stats are calculated for patches of the parent image specified by parent_id.
If parent_id is None, pixel stats are calculated for all parent images in the object.
If mean or standard deviation of pixel values has already been calculated for a patch, the calculation is skipped.
Pixel stats are stored in the images attribute of the MapImages instance, under the patch key for each patch.
If no patches are found for a parent image, a warning message is displayed and the method moves on to the next parent image.

convert_images(save=False, save_format='csv', delimiter=',')

Convert the MapImages instance’s images dictionary into pandas DataFrames (or geopandas GeoDataFrames if geo-referenced) for easy manipulation.

Parameters:

save (bool, optional) – Whether to save the dataframes as files. By default False.
save_format (str, optional) – If save = True, the file format to use when saving the dataframes. Options of csv (“csv”), excel (“excel” or “xlsx”) or geojson (“geojson”). By default, “csv”.
delimiter (str, optional) – The delimiter to use when saving the dataframe. By default ",".

Returns:

The method returns a tuple of two DataFrames/GeoDataFrames: One for the parent images and one for the patch images.

Return type:

tuple of two pandas DataFrames or geopandas GeoDataFrames

explore_patches(parent_id, column_to_plot=None, xyz_url=None, categorical=False, cmap='viridis', vmin=None, vmax=None, style_kwargs=None)

Explore patches of a parent image. This method only works with georeferenced images.

Parameters:

parent_id (str) – The ID of the parent image to explore.
column_to_plot (str | None, optional) – The column values to plot on patches. If None, plot just the patch bounding boxes. By default None.
xyz_url (str | None, optional) – The XYZ URL of the tilelayer to use as a baselayer for the map. If None, will default to OpenStreetMap.Mapnik. By default None.
categorical (bool, optional) – Whether the column to plot is categorical or not. By default False.
cmap (str, optional) – The colormap to use when plotting column values. By default “viridis”.
vmin (float | None, optional) – The minimum value of the colormap. If None, will use the minimum value in the data. By default None.
vmax (float | None, optional) – The maximum value of the colormap. If None, will use the minimum value in the data. By default None.
style_kwargs (dict | None, optional) – A dictionary of style keyword arguments to pass to the folium style_function. By default None.

Returns:

The folium map object with the patches plotted.

Return type:

folium.Map

show_patches(parent_id, column_to_plot=None, figsize=(10, 10), alpha=0.5, categorical=False, cmap='viridis', vmin=None, vmax=None, style_kwargs=None)

Plot patches of a parent image using matplotlib. This method works for both georeferenced and non-georeferenced images.

Parameters:

parent_id (str) – The ID of the parent image to plot.
column_to_plot (str | None, optional) – The column values to plot on patches. If None, plot just the patch bounding boxes.
figsize (tuple, optional) – The size of the figure to be plotted. By default, (10,10).
alpha (float, optional) – Transparency level for plotting patches, by default 0.5.
categorical (bool, optional) – Whether the column to plot is categorical or not. By default False.
cmap (str, optional) – The colormap to use when plotting column values. By default “viridis”.
vmin (float | None, optional) – The minimum value of the colormap. If None, will use the minimum value in the data. By default None.
vmax (float | None, optional) – The maximum value of the colormap. If None, will use the minimum value in the data. By default None.
style_kwargs (dict | None, optional) – A dictionary of style keyword arguments to pass to matplotlib.pyplot.plot. By default None.

Returns:

The matplotlib axes object with the patches plotted.

Return type:

matplotlib.axes.Axes

Notes

Users with georeferenced images may wish to use the explore_patches method instead.

load_patches(patch_paths, parent_paths=False, patch_file_ext=False, parent_file_ext=False, add_geo_info=False, clear_images=False)

Loads patch images from the given paths and adds them to the images dictionary in the MapImages instance.

Parameters:

patch_paths (str) –
The file path of the patches to be loaded.

Note: The ``patch_paths`` parameter accepts wildcards.
parent_paths (str or bool, optional) –
The file path of the parent images to be loaded. If set to False, no parents are loaded. Default is False.

Note: The ``parent_paths`` parameter accepts wildcards.
patch_file_ext (str or bool, optional) – The file extension of the patches to be loaded, ignored if file extensions are specified in patch_paths (e.g. with "./path/to/dir/*png") By default False.
parent_file_ext (str or bool, optional) – The file extension of the parent images, ignored if file extensions are specified in parent_paths (e.g. with "./path/to/dir/*png") By default False.
add_geo_info (bool, optional) – If True, adds geographic information to the parent image. Default is False.
clear_images (bool, optional) – If True, clears the images from the images dictionary before loading. Default is False.

Return type:

None

static detect_parent_id_from_path(image_id, parent_delimiter='#')

Detect parent IDs from image_id.

Parameters:

image_id (int or str) – ID of patch.
parent_delimiter (str, optional) – Delimiter used to separate parent ID when naming patch, by default "#".

Returns:

Parent ID.

Return type:

str

static detect_pixel_bounds_from_path(image_id)

Detects borders from the path assuming patch is named using the following format: ...-min_x-min_y-max_x-max_y-...

Parameters:

image_id (int or str) – ID of image
.. –

border_delimiterstr, optional
Delimiter used to separate border values when naming patch image, by default "-".

Returns:

Border (min_x, min_y, max_x, max_y) of image

Return type:

tuple of min_x, min_y, max_x, max_y

load_parents(parent_paths=False, parent_ids=False, parent_file_ext=False, overwrite=False, add_geo_info=False)

Load parent images from file paths (parent_paths).

If parent_paths is not given, only parent_ids, no image path will be added to the images.

Parameters:

parent_paths (str or bool, optional) – Path to parent images, by default False.
parent_ids (list, str or bool, optional) – ID(s) of parent images. Ignored if parent_paths are specified. By default False.
parent_file_ext (str or bool, optional) – The file extension of the parent images, ignored if file extensions are specified in parent_paths (e.g. with "./path/to/dir/*png") By default False.
overwrite (bool, optional) – If True, current parents will be overwritten, by default False.
add_geo_info (bool, optional) – If True, geographical info will be added to parents, by default False.

Return type:

None

load_df(parent_df=None, patch_df=None, clear_images=True)

Create MapImages instance by loading data from pandas DataFrame(s).

Parameters:

parent_df (pandas.DataFrame or gpd.GeoDataFrame or None, optional) – DataFrame containing parents or path to parents, by default None.
patch_df (pandas.DataFrame or gpd.GeoDataFrame or None, optional) – DataFrame containing patches, by default None.
clear_images (bool, optional) – If True, clear images before reading the dataframes, by default True.

Return type:

None

load_csv(parent_path=None, patch_path=None, clear_images=False, index_col_patch=0, index_col_parent=0, delimiter=',')

Load CSV files containing information about parent and patches, and update the images attribute of the MapImages instance with the loaded data.

Parameters:

parent_path (str or pathlib.Path or None) – Path to the CSV file containing parent image information. By default, None.
patch_path (str or pathlib.Path or None) – Path to the CSV file containing patch information. By default, None.
clear_images (bool, optional) – If True, clear all previously loaded image information before loading new information. Default is False.
index_col_patch (int or str or None, optional) – Column to set as index for the patch DataFrame, by default 0.
index_col_parent (int or str or None, optional) – Column to set as index for the parent DataFrame, by default 0.
delimiter (str, optional) – The delimiter to use when reading the dataframe. By default ",".

Return type:

None

add_geo_info(target_crs='EPSG:4326', verbose=True)

Add coordinates (reprojected to EPSG:4326) to all parents images using image metadata.

Parameters:

target_crs (str, optional) – Projection to convert coordinates into, by default "EPSG:4326".
verbose (bool, optional) – Whether to print verbose output, by default True

Return type:

None

Notes

For each image in the parents dictionary, this method calls _add_geo_info_id and coordinates (if present) to the image in the parent dictionary.

save_parents_as_geotiffs(rewrite=False, verbose=False, crs=None)

Save all parents in MapImages instance as geotiffs.

Parameters:

rewrite (bool, optional) – Whether to rewrite files if they already exist, by default False
verbose (bool, optional) – Whether to print verbose outputs, by default False
crs (str, optional) – The CRS of the coordinates. If None, the method will first look for crs in the parents dictionary and use those. If crs cannot be found in the dictionary, the method will use “EPSG:4326”. By default None.

Return type:

None

save_patches_as_geotiffs(rewrite=False, verbose=False, crs=None)

Save all patches in MapImages instance as geotiffs.

Parameters:

rewrite (bool, optional) – Whether to rewrite files if they already exist, by default False
verbose (bool, optional) – Whether to print verbose outputs, by default False
crs (str, optional) – The CRS of the coordinates. If None, the method will first look for crs in the patches dictionary and use those. If crs cannot be found in the dictionary, the method will use “EPSG:4326”. By default None.

Return type:

None

save_patches_to_geojson(geojson_fname='patches.geojson', rewrite=False, crs=None)

Saves patches to a geojson file.

Parameters:

geojson_fname (Optional[str], optional) – The name of the geojson file, by default “patches.geojson”
rewrite (Optional[bool], optional) – Whether to overwrite an existing file, by default False.
crs (Optional[str], optional) – The CRS to use when writing the geojson. If None, the method will look for “crs” in the patches dictionary and, if found, will use that. Otherwise it will set the crs to the default value of “EPSG:4326”. By default None

Return type:

None