gediWFMetrics: GEDI full waveform data processing

Description

GEDI full waveform data processing and metrics extraction

Usage

gediWFMetrics(
  input,
  outRoot,
  writeFit = FALSE,
  writeGauss = FALSE,
  bounds = NULL,
  ground = FALSE,
  useInt = FALSE,
  useFrac = FALSE,
  rhRes = 5,
  laiRes = 10,
  laiH = 30,
  noRHgauss = FALSE,
  gTol = 0,
  fhdHistRes = 0.001,
  forcePsigma = FALSE,
  bayesGround = FALSE,
  dontTrustGround = FALSE,
  noRoundCoord = FALSE,
  noCanopy = FALSE,
  dcBias = 0,
  nSig = 0,
  hNoise = 0,
  linkNoise = NULL,
  linkFsig = NULL,
  linkPsig = NULL,
  trueSig = NULL,
  bitRate = NULL,
  maxDN = NULL,
  renoise = FALSE,
  newPsig = -1,
  oldPsig = 0.764331,
  addDrift = NULL,
  missGround = FALSE,
  minGap = NULL,
  photonCount = FALSE,
  pcl = FALSE,
  nPhotons = 2.1,
  photonWind = 200,
  noiseMult = 0.1,
  rhoVrhoG = 1,
  nPhotC = 2.1,
  nPhotG = -1,
  photHDF = FALSE,
  meanN = 0,
  thresh = 1e-14,
  varNoise = FALSE,
  varScale = NULL,
  statsLen = NULL,
  noiseTrack = FALSE,
  sWidth = NULL,
  psWidth = 0,
  msWidth = NULL,
  preMatchF = FALSE,
  postMatchF = FALSE,
  pFile = NULL,
  gWidth = 1.2,
  minGsig = 0.764331,
  minWidth = 0,
  medNoise = FALSE,
  varDrift = NULL,
  driftFac = NULL,
  rhoG = 0.4,
  rhoC = 0.57,
  pSigma = NULL,
  gold = FALSE,
  deconTol = NULL
)

Arguments

input

gedi.level1bSim (may be a list of objects). Simulated waveform input object(s).

outRoot

name. output filename root

writeFit

write fitted waveform

writeGauss

write Gaussian parameters

bounds

minX minY maxX maxY. only analyse data within bounds

ground

read true ground from file

useInt

use discrete intensity instead of count

useFrac

use fractional hits rather than counts

rhRes

r. percentage energy resolution of RH metrics

laiRes

res. lai profile resolution in metres

laiH

h. height to calculate LAI to

noRHgauss

do not fit Gaussians

gTol

tol. ALS ground tolerance. Used to calculate slope.

fhdHistRes

res. waveform intensity resolution to use when calculating FHD from histograms

forcePsigma

do not read pulse sigma from file

bayesGround

use Bayseian ground finding

dontTrustGround

don't trust ground in waveforms, if included

noRoundCoord

do not round up coords when outputting

noCanopy

do not calculate FHD histograms and LAI profiles

dcBias

n. mean noise level

nSig

sig. noise sigma

hNoise

n. hard threshold noise as a fraction of integral

linkNoise

linkM cov. apply Gaussian noise based on link margin at a cover

linkFsig

sig. footprint width to use when calculating and applying signal noise

linkPsig

sig. pulse width to use when calculating and applying signal noise

trueSig

sig. true sigma of background noise

bitRate

n. digitisation bit rate

maxDN

max. maximum DN

renoise

remove noise from truth before applying new noise level

newPsig

sig. new value for pulse width, when lengthening pulse

oldPsig

sig. old value for pulse width if not defined in waveform file, when lengthening pulse

addDrift

xi. apply detector background drift

missGround

assume ground is missed to assess RH metrics

minGap

gap. delete signal beneath min detectable gap fraction

photonCount

output point cloud from photon counting

pcl

convert to photon counting pulsecompressed

nPhotons

n. mean number of photons

photonWind

x. window length for photon counting search, metres

noiseMult

x. noise multiplier for photoncounting

rhoVrhoG

x. ratio of canopy to ground reflectance at this wavelength. Not different from rhoV and rhoG

nPhotC

n. mean number of canopy photons (replaces nPhotons and rhoVrhoG)

nPhotG

n. mean number of ground photons (replaces nPhotons and rhoVrhoG)

photHDF

write photoncounting

meanN

n. mean noise level, if using a predefined mean level

thresh

