RSGISLib Image Utilities Module

The imageutils module contains general utilities for applying to images.

Image Stats and Pyramids

rsgislib.imageutils.popImageStats(image, usenodataval=True, nodataval=0, calcpyramids=True, pyscales=list)

Calculate the image statistics and build image pyramids populating the image file.

Where:

  • image is a string containing the name of the input file
  • usenodataval is a boolean stating whether the no data value is to be used (default=True).
  • nodataval is a floating point value to be used as the no data value (default=0.0).
  • calcpyramids is a boolean stating whether image pyramids should be calculated (default=True).
  • pyscales is a list which allows the levels of the image pyramid to be specified. If not provided then levels automatically calculated.

Example:

from rsgislib import imageutils
inputImage = './TestOutputs/injune_p142_casi_sub_utm.kea'
imageutils.popImageStats(inputImage,True,0.,True)
# OR Define the pyramids levels.
imageutils.popImageStats(inputImage,True,0.,True, [4,8,16,32,64,128])
rsgislib.imageutils.combineImageOverviews(base=string, images=list, pyscales=list)

A function to combine (mosaic) the image overviews (pyramids) from the list of input images and add them to the base image, enables pyramids to be created using a tiled processing chain for large images. Note. For small images use rsgislib.imageutils.popImageStats.

Where:

  • base is a string containing the name of the input image file the overviews will be added to

  • images is a list of input images that have the same number of bands and overviews and are within the extent of the base image.

  • pyscales is a list specifying the scales (levels) of the pyramids which will be defined in the base image

    (Note. the input images need to have the same pyramids scales; use rsgislib.imageutils.popImageStats).

Example:

from rsgislib import imageutils
baseImage = './TestOutputs/injune_p142_casi_sub_utm.kea'
imgTiles = ['./TestOutputs/injune_p142_casi_sub_utm_tile1.kea', './TestOutputs/injune_p142_casi_sub_utm_tile2.kea']
imageutils.combineImageOverviews(baseImage, imgTiles, [4,8,16,32,64,128])

Projection

rsgislib.imageutils.assignProj(inputImage, wktString, wktFile)

Assign a projection to the input GDAL image file.

Where:

  • inputImage is a string containing the name of the input file
  • wktString is the wkt string to be assigned to the image. If None then it will be read from the wktStringFile.
  • wktFile is a file path to a text file containing the WKT string to be assigned. This is ignored if wktString is not None.

Example:

from rsgislib import imageutils
wktString = '''PROJCS["WGS 84 / UTM zone 55S",
 GEOGCS["WGS 84",
     DATUM["WGS_1984",
         SPHEROID["WGS 84",6378137,298.257223563,
             AUTHORITY["EPSG","7030"]],
         AUTHORITY["EPSG","6326"]],
     PRIMEM["Greenwich",0],
     UNIT["degree",0.0174532925199433],
     AUTHORITY["EPSG","4326"]],
 PROJECTION["Transverse_Mercator"],
 PARAMETER["latitude_of_origin",0],
 PARAMETER["central_meridian",147],
 PARAMETER["scale_factor",0.9996],
 PARAMETER["false_easting",500000],
 PARAMETER["false_northing",10000000],
 UNIT["metre",1,
     AUTHORITY["EPSG","9001"]],
 AUTHORITY["EPSG","32755"]]'''
inputImage = './TestOutputs/injune_p142_casi_sub_utm.kea'
imageutils.assignProj(inputImage, wktString)
rsgislib.imageutils.assignSpatialInfo(inputImage, tlX, tlY, resX, resY, rotX, rotY)

Assign the spatial information to an input GDAL image file.

Where:

  • inputImage is a string containing the name and path of the input file
  • tlX is a double representing the top left X coordinate of the image.
  • tlY is a double representing the top left Y coordinate of the image.
  • resX is a double representing X resolution of the image.
  • resY is a double representing Y resolution of the image.
  • rotX is a double representing X rotation of the image.
  • rotY is a double representing Y rotation of the image.
rsgislib.imageutils.copyProjFromImage(inputImage, refImage)

Copy the projection from a reference image to an input GDAL image file.

Where:

  • inputImage is a string containing the name and path of the input file
  • refImage is a string containing the name and path of the reference image.
rsgislib.imageutils.copySpatialAndProjFromImage(inputImage, refImage)

Copy the spatial information and projection from a reference image to an input GDAL image file.

Where:

  • inputImage is a string containing the name and path of the input file
  • refImage is a string containing the name and path of the reference image.
