RSGISLib Histogram Cube Module

The histocube module provides histogram cube functionality within RSGISLib.

Histogram Summary Statistics:

  • SUMTYPE_HC_UNDEFINED = 0

  • SUMTYPE_HC_MIN = 1

  • SUMTYPE_HC_MAX = 2

  • SUMTYPE_HC_MEAN = 3

  • SUMTYPE_HC_MEDIAN = 4

  • SUMTYPE_HC_RANGE = 5

  • SUMTYPE_HC_STDDEV = 6

  • SUMTYPE_HC_SUM = 7

  • SUMTYPE_HC_MODE = 8

Create HistoCube (HCF) File

rsgislib.histocube.createEmptyHistoCube(filename=string, numOfFeats=unsigned long)

Create an empty histogram cube file ready for populating.

Where:

Parameters

  • filename – is the file path and name for the histogram cube file.

  • numOfFeats – is the number of features within the cube - this is defined globally within the file.

Example:

import rsgislib.histocube
rsgislib.histocube.createEmptyHistoCube('HistoCubeTest.hcf', 10000)

Create HistoCube Layer(s)

rsgislib.histocube.createHistoCubeLayer(filename=string, layerName=string, lowBin=int, upBin=int, scale=float, offset=float, hasDateTime=boolean, dataTime=string)

Create an empty histogram cube layer, with all zero’d. The histogram is made up of integer bins and with a scale and offset to define the bin sizes.

Where:

Parameters

  • filename – is the file path and name for the histogram cube file.

  • layerName – is the name of the layer to be created.

  • lowBin – is the lower limit of the histogram bins created (Can be negative).

  • upBin – is the upper limit of the histogram bins created.

  • scale – is the scale parameter used to scale/offset the input data (Optional: default = 1)

  • offset – is the offset parameter used to scale/offset the input data (Optional: default = 0)

  • hasDateTime – is a boolean parameter specifying whether the layer has a date/time associated with it (Optional: default = False).

  • dataTime – is an ISO string representing the date and time associated with the layer.

Example:

import rsgislib.histocube

hcFile = 'HistoCubeTest.hcf'
rsgislib.histocube.createEmptyHistoCube(hcFile, 1000)

layerName = 'LyrName'
rsgislib.histocube.createHistoCubeLayer(hcFile, layerName=layerName, lowBin=0, upBin=100)

Populate with Data

rsgislib.histocube.populateHistoCubeLayer(filename=string, layerName=string, clumpsImg=string, valsImg=string, band=int, inMem=bool)

Populate the histogram layer with information from an image band. Note, data from this band is ‘added’ to any existing data already within the histogram(s).

Where:

Parameters

  • filename – is the file path and name for the histogram cube file.

  • layerName – is the name of the layer to be created.

  • clumpsImg – is a clumps image that specifies which histogram cube row pixels in with values image are associated (note resolution must be the same as the values image).

  • valsImg – is the image with the values which are populated into the histogram cube.

  • band – is the band number (note band numbers start at 1)

  • inMem – is a boolean specifying whether the data array should be kept in memory; much faster in memory. (Optional, default is True)

Example:

import rsgislib.histocube
import rsgislib.imagecalc
import math
import rsgislib

clumpsImg = 'WV2_525N040W_20110727_TOARefl_clumps_final.kea'
minVal, maxVal = rsgislib.imagecalc.getImageBandMinMax(clumpsImg, 1, False, 0)

hcFile = 'HistoCubeTest.hcf'
rsgislib.histocube.createEmptyHistoCube(hcFile, math.ceil(maxVal)+1)

layerName = 'SceneCount'
rsgislib.histocube.createHistoCubeLayer(hcFile, layerName=layerName, lowBin=0, upBin=256)

timer = rsgislib.RSGISTime()
timer.start(True)
valsImg = 'WV2_525N040W_20110727_TOARefl_b762_stch.kea'
rsgislib.histocube.populateHistoCubeLayer(hcFile, layerName=layerName, clumpsImg=clumpsImg, valsImg=valsImg, band=1)
timer.end()

Export Data

rsgislib.histocube.exportHistoBins2ImgBands(filename=string, layerName=string, clumpsImg=string, outputImg=string, gdalformat=string, binidxs=list)

Export bins from the histogram cube to an output image.

Where:

Parameters

  • filename – is the file path and name for the histogram cube file.

  • layerName – is the name of the layer to be created.

  • clumpsImg – is a clumps image that specifies which histogram cube row pixels in with values image are associated (note resolution must be the same as the values image).

  • outputImg – is the file path to the output image.

  • gdalformat – is the format of the output image (e.g., KEA)

  • binidxs – is list of indexed (start 0) within the histogram to export.

Example:

import rsgislib.histocube

hcTileFile='./HistoCube/LandsatWalesRegion_60m_tile7.hcf'
tile='./RefImages/LandsatWalesRegion_60m_tile7.kea'
outputImg='./FreqImgs/LandsatWalesRegion_60m_tile7.kea'
rsgislib.histocube.exportHistoBins2ImgBands(filename=hcTileFile, layerName='OverallPxlCount', clumpsImg=tile, outputImg=outputImg, gdalformat='KEA', binidxs=[0,1])
rsgislib.histocube.exportHistoStats2ImgBands(filename=string, layerName=string, clumpsImg=string, outputImg=string, gdalformat=string, datatype=int, binstats=list)

Export summary statistics (e.g., median, mean, mode, min, max etc.) from the histogram cube to an output image.

Where:

Parameters

  • filename – is the file path and name for the histogram cube file.

  • layerName – is the name of the layer to be created.

  • clumpsImg – is a clumps image that specifies which histogram cube row pixels in with values image are associated (note resolution must be the same as the values image).

  • outputImg – is the file path to the output image.

  • gdalformat – is the format of the output image (e.g., KEA)

  • datatype – specifies one of the values from rsgislib.TYPE_*

  • binstats – is list of summary statistics which will be calculated for each histogram and exported (Must be of type: rsgislib.histocube.SUMTYPE_HC_*).

Example:

import rsgislib
import rsgislib.histocube

hcTileFile='./HistoCube/LandsatWalesRegion_60m_tile7.hcf'
tile='./RefImages/LandsatWalesRegion_60m_tile7.kea'
outputImg='./StatsImgs/LandsatWalesRegion_60m_tile7.kea'
binstats=[rsgislib.histocube.SUMTYPE_HC_MEDIAN, rsgislib.histocube.SUMTYPE_HC_MEAN]
rsgislib.histocube.exportHistoStats2ImgBands(filename=hcTileFile, layerName='OverallPxlCount', clumpsImg=tile, outputImg=outputImg, gdalformat='KEA', datatype=rsgislib.TYPE_32FLOAT binstats=binstats)

Get Metadata

rsgislib.histocube.getLayerNames(filename=string)

Get a list of the layer names within the histocube file..

Where:

Parameters

filename – is the file path and name for the histogram cube file.

Returns

List of layer names of string type.

Example:

import rsgislib.histocube

hcTileFile='./HistoCube/LandsatWalesRegion_60m_tile7.hcf'
lyrNames = rsgislib.histocube.getLayerNames(filename=hcTileFile)