n. noise threshold, if using a predefined noise threshold

varNoise

use a variable noise threshold

varScale

x. variable noise threshold scale (multiple of stdev above mean to set threshold)

statsLen

len. length to calculate noise stats over for varNoise

noiseTrack

use noise tracking

sWidth

sig. smoothing width, after densoising

psWidth

sigma. smoothing width, before denoising

msWidth

sig. smoothing width, after noise stats, before denoising

preMatchF

matched filter before denoising

postMatchF

matched filter after denoising

pFile

file. read pulse file, for deconvoltuion and matched filters

gWidth

sig. Gaussian parameter selection smoothing width

minGsig

sig. minimum Gaussian sigma to fit

minWidth

n. minimum feature width in bins

medNoise

use median stats rather than mean

varDrift

correct detector drift with variable factor

driftFac

xi. fix drift with constant drift factor

rhoG

rho. ground reflectance

rhoC

rho. canopy reflectance

pSigma

sig. pulse width to smooth by if using Gaussian pulse

gold

deconvolve with Gold's method

deconTol

deconvolution tolerance

Value

Returns a list of metrics derived from the simulated full waveform. A text file (txt) containing the metrics will be saved in the output folder (outRoot). Please see the details section for checking the definition of the metrics.

Details

a) Metrics descriptions

a.1) Metrics available to GEDI

gHeight Ground elevation (m) from Gaussian fitting
maxGround Ground elevation (m) from lowest maximum
inflGround Ground elevation (m) from inflection points.
signal top Elevation of first point above noise (may include noise tracking).
signal bottom Elevation of last return above noise (may include noise tracking).
cover Canopy cover (fraction) from area of Gaussian fitted ground. Uses rho_v=0.57 and rho_g=0.4.
leading edge ext Leading edge extent (m), from Lefksy et al (2007).
trailing edge extent Trailing edge extent (m), from Lefksy et al (2007).
rhGauss 0-100 RH metrics, 0
rhMax 0-100 RH metrics, 0
rhInfl 0-100 RH metrics, 0
gaussHalfCov Canopy cover (fraction) from double the energy beneath the Gaussian ground. Uses rho_v=0.57 and rho_g=0.4.
maxHalfCov Canopy cover (fraction) from double the energy beneath the lowest maximum ground. Uses rho_v=0.57 and rho_g=0.4.
infHalfCov Canopy cover (fraction) from double the energy beneath the inflection point ground. Uses rho_v=0.57 and rho_g=0.4.
bayHalfCov Canopy cover (fraction) from double the energy beneath the experimental "Bayesian" ground. Uses rho_v=0.57 and rho_g=0.4.
lon Footprint centre longitude in projection of ALS data (m).
lat Footprint centre latitude in projection of ALS data (m).
waveEnergy Total energy within waveform (will be 1 scaled by noise for simulations).
blairSense Blair's sensitivity metric. Canopy cover at which this SNR would have90
FHD Foliage height diversity
niM2 Wenge Ni's biomass metric, equal to the sum of the RH metrics to the power of 2 (unpublished)
niM2.1 Wenge Ni's biomass metric, equal to the sum of the RH metrics to the power of 2.1 (unpublished)

a.2) Metrics unavailable to GEDI

wave ID Waveform label, relates to plot name and footprint number.
true ground Ground elevation (m) from ALS. Centre of gravity of ground points within footprint
true top Levation of highest point of waveform (m), without noise. Includes pulse blurring.
ground slope Effective ground slope (degrees), from width of ground return. Includes roughness.
ALS cover Canopy cover (fraction) from ALS data. Uses rho_v=0.57 and rho_g=0.4.
rhReal 0-100 RH metrics, 0
groundOverlap Fraction of ground return overlapping with canopy return. A measure of understorey.
groundMin Depth of minimum between ground and canopy return. A measure of understorey.
groundInfl d2y/dx2 of inflection point between ground and canopy return. A measure of understorey.
pointDense Average ALS point density within GEDI footprint.
beamDense Average ALS beam density within GEDI footprint.

a.3) System settings

pSigma GEDI system pulse width, sigma (m).
fSigma GEDI footprint width, sigma (m).
linkM Link margin if noise is added (db).
linkCov Canopy cover at which the above link margin is true (fraction).
filename Name of input waveform file.

b) Signal processing description

