StereoFramework - Stereo Framework

Compute the ground elevation based on one or multiple stereo pair(s)

Detailed description

Compute the ground elevation with a stereo block matching algorithm between one or multiple stereo pair in sensor geometry. The output is projected in desired geographic or cartographic map projection (WGS84 by default).

This application is chaining different processing steps. Some of them are also performed by other applications in the stereo-reconstruction framework:
  • StereoRectificationGridGenerator [1] : for the generation of deformation grids
  • GridBasedImageResampling [2] : resampling into epipolar geometry
  • BlockMatching [3] : estimation of dense disparity maps
The pipeline executes the following steps on each stereo pair:
  • compute the epipolar displacement grids from the stereo pair (direct and inverse)
  • resample the stereo pair into epipolar geometry using BCO interpolation
  • create masks for each epipolar image : remove black borders and resample input masks
  • compute horizontal disparities with a block matching algorithm
  • refine disparities to sub-pixel precision with a dichotomy algorithm
  • apply an optional median filter
  • filter disparities based on the correlation score and exploration bounds
  • translate disparities in sensor geometry
  • convert disparity to 3D Map.

Then all 3D maps are fused to produce DSM. The fusion method in each DEM cell can be chosen between maximum, minimum and average.

Parameters

This section describes in details the parameters available for this application. Table [1] presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is StereoFramework .

[1]Table: Parameters table for Stereo Framework.
Parameter Key Parameter Name Parameter Type
input Input parameters Group
input.il Input images list Input image list
input.co Couples list String
input.channel Input Image channel Int
elev Elevation management Group
elev.dem DEM directory Directory
elev.geoid Geoid File Input File name
elev.default Default elevation Float
output Output parameters Group
output.res Output resolution Float
output.nodata NoData value Float
output.fusionmethod Method to fuse measures in each DSM cell Choices
output.fusionmethod max Maximum Choice
output.fusionmethod min Minimum Choice
output.fusionmethod mean Mean Choice
output.fusionmethod acc Accumulator Choice
output.out Output DSM Output image
output.mode Parameters estimation modes Choices
output.mode fit Fit to sensor image Choice
output.mode user User Defined Choice
output.mode.user.ulx Upper Left X Float
output.mode.user.uly Upper Left Y Float
output.mode.user.sizex Size X Int
output.mode.user.sizey Size Y Int
output.mode.user.spacingx Pixel Size X Float
output.mode.user.spacingy Pixel Size Y Float
map Map Projection Choices
map utm Universal Trans-Mercator (UTM) Choice
map lambert2 Lambert II Etendu Choice
map lambert93 Lambert93 Choice
map wgs WGS 84 Choice
map epsg EPSG Code Choice
map.utm.zone Zone number Int
map.utm.northhem Northern Hemisphere Boolean
map.epsg.code EPSG Code Int
stereorect Stereorectification Grid parameters Group
stereorect.fwdgridstep Step of the displacement grid (in pixels) Int
stereorect.invgridssrate Sub-sampling rate for epipolar grid inversion Int
bm Block matching parameters Group
bm.metric Block-matching metric Choices
bm.metric ssdmean Sum of Squared Distances divided by mean of block Choice
bm.metric ssd Sum of Squared Distances Choice
bm.metric ncc Normalized Cross-Correlation Choice
bm.metric lp Lp pseudo-norm Choice
bm.metric.lp.p p value Float
bm.radius Correlation window radius (in pixels) Int
bm.minhoffset Minimum altitude offset (in meters) Float
bm.maxhoffset Maximum altitude offset (in meters) Float
postproc Postprocessing parameters Group
postproc.bij Use bijection consistency in block matching strategy Boolean
postproc.med Use median disparities filtering Boolean
postproc.metrict Correlation metric threshold Float
mask Masks Group
mask.left Input left mask Input image
mask.right Input right mask Input image
mask.variancet Discard pixels with low local variance Float
ram Available RAM (Mb) Int
inxml Load otb application from xml file XML input parameters file
outxml Save otb application to xml file XML output parameters file

