EStereo v1.0 documentation

This document describes the main features of the Estereo library.

 

Main structure

Classes description

Example

 

 

Main structure

 

The following figure illustrates how the different objects of the EStereo library are organized and used in the

estimation of the disparity corresponding to a pair of grayscale images.

 

 

 

 

class

role

 

StereoImage

Contains the disparity/stereo images and associated information (eg. subpixel info)

 

ReconstPoints3D

Contains the list of 3D points reconstructed from the disparity information (StereoImage object)

 

StereoMatching

Used to compute the disparity (StereoImage) from a pair of images

 

Reconst3D

Used to estimate a 3D reconstruction (ReconstPoints3D) from disparity information (StereoImage)

 

InputImages

Object used to represent images internally (in StereoMatching).

 

StereoBuffer

Object containing intermediate results for the disparity estimation (in StereoMatching).

 

 

 

StereoImage class

Description: Contains the disparity/stereo images and associated information (eg. subpixel info)

 

Constructors/Destructors

StereoImage()

Creates the StereoImage object

~ StereoImage()

Destructs the StereoImage object

 

Main elements

unsigned char *imDepth8u

Disparity image stored as a (unsigned char) 1D array. Not subpixel.

float *imDepth32f

Disparity image stored as a (float) 1D array. The values of the disparities are obtained by sub-pixel estimation.

int width, height

Width and height of the disparity images.

void setUndefinedDepthValue(int unval)

Set the disparity value of spatially undefined pixels to unval. It is recommended to set this value to 0 (default value).

 

 

ReconstPoints3D class

Description: Contains the list of 3D points reconstructed from the disparity information (StereoImage object)

Constructors/Destructors

ReconstPoints3D()

Creates the ReconstPoints3D object

~ ReconstPoints3D()

Destructs the ReconstPoints3D object

 

Methods

Parameter initialization

float* getNumPoints()

Return the number of points contained in the reconstruction.

float* getXlist() const

float* getYlist() const

float* getZlist() const

 

Returns a pointer on an array containing the list of X, Y and Z coordinates of the reconstruction.

·        X and Y are oriented as the x and y of the images

·        Z is the depth

unsigned char* getARGBlist() const

Returns a pointer on an array containing the list of colors (ARGB) of the points in the reconstruction.

This function requires that the library be compiled with GDI (the compiler variable _USEDI needs then to be defined).

 

StereoMatching class

Description: The StereoMatching class is designed to perform the computation of disparity images

from 2 or 3 rectified images.

 

Constructors/Destructors

StereoMatching()

Creates the StereoMatching object

~StereoMatching()

Destructs the StereoMatching object (and deallocates all internal buffers)

 

Methods

Parameter initialization

void setInputImageSize(int w, int h)

Set the size of the input images to w*h

void setScale(int s)

Set the scale s of the disparity images.

The size of the disparity images is 2s times smaller than the size of the input images.

void setNumDepth(int d)

Set the range of disparities to search to d

void setHoropter(int h)

Set the horopter (disparity offset) to h.

void initializeContext()

Initialize the context and allocates necessary internal buffers for the (SAD) disparity estimation algorithm. The function initializeContext must be called after setImageSize and setNumDepth have been called.

void setCorrelationWindowSize(int cw, int ch)

Set the SAD correlation window to cw * ch

In the current implementation, cw and ch are supposed to have their value between 5 and 17.

void setAcceptDisparityThreshold(int thresh)

Set the SAD threshold to thresh. Pixels for which the smallest SAD score (over all searched disparities) is higher than thresh will be considered as spatially undefined.

Typical value: thresh between 1 and 5.

void setScaleProcessing( tScaleProcessing sprocessing)

Set the type of disparity estimation algorithm  desired. sprocessing can have the value MONOSCALE or MULTISCALE.

 

Disparity estimation algorithm

void doStereo(StereoImage* simage,

const unsigned char* leftImage,

const unsigned char* rightImage)

Run the SAD algorithm on the leftImage and rightImage images.

leftImage and rightImage are assumed to be a pair (left and right) of rectified grayscale images.

The function initializeContext() must be called (once) before any call to the function doStereo.

 

The result of the disparity estimation is contained in the variable simage.

 

Reconst3D class

Description: Used to estimate a 3D reconstruction (ReconstPoints3D) from disparity information (StereoImage).

Constructors/Destructors

Reconst3D()

Creates the Reconst3D object

~ Reconst3D()

Destructs the Reconst3D object

Methods

void setCameraParameters(float f, float bline, float u0, float v0)

Set the camera parameters for the 3D reconstruction.

  • f is the focal length of the right camera (in pixels)
  • bline is the distance between the 2 optical centers of the cameras (baseline)
  • (u0,v0) is the principal point of the right camera (in pixels)

int doReconstruction(ReconstPoints3D* reconstPts3d, const StereoImage* pStereoData)

Build the 3D reconstruction reconstPts3d corresponding to the disparity information pStereoData.

 

Image format

The current implementation of StereoMatching supports grayscale 8-bit images only.

The images are supposed to be encoded in a standard way (1-dimensionnal array, pixels listed left to right, then up to bottom).

 

Implementation examples

Example 1

The following program computes the disparity image corresponding to a pair of 320x240 images.

The number of disparities used for the search is 32.

The correlation window size is 9x9 and the SAD threshold is set to 5.

 

// create a StereoMatching object

      StereoMatching* stereo = new StereoMatching();

// initialize SAD parameters

      stereo->setInputImageSize(320,240); // input images will be 320x240

      stereo->setNumDepth(32);                  // search disparities in [0,31]

      stereo->setCorrelationWindowSize(9,9);    // SAD mask size 9x9

      stereo->setAcceptDisparityThreshold(5);   //

stereo->setScale(0);                      // disparity images will be 320x240

      stereo->setScaleProcessing(StereoMatching::MONOSCALE) // process one scale only

 // allocate buffers for SAD computation

      stereo->initializeContext();

 

      uchar *leftImage, *rightImage;  // 8-bits B&W images

// below, write your code to grab the left and right images

      .....

                             

// do stereo

StereoImage *simage = new StereoImage()         // create new StereoImage object

      stereo->doStereo(simage leftImage, rightImage); // estimate disparity image simage

 

// perform 3D reconstruction

Reconst3d reconst3d;

reconst3d.setCameraParameters(focalLength, baseline, 160,120);

ReconstPoints3D *pPts3d = new ReconstPoints3D();

      reconst3d.doReconstruction(pPts3d, simage);    

     

// draw 3D points

      float *X = pPts3d->Xlist();

      float *Y = pPts3d->Ylist();

      float *Z = pPts3d->Zlist();

      for (int i=0; i< pPts3d->getNumPoints(); ++i) {

            // assuming you have some plot3d function to draw 3D points…

            plot3d( X[i], Y[i], Z[i] );

}

 

// below, write your code to draw the disparity image stereo-> imDepth8u

// as an 8-bits grayscale image

      .....