RSGISLib Mapping Tools

Map Vector Layers

rsgislib.tools.mapping.create_vec_lyr_map(ax: matplotlib.pyplot.axis, gp_vecs: Union[geopandas.geodataframe.GeoDataFrame, List[geopandas.geodataframe.GeoDataFrame]], bbox: List[float], title_str: Optional[str] = None, vec_fill_clrs: Union[str, List[str]] = 'grey', vec_line_clrs: Union[str, List[str]] = 'black', vec_line_widths: Union[float, List[float]] = 0.25, vec_fill_alphas: Union[float, List[float]] = 1.0, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, sub_in_vec: bool = False)

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

rsgislib.tools.mapping.create_choropleth_vec_lyr_map(ax: matplotlib.pyplot.axis, gp_vec: geopandas.geodataframe.GeoDataFrame, vec_col: str, bbox: List[float], title_str: Optional[str] = None, vec_fill_cmap: Optional[matplotlib.colors.Colormap] = None, vec_var_norm: Optional[matplotlib.colors.Normalize] = None, vec_line_clr: str = 'black', vec_line_width: float = 0.25, vec_fill_alpha: float = 1.0, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, sub_in_vec: bool = False)

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)

  • 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

Map Raster Layers

rsgislib.tools.mapping.create_raster_img_map(ax: matplotlib.pyplot.axis, input_img: str, img_bands: List[int], img_stch: int, bbox: Optional[List[float]] = None, title_str: Optional[str] = None, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True, img_no_data_val: Optional[float] = None, stch_min_max_vals: Optional[Union[Dict, List[Dict]]] = None, stch_n_stdevs: float = 2.0)

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

rsgislib.tools.mapping.create_thematic_raster_map(ax: matplotlib.pyplot.axis, input_img: Union[str, List], bbox: Optional[List[float]] = None, title_str: Optional[str] = None, alpha_backgd: bool = True, show_scale_bar: bool = True, use_grid: bool = False, show_map_axis: bool = True)

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.

  • 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

Background Layers

rsgislib.tools.mapping.add_contextily_basemap(ax: matplotlib.pyplot.axis, epsg_crs: int, cx_src, cx_zoom_lvl: Union[int, str] = 'auto', cx_attribution: Optional[Union[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: matplotlib.pyplot.axis, overview_lyr: geopandas.geodataframe.GeoDataFrame, overview_bbox: List[float], overview_pt: Optional[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)

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

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.