Extended disparity range available with new Triclops SDK

Last Revision Date: 6/12/2015

This article describes how the upper bound on the allowable disparity range has been changed for the new 3.2.x.x versions of the Triclops SDK. 

Please note: this article only applies to 3.2.x.x versions of the Triclops SDK, available for download from our downloads section.

The upper bound on the allowable disparity range within the Triclops library has been increased from 240 to 1024. This change will allow users to make depth measurements on objects significantly closer to their cameras than was previously possible. 

In order to properly use the new functionality, the user should be aware of the following:

1. 1. The range of disparities (maxDisparity-minDisparity) is still limited to be less than or equal to 240. Trying to set a range larger than the maximum range of 240 will result in an error.
      
      
   2. The disparity range is still set using the triclopsSetDisparity() API call, but now a new internal parameter, disparityOffset, is also set during this call to MAX(0, maxDisparity-240). This disparityOffset is accessible using a new API call triclopsGetDisparityOffset().
      
      
   3. Disparity image pixel values are now not complete until the disparityOffset is added back to them. (However, see (4) below.) For 16-bit disparity images, the actual disparity value d_act (for pixel disparity value d_p and disparity offset value d_off) is given by:
      
      d_act = (d_p/256.0) + d_off
      
      For 8-bit disparities, the equivalent conversion is simply:
      
      d_act = d_p + d_off
      
      Of course, if maxDisparity<240, then d_off = 0, and we revert to the situation as it was before the extended range was available.
      
      
   4. Most of the functions that take disparity as an input parameter can be used exactly as before, i.e. with the disparity image pixel values input directly. The conversion to actual disparity is done internally. These functions are:
      
      
      • • triclopsRCDToXYZ

        • triclopsRCDMappedToXYZ

        • triclopsRCD8ToXYZ

        • triclopsRCD16ToXYZ

        • triclopsRCDToWorldXYZ

        • triclopsRCDMappedToWorldXYZ

        • triclopsRCD8ToWorldXYZ

        • triclopsRCD16ToWorldXYZ
      
      However, two of the functions require conversion (see (3) above) to actual disparity before the disparity value is passed to the function. These are:
      
      
      • • triclopsRCDFloatToXYZ

        • triclopsRCDFloatToWorldXYZ
      
      If you are currently using these two functions, and want to begin using the expanded range of disparities, these are the most likely places where changes will need to be made.
      
      This combination of functionality was chosen to provide both the simplicity of the original methods (e.g. stepping through an image and using one of the first group of functions for conversion) with the flexibility to input any absolute RCD trio (even floating point R/C) and retrieve the actual XYZ values associated with it.