StereoFramework¶

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

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: for the generation of deformation grids
GridBasedImageResampling: resampling into epipolar geometry
BlockMatching: 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¶

Input parameters ¶

This group of parameters allows one to set input data.

Input images list -input.il image1 image2... Mandatory
List of images corresponding to multiple views on a single scene, in sensor geometry.

Couples list -input.co string
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 -input.channel int Default value: 1
Channel used for block matching (the same for all images)

Elevation management ¶

This group of parameters allows managing elevation values.

DEM directory -elev.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. Input DEM tiles should be in a raster format supported by GDAL.

Geoid File -elev.geoid filename [dtype]
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 (egm96.grd and egm96.grd.hdr at https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/-/tree/master/Data/Input/DEM).

Default elevation -elev.default float Default value: 0
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 -output.res float Default value: 1
Spatial sampling distance of the output elevation: the cell size (in m)

NoData value -output.nodata float Default value: -32768
DSM empty cells are filled with this value (optional -32768 by default)

Method to fuse measures in each DSM cell -output.fusionmethod [max|min|mean|acc] Default value: max
This parameter allows one to choose the method used to fuse elevation measurements in each output DSM cell

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.out image [dtype] Mandatory
Output elevation image

Parameters estimation modes -output.mode [fit|user] Default value: fit

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.

User Defined options ¶

Upper Left X -output.mode.user.ulx float Mandatory
Cartographic X coordinate of upper-left corner (meters for cartographic projections, degrees for geographic ones)

Upper Left Y -output.mode.user.uly float Mandatory
Cartographic Y coordinate of the upper-left corner (meters for cartographic projections, degrees for geographic ones)

Size X -output.mode.user.sizex int Mandatory
Size of projected image along X (in pixels)

Size Y -output.mode.user.sizey int Mandatory
Size of projected image along Y (in pixels)

Pixel Size X -output.mode.user.spacingx float Mandatory
Size of each pixel along X axis (meters for cartographic projections, degrees for geographic ones)

Pixel Size Y -output.mode.user.spacingy float Mandatory
Size of each pixel along Y axis (meters for cartographic projections, degrees for geographic ones)

Map Projection -map [utm|lambert2|lambert93|wgs|epsg] Default value: wgs
Defines the map projection to be used.

Universal Trans-Mercator (UTM)
A system of transverse mercator projections dividing the surface of Earth between 80S and 84N latitude.
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;

Universal Trans-Mercator (UTM) options ¶

Zone number -map.utm.zone int Default value: 31
The zone number ranges from 1 to 60 and allows defining the transverse mercator projection (along with the hemisphere)

Northern Hemisphere -map.utm.northhem bool Default value: false
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.

EPSG Code options ¶

EPSG Code -map.epsg.code int Default value: 4326
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) -stereorect.fwdgridstep int Default value: 16
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 -stereorect.invgridssrate int Default value: 10
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 -bm.metric [ssdmean|ssd|ncc|lp] Default value: ssdmean
Metric used to compute matching score

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

Lp pseudo-norm options ¶

p value -bm.metric.lp.p float Default value: 1
Value of the p parameter in Lp pseudo-norm (must be positive)

Correlation window radius (in pixels) -bm.radius int Default value: 2
The radius of blocks in Block-Matching (in pixels)

Minimum altitude offset (in meters) -bm.minhoffset float Default value: -20
Minimum altitude below the selected elevation source (in meters)

Maximum altitude offset (in meters) -bm.maxhoffset float Default value: 20
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 -postproc.bij bool Default value: true
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 -postproc.med bool Default value: false
Disparity map can be filtered using median post filtering (disabled by default).

Correlation metric threshold -postproc.metrict float Default value: 0.6
Use block matching metric output to discard pixels with low correlation value (disabled by default, float value)

Masks ¶

Input left mask -mask.left image
Mask for left input image. Pixel with a null mask value are discarded.

Input right mask -mask.right image
Mask for right input image. Pixel with a null mask value are discarded.

Discard pixels with low local variance -mask.variancet float Default value: 50
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) -ram int Default value: 256
Available memory for processing (in MB).

Examples¶

From the command-line:

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

From Python:

import otbApplication

app = otbApplication.Registry.CreateApplication("StereoFramework")

app.SetParameterStringList("input.il", ['sensor_stereo_left.tif', 'sensor_stereo_right.tif'])
app.SetParameterFloat("elev.default", 200)
app.SetParameterInt("stereorect.fwdgridstep", 8)
app.SetParameterInt("stereorect.invgridssrate", 4)
app.SetParameterString("postproc.med","1")
app.SetParameterFloat("output.res", 2.5)
app.SetParameterString("output.out", "dem.tif")

app.ExecuteAndWriteOutput()