RSGISLib Tools Module

The tools module contains some useful tools and utilities for remote sensing work.

Plotting

These functions make use of rsgislib functions and matplotlib to provide useful plotting functionality.

rsgislib.tools.plotImageSpectra(inputImage, roiFile, outputPlotFile, wavelengths, plotTitle, scaleFactor=0.1, showReflStd=True, reflMax=None)

A utility function to extract and plot image spectra. Where:

Parameters

  • inputImage – is the input image

  • roiFile – is the region of interest file as a shapefile - if multiple polygons are defined the spectra for each will be added to the plot.

  • outputPlotFile – is the output PDF file for the plot which has been create

  • wavelengths – is list of numbers with the wavelength of each band (must have the same number of wavelengths as image bands)

  • plotTitle – is a string with the title for the plot

  • scaleFactor – is a float specifying the scaling to percentage (0 - 100). (Default is 0.1, i.e., pixel values are scaled between 0-1000; ARCSI default).

  • showReflStd – is a boolean (default: True) to specify whether a shaded region showing 1 standard deviation from the mean on the plot alongside the mean spectra.

  • reflMax – is a parameter for setting the maximum reflectance value on the Y axis (if None the maximum value in the dataset is used

Example:

from rsgislib import tools

inputImage = 'injune_p142_casi_sub_utm.kea'
roiFile = 'spectraROI.shp'
outputPlotFile = 'SpectraPlot.pdf'
wavelengths = [446.0, 530.0, 549.0, 569.0, 598.0, 633.0, 680.0, 696.0, 714.0, 732.0, 741.0, 752.0, 800.0, 838.0]
plotTitle = "Image Spectral from CASI Image"

tools.plotting.plotImageSpectra(inputImage, roiFile, outputPlotFile, wavelengths, plotTitle)
rsgislib.tools.plotImageComparison(inputImage1, inputImage2, img1Band, img2Band, outputPlotFile, numBins=100, img1Min=None, img1Max=None, img2Min=None, img2Max=None, img1Scale=1, img2Scale=1, img1Off=0, img2Off=0, normOutput=False, plotTitle='2D Histogram', xLabel='X Axis', yLabel='Y Axis', ctable='jet', interp='nearest')

A function to plot two images against each other. Where:

Parameters

  • inputImage1 – is a string with the path to the first image.

  • inputImage2 – is a string with the path to the second image.

  • img1Band – is an int specifying the band in the first image to be plotted.

  • img2Band – is an int specifying the band in the second image to be plotted.

  • outputPlotFile – is a string specifying the output PDF for the plot.

  • numBins – is an int specifying the number of bins within each axis of the histogram (default: 100)

  • img1Min – is a double specifying the minimum value to be used in the histogram from image 1. If value is None then taken from the image.

  • img1Max – is a double specifying the maximum value to be used in the histogram from image 1. If value is None then taken from the image.

  • img2Min – is a double specifying the minimum value to be used in the histogram from image 2. If value is None then taken from the image.

  • img2Max – is a double specifying the maximum value to be used in the histogram from image 2. If value is None then taken from the image.

  • img1Scale – is a double specifying the scale for image 1 (Default 1).

  • img2Scale – is a double specifying the scale for image 2 (Default 1).

  • img1Off – is a double specifying the offset for image 1 (Default 0).

  • img2Off – is a double specifying the offset for image 2 (Default 0).

  • normOutput – is a boolean specifying whether the histogram should be normalised (Default: False).

  • plotTitle – is a string specifying the title of the plot (Default: ‘2D Histogram’).

  • xLabel – is a string specifying the x axis label (Default: ‘X Axis’)

  • yLabel – is a string specifying the y axis label (Default: ‘Y Axis’)

  • ctable – is a string specifying the colour table to be used (Default: jet), list of available colour tables specified by matplotlib: http://matplotlib.org/examples/color/colormaps_reference.html

  • interp – is a string specifying the interpolation algorithm to be used (Default: ‘nearest’). Available values are ‘none’, ‘nearest’, ‘bilinear’, ‘bicubic’, ‘spline16’, ‘spline36’, ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘catrom’, ‘gaussian’, ‘bessel’, ‘mitchell’, ‘sinc’, ‘lanczos’.

Example:

from rsgislib.tools import plotting

inputImage1 = 'LS5TM_20000613_lat10lon6217_r67p231_rad_sref_ndvi.kea'
inputImage2 = 'LS5TM_20000613_lat10lon6217_r67p231_rad_ndvi.kea'
outputPlotFile = 'ARCSI_RAD_SREF_NDVI.pdf'

plotting.plotImageComparison(inputImage1, inputImage2, 1, 1, outputPlotFile, img1Min=-0.5, img1Max=1, img2Min=-0.5, img2Max=1, plotTitle='ARCSI SREF NDVI vs ARCSI RAD NDVI', xLabel='ARCSI SREF NDVI', yLabel='ARCSI RAD NDVI')
rsgislib.tools.plotImageHistogram(inputImage, imgBand, outputPlotFile, numBins=100, imgMin=None, imgMax=None, normOutput=False, plotTitle='Histogram', xLabel='X Axis', colour='blue', edgecolour='black', linewidth=None)

A function to plot the histogram of an image.

Where:

Parameters

  • inputImage – is a string with the path to the image.

  • imgBand – is an int specifying the band in the image to be plotted.

  • outputPlotFile – is a string specifying the output PDF for the plot.

  • numBins – is an int specifying the number of bins within each axis of the histogram (default: 100)

  • imgMin – is a double specifying the minimum value to be used in the histogram from the image. If value is None then taken from the image.

  • imgMax – is a double specifying the maximum value to be used in the histogram from the image. If value is None then taken from the image.

  • normOutput – is a boolean specifying whether the histogram should be normalised (Default: False).

  • plotTitle – is a string specifying the title of the plot (Default: ‘2D Histogram’).

  • xLabel – is a string specifying the x axis label (Default: ‘X Axis’)

  • colour – is the colour of the bars in the plot (see matplotlib documentation for how to specify, either keyword or RGB values (e.g., [1.0,0,0])

  • edgecolour – is the colour of the edges of the bars

  • linewidth – is the thickness of the edges of the bars in the plot.

Example:

from rsgislib.tools import plotting

plotting.plotImageHistogram("Baccini_Manaus_AGB_30.kea", 1, "BacciniHistogram.pdf", numBins=100, imgMin=0, imgMax=400, normOutput=True, plotTitle='Histogram of Baccini Biomass', xLabel='Baccini Biomass', color=[1.0,0.2,1.0], edgecolor='red', linewidth=0)

Projection

rsgislib.tools.degrees_to_metres(latitude, lonsize, latsize)

Convert pixel sizes or distances in degrees to metres.

Where:

Parameters

  • latitude – latitude

  • lonsize – numpy array of x pixel sizes (degrees)

  • latsize – numpy array of y pixel sizes (degrees)

Returns

xsize (numpy array of x pixel sizes (m)), ysize (numpy array of y pixel sizes (m))

Example:

from rsgislib import tools
xsize, ysize = tools.degrees_to_metres(52,1.0,1.0)
rsgislib.tools.metres_to_degrees(latitude, xsize, ysize)

Convert pixel sizes or distances in metres to degrees.

Where:

Parameters

  • latitude – latitude

  • xsize – numpy array of x pixel sizes (m)

  • ysize – numpy array of y pixel sizes (m)

Returns

lonsize (numpy array of x pixel sizes (degrees)), latsize (numpy array of y pixel sizes (degrees))

Example:

from rsgislib import tools
xsize, ysize = tools.metres_to_degrees(52, 1.0, 1.0)

UTM

rsgislib.tools.utm.check_valid_zone(zone_number, zone_letter)

Check that the UTM zone is valid.

Parameters

  • zone_number – int

  • zone_letter – string

Returns

True if successful otherwise raises an exception.

rsgislib.tools.utm.epsg_for_UTM(zone, hemisphere)

Return EPSG code for given UTM zone and hemisphere using WGS84 datum.

Parameters

  • zone – UTM zone

  • hemisphere – hemisphere either ‘N’ or ‘S’

Returns

corresponding EPSG code

rsgislib.tools.utm.from_latlon(latitude, longitude, force_zone_number=None, force_zone_letter=None)

This function convert Latitude and Longitude to UTM coordinate

Parameters

  • latitude – float or array. Latitude between 80 deg S and 84 deg N, e.g. (-80.0 to 84.0)

  • longitude – float or array: Longitude between 180 deg W and 180 deg E, e.g. (-180.0 to 180.0).

  • number (force_zone) – int: Zone Number is represented with global map numbers of an UTM Zone Numbers Map. You may force conversion including one UTM Zone Number. More information see http://www.jaworski.ca/utmzones.htm

rsgislib.tools.utm.latitude_to_zone_letter(latitude)

Find the zone letter for the latitude. If the input is a numpy array, just use the first element user responsibility to make sure that all points are in one zone

Parameters

latitude –

Returns

string if found otherwise None.

rsgislib.tools.utm.latlon_to_zone_number(latitude, longitude)

Find the UTM zone number for a give latitude and longitude. If the input is a numpy array, just use the first element user responsibility to make sure that all points are in one zone

Parameters

  • latitude – float

  • longitude – float

Returns

int

rsgislib.tools.utm.min_max_eastings_for_lat(latitude, zone=1)

Find the minimum and maximum Eastings for a specified latitude within a specific zone. This should be the same for all zones.

Parameters

  • latitude – float

  • zone – int

Returns

tuple [min, max]

rsgislib.tools.utm.split_wgs84_bbox_utm_zones(wgs84_bbox)

Function which splits a bounding box (MinX, MaxX, MinY, MaxY) into a number of small bounding boxes (MinX, MaxX, MinY, MaxY) at UTM zone boundaries.

Parameters

wgs84_bbox – bounding box in lat/long WGS84 (MinX, MaxX, MinY, MaxY)

Returns

list [utm zone, bbox]

rsgislib.tools.utm.to_latlon(easting, northing, zone_number, zone_letter=None, northern=None, strict=True)

This function convert an UTM coordinate into Latitude and Longitude

Parameters

  • easting – int or array: Easting value of UTM coordinate

  • northing – int or array: Northing value of UTM coordinate

  • number (zone) – int: Zone Number is represented with global map numbers of an UTM Zone Numbers Map. More information see http://www.jaworski.ca/utmzones.htm

  • zone_letter – str: Zone Letter can be represented as string values. Where UTM Zone Designators can be accessed in http://www.jaworski.ca/utmzones.htm

  • northern – bool: You can set True or False to set this parameter. Default is None

rsgislib.tools.utm.zone_number_to_central_longitude(zone_number)

Find the central longitude for the given zone.

Parameters

zone_number – int

Returns

float

File Manipulation

rsgislib.tools.sortImgsUTM2DIRs(inputImgsDIR, fileSearchStr, outBaseDIR)

A function which will sort a series of input image files which a projected using the UTM system into individual directories per UTM zone. Please note that the input files are moved on your system!!

Where:

Parameters

  • inputImgsDIR – directory where the input files are to be found.

  • fileSearchStr – the wildcard search string to find files within the input directory (e.g., *.kea).

  • outBaseDIR – the output directory where the UTM folders will be created and the files copied.

Visualisation

rsgislib.tools.visualisation.createKMZImg(inputImg, outputFile, bands, reprojLatLong=True, finiteMsk=False)

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.

Where:

Parameters

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

  • outputFile – 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’)

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

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

rsgislib.tools.visualisation.createWebTilesImg(inputImg, bands, outputDIR, zoomLevels='2-10', img_stats_msk=None, img_msk_vals=1, tmp_dir=None, webview=True, tms=True)

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

Parameters

  • inputImg – 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’)

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

  • zoomLevels – 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 tempory 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)