Fast Transient Imaging
A Python framework revolving around reconstruction of impulse responses from AMCW lidar measurements.
CTrigonometricMomentImageStack Class Reference

This class encapsulates a stack of images containing trigonometric moments. More...

Public Member Functions

def __init__
 Initializes this class with the given list of images. More...
 
def Crop (self, CropOffLeft, CropOffRight, CropOffTop, CropOffBottom)
 Crops off the specified number of pixels from each of the boundaries of the moment images contained in this stack. More...
 
def Conjugate (self)
 This function applies convex conjugation to all held moments (in place). More...
 
def GetPerPixelCalibration
 This function computes calibration coefficients, which turn this moment image stack into an image stack describing the given distribution at all pixels (by default a Dirac-delta distribution at zero). More...
 
def ApplyPerPixelCalibration (self, PerPixelScaling)
 This function applies previously computed calibration values to this stack. More...
 
def ApplyScaling (self, Scaling)
 Multiplies all moment images by the given scalar factor. More...
 
def ApplyBiasing
 This function scales values of particular moments wherever this is necessary to make the moment vectors valid. More...
 
def Smooth (self, StandardDeviationInPixels)
 Applies smoothing using a Gaussian filter with the specified standard deviation in pixels. More...
 
def PrepareMaximumEntropySpectralEstimate
 This function pre-computes coefficients needed for the maximum entropy spectral estimate which depend upon the held moment images. More...
 
def GetMomentVector (self, X, Y)
 This function returns the moment vector for the pixel with the given coordinates as one-dimensional numpy array. More...
 
def GetMaximumEntropySpectralEstimate (self, Phase)
 This function returns an image of brightness values for the given phase. More...
 