[Input parameters]: This group of parameters allows one to set input data.

  • Input images list: List of images corresponding to multiple views on a single scene, in sensor geometry.
  • Couples list: List of index of couples im image list. Couples must be separated by a comma (index start at 0). For example : 0 1,1 2 will process a first couple composed of the first and the second image in image list, then the second and the third image . Note that images are handled by pairs. If left empty, couples are created from input index i.e. a first couple will be composed of the first and second image, a second couple with third and fourth image etc. (in this case image list must be even).
  • Input Image channel: Channel used for block matching (the same for all images).

[Elevation management]: This group of parameters allows managing elevation values. Supported formats are SRTM, DTED or any geotiff. DownloadSRTMTiles application could be a useful tool to list/download tiles related to a product.

  • DEM directory: This parameter allows selecting a directory containing Digital Elevation Model files. Note that this directory should contain only DEM files. Unexpected behaviour might occurs if other images are found in this directory.
  • Geoid File: Use a geoid grid to get the height above the ellipsoid in case there is no DEM available, no coverage for some points or pixels with no_data in the DEM tiles. A version of the geoid can be found on the OTB website(https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb-data/blob/master/Input/DEM/egm96.grd).
  • Default elevation: This parameter allows setting the default height above ellipsoid when there is no DEM available, no coverage for some points or pixels with no_data in the DEM tiles, and no geoid file has been set. This is also used by some application as an average elevation value.

[Output parameters]: This group of parameters allows one to choose the DSM resolution, nodata value, and projection parameters.

  • Output resolution: Spatial sampling distance of the output elevation : the cell size (in m).
  • NoData value: DSM empty cells are filled with this value (optional -32768 by default).
  • Method to fuse measures in each DSM cell: This parameter allows one to choose the method used to fuse elevation measurements in each output DSM cell. Available choices are:
  • Maximum: The cell is filled with the maximum measured elevation values.
  • Minimum: The cell is filled with the minimum measured elevation values.
  • Mean: The cell is filled with the mean of measured elevation values.
  • Accumulator: Accumulator mode. The cell is filled with the the number of values (for debugging purposes).
  • Output DSM: Output elevation image.
  • Parameters estimation modes Available choices are:
  • Fit to sensor image: Fit the size, origin and spacing to an existing ortho image (uses the value of outputs.ortho).
  • User Defined: This mode allows you to fully modify default values.
  • Upper Left X: Cartographic X coordinate of upper-left corner (meters for cartographic projections, degrees for geographic ones).
  • Upper Left Y: Cartographic Y coordinate of the upper-left corner (meters for cartographic projections, degrees for geographic ones).
  • Size X: Size of projected image along X (in pixels).
  • Size Y: Size of projected image along Y (in pixels).
  • Pixel Size X: Size of each pixel along X axis (meters for cartographic projections, degrees for geographic ones).
  • Pixel Size Y: Size of each pixel along Y axis (meters for cartographic projections, degrees for geographic ones).

Map Projection: Defines the map projection to be used. Available choices are:

  • Universal Trans-Mercator (UTM): A system of transverse mercator projections dividing the surface of Earth between 80S and 84N latitude.
  • Zone number: The zone number ranges from 1 to 60 and allows defining the transverse mercator projection (along with the hemisphere).
  • Northern Hemisphere: The transverse mercator projections are defined by their zone number as well as the hemisphere. Activate this parameter if your image is in the northern hemisphere.
  • Lambert II Etendu: This is a Lambert Conformal Conic projection mainly used in France.
  • Lambert93: This is a Lambert 93 projection mainly used in France.
  • WGS 84: This is a Geographical projection.
  • EPSG Code: This code is a generic way of identifying map projections, and allows specifying a large amount of them. See www.spatialreference.org to find which EPSG code is associated to your projection;.
  • EPSG Code: See www.spatialreference.org to find which EPSG code is associated to your projection.