Gaussian fitting Used for "gHeight", "rhGauss" and "gaussHalfCov". The waveform is denoised (mean+5*sigma, noise tracking to avoid truncation), smoothed (pSigma*0.75) and Gaussians fitted with Levenberg-Marquardt optimisation. The center of the lowest Gaussian containing at least 0.5
Maximum Used for "maxGround", "rhMax" and "maxHalfCov". The waveform is denoised (mean+5*sigma, noise tracking to avoid truncation), smoothed (pSigma*0.75). The lowest maximum is taken as the ground.
Inflection points Used for "inflGround", "rhInfl" and "inflHalfCov". The waveform is denoised (mean+5*sigma, noise tracking to avoid truncation), smoothed (pSigma*0.75). The centre of gravity between the lowest two inflection points is taken as the ground.
Half covers Used for "gaussHalfCov", "maxHalfCov" and "inflHalfCov". Sum energy beneath estimated ground position. Double that is the ground energy. Calculate canopy cover, correcting for rho_v and rho_g.

\(cover = \frac{E_{can}}{E_{can} + E_g*\frac{rho_v}{rho_g}}\)
Where Ecan is the canopy energy, Eg is the ground energy, rho_v is the vegetation reflectance and rho_g is the ground reflectance.
Edge extents These are described in: Lefsky, Michael A., Michael Keller, Yong Pang, Plinio B. De Camargo, and Maria O. Hunter. "Revised method for forest canopy height estimation from Geoscience Laser Altimeter System waveforms." Journal of Applied Remote Sensing 1, no. 1 (2007): 013537-013537.

Examples

Run this code

# NOT RUN {
libsAvailable = require(lidR) && require(plot3D)
if (libsAvailable) {
outdir = tempdir()

# Specifying the path to ALS data (zip)
alsfile_Amazon_zip <- system.file("extdata", "Amazon.zip", package="rGEDI")
alsfile_Savanna_zip <- system.file("extdata", "Savanna.zip", package="rGEDI")

# Unzipping ALS data
alsfile_Amazon_filepath <- unzip(alsfile_Amazon_zip,exdir = outdir)
alsfile_Savanna_filepath <- unzip(alsfile_Savanna_zip,exdir = outdir)

# Reading and plot ALS file (las file)
als_Amazon<-readLAS(alsfile_Amazon_filepath)
als_Savanna<-readLAS(alsfile_Savanna_filepath)

# Extracting plot center geolocations
xcenter_Amazon = mean(als_Amazon@bbox[1,])
ycenter_Amazon = mean(als_Amazon@bbox[2,])
xcenter_Savanna = mean(als_Savanna@bbox[1,])
ycenter_Savanna = mean(als_Savanna@bbox[2,])

# Simulating GEDI full waveform
wf_Amazon<-gediWFSimulator(input=alsfile_Amazon_filepath,
                          output=file.path(outdir,"gediWF_amazon_simulation.h5"),
                          coords = c(xcenter_Amazon, ycenter_Amazon))

wf_Savanna<-gediWFSimulator(input=alsfile_Savanna_filepath,
                           output=file.path(outdir,"gediWF_Savanna_simulation.h5"),
                           coords = c(xcenter_Savanna, ycenter_Savanna))

# Extracting GEDI full waveform derived metrics without adding noise to the full waveform
wf_amazon_metrics<-gediWFMetrics(input=wf_Amazon,outRoot=file.path(outdir, "amazon"))
wf_savanna_metrics<-gediWFMetrics(input=wf_Savanna,outRoot=file.path(outdir, "savanna"))

metrics<-rbind(wf_amazon_metrics,wf_savanna_metrics)
rownames(metrics)<-c("Amazon","Savanna")
head(metrics)

# Extracting GEDI full waveform derived metrics after adding noise to the waveform
wf_amazon_metrics_noise<-gediWFMetrics(input=wf_Amazon,
                        outRoot=file.path(outdir, "amazon"),
                        linkNoise= c(3.0103,0.95),
                        maxDN= 4096,
                        sWidth= 0.5,
                        varScale= 3)

wf_savanna_metrics_noise<-gediWFMetrics(
                       input=wf_Savanna,
                       outRoot=file.path(outdir, "savanna"),
                       linkNoise= c(3.0103,0.95),
                       maxDN= 4096,
                       sWidth= 0.5,
                       varScale= 3)

close(wf_Amazon)
close(wf_Savanna)

metrics_noise<-rbind(wf_amazon_metrics_noise,wf_savanna_metrics_noise)
rownames(metrics_noise)<-c("Amazon","Savanna")
head(metrics_noise)

}
# }