mapreader.load.images ===================== .. py:module:: mapreader.load.images Classes ------- .. autoapisummary:: mapreader.load.images.MapImages Module Contents --------------- .. py:class:: 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. :param path_images: Path to the directory containing images (accepts wildcards). By default, ``None`` (no images will be loaded). :type path_images: str or None, optional :param file_ext: 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``. :type file_ext: str or None, optional :param tree_level: Level of the image hierarchy to construct. The value can be ``"parent"`` (default) and ``"patch"``. :type tree_level: str, optional :param parent_path: Path to parent images (if applicable), by default ``None``. :type parent_path: str or None, optional :param \*\*kwargs: Keyword arguments to pass to the :meth:`~.load.images.MapImages._images_constructor` method. :type \*\*kwargs: dict, optional .. attribute:: path_images List of paths to the image files. :type: list .. attribute:: 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 .. py:attribute:: images .. py:attribute:: parents .. py:attribute:: patches .. py:attribute:: georeferenced :value: False .. py:method:: check_georeferencing() .. py:method:: add_metadata(metadata, index_col = 0, delimiter = ',', usecols = None, tree_level = 'parent', ignore_mismatch = False) Add metadata information to the ``images`` dictionary property. :param metadata: Path to a CSV/TSV/etc, Excel or JSON/GeoJSON file or a pandas DataFrame or geopandas GeoDataFrame. :type metadata: str or pathlib.Path or pandas.DataFrame or geopandas.GeoDataFrame :param index_col: 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. :type index_col: int or str, optional :param delimiter: Delimiter used in the ``csv`` file, by default ``","``. Only used if a ``csv`` file path is provided as the ``metadata`` parameter. :type delimiter: str, optional :param usecols: List of columns indices or names to add to MapImages. If ``None`` is passed, all columns will be used. By default ``None``. :type usecols: list, optional :param tree_level: Determines which images dictionary (``"parent"`` or ``"patch"``) to add the metadata to, by default ``"parent"``. :type tree_level: str, optional :param ignore_mismatch: Whether to error if metadata with mismatching information is passed. By default ``False``. :type ignore_mismatch: bool, optional :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. :rtype: None .. rubric:: 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 :class:`~.load.images.MapImages` object will be overwritten if there are overlapping column headings in your metadata file/dataframe. .. py:method:: 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. :param num_samples: The number of images to display. Default is ``6``. :type num_samples: int, optional :param tree_level: The level of the hierarchy to display images from, which can be ``"patch"`` or ``"parent"``. By default "patch". :type tree_level: str, optional :param random_seed: The random seed to use for reproducibility. Default is ``42``. :type random_seed: int, optional :param \*\*kwargs: Additional keyword arguments to pass to ``matplotlib.pyplot.figure()``. :type \*\*kwargs: dict, optional :returns: The figure generated :rtype: matplotlib.Figure .. py:method:: list_parents() Return list of all parents .. py:method:: list_patches() Return list of all patches .. py:method:: add_shape(tree_level = 'parent', tqdm_kwargs = None) Add a shape to each image in the specified level of the image hierarchy. :param tree_level: The level of the hierarchy to add shapes to, either ``"parent"`` (default) or ``"patch"``. :type tree_level: str, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional :rtype: None .. rubric:: Notes The method runs :meth:`~.load.images.MapImages._add_shape_id` for each image present at the ``tree_level`` provided. .. py:method:: add_coords_from_grid_bb(verbose = False, tqdm_kwargs = None) Add coordinates to parent images using grid bounding boxes. :param verbose: Whether to print verbose outputs. By default, ``False``. :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional :raises ValueError: If no grid bounding box found for a parent image. .. py:method:: infer_parent_coords_from_patches(verbose = False, tqdm_kwargs = None) Infers parent coordinates from patches. :param verbose: Whether to print verbose outputs. By default, ``False`` :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional .. py:method:: add_coord_increments(verbose = False, tqdm_kwargs = None) Adds coordinate increments to each image at the parent level. :param verbose: Whether to print verbose outputs, by default ``False``. :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional :rtype: None .. rubric:: Notes The method runs :meth:`~.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. .. py:method:: add_patch_coords(verbose = False, tqdm_kwargs = None) Add coordinates to all patches in patches dictionary. :param verbose: Whether to print verbose outputs. By default, ``False`` :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional .. py:method:: add_patch_polygons(verbose = False, tqdm_kwargs = None) Add polygon to all patches in patches dictionary. :param verbose: Whether to print verbose outputs. By default, ``False`` :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional .. py:method:: add_center_coord(tree_level = 'patch', verbose = False, tqdm_kwargs = None) Adds center coordinates to each image at the specified tree level. :param tree_level: The tree level where the center coordinates will be added. It can be either ``"parent"`` or ``"patch"`` (default). :type tree_level: str, optional :param verbose: Whether to print verbose outputs, by default ``False``. :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional :rtype: None .. rubric:: Notes The method runs :meth:`~.load.images.MapImages._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. .. py:method:: add_parent_polygons(verbose = False, tqdm_kwargs = None) Add polygon to all parents in parents dictionary. :param verbose: Whether to print verbose outputs. By default, ``False`` :type verbose: bool, optional :param tqdm_kwargs: Additional keyword arguments to pass to the ``tqdm`` progress bar. By default, ``None``. :type tqdm_kwargs: dict, optional .. py:method:: 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. :param method: Method used to patchify images, choices between ``"pixel"`` (default) and ``"meters"`` or ``"meter"``. :type method: str, optional :param patch_size: Number of pixels/meters in both x and y to use for slicing, by default ``100``. :type patch_size: int, optional :param tree_level: Tree level, choices between ``"parent"`` or ``"patch``, by default ``"parent"``. :type tree_level: str, optional :param path_save: Directory to save the patches. If None, will be set as f"patches_{patch_size}_{method}" (e.g. "patches_100_pixel"). By default None. :type path_save: str, optional :param skip_blank_patches: If True, any patch that only contains 0 values will be skipped, by default ``False``. Uses PIL.Image().get_bbox(). :type skip_blank_patches: bool :param add_to_parents: If True, patches will be added to the MapImages instance's ``images`` dictionary, by default ``True``. :type add_to_parents: bool, optional :param square_cuts: If True, all patches will have the same number of pixels in x and y, by default ``False``. :type square_cuts: bool, optional :param resize_factor: If True, resize the images before patchifying, by default ``False``. :type resize_factor: bool, optional :param output_format: Format to use when writing image files, by default ``"png"``. :type output_format: str, optional :param rewrite: If True, existing patches will be rewritten, by default ``False``. :type rewrite: bool, optional :param verbose: If True, progress updates will be printed throughout, by default ``False``. :type verbose: bool, optional :param overlap: Fractional overlap between patches, by default ``0``. :type overlap: int, optional :rtype: None .. py:method:: 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. :param parent_id: The ID of the parent image to calculate pixel stats for. If ``None``, calculate pixel stats for all parent images. By default, None :type parent_id: str or None, optional :param calc_mean: Whether to calculate mean pixel values. By default, ``True``. :type calc_mean: bool, optional :param calc_std: Whether to calculate standard deviation of pixel values. By default, ``True``. :type calc_std: bool, optional :param verbose: Whether to print verbose outputs. By default, ``False``. :type verbose: bool, optional :rtype: None .. rubric:: 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. .. py:method:: convert_images(save = False, save_format = 'csv', delimiter = ',') Convert the :class:`~.load.images.MapImages` instance's ``images`` dictionary into pandas DataFrames (or geopandas GeoDataFrames if geo-referenced) for easy manipulation. :param save: Whether to save the dataframes as files. By default ``False``. :type save: bool, optional :param save_format: 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". :type save_format: str, optional :param delimiter: The delimiter to use when saving the dataframe. By default ``","``. :type delimiter: str, optional :returns: The method returns a tuple of two DataFrames/GeoDataFrames: One for the ``parent`` images and one for the ``patch`` images. :rtype: tuple of two pandas DataFrames or geopandas GeoDataFrames .. py:method:: 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. :param parent_id: The ID of the parent image to explore. :type parent_id: str :param column_to_plot: The column values to plot on patches. If None, plot just the patch bounding boxes. By default None. :type column_to_plot: str | None, optional :param xyz_url: The XYZ URL of the tilelayer to use as a baselayer for the map. If None, will default to OpenStreetMap.Mapnik. By default None. :type xyz_url: str | None, optional :param categorical: Whether the column to plot is categorical or not. By default False. :type categorical: bool, optional :param cmap: The colormap to use when plotting column values. By default "viridis". :type cmap: str, optional :param vmin: The minimum value of the colormap. If `None`, will use the minimum value in the data. By default `None`. :type vmin: float | None, optional :param vmax: The maximum value of the colormap. If `None`, will use the minimum value in the data. By default `None`. :type vmax: float | None, optional :param style_kwargs: A dictionary of style keyword arguments to pass to the folium style_function. By default None. :type style_kwargs: dict | None, optional :returns: The folium map object with the patches plotted. :rtype: folium.Map .. py:method:: 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. :param parent_id: The ID of the parent image to plot. :type parent_id: str :param column_to_plot: The column values to plot on patches. If None, plot just the patch bounding boxes. :type column_to_plot: str | None, optional :param figsize: The size of the figure to be plotted. By default, (10,10). :type figsize: tuple, optional :param alpha: Transparency level for plotting patches, by default 0.5. :type alpha: float, optional :param categorical: Whether the column to plot is categorical or not. By default False. :type categorical: bool, optional :param cmap: The colormap to use when plotting column values. By default "viridis". :type cmap: str, optional :param vmin: The minimum value of the colormap. If `None`, will use the minimum value in the data. By default `None`. :type vmin: float | None, optional :param vmax: The maximum value of the colormap. If `None`, will use the minimum value in the data. By default `None`. :type vmax: float | None, optional :param style_kwargs: A dictionary of style keyword arguments to pass to matplotlib.pyplot.plot. By default None. :type style_kwargs: dict | None, optional :returns: The matplotlib axes object with the patches plotted. :rtype: matplotlib.axes.Axes .. rubric:: Notes Users with georeferenced images may wish to use the `explore_patches` method instead. .. py:method:: 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 :class:`~.load.images.MapImages` instance. :param patch_paths: The file path of the patches to be loaded. *Note: The ``patch_paths`` parameter accepts wildcards.* :type patch_paths: str :param parent_paths: 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.* :type parent_paths: str or bool, optional :param patch_file_ext: 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``. :type patch_file_ext: str or bool, optional :param parent_file_ext: 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``. :type parent_file_ext: str or bool, optional :param add_geo_info: If ``True``, adds geographic information to the parent image. Default is ``False``. :type add_geo_info: bool, optional :param clear_images: If ``True``, clears the images from the ``images`` dictionary before loading. Default is ``False``. :type clear_images: bool, optional :rtype: None .. py:method:: detect_parent_id_from_path(image_id, parent_delimiter = '#') :staticmethod: Detect parent IDs from ``image_id``. :param image_id: ID of patch. :type image_id: int or str :param parent_delimiter: Delimiter used to separate parent ID when naming patch, by default ``"#"``. :type parent_delimiter: str, optional :returns: Parent ID. :rtype: str .. py:method:: detect_pixel_bounds_from_path(image_id) :staticmethod: Detects borders from the path assuming patch is named using the following format: ``...-min_x-min_y-max_x-max_y-...`` :param image_id: ID of image :type image_id: int or str :param ..: border_delimiter : str, 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 :rtype: tuple of min_x, min_y, max_x, max_y .. py:method:: 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. :param parent_paths: Path to parent images, by default ``False``. :type parent_paths: str or bool, optional :param parent_ids: ID(s) of parent images. Ignored if ``parent_paths`` are specified. By default ``False``. :type parent_ids: list, str or bool, optional :param parent_file_ext: 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``. :type parent_file_ext: str or bool, optional :param overwrite: If ``True``, current parents will be overwritten, by default ``False``. :type overwrite: bool, optional :param add_geo_info: If ``True``, geographical info will be added to parents, by default ``False``. :type add_geo_info: bool, optional :rtype: None .. py:method:: load_df(parent_df = None, patch_df = None, clear_images = True) Create :class:`~.load.images.MapImages` instance by loading data from pandas DataFrame(s). :param parent_df: DataFrame containing parents or path to parents, by default ``None``. :type parent_df: pandas.DataFrame or gpd.GeoDataFrame or None, optional :param patch_df: DataFrame containing patches, by default ``None``. :type patch_df: pandas.DataFrame or gpd.GeoDataFrame or None, optional :param clear_images: If ``True``, clear images before reading the dataframes, by default ``True``. :type clear_images: bool, optional :rtype: None .. py:method:: 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 :class:`~.load.images.MapImages` instance with the loaded data. :param parent_path: Path to the CSV file containing parent image information. By default, ``None``. :type parent_path: str or pathlib.Path or None :param patch_path: Path to the CSV file containing patch information. By default, ``None``. :type patch_path: str or pathlib.Path or None :param clear_images: If True, clear all previously loaded image information before loading new information. Default is ``False``. :type clear_images: bool, optional :param index_col_patch: Column to set as index for the patch DataFrame, by default ``0``. :type index_col_patch: int or str or None, optional :param index_col_parent: Column to set as index for the parent DataFrame, by default ``0``. :type index_col_parent: int or str or None, optional :param delimiter: The delimiter to use when reading the dataframe. By default ``","``. :type delimiter: str, optional :rtype: None .. py:method:: add_geo_info(target_crs = 'EPSG:4326', verbose = True) Add coordinates (reprojected to EPSG:4326) to all parents images using image metadata. :param target_crs: Projection to convert coordinates into, by default ``"EPSG:4326"``. :type target_crs: str, optional :param verbose: Whether to print verbose output, by default ``True`` :type verbose: bool, optional :rtype: None .. rubric:: 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. .. py:method:: save_parents_as_geotiffs(rewrite = False, verbose = False, crs = None) Save all parents in :class:`~.load.images.MapImages` instance as geotiffs. :param rewrite: Whether to rewrite files if they already exist, by default False :type rewrite: bool, optional :param verbose: Whether to print verbose outputs, by default False :type verbose: bool, optional :param crs: 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. :type crs: str, optional .. py:method:: save_patches_as_geotiffs(rewrite = False, verbose = False, crs = None) Save all patches in :class:`~.load.images.MapImages` instance as geotiffs. :param rewrite: Whether to rewrite files if they already exist, by default False :type rewrite: bool, optional :param verbose: Whether to print verbose outputs, by default False :type verbose: bool, optional :param crs: 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. :type crs: str, optional .. py:method:: save_patches_to_geojson(geojson_fname = 'patches.geojson', rewrite = False, crs = None) Saves patches to a geojson file. :param geojson_fname: The name of the geojson file, by default "patches.geojson" :type geojson_fname: Optional[str], optional :param rewrite: Whether to overwrite an existing file, by default False. :type rewrite: Optional[bool], optional :param crs: 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 :type crs: Optional[str], optional