rsgislib.imageutils.resampleImage2Match(inRefImg, inProcessImg, outImg, gdalFormat, interpMethod, datatype=None)

A utility function to resample an existing image to the projection and/or pixel size of another image.

Where:

  • inRefImg is the input reference image to which the processing image is to resampled to.
  • inProcessImg is the image which is to be resampled.
  • outImg is the output image file.
  • gdalFormat is the gdal format for the output image.
  • interpMethod is the interpolation method used to resample the image [bilinear, lanczos, cubicspline, nearestneighbour, cubic, average, mode]
  • datatype is the rsgislib datatype of the output image (if none then it will be the same as the input file).
rsgislib.imageutils.reprojectImage(inputImage, outputImage, outWKT, gdalFormat='KEA', interp='cubic', inWKT=None, noData=0.0, outPxlRes='image', snap2Grid=True)

This function provides a tool which uses the gdalwarp function to reproject an input image.

Where:

  • inputImage - the input image name and path

  • outputImage - the output image name and path

  • outWKT - a WKT file representing the output projection

  • gdalFormat - the output image file format (Default is KEA)

  • interp - interpolation algorithm. Options are: near, bilinear, cubic, cubicspline, lanczos, average, mode. (Default is cubic)

  • inWKT - if input image is not well defined this is the input image projection as a WKT file (Default is None, i.e., ignored)

  • noData - float representing the not data value (Default is 0.0)

  • outPxlRes three inputs can be provided
    1. ‘image’ where the output resolution will match the input (Default is image)
    2. ‘auto’ where an output resolution maintaining the image size of the input image will be used
    3. provide a floating point value for the image resolution (note. pixels will be sqaure)
  • snap2Grid is a boolean specifying whether the TL pixel should be snapped to a multiple of the pixel resolution (Default is True).

Mosaic

rsgislib.imageutils.createImageMosaic(inputimagelist, outputimage, backgroundVal, skipVal, skipBand, overlapBehaviour, gdalformat, type)

Create mosaic from list of input images.

Where

  • inputimagelist is a list of input images.

  • outputimage is a string containing the name of the output mosaic

  • backgroundVal is a float providing the background (nodata) value for the mosaic

  • skipVal is a float providing the value to be skipped (nodata values) in the input images

  • skipBand is an integer providing the band to check for skipVal

  • overlapBehaviour is an integer specifying the behaviour for overlaping regions
    • 0 - Overwrite
    • 1 - Overwrite if value of new pixel is lower (minimum)
    • 2 - Overwrite if value of new pixel is higher (maximum)
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).

  • type is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

import rsgislib
from rsgislib import imageutils
import glob

# Search for all files with the extension 'kea'
inputList = glob.glob('./TestOutputs/Tiles/*.kea')
outImage = './TestOutputs/injune_p142_casi_sub_utm_mosaic.kea'
backgroundVal = 0.
skipVal = 0.
skipBand = 1
overlapBehaviour = 0
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
imageutils.createImageMosaic(inputList, outImage, backgroundVal, skipVal, skipBand, overlapBehaviour, gdalformat, datatype)
rsgislib.imageutils.includeImages(baseImage, inputImages, inputBands=None, skipVal=None)

Create mosaic from list of input images.

Where:

  • baseImage is a string containing the name of the input image to add image to
  • inputimagelist is a list of input images
  • inputBands is a subset of input bands to use (optional)
  • skipVal is a float specifying a value which should be ignored and not copied into the new image (optional). To use you must also provided a list of subset image bands.

Example:

import rsgislib
from rsgislib import imageutils
import glob
# Search for all files with the extension 'kea'
baseImage = './TestOutputs/injune_p142_casi_sub_utm_mosaic.kea'
inputList = glob.glob('./TestOutputs/Tiles/*.kea')
imageutils.includeImages(baseImage, inputList)
rsgislib.imageutils.includeImagesWithOverlap(baseImage, inputImages, pxlOverlap)

Create mosaic from list of input images where the input images have an overlap.

Where:

  • baseImage is a string containing the name of the input image to add image to
  • inputimagelist is a list of input images
  • inputBands is a subset of input bands to use (optional)

Example:

     import rsgislib
     from rsgislib import imageutils
     import glob