def GetTransientImage (self, PhaseSampling=np.linspace(0.0, 2.0 *np.pi)
 This function returns a CTransientImage containing the maximum entropy spectral estimate of the transient image described by the held trigonometric moment images. More...
 
def GetGodbazPhaseImage (self)
 This function computes a phase image using the technique proposed by Godbaz et al. More...
 
def GetPhaseImage (self)
 This function computes the phase of the global maximum of the maximum entropy spectral estimate per pixel and returns it as image with radians in the range from zero to two pi. More...
 
def GetPisarenkoEstimate (self)
 This function constructs a Pisarenko estimate for each pixel, i.e. More...
 
def SeparateDirectIllumination
 This function uses a Pisarenko estimate to separate the direct component of illumination from indirect components. More...
 
def GetErrorBound (self, PoissonKernelRadius, Phase)
 This function computes a lower and upper bound for the value of a density function having the held trigonometric moments per pixel. More...
 
def GetToeplitzImage
 This function constructs a Hermitian Toeplitz matrix for each pixel. More...
 
def Store
 This function stores the held trigonometric moment images to the specified location. More...
 
def GetWidth (self)
 This function returns the width of the held moment images in pixels. More...
 
def GetHeight (self)
 This function returns the height of the held moment images in pixels. More...
 
def GetMomentCount (self)
 This function returns the number of trigonometric moments available per pixel NOT counting the zeroth moment. More...
 
def GetFullMomentCount (self)
 This function returns the number of trigonometric moments available per pixel counting the zeroth moment. More...
 
def PlotEigenvalues
 This method visualizes the eigenvalues of the Toeplitz matrix per pixel. More...
 
def PlotPisarenkoEstimate (self)
 This function plots weight images and phase images resulting from the Pisarenko estimate. More...
 
def Display (self)
 This method displays this stack of moment images in a human-friendly fashion. More...
 

Public Attributes

 MomentImageList
 

Static Public Attributes

tuple MomentImageList = list()
 A list containing all moment images sorted by the index of the held moments. More...
 
 EvaluationPolynomialImage = None;
 This array holds coefficients used by GetMaximumEntropySpectralEstimate(). More...
 

Detailed Description

This class encapsulates a stack of images containing trigonometric moments.

It provides a lot of functionality to analyze and process these images.

Constructor & Destructor Documentation

def __init__ (   self,
  MomentImageList,
  Normalized = False 
)

Initializes this class with the given list of images.

MomentImageList[j] is supposed to be a two-dimensional array of complex values containing j-th trigonometric moments. For the zeroth trigonometric moment image only the magnitude is considered. Alternatively, MomentImageList can contain file names of *.exr files as produced by StoreScalarImage(). If Normalized is True all moment images except for the zeroth one are multiplied by the zeroth one per pixel.

Member Function Documentation

def Crop (   self,
  CropOffLeft,
  CropOffRight,
  CropOffTop,
  CropOffBottom 
)

Crops off the specified number of pixels from each of the boundaries of the moment images contained in this stack.

def Conjugate (   self)

This function applies convex conjugation to all held moments (in place).

def GetPerPixelCalibration (   self,
  ReferenceDistribution = CFiniteDistribution([0.0]),
  DiscardZerothMomentImage = True 
)

This function computes calibration coefficients, which turn this moment image stack into an image stack describing the given distribution at all pixels (by default a Dirac-delta distribution at zero).

The overall brightness (i.e. zeroth moment) remains unchanged unless the zeroth moment is not available or DiscardZerothMomentImage is True. If the given distribution matches the ground truth distribution (at least with respect to its trigonometric moments), it is safe to transfer the resulting per pixel calibration to other measurements.

Parameters
ReferenceDistributionThe reference distribution as CFiniteDistribution(). In the end only its trigonometric moments matter. Values should be phases of the base frequency.
Returns
Per pixel calibration coefficients in the form expected by self.ApplyPerPixelCalibration().
def ApplyPerPixelCalibration (   self,
  PerPixelScaling 
)

This function applies previously computed calibration values to this stack.

PerPixelScaling[j,:,:] is supposed to be an image of scaling factors to be applied to self.MomentImageList[j] as factor.

def ApplyScaling (   self,
  Scaling 
)

Multiplies all moment images by the given scalar factor.

def ApplyBiasing (   self,
  MinNormalizedEigenvalue = 0.01,
  BiasingMode = "Keep" 
)

This function scales values of particular moments wherever this is necessary to make the moment vectors valid.

A moment vector is considered valid if the smallest eigenvalue of the corresponding Toeplitz matrix divided by the zeroth moment is greater than or equal to the given threshold.

Parameters
BiasingModeYou can pass four different strings to trigger four different biasing modes. "Keep" scales all moments except for the zeroth moment uniformly. "Increase" increases the zeroth moment by the smallest amount necessary for valid moment vectors. "Discard" discards the zeroth moment image entirely and instead computes it to realize the given minimal eigenvalue. This mode is chosen automatically if zeroth moments are unavailable. "Mask" turns pixels requiring a bias entirely black.
Returns
A boolean image indicating which pixels have been modified.
def Smooth (   self,
  StandardDeviationInPixels 
)

Applies smoothing using a Gaussian filter with the specified standard deviation in pixels.

The smoothing is applied to all moment images.

def PrepareMaximumEntropySpectralEstimate (   self,
  ForceRecomputation = False 
)

This function pre-computes coefficients needed for the maximum entropy spectral estimate which depend upon the held moment images.

This way it ensures that GetMaximumEntropySpectralEstimate() can function efficiently. You do not need to call it yourself unless you have changed moment images after using a maximum entropy spectral estimate. In this case you should pass True for ForceRecomputation.

def GetMomentVector (   self,
  X,
  Y 
)

This function returns the moment vector for the pixel with the given coordinates as one-dimensional numpy array.

def GetMaximumEntropySpectralEstimate (   self,
  Phase 
)

This function returns an image of brightness values for the given phase.

The brightness per pixel as function of the phase is a density matching all held trigonometric moments while realizing the minimal possible Burg entropy.

def GetTransientImage (   self,
  PhaseSampling = np.linspace(0.0,2.0*np.pi 
)

This function returns a CTransientImage containing the maximum entropy spectral estimate of the transient image described by the held trigonometric moment images.

Parameters
PhaseSamplingAn iterable of phases at which the density should be sampled. This should be a sorted list of equidistant samples.
def GetGodbazPhaseImage (   self)

This function computes a phase image using the technique proposed by Godbaz et al.

in the paper "Closed-form Inverses for the Mixed Pixel/ Multipath Interference Problem in AMCW Lidar".

Returns
An image of phases as radians in the range from zero to two pi.
Precondition
self.GetMomentCount()==4.
def GetPhaseImage (   self)

This function computes the phase of the global maximum of the maximum entropy spectral estimate per pixel and returns it as image with radians in the range from zero to two pi.

def GetPisarenkoEstimate (   self)

This function constructs a Pisarenko estimate for each pixel, i.e.

a distribution consisting of exactly self.GetMomentCount() Dirac-delta distributions, which realizes all held moments except for the zeroth one.

Returns
A tuple (Phase,Weight) consisting of two real-valued arrays of shape (self.GetHeight(),self.GetWidth(),self.GetMomentCount()). Phase contains the locations of Dirac-deltas for each pixel using radians in the range from zero to two pi, Weight contains the corresponding weights. The weights are sorted in decreasing order.
def SeparateDirectIllumination (   self,
  MinDirectFraction = 0.2 
)

This function uses a Pisarenko estimate to separate the direct component of illumination from indirect components.

Parameters
MinDirectFractionThe minimal fraction of the total weight which should be contained in the direct component. The direct component is the component with minimal phase surpassing this threshold. Pass None for this threshold to define that the strongest component is the direct component.
Returns
A triple (Direct,Indirect,DirectPhase) consisting of three real- valued arrays of shape (self.GetHeight(),self.GetWidth()). Direct contains the weights of the Dirac-delta describing the direct component. Indirect is the difference to the zeroth moment image. Phase contains the phase associated with the direct return.
def GetErrorBound (   self,
  PoissonKernelRadius,
  Phase 
)

This function computes a lower and upper bound for the value of a density function having the held trigonometric moments per pixel.

Since such densities can usually be arbitrary big or small, the bounds actually refer to the density obtained after smoothing with a Poisson kernel.

Parameters
PoissonKernelRadiusA parameter controlling the sharpness of the kernel. For zero it is uniform, for one it converges to a Dirac- delta at zero. This has to be less than one.
PhaseThe phase in radians at which the upper and lower bound should be evaluated. This has to be an array with shape (nSample,).
Returns
A pair (LowerBound,UpperBound) of arrays of shape (self.GetHeight(),self.GetWidth(),nSample) where LowerBound[Y,X,i] provides the minimal smoothed density at Phase[i] and pixel (X,Y). UpperBound provides corresponding upper bounds.
def GetToeplitzImage (   self,
  Mode = "Default" 
)

This function constructs a Hermitian Toeplitz matrix for each pixel.

Parameters
ModeDetermines the contents of the Toeplitz matrix. "Default" generates a Toeplitz matrix containing all held moments in the appropriate diagonals, "Normalized" is like "Default" except that all moments are divided by the zeroth moment and "ZeroDiagonal" treats the zeroth moment as zero.
Returns
An array of shape (self.GetHeight(),self.GetWidth(),self.GetFullMomentCount(),self.GetFullMomentCount()) where entry [Y,X,:,:] is the requested Toeplitz matrix for the pixel at (X,Y).
def Store (   self,
  DirectoryPathOrFileList,
  Normalize = True,
  Print = False 
)

This function stores the held trigonometric moment images to the specified location.

The image format is the same as for StoreScalarImage().

Parameters
DirectoryPathOrFileListIf this is a string, it specifies a directory. The images are stored to this directory using Measurement<FrequencyIndex>.exr as file name. Otherwise, it has to be a list of strings specifying full file paths for every single moment image.
NormalizePass True to ensure that all moment images (except for the zeroth one) are divided per pixel by the zeroth one.
PrintIf this boolean is True, the function prints information about produced files.
def GetWidth (   self)

This function returns the width of the held moment images in pixels.

def GetHeight (   self)

This function returns the height of the held moment images in pixels.

def GetMomentCount (   self)

This function returns the number of trigonometric moments available per pixel NOT counting the zeroth moment.

def GetFullMomentCount (   self)

This function returns the number of trigonometric moments available per pixel counting the zeroth moment.

def PlotEigenvalues (   self,
  Normalize = True 
)

This method visualizes the eigenvalues of the Toeplitz matrix per pixel.

Parameters
NormalizePass True to get Eigenvalues divided by the zeroth moment.
def PlotPisarenkoEstimate (   self)

This function plots weight images and phase images resulting from the Pisarenko estimate.

def Display (   self)

This method displays this stack of moment images in a human-friendly fashion.

Member Data Documentation

tuple MomentImageList = list()
static

A list containing all moment images sorted by the index of the held moments.

EvaluationPolynomialImage = None;
static

This array holds coefficients used by GetMaximumEntropySpectralEstimate().

If PrepareMaximumEntropySpectralEstimate() has not been invoked yet, it is None.

MomentImageList

The documentation for this class was generated from the following file: