RSGISLib Visualisation Tools

rsgislib.tools.visualisation.create_kmz_img(input_img: str, output_file: str, bands: str, reproj_wgs84: bool = True, finite_msk: bool = False, tmp_dir: str = None)

A function to convert an input image to a KML/KMZ file, where the input image is stretched and bands sub-selected / ordered as required for visualisation.

Parameters:

  • input_img – input image file (any format that gdal supports)

  • output_file – output image file (extension kmz for KMZ output / kml for KML output)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • reproj_wgs84 – specify whether the image should be explicitly reprojected to WGS84 Lat/Long before transformation to KML.

  • finite_msk – specify whether the image data should be masked so all values are finite before stretching.

  • tmp_dir – A temp directory path for processing files.

rsgislib.tools.visualisation.create_webtiles_img_no_stats_msk(input_img: str, out_dir: str, bands: str, zoom_levels: str = '2-10', resample='average', finite_msk: bool = False, tms: bool = True, tmp_dir=None)

A function to convert an input image to a tile cache for web map servers, where the input image is stretched and bands sub-selected / ordered as required for visualisation.

Parameters:

  • input_img – input image file (any format that gdal supports)

  • out_dir – output directory within which the cache will be created.

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • zoom_levels – The zoom levels to be created for the web tile cache.

  • resample – Method of resampling (average,near,bilinear,cubic,cubicspline,lanczos,antialias)

  • finite_msk – specify whether the image data should be masked so all values are finite before stretching.

  • tms – if TMS is True then a tile grid in TMS format is returned with the grid origin at the bottom-left. If False then an XYZ tile grid format is used with the origin in the top-left. (TMS: gdal2tiles.py native. XYZ: GIS Compatible)

  • tmp_dir – A temp directory path for processing files.

rsgislib.tools.visualisation.create_webtiles_img(input_img: str, bands: str, out_dir: str, zoom_levels: str = '2-10', img_stats_msk: str = None, img_msk_vals: int = 1, tmp_dir: str = None, webview: bool = True, tms: bool = True, no_data_val: float = None)

A function to produce a web cache for the input image.

Parameters:

  • input_img – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • out_dir – output directory within which the cache will be created.

  • zoom_levels – The zoom levels to be created for the web tile cache.

  • img_stats_msk – Optional (default=None) input image which is used to define regions calculate the image stats for stretch.

  • img_msk_vals – The pixel(s) value define the region of interest in the image mask (can be list of values or single value).

  • tmp_dir – an input directory which can be used to write temporary files / directories. If not provided (i.e., input is None) then a local directory will be define in the same folder as the input image.

  • webview – Provide default GDAL leaflet web viewer.

  • tms – if TMS is True then a tile grid in TMS format is returned with the grid origin at the bottom-left. If False then an XYZ tile grid format is used with the origin in the top-left. (TMS: gdal2tiles.py native. XYZ: GIS Compatible)

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.create_quicklook_imgs(input_img: str, bands: str, output_imgs: str | List[str] = 'quicklook.jpg', output_img_sizes: int | List[int] = 250, scale_axis: str = 'auto', img_stats_msk: str = None, img_msk_vals: int = 1, stretch_file: str = None, tmp_dir: str = None, no_data_val: float = None)

A function to produce a quicklook image(s).

Parameters:

  • input_img – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • output_imgs – a single output image or list of output images. The same size as output_img_sizes.

  • output_img_sizes – the output image size (in pixels) or list of output image sizes.

  • scale_axis – the axis to which the output_img_sizes refer. Options: width, height or auto. Auto applies the output_img_sizes to the longest of the two axes.

  • img_stats_msk – Optional (default=None) input image which is used to define regions calculate the image stats for stretch.

  • img_msk_vals – The pixel(s) value define the region of interest in the image mask (can be list of values or single value).

  • stretch_file – a stretch stats file to standardise the stretch between a number of input files.

  • tmp_dir – an input directory which can be used to write temporary files / directories. If not provided (i.e., input is None) then a local directory will be define in the same folder as the input image.

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.create_mbtile_file(input_img: str, bands: str, output_mbtiles: str, scale_input_img: int = 50, img_stats_msk: str = None, img_msk_vals: int = 1, tmp_dir: str = None, tile_format: str = 'PNG', no_data_val: float = None)