inputImg = 'LandsatImg.kea'
tilesImgBase = './tiles/LandsatTile'
outputImg = 'LandsatImgProcessed.kea'
imageutils.createTiles(inputImg, tilesImgBase, 1000, 1000, 10, False, 'KEA', rsgislib.TYPE_32FLOAT, 'kea')
# Do some processing on the tiles... 
imageutils.createCopyImage(inputImg, outputImg, 6, 0, 'KEA', rsgislib.TYPE_32FLOAT)
     inputList = glob.glob('./tiles/LandsatTile*.kea')
     imageutils.includeImagesWithOverlap(outputImg, inputList, 10)
rsgislib.imageutils.combineImages2Band(inimages=list, outimage=string, format=string, datatype=int, nodata=float)

Combine images together into a single image band by excluding the no data value.

Where:

  • inimages is a list of strings containing the names and paths of the input image files
  • outimage is a string containing the name of the output file.
  • format is a string with the GDAL output file format.
  • datatype is an containing one of the values from rsgislib.TYPE_*
  • nodata is the no data value which will be ignored (Default is 0)

Example:

from rsgislib import imageutils
inputImages = ['./forest.kea', './urban.kea', './water.kea']
outputImage = './classes.kea'
datatype = rsgislib.TYPE_8UINT
format = 'KEA'
imageutils.combineImages2Band(inputImages, outputImage, format, datatype, 0.0)

Tile

rsgislib.imageutils.createTiles(inputimage, baseimage, width, height, overlap, offsettiling, gdalformat, datatype, ext)

Create tiles from a larger image, useful for splitting a large image into multiple smaller ones for processing.

