RSGISLib Mapping Tools

Map Vector Layers

rsgislib.tools.mapping.create_vec_lyr_map(ax: axis, gp_vecs: GeoDataFrame | List[GeoDataFrame], bbox: List[float], title_str: str = None, vec_fill_clrs: str | List[str] = 'grey', vec_line_clrs: str | List[str] = 'black', vec_line_widths: float | List[float] = 0.25, vec_fill_alphas: float | List[float] = 1.0, vec_markersize: str | float = None, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, sub_in_vec: bool = False, scale_bar_loc: str = 'upper right', plot_zorders: float | List[float] = 1)

A function which adds vector layer(s) to a matplotlib axis. This function takes either a single or list of geopandas dataframes to be displayed on the axis.

Note. if only the vector outlines are required (i.e., no colour fill of the polygons) then use the boundary i.e., gp_df_lyr.boundary

Parameters:

ax – The matplotlib axis to which to add the vector layer.
gp_vecs – either a geopandas dataframe or list of geopandas dataframes. Note. all the dataframes must be the same projection.
bbox – a bbox (MinX, MaxX, MinY, MaxY) for the region to be displayed
title_str – an optional title for the map (Default: None)
vec_fill_clrs – either a single string or list of strings with the colours for filling the vectors. (Default: grey)
vec_line_clrs – either a single string or list of strings with the colours for the vector lines. (Default: black)
vec_line_widths – either a single float or list of floats for the line width to be used for the vector layer(s). (Default: 0.25)
vec_fill_alphas – either a single float or list of floats for the alpha value(s) for the vector layers. (Default: 1)
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
sub_in_vec – boolean specifying whether the vector layer should be spatially subset before displaying as for large vector layers this can make the processing much faster. Default: False
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right
plot_zorders – the drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. https://matplotlib.org/stable/gallery/misc/zorder_demo.html

Parma vec_markersize:

if the vector layer has point geometries then this variable allows the size of the points to be defined as either a constant (float) or using column from the vector layer (string).

rsgislib.tools.mapping.create_choropleth_vec_lyr_map(ax: axis, gp_vec: GeoDataFrame, vec_col: str, bbox: List[float], title_str: str = None, vec_fill_cmap: Colormap = None, vec_var_norm: Normalize = None, vec_line_clr: str = 'black', vec_line_width: float = 0.25, vec_fill_alpha: float = 1.0, vec_markersize: str | float = None, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, sub_in_vec: bool = False, scale_bar_loc: str = 'upper right', plot_zorder: float = 1)

A function which adds a vector layer to a matplotlib axis. This function takes a single geopandas dataframe to be displayed on the axis.

Note. this function uses a variable from the attribute table to colour the features creating a choropleth map.

Parameters:

ax – The matplotlib axis to which to add the vector layer.
gp_vec – geopandas dataframe to be displayed
vec_col – the column within the dataframe to be displayed.
bbox – a bbox (MinX, MaxX, MinY, MaxY) for the region to be displayed
title_str – an optional title for the map (Default: None)
vec_fill_cmap – a matplotlib colour map used to visualise the choropleth map. If None (Default) then the viridis colour map will be used.
vec_var_norm – a matplotlib normalisation used to visualise the choropleth map. If None (Default) then no normalisation will be applied.
vec_line_clrs – either a single string or list of strings with the colours for the vector lines. (Default: black)
vec_line_widths – either a single float or list of floats for the line width to be used for the vector layer(s). (Default: 0.25)
vec_fill_alphas – either a single float or list of floats for the alpha value(s) for the vector layers. (Default: 1)
vec_markersize – if the vector layer has point geometries then this variable allows the size of the points to be defined as either a constant (float) or using column from the vector layer (string).
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
sub_in_vec – boolean specifying whether the vector layer should be spatially subset before displaying as for large vector layers this can make the processing much faster. Default: False
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right
plot_zorder – the drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. https://matplotlib.org/stable/gallery/misc/zorder_demo.html

rsgislib.tools.mapping.create_vec_pt_density_map(ax: axis, gp_vec: GeoDataFrame, bbox: List[float], title_str: str = None, cmap_name: str = 'viridis', use_log_norm: bool = False, density_norm_vmin: float = 1, density_norm_vmax: float = None, density_dpi: int = 72, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, sub_in_vec: bool = False, scale_bar_loc: str = 'upper right', plot_zorder: float = 1)

A function which adds a vector layer(s) to a matplotlib axis as a density plot. Therefore, the vector layer needs to a points layer.

Note. there are geopandas functions to calculate centroids or representative points if your dataset is not a points file.

Colour bar information is returned. Note to add the colour bar to your plot you’ll want to use code such as:

c_cmap, c_norm = mapping.create_vec_pt_density_map(…) fig.colorbar(matplotlib.cm.ScalarMappable(norm=c_norm, cmap=c_cmap),

label=’Some Data’, ax=ax1)