A function to produce an MBTile file for visualisation.

Parameters:

  • input_img – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • output_mbtiles – output MBTiles file which will be created.

  • scale_input_img – The scale of the output image with respect to the input as a percentage (e.g., 50% reduction in size).

  • img_stats_msk – Optional (default=None) input image which is used to define regions calculate the image stats for stretch.

  • img_msk_vals – The pixel(s) value define the region of interest in the image mask (can be list of values or single value).

  • tmp_dir – an input directory which can be used to write temporary files / directories. If not provided (i.e., input is None) then a local directory will be define in the same folder as the input image.

  • tile_format – Specify the tile file format to use, options: PNG, PNG8 and JPG. Default: PNG

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.create_webtiles_vis_gtiff_img(input_img: str, bands: str, output_dir: str, scaled_gtiff_img: str, zoom_levels: str = '2-10', img_stats_msk: str = None, img_msk_vals: int = 1, stretch_file: str = None, tmp_dir: str = None, webview: bool = True, scale: float = 0, tms: bool = True, no_data_val: float = None)

A function to produce web cache and scaled and stretched geotiff.

Parameters:

  • input_img – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • output_dir – output directory within which the cache will be created.

  • scaled_gtiff_img – output geotiff image path and file name.

  • zoom_levels – The zoom levels to be created for the web tile cache.

  • img_stats_msk – Optional (default=None) input image which is used to define regions calculate the image stats for stretch.

  • img_msk_vals – The pixel(s) value define the region of interest in the image mask (can be list of values or single value).

  • stretch_file – a stretch stats file to standardise the stretch between a number of input files.

  • tmp_dir – an input directory which can be used to write temporary files / directories. If not provided (i.e., input is None) then a local directory will be define in the same folder as the input image.

  • webview – Provide default GDAL leaflet web viewer.

  • scale – the scale output geotiff. Input is percentage in the x-axis. If zero (default) then no scaling will be applied.

  • tms – if TMS is True then a tile grid in TMS format is returned with the grid origin at the bottom-left. If False then an XYZ tile grid format is used with the origin in the top-left. (TMS: gdal2tiles.py native. XYZ: GIS Compatible)

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.create_quicklook_overview_imgs(input_imgs: List[str], bands: str, tmp_dir: str, output_imgs: str | List[str] = 'quicklook.jpg', output_img_sizes: int | List[int] = 250, scale_axis: str = 'auto', stretch_file: str = None, no_data_val: float = None)

A function to produce an overview quicklook for a number of input images.

Parameters:

  • input_imgs – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • tmp_dir – an input directory which can be used to write temporary files / directories.

  • output_imgs – a single output image or list of output images. The same size as output_img_sizes. The output format is JPEG.

  • output_img_sizes – the output image size (in pixels) or list of output image sizes.

  • scale_axis – the axis to which the output_img_sizes refer. Options: width, height or auto. Auto applies the output_img_sizes to the longest of the two axes.

  • stretch_file – a stretch stats file to standardise the stretch between a number of input files.

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.burn_in_binary_msk(base_image: str, mask_img: str, output_img: str, gdalformat: str, msk_colour=None)

A function which is used for visualisation applications where a rasterised binary mask is ‘burnt’ into a base image with a user selected colour.

Parameters:

  • base_image – the base image with continuous output values. It is expected that this image has 8uint pixel values.

  • mask_img – the binary mask (value 1 will be used) to be ‘burnt’ into the base_image.

  • output_img – the output image file name and path

  • gdalformat – the GDAL image file format of the output image file.

  • msk_colour – the colour of the pixels burnt in to the base image. Should have the same number of dimensions as the input base image has image bands. Default, if None is 255.