[Stereorectification Grid parameters]: This group of parameters allows one to choose direct and inverse grid subsampling. These parameters are very useful to tune time and memory consumption.

  • Step of the displacement grid (in pixels): Stereo-rectification displacement grid only varies slowly. Therefore, it is recommended to use a coarser grid (higher step value) in case of large images.
  • Sub-sampling rate for epipolar grid inversion: Grid inversion is an heavy process that implies spline regression on control points. To avoid eating to much memory, this parameter allows one to first sub-sample the field to invert.

[Block matching parameters]: This group of parameters allow tuning the block-matching behavior.

  • Block-matching metric: Metric used to compute matching score. Available choices are:
  • Sum of Squared Distances divided by mean of block: derived version of Sum of Squared Distances between pixels value in the metric window (SSD divided by mean over window).
  • Sum of Squared Distances: Sum of squared distances between pixels value in the metric window.
  • Normalized Cross-Correlation: Normalized Cross-Correlation between the left and right windows.
  • Lp pseudo-norm: Lp pseudo-norm between the left and right windows.
  • p value: Value of the p parameter in Lp pseudo-norm (must be positive).
  • Correlation window radius (in pixels): The radius of blocks in Block-Matching (in pixels).
  • Minimum altitude offset (in meters): Minimum altitude below the selected elevation source (in meters).
  • Maximum altitude offset (in meters): Maximum altitude above the selected elevation source (in meters).

[Postprocessing parameters]: This group of parameters allow use optional filters.

  • Use bijection consistency in block matching strategy: Use bijection consistency. Right to Left correlation is computed to validate Left to Right disparities. If bijection is not found, the disparity is rejected.
  • Use median disparities filtering: Disparity map can be filtered using median post filtering (disabled by default).
  • Correlation metric threshold: Use block matching metric output to discard pixels with low correlation value (disabled by default, float value).

[Masks]

  • Input left mask: Mask for left input image. Pixel with a null mask value are discarded.
  • Input right mask: Mask for right input image. Pixel with a null mask value are discarded.
  • Discard pixels with low local variance: This parameter allows one to discard pixels whose local variance is too small (the size of the neighborhood is given by the correlation window radius).

Available RAM (Mb): Available memory for processing (in MB).

Load otb application from xml file: Load otb application from xml file.

Save otb application to xml file: Save otb application to xml file.

Example

To run this example in command-line, use the following:

otbcli_StereoFramework -input.il sensor_stereo_left.tif sensor_stereo_right.tif -elev.default 200 -stereorect.fwdgridstep 8 -stereorect.invgridssrate 4 -postproc.med 1 -output.res 2.5 -output.out dem.tif

To run this example from Python, use the following code snippet:

#!/usr/bin/python

# Import the otb applications package
import otbApplication

# The following line creates an instance of the StereoFramework application
StereoFramework = otbApplication.Registry.CreateApplication("StereoFramework")

# The following lines set all the application parameters:
StereoFramework.SetParameterStringList("input.il", ['sensor_stereo_left.tif', 'sensor_stereo_right.tif'])

StereoFramework.SetParameterFloat("elev.default", 200)

StereoFramework.SetParameterInt("stereorect.fwdgridstep", 8)

StereoFramework.SetParameterInt("stereorect.invgridssrate", 4)

StereoFramework.SetParameterString("postproc.med","1")

StereoFramework.SetParameterFloat("output.res", 2.5)

StereoFramework.SetParameterString("output.out", "dem.tif")

# The following line execute the application
StereoFramework.ExecuteAndWriteOutput()

Authors

This application has been written by OTB-Team.

See Also

These additional resources can be useful for further information:
[1] StereoRectificationGridGenerator
[2] GridBasedImageResampling
[3] BlockMatching