Parameters:

ax – The matplotlib axis to which to add the vector layer. Note, the axis must be created with the option projection=’scatter_density’ which requires the mpl_scatter_density module to be available.
gp_vec – a geopandas dataframe with the data - must be a points geometry type.
bbox – a bbox (MinX, MaxX, MinY, MaxY) for the region to be displayed
title_str – an optional title for the map (Default: None)
cmap_name – either a single string or list of strings with the colours for filling the vectors. (Default: grey)
norm_img_vals – Boolean specifying whether the colour bar values should be normalised. Default: False
use_log_norm – Specify whether to use log normalisation for the plot instead of linear. (Default: False)
density_norm_vmin – the minimum value for the normalisation (default: 1).
density_norm_vmax – the maximum value for the normalisation (default: None). If None then the maximum value will be automatically defined.
density_dpi – the dots per inch used for displaying the density plot. The lower the value the large the bins (pixels) used for defining the density plot.
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
sub_in_vec – boolean specifying whether the vector layer should be spatially subset before displaying as for large vector layers this can make the processing much faster. Default: False
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right
plot_zorder – the drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. https://matplotlib.org/stable/gallery/misc/zorder_demo.html

Returns:

The colour map and normalisation so a colour bar can be created. (c_cmap, c_norm)

Map Raster Layers

rsgislib.tools.mapping.create_raster_img_map(ax: axis, input_img: str, img_bands: List[int], img_stch: int, bbox: List[float] = None, title_str: str = None, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, img_no_data_val: float = None, stch_min_max_vals: Dict | List[Dict] = None, stch_n_stdevs: float = 2.0, scale_bar_loc: str = 'upper right', plot_zorder: float = 1)

A function which displays a stretched raster layer onto the axis provided.

Parameters:

ax – The matplotlib axis to which to add the image to.
input_img – the file path for the input image
img_bands – a list of bands (either 1 or 3) to be used for display. Note, band numbering starts at 1.
img_stch – the stretch used for the input image. Options are: rsgislib.IMG_STRETCH_XXXX
bbox – An optional bbox (MinX, MaxX, MinY, MaxY) specifying the spatial region to be displayed. If None then the whole image bbox will be used.
title_str – an optional title for the map (Default: None)
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
img_no_data_val – a float with the no data value for the input image. if None then the no data value will be read from the input image.
stch_min_max_vals – If using the rsgislib.IMG_STRETCH_USER stretch then these are the user specified min and max values for the stretch. See rsgislib.tools.plotting.manual_stretch_np_arr
stch_n_stdevs – If using the rsgislib.IMG_STRETCH_STDEV stretch then this is the number of standard deviations parameters. See rsgislib.tools.plotting.stdev_stretch_np_arr
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right
plot_zorder – the drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. https://matplotlib.org/stable/gallery/misc/zorder_demo.html

rsgislib.tools.mapping.create_raster_cmap_img_map(ax: axis, input_img: str, img_band: int, bbox: List[float] = None, title_str: str = None, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, cmap_name: str = 'viridis', norm_img_vals: bool = False, use_log_norm: bool = False, norm_vmin: float = None, norm_vmax: float = None, vals_under_white: bool = False, print_norm_vals: bool = False, scale_bar_loc: str = 'upper right', plot_zorder: float = 1)

A function which displays a single band raster layer onto the axis provided using a colour bar.

Colour bar information is returned. Note to add the colour bar to your plot you’ll want to use code such as:

c_cmap, c_norm = mapping.create_raster_cmap_img_map(…) fig.colorbar(matplotlib.cm.ScalarMappable(norm=c_norm, cmap=c_cmap),

label=’Some Data’, ax=ax1)

Parameters:

ax – The matplotlib axis to which to add the image to.
input_img – the file path for the input image
img_band – the image band within the file to be displayed. Note, band numbering starts at 1.
bbox – An optional bbox (MinX, MaxX, MinY, MaxY) specifying the spatial region to be displayed. If None then the whole image bbox will be used.
title_str – an optional title for the map (Default: None)
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
cmap_name – The name of the colour bar to use for the density plot Default: viridis
norm_img_vals – Boolean specifying whether the colour bar values should be normalised. Default: False
use_log_norm – Specify whether to use log normalisation for the plot instead of linear. (Default: False)
norm_vmin – the minimum value for the normalisation (default: None). If None then the minimum value will be calculated from the data.
norm_vmax – the maximum value for the normalisation (default: None). If None then the maximum value will be calculated from the data.
vals_under_white – Set pixels with values less than norm_vmin to white (i.e., mask / ignore). Can be useful if visualising counts or density estimates.
print_norm_vals – boolean specifying to print the normalisation min / max values. This is useful for debugging and finding a range of values before manually setting across a set of images.
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right
plot_zorder – the drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. https://matplotlib.org/stable/gallery/misc/zorder_demo.html