rsgislib.tools.visualisation.create_quicklook_overview_imgs_vec_overlay(input_imgs: List[str], bands: str, tmp_dir: str, vec_overlay_file: str, vec_overlay_lyr: str, output_imgs: str | List[str] = 'quicklook.jpg', output_img_sizes: int | List[int] = 250, gdalformat: str = 'JPEG', scale_axis: str = 'auto', stretch_file: str = None, overlay_clrs: List[int] = None, no_data_val: float = None)

A function to produce an overview quicklook with a vector overlain for a number of input images.

Parameters:

  • input_imgs – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • tmp_dir – an input directory which can be used to write temporary files / directories.

  • vec_overlay_file – an vector overlay which will be rasterised to the overlay on the output images.

  • vec_overlay_lyr – the layer name for the vector overlay.

  • output_imgs – a single output image or list of output images. The same size as output_img_sizes.

  • output_img_sizes – the output image size (in pixels) or list of output image sizes.

  • gdalformat – the output file format - probably either JPG, PNG or GTIFF.

  • scale_axis – the axis to which the output_img_sizes refer. Options: width, height or auto. Auto applies the output_img_sizes to the longest of the two axes.

  • stretch_file – a stretch stats file to standardise the stretch between a number of input files.

  • overlay_clrs – list of output pixel values defining colour for the overlay image (value between 0-255). The list should be the same length as the number of input image bands (i.e., specified by bands). If None then default all values are all 255.

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.create_visual_overview_imgs_vec_extent(input_imgs: List[str], bands: str, tmp_dir: str, vec_extent_file: str = None, vec_extent_lyr: str = None, output_imgs: str | List[str] = 'quicklook.tif', output_img_sizes: int | List[int] = 500, gdalformat: str = 'GTIFF', scale_axis: str = 'auto', stretch_file: str = None, export_stretch_file: bool = False, no_data_val: float = None)

A function to produce an 8bit overview image (i.e., stretched visualisation) with an optional specified extent.

Parameters:

  • input_imgs – input image file (any format that gdal supports)

  • bands – a string (comma seperated) with the bands to be selected. (e.g., ‘1’, ‘1,2,3’, ‘5,6,4’)

  • tmp_dir – an input directory which can be used to write temporary files / directories.

  • vec_extent_file – an vector file to define the extent of the output image files.

  • vec_extent_lyr – the layer name for the vector extent.

  • output_imgs – a single output image or list of output images. The same size as output_img_sizes.

  • output_img_sizes – the output image size (in pixels) or list of output image sizes.

  • gdalformat – the output file format - probably either JPG, PNG or GTIFF.

  • scale_axis – the axis to which the output_img_sizes refer. Options: width, height or auto. Auto applies the output_img_sizes to the longest of the two axes.

  • stretch_file – a stretch stats file to standardise the stretch between a number of input files. If export_stretch_file is True then this variable is used as the output stretch file path.

  • export_stretch_file – If true then the stretch parameters are outputted as a text file to the path defined by stretch_file.

  • no_data_val – Optionally provide an input image no data value otherwise it will be read from the input image header.

rsgislib.tools.visualisation.overlay_vec_on_img(input_img: str, output_img: str, vec_overlay_file: str, vec_overlay_lyr: str, tmp_dir: str, gdalformat: str = 'PNG', overlay_clrs: List[int] = None)

A function to overlay a vector layer on to a raster image ‘burning’ in the vector as a particular colour. This is most appropriate for polyline vectors, polygons will be filled.

Parameters:

  • input_img – The input image, usually a stretched byte (8uint) image ready for visualisation but needs spatial header information associated.

  • output_img – A output image file commonly in none specialist format such as JPEG, PNG or TIFF.

  • vec_overlay_file – The vector file to overlay (recommended to be a polyline vector)

  • vec_overlay_lyr – The name of the vector layer

  • tmp_dir – A temporary were processing stage file can be written during processing.

  • gdalformat – The output format - commonly PNG, JPEG or GTIFF.

  • overlay_clrs – An array with the output pixel values for the vector overlay, needs the same length as the number of image bands. If None then the overlay will be white (i.e., [255, 255, 255].