mapreader.load
Submodules
Package Contents
Classes
Class to manage a collection of image paths and construct image objects. |
Functions
|
Creates a |
|
Creates a |
- class mapreader.load.MapImages(path_images=None, file_ext=False, 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,
False
file_ext (str or False, 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 defaultFalse
.tree_level (str, optional) – Level of the image hierarchy to construct. The value can be
"parent"
(default) and"patch"
.parent_path (str, optional) – Path to parent images (if applicable), by default
None
.**kwargs (dict, optional) – Additional keyword arguments to be passed 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 thetree_level
parameter.- Type:
dict
- add_metadata(metadata, index_col=0, delimiter=',', columns=None, tree_level='parent', ignore_mismatch=False)
Add metadata information to the images dictionary.
- Parameters:
metadata (str or pandas.DataFrame) – Path to a
csv
(or similar),xls
orxlsx
file or a pandas DataFrame that contains the metadata information.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 file path is provided as the
metadata
parameter. Ignored ifcolumns
parameter is passed.delimiter (str, optional) –
Delimiter used in the
csv
file, by default","
.Only used if a
csv
file path is provided as themetadata
parameter.columns (list, optional) – List of columns indices or names to add to MapImages. If
None
is passed, all columns will be used. By defaultNone
.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 pandas DataFrame or a
csv
,xls
orxlsx
file path.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
orimage_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, tree_level='patch', random_seed=65, **kwargs)
Display a sample of images from a particular level in the image hierarchy.
- Parameters:
num_samples (int) – The number of images to display.
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
65
.**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')
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"
.- Return type:
None
Notes
The method runs
mapreader.load.images.MapImages._add_shape_id()
for each image present at thetree_level
provided.
- add_coord_increments(verbose=False)
Adds coordinate increments to each image at the parent level.
- Parameters:
verbose (bool, optional) – Whether to print verbose outputs, by default
False
.- Return type:
None
Notes
The method runs
mapreader.load.images.MapImages._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)
Add coordinates to all patches in patches dictionary.
- Parameters:
verbose (bool, optional) – Whether to print verbose outputs. By default,
False
- Return type:
None
- add_patch_polygons(verbose=False)
Add polygon to all patches in patches dictionary.
- Parameters:
verbose (bool, optional) – Whether to print verbose outputs. By default,
False
- Return type:
None
- add_center_coord(tree_level='patch', verbose=False)
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
.
- Return type:
None
Notes
The method runs
mapreader.load.images.MapImages._add_center_coord_id()
for each image present at thetree_level
provided, which calculates central longitude and latitude (center_lon
andcenter_lat
) for the image and adds the data to it.
- patchify_all(method='pixel', patch_size=100, tree_level='parent', path_save=None, add_to_parents=True, square_cuts=False, resize_factor=False, output_format='png', rewrite=False, verbose=False)
Patchify all images in the specified
tree_level
and (ifadd_to_parents=True
) add the patches to the MapImages instance’simages
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.
add_to_parents (bool, optional) – If True, patches will be added to the MapImages instance’s
images
dictionary, by defaultTrue
.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
.
- 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, Nonecalc_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
isNone
, 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 theMapImages
instance, under thepatch
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’simages
dictionary into pandas DataFrames 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”) or excel (“excel” or “xlsx”). 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: One for the
parent
images and one for thepatch
images.- Return type:
tuple of two pandas DataFrames
- show_parent(parent_id, column_to_plot=None, **kwargs)
A wrapper method for .show() which plots all patches of a specified parent (parent_id).
- Parameters:
parent_id (str) – ID of the parent image to be plotted.
column_to_plot (str, optional) – Column whose values will be plotted on patches, by default
None
.**kwargs (Dict) – Key words to pass to
show
method. See help text forshow
for more information.
- Returns:
A list of figures created by the method.
- Return type:
list
Notes
This is a wrapper method. See the documentation of the
mapreader.load.images.MapImages.show()
method for more detail.
- show(image_ids, column_to_plot=None, figsize=(10, 10), plot_parent=True, patch_border=True, border_color='r', vmin=None, vmax=None, alpha=1.0, cmap='viridis', discrete_cmap=256, plot_histogram=False, save_kml_dir=False, image_width_resolution=None, kml_dpi_image=None)
Plot images from a list of image_ids.
- Parameters:
image_ids (str or list) – Image ID or list of image IDs to be plotted.
column_to_plot (str, optional) – Column whose values will be plotted on patches, by default
None
.plot_parent (bool, optional) – If
True
, parent image will be plotted in background, by defaultTrue
.figsize (tuple, optional) – The size of the figure to be plotted. By default,
(10,10)
.patch_border (bool, optional) – If
True
, a border will be placed around each patch, by defaultTrue
.border_color (str, optional) – The color of the border. Default is
"r"
.vmin (float, optional) – The minimum value for the colormap. If
None
, will be set to minimum value incolumn_to_plot
, by defaultNone
.vmax (float, optional) – The maximum value for the colormap. If
None
, will be set to the maximum value incolumn_to_plot
, by defaultNone
.alpha (float, optional) – Transparency level for plotting
value
with floating point values ranging from 0.0 (transparent) to 1 (opaque), by default1.0
.cmap (str, optional) – Color map used to visualize chosen
column_to_plot
values, by default"viridis"
.discrete_cmap (int, optional) – Number of discrete colors to use in color map, by default
256
.plot_histogram (bool, optional) – If
True
, plot histograms of thevalue
of images. By defaultFalse
.save_kml_dir (str or bool, optional) – If
True
, save KML files of the images. If a string is provided, it is the path to the directory in which to save the KML files. If set toFalse
, no files are saved. By defaultFalse
.image_width_resolution (int or None, optional) –
The pixel width to be used for plotting. If
None
, the resolution is not changed. Default isNone
.Note: Only relevant when
tree_level="parent"
.kml_dpi_image (int or None, optional) – The resolution, in dots per inch, to create KML images when
save_kml_dir
is specified (as eitherTrue
or with path). By defaultNone
.
- Returns:
A list of figures created by the method.
- Return type:
list
- load_patches(patch_paths, patch_file_ext=False, parent_paths=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 theMapImages
instance.- Parameters:
patch_paths (str) –
The file path of the patches to be loaded.
Note: The ``patch_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 defaultFalse
.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 isFalse
.Note: The ``parent_paths`` parameter accepts wildcards.
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 defaultFalse
.add_geo_info (bool, optional) – If
True
, adds geographic information to the parent image. Default isFalse
.clear_images (bool, optional) – If
True
, clears the images from theimages
dictionary before loading. Default isFalse
.
- 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, onlyparent_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 defaultFalse
.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 defaultFalse
.overwrite (bool, optional) – If
True
, current parents will be overwritten, by defaultFalse
.add_geo_info (bool, optional) – If
True
, geographical info will be added to parents, by defaultFalse
.
- 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, optional) – DataFrame containing parents or path to parents, by default
None
.patch_df (pandas.DataFrame, optional) – DataFrame containing patches, by default
None
.clear_images (bool, optional) – If
True
, clear images before reading the dataframes, by defaultTrue
.
- 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 theMapImages
instance with the loaded data.- Parameters:
parent_path (str, optional) – Path to the CSV file containing parent image information.
patch_path (str, optional) – Path to the CSV file containing patch information.
clear_images (bool, optional) – If True, clear all previously loaded image information before loading new information. Default is
False
.index_col_patch (int, optional) – Column to set as index for the patch DataFrame, by default
0
.index_col_parent (int, 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 theparent
dictionary.
- 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. Ifcrs
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
- mapreader.load.loader(path_images=None, tree_level='parent', parent_path=None, **kwargs)
Creates a
MapImages
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
tree_level (str, optional) – Level of the image hierarchy to construct. The value can be
"parent"
(default) and"patch"
.parent_path (str, optional) – Path to parent images (if applicable), by default
None
.**kwargs (dict, optional) – Additional keyword arguments to be passed to the
_images_constructor()
method.
- Returns:
The
MapImages
class which can manage a collection of image paths and construct image objects.- Return type:
Notes
This is a wrapper method. See the documentation of the
mapreader.load.images.MapImages
class for more detail.
- mapreader.load.load_patches(patch_paths, patch_file_ext=False, parent_paths=False, parent_file_ext=False, add_geo_info=False, clear_images=False)
Creates a
MapImages
class to manage a collection of image paths and construct image objects. Then loads patch images from the given paths and adds them to theimages
dictionary in theMapImages
instance.- Parameters:
patch_paths (str) –
The file path of the patches to be loaded.
Note: The ``patch_paths`` parameter accepts wildcards.
patch_file_ext (str or bool, optional) – The file extension of the patches, ignored if file extensions are specified in
patch_paths
(e.g. with"./path/to/dir/*png"
) By defaultFalse
.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 isFalse
.Note: The ``parent_paths`` parameter accepts wildcards.
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 defaultFalse
.add_geo_info (bool, optional) – If
True
, adds geographic information to the parent image. Default isFalse
.clear_images (bool, optional) – If
True
, clears the images from theimages
dictionary before loading. Default isFalse
.
- Returns:
The
MapImages
class which can manage a collection of image paths and construct image objects.- Return type:
Notes
This is a wrapper method. See the documentation of the
mapreader.load.images.MapImages
class for more detail.This function in particular, also calls the
mapreader.load.images.MapImages.loadPatches()
method. Please see the documentation for that method for more information as well.