Returns:

The colour map and normalisation so a colour bar can be created. (c_cmap, c_norm)

rsgislib.tools.mapping.create_thematic_raster_map(ax: axis, input_img: str | List, bbox: List[float] = None, title_str: str = None, alpha_backgd: bool = True, img_alpha: float = 1.0, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, scale_bar_loc: str = 'upper right', plot_zorders: float | List[float] = 1)

A function which displays a thematic raster layer onto the axis provided where the colours are read from the colour table of the input image.

Parameters:

ax – The matplotlib axis to which to add the image to.
input_img – the file path for the input image
bbox – An optional bbox (MinX, MaxX, MinY, MaxY) specifying the spatial region to be displayed. If None then the whole image bbox will be used.
title_str – an optional title for the map (Default: None)
alpha_backgd – boolean specifying that the background (i.e., 0) value will be transparent and not shown.
img_alpha – a float specifying the alpha transparency value for all the image layers provided. Default: 1.0 (i.e., not transparent)
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right
plot_zorders – the drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. https://matplotlib.org/stable/gallery/misc/zorder_demo.html

rsgislib.tools.mapping.create_wmts_img_map(ax: axis, wmts_url: str, wmts_lyr: str, bbox: List[float], bbox_epsg: int, wmts_zoom_level: int = None, title_str: str = None, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, tmp_dir: str = None, wmts_epsg: int = None, scale_bar_loc: str = 'upper right')

A function which downloading image from a WMTS service and adding it

Parameters:

ax – The matplotlib axis to which to add the WMTS image to.
wmts_url – The url for the WMTS service
wmts_lyr – the layer within the WMTS to use.
bbox – The bbox (MinX, MaxX, MinY, MaxY) specifying the spatial region to be displayed.
bbox_epsg – the EPSG code of the inputted bbox, with will be the epsg for the outputted map.
wmts_zoom_level – Optionally, the zoom level from the WMTS. If None then automatically defined.
title_str – an optional title for the map (Default: None)
show_scale_bar – boolean specifying whether a scale bar should be added to the axis. Default: False
use_grid – boolean specifying whether a grid should be added to the axis. Default: False
show_map_axis – boolean specifying whether the axes should be shown Default: False
tmp_dir – Optionally, a temporary directory for some intermediate files. If not specified, a tmp dir is created and removed in the local path from where the script is run from.
wmts_epsg – Provide the epsg code for the WMTS layer (probably 3857) if the code can’t automatically find it.
scale_bar_loc – the location on the plot of the scale bar. Options defined by the matplotlib-scalebar module. But must be one of: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center. Default: upper right

Background Layers

rsgislib.tools.mapping.add_contextily_basemap(ax: axis, epsg_crs: int, cx_src, cx_zoom_lvl: int | str = 'auto', cx_attribution: str | bool = None, cx_att_size: int = 8)