Where

  • inputImage is a string containing the name of the input file
  • baseimage is a string containing the base name of the output file the number of the tile and file extension will be appended.
  • width is the width of each tile, in pixels.
  • height is the height of each tile, in pixels.
  • overlap is the overlap between tiles, in pixels
  • offsettiling is a bool, determining if tiles should start halfway into the image useful for generating overlapping sets of tiles.
  • gdalformat is a string providing the output gdalformat of the tiles (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the output data type of the tiles.
  • ext is a string providing the extension for the tiles (as required by the specified data type).

Returns:

  • list of tile file names

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
outBase = './TestOutputs/Tiles/injune_p142_casi_sub_utm'
width = 100
height = width
overlap = 5
offsettiling = False
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32INT
ext='kea'
tiles = imageutils.createTiles(inputImage, outBase, width, height, overlap, offsettiling, gdalformat, datatype, ext)
rsgislib.imageutils.tilingutils.createMinDataTiles(inputImage, outshp, outclumpsFile, width, height, validDataThreshold, maskIntersect=None, offset=False, force=True, tmpdir='tilestemp')

A function to create a tiling for an input image where each tile has a minimum amount of valid data.

Where:

  • inputImage is a string for the image to be tiled

  • outshp is a string for the output shapefile the tiling will be written to (if None a shapefile won’t be outputted).

  • outclumpsFile is a string for the output image file containing the tiling

  • width is an int for the width of the tiles

  • height is an int for the height of the tiles

  • validDataThreshold is a float (0-1) with the proportion of valid data needed within a tile.

  • force is a boolean (default True) to delete the output shapefile if it already exists.

  • tmpdir is a string with a temporary directory for temp outputs to be stored (they will be deleted)
    • if tmpdir doesn’t exist it will be created and then deleted during the processing.
rsgislib.imageutils.tilingutils.createTileMaskImagesFromShp(inputImage, tileShp, tilesNameBase, tilesMaskDIR, tmpdir='tilestemp', imgFormat='KEA')

A function to create individual image masks from the tiles shapefile which can be individually used to mask (using rsgislib mask function) each tile from the inputimage.

Where:

  • inputImage is the input image being tiled.

  • tileShp is a shapefile containing the shapefile tiles.

  • tilesNameBase is the base file name for the tile masks

  • tilesMaskDIR is the directory where the output images will be outputted

  • tmpdir is a string with a temporary directory for temp outputs to be stored (they will be deleted)
    • If tmpdir doesn’t exist it will be created and then deleted during the processing.
rsgislib.imageutils.tilingutils.createTileMaskImagesFromClumps(clumpsImage, tilesNameBase, tilesMaskDIR, imgFormat='KEA')

A function to create individual image masks from the tiles shapefile which can be individually used to mask (using rsgislib mask function) each tile from the inputimage.

Where:

  • clumpsImage is an image file with RAT where each clump represented a tile region.
  • tilesNameBase is the base file name for the tile masks
  • tilesMaskDIR is the directory where the output images will be outputted
  • imgFormat is the output image file format of the tile masks
rsgislib.imageutils.tilingutils.createTilesFromMasks(inputImage, tilesBase, tilesMetaDIR, tilesImgDIR, datatype, gdalformat)

A function to apply the image tile masks defined in createTileMaskImages to the input image to extract the individual tiles.

Where:

  • inputImage is the input image being tiled.
  • tileMasksBase is the base path for the tile masks. glob will be used to find them with ‘*.kea’ added to the end.
  • outTilesBase is the base file name for the tiles.

Visualisation / Normalisation

rsgislib.imageutils.stretchImage(inputimage, outputimage, saveoutstats, outstatsfile, ignorezeros, onepasssd, gdalformat, datatype, stretchtype, stretchparam)

Stretches (scales) pixel values from 0 - 255, normally for display although also used for normalisation.

Where:

  • inputImage is a string containing the name of the input file

  • outputImage is a string containing the name of the output file

  • saveoutstats is a bool specifying if stats should be saved to a text file.

  • outstatsfile is a string providing the name of the file to save stats to.

  • ignorezeros is a bool specifying if pixels with a value of zero should be ignored.

  • onepasssd is a bool specifying if is single pass should be used for calculating standard deviation (faster but less accurate)

  • gdalformat is a string providing the output gdalformat of the tiles (e.g., KEA).

  • datatype is a rsgislib.TYPE_* value providing the output data type.

  • stretchtype is a STRETCH_* value providing the type of stretch, options are:
    • imageutils.STRETCH_LINEARMINMAX - Stretches between min and max.
    • imageutils.STRETCH_LINEARPERCENT - Stretches between percentage of image range. Parameter defines percent.
    • imageutils.STRETCH_LINEARSTDDEV - Stretches between mean - sd to mean + sd. Parameter defines number of standard deviations.
    • imageutils.STRETCH_EXPONENTIAL - Exponential stretch between mean - 2*sd to mean + 2*sd. No parameter.
    • imageutils.STRETCH_LOGARITHMIC - Logarithmic stretch between mean - 2*sd to mean + 2*sd. No parameter.
    • imageutils.STRETCH_POWERLAW - Power law stretch between mean - 2*sd to mean + 2*sd. Parameter defines power.
  • stretchparam is a float, providing the input parameter to the stretch (if required).

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_2sd.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_8INT
imageutils.stretchImage(inputImage, outputImage, False, '', True, False, gdalformat, datatype, imageutils.STRETCH_LINEARSTDDEV, 2)
rsgislib.imageutils.stretchImageWithStats(inputimage, outputimage, instatsfile, gdalformat, outtype, stretchtype, stretchparam)

Stretches (scales) pixel values from 0 - 255, normally for display although also used for normalisation. Users pre-calculated statistics.

Where:

  • inputImage is a string containing the name of the input file

  • outputImage is a string containing the name of the output file

  • instatsfile is a string providing the name of the file to read stats from.

  • ignorezeros is a bool specifying if pixels with a value of zero should be ignored.

  • onepasssd is a bool specifying if is single pass should be used for calculating standard deviation (faster but less accurate)

  • gdalformat is a string providing the output gdalformat of the tiles (e.g., KEA).

  • datatype is a rsgislib.TYPE_* value providing the output data type.

  • stretchtype is a STRETCH_* value providing the type of stretch, options are:
    • imageutils.STRETCH_LINEARMINMAX - Stretches between min and max.
    • imageutils.STRETCH_LINEARPERCENT - Stretches between percentage of image range. Parameter defines percent.
    • imageutils.STRETCH_LINEARSTDDEV - Stretches between mean - sd to mean + sd. Parameter defines number of standard deviations.
    • imageutils.STRETCH_EXPONENTIAL - Exponential stretch between mean - 2*sd to mean + 2*sd. No parameter.
    • imageutils.STRETCH_LOGARITHMIC - Logarithmic stretch between mean - 2*sd to mean + 2*sd. No parameter.
    • imageutils.STRETCH_POWERLAW - Power law stretch between mean - 2*sd to mean + 2*sd. Parameter defines power.
  • stretchparam is a float, providing the input parameter to the stretch (if required).

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
inputImageStats = './Rasters/injune_p142_casi_sub_utm_stats.txt'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_2sd.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_8INT
imageutils.stretchImageWithStats(inputImage, outputImage, inputImageStats, True, False, gdalformat, datatype, imageutils.STRETCH_LINEARSTDDEV, 2)

Subset / Mask

rsgislib.imageutils.maskImage(inputimage, imagemask, outputimage, gdalformat, datatype, outvalue, maskvalue)

This command will mask an input image using a single band mask image - commonly this is a binary image.

Where:

  • inputImage is a string containing the name and path of the input image file.
  • imagemask is a string containing the name and path of the mask image file.
  • outputimage is a string containing the name and path for the output image following application of the mask.
  • gdalformat is a string representing the output image file format (e.g., KEA, ENVI, GTIFF, HFA etc).
  • datatype is a rsgislib.TYPE_* value for the data type of the output image.
  • outvalue is a float representing the value written to the output image in place of the regions being masked.
  • maskvalue is a float or list of floats representing the value(s) within the mask image for the regions which are to be replaced with the outvalue.

Example:

import rsgislib
from rsgislib import imageutils

inImg = './LS5/Outputs/LS5TM_20110926_lat53lon511_r23p205_rad_toa.kea'
imgMask = './LS5/Outputs/LS5TM_20110926_lat53lon511_r23p205_clouds.kea'
outImg = './LS5/Outputs/LS5TM_20110926_lat53lon511_r23p205_rad_toa_mclds.kea'

imageutils.maskImage(inImg, imgMask, outImg, 'KEA', rsgislib.TYPE_16UINT, 0, [1,2])
imageutils.popImageStats(outImg, True, 0.0, True)
rsgislib.imageutils.subset(inputimage, inputvector, outputimage, gdalformat, datatype)

Subset an image to the bounding box of a vector.

Where:

  • inputimage is a string providing the name of the input file.
  • inputvector is a string providing the vector which the image is to be clipped to.
  • outputimage is a string providing the output image.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
inputVector = './Vectors/injune_p142_plot_location_utm.shp'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_subset.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
imageutils.subset(inputImage, inputVector, outputImage, gdalformat, datatype)
rsgislib.imageutils.subset2img(inputimage, inputROIimage, outputimage, gdalformat, type)

Subset an image to the bounding box of an image.

Where:

  • inputimage is a string providing the name of the input file.
  • inputvector is a string providing the image which the ‘inputimage’ is to be clipped to.
  • outputimage is a string providing the output image.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
inputVector = './Vectors/injune_p142_plot_location_utm.shp'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_subset.kea'
gdalformat = 'KEA'
gdaltype = rsgislib.TYPE_32FLOAT
imageutils.subset(inputImage, inputVector, outputImage, gdalformat, datatype)
rsgislib.imageutils.subset2polys()

imageutils.subset(inputimage, inputvector, attribute, baseimage, gdalformat, datatype, ext) Subset an image to the bounding box of a each polygon in an input vector. Useful for splitting an image into tiles of unequal sizes.

Where:

  • inputimage is a string providing the name of the input file.
  • inputvector is a string providing the vector which the image is to be clipped to.
  • attribute is a string providing the attribute in the vector to use for the ouput name
  • baseimage is a string providing the base name of the output file. The specified attribute of each polygon and extension will be appended.
  • gdalformat is a string providing the output gdalformat of the subsets (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the output data type of the subsets.
  • ext is a string providing the extension for the tiles (as required by the specified data gdalformat).

Return: * A list of strings containing the filenames.

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
inputVector = './Vectors/injune_p142_plot_location_utm.shp'
attribute = 'PLOTNO'
outputImageBase = './TestOutputs/injune_p142_casi_sub_utm_subset_polys_'
gdalformat = 'KEA'
gdaltype = rsgislib.TYPE_32FLOAT
ext = 'kea'
imageutils.subset2polys(inputImage, inputVector, attribute, outputImageBase, gdalformat, gdaltype, ext)
rsgislib.imageutils.subsetImgs2CommonExtent(inImagesDict, outShpEnv, gdalFormat)

A command to subset a set of images to the same overlapped extent.

Where:

  • inImagesDict is a list of dictionaries containing values for IN (input image) OUT (output image) and TYPE (data type for output)
  • outShpEnv is a file path for the output shapefile representing the overlap extent.
  • gdalFormat is the gdal format of the output images.

Example:

from rsgislib import imageutils

inImagesDict = []
inImagesDict.append({'IN': './Images/Lifeformclip.tif', 'OUT':'./Subsets/Lifeformclip_sub.kea', 'TYPE':rsgislib.TYPE_32INT})
inImagesDict.append({'IN': './Images/chmclip.tif', 'OUT':'./Subsets/chmclip_sub.kea', 'TYPE':rsgislib.TYPE_32FLOAT})
inImagesDict.append({'IN': './Images/peakBGclip.tif', 'OUT':'./Subsets/peakBGclip_sub.kea', 'TYPE':rsgislib.TYPE_32FLOAT})

outputVector = 'imgSubExtent.shp'
imageutils.subsetImgs2CommonExtent(inImagesDict, outputVector, 'KEA')
rsgislib.imageutils.subsetbbox(inputimage, outputimage, gdalformat, datatype, xMin, xMax, yMin, yMax)

Subset an image to the bounding box of a vector.

Where:

  • inputimage is a string providing the name of the input file.
  • outputimage is a string providing the output image.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.
  • xMin double within the minimum X for the bounding box
  • xMax double within the maximum X for the bounding box
  • yMin double within the minimum Y for the bounding box
  • yMax double within the maximum X for the bounding box

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_subset.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
xMin = 295371.5
xMax = 295401.5
yMin = 359470.8
yMax = 359500.8
imageutils.subsetbbox(inputImage, outputImage, gdalformat, datatype, xMin, xMax, yMin, yMax)
rsgislib.imageutils.buildImgSubDict(globFindImgsStr, outDir, suffix, ext)

Automate building the dictionary of image to be used within the subsetImgs2CommonExtent(inImagesDict, outShpEnv, imgFormat) function.

Where:

  • globFindImgsStr is a string to be passed to the glob module to find the input image files.
  • outDir is the output directory path for the images.
  • suffix is a suffix to be appended on to the end of the file name (can be a blank string, i.e., ‘’)
  • ext is a string with the output file extension

Example:

from rsgislib import imageutils

inImagesDict = imageutils.buildImgSubDict("./Images/*.tif", "./Subsets/", "_sub", ".kea")
print(inImagesDict)

outputVector = 'imgSubExtent.shp'
imageutils.subsetImgs2CommonExtent(inImagesDict, outputVector, 'KEA')
rsgislib.imageutils.genFiniteMask(inimage=string, outimage=string, format=string)

Generate a binary image mask defining the finite image regions.

Where:

  • inimage is a string containing the name of the input file
  • outimage is a string containing the name of the output file.
  • format is a string with the GDAL output file format.

Example:

from rsgislib import imageutils
inputImage = './injune_p142_casi_sub_utm.kea'
outputImage = './injune_p142_casi_sub_utm.kea'
imageutils.genFiniteMask(inputImage, outputImage, 'KEA')
rsgislib.imageutils.genValidMask(inimages=string|list, outimage=string, format=string, nodata=float)

Generate a binary image mask defining the regions which are not ‘no data’.

Where:

  • inimages can be either a string or a list containing the input file(s)
  • outimage is a string containing the name of the output file.
  • format is a string with the GDAL output file format.
  • nodata is a float defining the no data value (Optional and default is 0.0)

Example:

from rsgislib import imageutils
inputImage = './injune_p142_casi_sub_utm.kea'
outputImage = './injune_p142_casi_sub_utm.kea'
imageutils.genValidMask(inputImage, outputImage, 'KEA', 0.0)

Extract

rsgislib.imageutils.ImageBandInfo(fileName=None, name=None, bands=None)

Create a list of these objects to pass to the extractZoneImageBandValues2HDF function * fileName - is the input image file name and path. * name - is a name associated with this layer - doesn’t really matter what you use but needs to be unique; this is used as a dict key in some functions. * bands - is a list of image bands within the fileName to be used for processing (band numbers start at 1).

rsgislib.imageutils.extractZoneImageValues2HDF(inputImage, imageMask, outputHDF, maskValue)

Extract the all the pixel values for raster regions to a HDF5 file (1 column for each image band).

Where:

  • inputImage is a string containing the name and path of the input file
  • imageMask is a string containing the name and path of the input image mask file; the mask file must have only 1 image band.
  • outputHDF is a string containing the name and path of the output HDF5 file
  • maskValue is a float containing the value of the pixel within the mask for which values are to be extracted
rsgislib.imageutils.extractZoneImageBandValues2HDF(inputImageInfo, imageMask, outputHDF, maskValue)

Extract the all the pixel values for raster regions to a HDF5 file (1 column for each image band). Multiple input rasters can be provided and the bands extracted selected.

Where:

  • inputImageInfo is a list of rsgislib::imageutils::ImageBandInfo objects with the file names and list of image bands within that file to be extracted.
  • imageMask is a string containing the name and path of the input image mask file; the mask file must have only 1 image band.
  • outputHDF is a string containing the name and path of the output HDF5 file
  • maskValue is a float containing the value of the pixel within the mask for which values are to be extracted

Example:

import rsgislib.imageutils
fileInfo = []
fileInfo.append(rsgislib.imageutils.ImageBandInfo('InputImg1.kea', [1,3,4]))
fileInfo.append(rsgislib.imageutils.ImageBandInfo('InputImg2.kea', [2]))
rsgislib.imageutils.extractZoneImageBandValues2HDF(fileInfo, 'ClassMask.kea', 'ForestRefl.h5', 1.0)
rsgislib.imageutils.performRandomPxlSampleInMask(inputImage=string, outputImage=string, gdalformat=string, maskvals=int|list, numSamples=unsigned int)

Randomly sample with a mask (e.g., classification). The same number of samples will be identified within each mask value listed by maskvals.

Where:

  • inputImage is a string for the input image mask - mask is typically whole values within regions (e.g., classifications).
  • outputImage is a string with the name and path of the output image. Output is the mask pixel values.
  • gdalformat is a string with the GDAL output file format.
  • maskvals can either be a single integer value or a list of values. If a list of values is specified then the total number of points identified (numSamples x n-maskVals).
  • numSamples is the number of samples to be created within each region.

Create

rsgislib.imageutils.createBlankImage(outputImage, numBands, width, height, tlX, tlY, res, pxlVal, wktFile, wktString, gdalformat, gdaltype)

Create a new blank image with the parameters specified.

Where:

  • outputImage is a string containing the name and path for the outputted image.
  • numBands is an integer specifying the number of image bands in the output image.
  • width is an integer specifying the width of the output image.
  • height is an integer specifying the height of the output image.
  • tlX is a double specifying the Top Left pixel X coordinate (eastings) of the output image.
  • tlY is a double specifying the Top Left pixel Y coordinate (northings) of the output image.
  • res is a double specifying the pixel resolution of the output image.
  • pxlVal is a float specifying the pixel value of the output image.
  • wktFile is a string specifying the location of a file containing the WKT string representing the coordinate system and projection of the output image (if specified this parameter overrides the wktString parameter).
  • wktString is a string specifying the WKT string representing the coordinate system and projection of the output image.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • gdaltype is a rsgislib.TYPE_* value providing the data type of the output image.
rsgislib.imageutils.createCopyImage(inputImage, outputImage, numBands, pxlVal, gdalformat, datatype)

Create a new blank image with the parameters specified.

Where:

  • inputImage is a string containing the name and path for the input image, which is to be copied.
  • outputImage is a string containing the name and path for the outputted image.
  • numBands is an integer specifying the number of image bands in the output image.
  • pxlVal is a float specifying the pixel value of the output image.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_blank.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
imageutils.createCopyImage(inputImage, outputImage, 1, 3, gdalformat, datatype)
rsgislib.imageutils.createCopyImageVecExtent(inputImage, shpFile, outputImage, numBands, pxlVal, gdalformat, datatype)

Create a new blank image with the parameters specified but with the extent of the inputted shapefile.

Where:

  • inputImage is a string containing the name and path for the input image, which is to be copied.
  • shpFile is a string specifying the name and path of the shapefile to which the image extent will be cut
  • outputImage is a string containing the name and path for the outputted image.
  • numBands is an integer specifying the number of image bands in the output image.
  • pxlVal is a float specifying the pixel value of the output image.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
shpFile = './Rasters/injune_p142_roi.shp'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_blank.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
imageutils.createCopyImageVecExtent(inputImage, shpFile, outputImage, 3, 1, gdalformat, datatype)

Select / Stack bands

rsgislib.imageutils.selectImageBands(inputImage, outputImage, gdalformat, datatype, bands)

Copy selected image bands from an image to a new image.

Where:

  • inputImage is a string containing the name and path of the input file
  • outputImage is a string containing the name and path of the output file.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.
  • bands is a list of integers for the bands in the input image to exported to the output image (Note band count starts at 1).

Example:

import rsgislib.imageutils
import rsgislib
bands = [1,2]
rsgislib.imageutils.selectImageBands('N06W053_07_ALL_sl_sub.kea', 'N06W053_07_ALL_sl_sub_HHVV.kea', 'KEA', rsgislib.TYPE_32INT, bands)
rsgislib.imageutils.stackImageBands(inputImages, imageBandNames, outputImage, skipValue, noDataValue, gdalformat, type)

Create a single image from list of input images through band stacking.

Where:

  • inputImages is a list of input images.
  • imageBandNames is a list of band names (one for each input image). If None then ignored.
  • outputImage is a string containing the name and path for the outputted image.
  • skipVal is a float providing the value to be skipped (nodata values) in the input images (If None then ignored)
  • noDataValue is float specifying a no data value.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • type is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

import rsgislib
from rsgislib import imageutils
imageList = ['./Rasters/injune_p142_casi_sub_utm_single_band.vrt','./Rasters/injune_p142_casi_sub_utm_single_band.vrt']
bandNamesList = ['Image1','Image2']
outputImage = './TestOutputs/injune_p142_casi_sub_stack.kea'
gdalformat = 'KEA'
gdaltype = rsgislib.TYPE_32FLOAT
imageutils.stackImageBands(imageList, bandNamesList, outputImage, None, 0, gdalformat, gdaltype)

Band Names

rsgislib.imageutils.setBandNames(inputImage, bandNames)

A utility function to set band names. Where:

  • inImage is the input image
  • bandNames is a list of band names

Example:

from rsgislib import imageutils

inputImage = 'injune_p142_casi_sub_utm.kea'
bandNames = ['446nm','530nm','549nm','569nm','598nm','633nm','680nm','696nm','714nm','732nm','741nm','752nm','800nm','838nm']

imageutils.setBandNames(inputImage, bandNames)
rsgislib.imageutils.getBandNames(inputImage)

A utility function to get band names.

Where:

  • inImage is the input image

Return:

  • list of band names

Example:

from rsgislib import imageutils

inputImage = 'injune_p142_casi_sub_utm.kea'
bandNames = imageutils.getBandNames(inputImage)

Image Data Types

rsgislib.imageutils.getGDALDataType(inImg)

Returns the rsgislib datatype ENUM for a raster file

  • inImg – The file to get the datatype for

return:

The rsgislib datatype enum, e.g., rsgislib.TYPE_8INT
rsgislib.imageutils.getRSGISLibDataType(inImg)

Returns the rsgislib datatype ENUM for a raster file

  • inImg – The file to get the datatype for

return:

The rsgislib datatype enum, e.g., rsgislib.TYPE_8INT

Other

rsgislib.imageutils.stackStats(inputImage, outputImage, numBands, stat, gdalformat, datatype)

Calculate statistics for every pixel in a stack of image. If all bands are used a single band image is produced with the specified statistics. If a number of bands are specified statistics are taken over every n bands to provide an image with B / n bands (where B is the number of input bands. For example, can be used to produce monthly composite images from a stack with images from every day.

Where:

  • inputImage is a string containing the name and path for the input image.
  • outputImage is a string containing the name and path for the output image.
  • numBands is an integer specifying the number of image bands in the output image, pass ‘None’ to use all bands.
  • stat is a string providing the statistics to calculate, options are ‘mean’, ‘min’, ‘max’, and ‘range’.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • datatype is a rsgislib.TYPE_* value providing the data type of the output image.

Example:

import rsgislib
from rsgislib import imageutils
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_stackStats.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
imageutils.stackStats(inputImage, outputImage, None, 'mean', gdalformat, datatype)
rsgislib.imageutils.orderImageUsingValidPxls(inputImages, noDataVal)

Order the list of input images based on the their proportion of valid image pixels. The primary use of this function is expected to be order (rank) images ahead of mosaicing.

Where:

  • inputImages is a list of string containing the name and path for the input images.
  • noDataVal is a float which specifies the no data value used to defined ‘invalid’ pixels.
Returns:
  • a list of images ordered, from low to high (i.e., the first image will be the image with the smallest number of valid image pixels).
rsgislib.imageutils.genSamplingGrid(InputImage, OutputImage, gdalformat, pxlRes, minVal, maxVal, singleLine)

Generate a regular sampling grid.

Where:

  • InputImage is a string specifying an image which defines the area of interest.
  • OutputImage is a string specifying an output image location.
  • gdalformat is a string providing the gdalformat of the output image (e.g., KEA).
  • pxlRes is a float specifying the output image resolution.
  • minVal is a minimum value for the output image pixel values.
  • maxVal is a maximum value for the output image pixel values.
  • singleLine is a boolean specifying whether the image is seen as a single line or new line with an offset in the starting value.
rsgislib.imageutils.calcPixelLocations(inputImg, outputImg, gdalFormat)

Function which produces a 2 band output image with the X and Y locations of the image pixels.

Where:

  • inputImg - the input reference image
  • outputImg - the output image file name and path (will be same dimensions as the input)
  • gdalFormat - the GDAL image file format of the output image file.