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:

  • 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:

  • 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:

  • 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:

  • 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])

Get Metadata

rsgislib.histocube.getLayerNames(filename=string)

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

Where:

  • 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)