A function which adds a contextily (https://contextily.readthedocs.io) basemap (e.g., open street map) to an matplotlib axis. This function is generally used to add a base map underneath other layers (e.g., after using one of the other mapping functions such as create_vec_lyr_map).

Note. this function must be called after you have added the other layers to the axis as those will define the spatial extent of the axis.

Parameters:

ax – The matplotlib axis to which to add the base map.
epsg_crs – An epsg code for the projection being used for the map. The contextily basemap will be warped to this projection.
cx_src – the contextily basemap (e.g., contextily.providers.OpenTopoMap)
cx_zoom_lvl – the zoom level of the basemap to be used. Default: auto
cx_attribution – The attribution of the map, if None then the default attribution will be used. If a string is provided then this will be used. If False is used then no attribution will be outputted. Default: None
cx_att_size – the font size of the attribution. Default: 8

Overview Maps

rsgislib.tools.mapping.get_overview_info(roi_bbox: List[float], roi_epsg: int = 4236, overview_buf: int = 30, out_epsg: int = 4236)

A function which uses the BBOX for the extent of the map being drawn to create the a BBOX for and centre point which can be used within the add_overview_maps function to add an overview map to an axis.

Parameters:

roi_bbox – the region of interest (ROI) bbox (MinX, MaxX, MinY, MaxY) representing the area for the which the map is being drawn for.
roi_epsg – the project (as an EPSG code) for the coordinates provided in the roi_bbox.
overview_buf – the buffer used to specify the overview area. This is taken from the centre point of the roi_bbox.

Returns:

the overview bbox (MinX, MaxX, MinY, MaxY) and point (X, Y)

rsgislib.tools.mapping.add_overview_maps(ax: axis, overview_lyr: GeoDataFrame, overview_bbox: List[float], overview_pt: List[float] = None, over_size_x: float = 0.1, over_size_y: float = 0.1, over_x_off: float = 0.0, over_y_off: float = 0.0, pt_clr='red', pt_size=10, fill_clr='white', line_clr='black', line_width=0.25) → axis

Add an overview map in the top-left corner of the map.

Parameters:

ax – The matplotlib axis to which to add the overview map.
overview_lyr – The geopandas layer to used used for the overview map usually this would be a global vector layer of the countries but could be anything.
overview_bbox – the bbox (MinX, MaxX, MinY, MaxY) for the area to be shown within the overview map.
overview_pt – an optional point (X, Y) to displayed on the overview map.
over_size_x – the size of the overview map in the x-axis
over_size_y – the size of the overview map in the y-axis
over_x_off – the x-axis offset for the overmap position
over_y_off – the y-axis offset for the overmap position
pt_clr – the colour of the point (if specified). Default: Red.
pt_size – the size of the point (if specified). Default: 10.
fill_clr – the colour used to fill the polygons within the overview layer. Default: white
line_clr – the colour of the lines of the overview layer. Default: black
line_width – the line width of the lines of the overview layer. Default: 0.25

Returns:

return the matplotlib axis for the overview map.

Add Extras to Map

rsgislib.tools.mapping.draw_bboxes_to_axis(ax: axis, bboxes: List[List[float]], bbox_labels: List[str] = None, rect_clr: str = 'black', line_width: float = 1, fill_rect: bool = False, clr_alpha: float = 1.0, lbl_font_size=12, lbl_font_weight='normal', lbl_font_clr='black', lbl_pos: str = 'centre', lbl_pos_buf: float = 0.0, lbl_fill_clr: str = None, lbl_padding: float = 3.0)

This function can be used to draw a set of rectangles to an axis, where typically the bboxes specify subset regions or areas of interest you are trying to highlight to the person viewing the map.

Parameters:

ax – The matplotlib axis to which the bboxes will be drawn
bboxes – a list of bboxes (MinX, MaxX, MinY, MaxY) to be drawn on the axis.
bbox_labels – An optional list of labels for the bboxes
rect_clr – the colour for the bbox regions.
line_width – the width of the lines for the bboxes
fill_rect – boolean specifying whether to fill the bbox regions (Default: False)
clr_alpha – the alpha value for the bbox regions (Default: 1.0)
lbl_font_size – the font size (Default: 12).
lbl_font_weight – the weight of the font (i.e., normal or bold)
lbl_font_clr – the colour of the text (Default: black)
lbl_pos – Options: [None, above, below, left, right]. Default: None (centre)

rsgislib.tools.mapping.add_axis_label(ax: axis, lbl_text: str, lbl_font_clr: str = 'black', lbl_font_weight: str = 'normal', lbl_font_size: int = 12, fill_clr: str = 'white', padding: float = 3.0)

This function adds a label in the top-left corner of the axis. This function would typically be used if you want to label a number of axes (e.g., a, b, c, etc.)

Parameters:

ax – The matplotlib axis to which the label will be added.
lbl_text – the label text to be written.
lbl_font_clr – the colour of the text (Default: black)
lbl_font_weight – the weight of the font (i.e., normal or bold)
lbl_font_size – the font size (Default: 12).
fill_clr – the colour the label area will be filled with (Default: white)
padding – the amount of padding around the text (Default: 3.0)

Utilities

rsgislib.tools.mapping.calc_y_fig_size(bbox: List[float], fig_x_size=typing.Union[int, float]) → float

A function which calculates the y axis size give the bbox and x axis size and the BBOX for the area to be mapped. This is useful so the map fills the whole area rather than having lots of white space in the resulting figure image file.

Parameters:

bbox – the (MinX, MaxX, MinY, MaxY) for the region of interest.
fig_x_size – the size for the figure in the x axis.

Returns:

the figure size in the y axis.

rsgislib.tools.mapping.define_axis_extent(ax: axis, bbox: List[float])

A function which defines the limits of the axis using the same bbox as the other mapping functions.

Note. this function was written and is probably mainly used for defining the axis limits when experimenting with the size/shape of the axis when laying out multiple axes. However, it could be used to change the axis limits from what the other functions have defined.

Parameters:

ax – The matplotlib axis for the limits to be set.
bbox – a bbox (MinX, MaxX, MinY, MaxY) to define the region of interest.

rsgislib.tools.mapping.define_map_tick_spacing(ax: axis, tick_spacing: float)

A function which defines the tick spacing on both axis of the map.

If projection is WGS84 (EPSG:4326) then a tick spacing of 0.1 would provide ticks every 0.1 degrees while if using UTM then a tick spacing of 1000 will give a tick every 1km.

Parameters:

ax – The matplotlib axis for the tick spacing to be defined.
tick_spacing – the spacing between the ticks.