/home/laradmin/lar/sensors/camera/xb3/triclops/include/triclops3d.h
Go to the documentation of this file.00001 /************************************************************************************************** 00002 Software License Agreement (BSD License) 00003 00004 Copyright (c) 2011-2013, LAR toolkit developers - University of Aveiro - http://lars.mec.ua.pt 00005 All rights reserved. 00006 00007 Redistribution and use in source and binary forms, with or without modification, are permitted 00008 provided that the following conditions are met: 00009 00010 *Redistributions of source code must retain the above copyright notice, this list of 00011 conditions and the following disclaimer. 00012 *Redistributions in binary form must reproduce the above copyright notice, this list of 00013 conditions and the following disclaimer in the documentation and/or other materials provided 00014 with the distribution. 00015 *Neither the name of the University of Aveiro nor the names of its contributors may be used to 00016 endorse or promote products derived from this software without specific prior written permission. 00017 00018 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR 00019 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 00020 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 00021 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00022 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 00023 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 00024 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 00025 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00026 ***************************************************************************************************/ 00032 //============================================================================= 00033 // Copyright � 2004 Point Grey Research, Inc. All Rights Reserved. 00034 // 00035 // This software is the confidential and proprietary information of Point 00036 // Grey Research, Inc. ("Confidential Information"). You shall not 00037 // disclose such Confidential Information and shall use it only in 00038 // accordance with the terms of the license agreement you entered into 00039 // with Point Grey Research, Inc. (PGR). 00040 // 00041 // PGR MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE 00042 // SOFTWARE, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE 00043 // IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 00044 // PURPOSE, OR NON-INFRINGEMENT. PGR SHALL NOT BE LIABLE FOR ANY DAMAGES 00045 // SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING 00046 // THIS SOFTWARE OR ITS DERIVATIVES. 00047 // 00048 //============================================================================= 00049 //============================================================================= 00050 // $Id: triclops3d.h,v 2.2 2007/11/30 00:43:03 soowei Exp $ 00051 //============================================================================= 00052 #ifndef TRICLOPS3D_H 00053 #define TRICLOPS3D_H 00054 00055 //============================================================================= 00056 // 00057 // This file defines the API for 3D extraction and manipulation for the 00058 // Triclops Stereo Vision SDK. 00059 // 00060 //============================================================================= 00061 00062 00063 //============================================================================= 00064 // Defines 00065 //============================================================================= 00066 00067 //============================================================================= 00068 // System Includes 00069 //============================================================================= 00070 00071 #include <triclops.h> 00072 00073 #ifdef __cplusplus 00074 extern "C" 00075 { 00076 #endif 00077 00078 //============================================================================= 00079 // Macros 00080 //============================================================================= 00081 00082 00083 //============================================================================= 00084 // Enumerations 00085 //============================================================================= 00086 00087 //============================================================================= 00088 // Types 00089 //============================================================================= 00090 // 00091 // Group = Types 00092 00093 // 00094 // Name: TriclopsPoint3d 00095 // 00096 // Description: 00097 // This structure defines a single 3d pixel. It is only used in the 00098 // TriclopsImage3d structure. 00099 // 00100 typedef struct TriclopsPoint3d 00101 { 00102 // The 3 values for the (x,y,z) point in order x = 0, y = 1, z = 2. 00103 float point[3]; 00104 00105 } TriclopsPoint3d; 00106 00107 // 00108 // Name: TriclopsImage3d 00109 // 00110 // Description: 00111 // This structure defines the format of an image consisting of 3d points. 00112 // 00113 typedef struct TriclopsImage3d 00114 { 00115 // The number of rows in the image. 00116 int nrows; 00117 // The number of columns in the image. 00118 int ncols; 00119 // The number of bytes between the beginning of a row and the beginning 00120 // of the following row 00121 int rowinc; 00122 // The area for the pixel data. This must be numRows * numCols bytes 00123 // large. 00124 TriclopsPoint3d* points; 00125 00126 } TriclopsImage3d; 00127 00128 // 00129 // Name: TriclopsTransform 00130 // 00131 // Description: 00132 // A transformation matrix. 00133 // 00134 // 00135 typedef struct 00136 { 00137 double matrix[4][4]; 00138 00139 } TriclopsTransform; 00140 00141 //============================================================================= 00142 // Function Prototypes 00143 //============================================================================= 00144 // 00145 // Group = 3D 00146 00147 // 00148 // Name: triclopsRCDToXYZ 00149 // 00150 // Synopsis: 00151 // Converts image coordinates with disparity values that have been mapped 00152 // using the disparity mapping function into true 3D points. 00153 // 00154 // Input: 00155 // context - The stereo context. 00156 // row - The row of the input pixel. 00157 // col - The column of the input pixel. 00158 // disp - The disparity value of the input pixel. 00159 // 00160 // Output: 00161 // x - The x coordinate of the point represented by the input row column 00162 // disparity in the camera coordinate system. 00163 // y - The y coordinate of the point represented by the input row column 00164 // disparity in the camera coordinate system. 00165 // z - The z coordinate of the point represented by the input row 00166 // column disparity in the camera coordinate system. 00167 // 00168 // Returns: 00169 // TriclopsErrorOk - The operation succeeded. 00170 // InvalidContext - The input context was invalid. 00171 // 00172 // Description: 00173 // This function takes disparity values that have been scaled by the disparity 00174 // mapping feature. 00175 // 00176 // Remarks: 00177 // If you do not have the disparity mapping values set to 00178 // the same as the disparity values, you should use this function. However, 00179 // it is less efficient than the other XYZ conversion functions and may have 00180 // some round-off errors. It is preferable to set the disparity mapping range 00181 // to the same as the disparity range and use one of the other conversion 00182 // functions. 00183 // 00184 // It is up to the user to supply valid pixel locations. Pixels that have 00185 // been invalidated may give negative results. 00186 // 00187 // Disparity offset SHOULD NOT be applied to input disp values. In this 00188 // way, users can step through a disparity image calling this function 00189 // and passing image disparity values straight in with no changes. 00190 // 00191 // See Also: 00192 // triclopsRCDFloatToXYZ(), triclopsRCD8ToXYZ(), triclopsRCD16ToXYZ() 00193 // 00194 TriclopsError 00195 triclopsRCDToXYZ( TriclopsContext context, 00196 float row, 00197 float col, 00198 float disp, 00199 float* x, 00200 float* y, 00201 float* z ); 00202 00203 // 00204 // Name: triclopsRCDMappedToXYZ 00205 // 00206 // Synopsis: 00207 // Converts image coordinates with disparity values that have been mapped 00208 // using the disparity mapping function into true 3D points. 00209 // 00210 // Input: 00211 // context - The stereo context. 00212 // row - The row of the input pixel. 00213 // col - The column of the input pixel. 00214 // disp - The disparity value of the input pixel. 00215 // 00216 // Output: 00217 // x - The x coordinate of the point represented by the input row 00218 // column disparity in the camera coordinate system. 00219 // y - The y coordinate of the point represented by the input row 00220 // column disparity in the camera coordinate system. 00221 // z - The z coordinate of the point represented by the input row 00222 // column disparity in the camera coordinate system. 00223 // 00224 // Returns: 00225 // TriclopsErrorOk - The operation succeeded. 00226 // InvalidContext - The input context was invalid. 00227 // 00228 // Description: 00229 // This function takes disparity values that have been scaled by the disparity 00230 // mapping feature. 00231 // 00232 // Remarks: 00233 // If you do not have the disparity mapping values set to the same as the 00234 // disparity values, you should use this function. However, it is less 00235 // efficient than the other XYZ conversion functions and may have some 00236 // round-off errors. It is preferable to set the disparity mapping range 00237 // to the same as the disparity range and use one of the other conversion 00238 // functions. 00239 // 00240 // It is up to the user to supply valid pixel locations. Pixels that have 00241 // been invalidated may give negative results. 00242 // 00243 // Disparity offset SHOULD NOT be applied to input disp values. In this 00244 // way, users can step through a disparity image calling this function 00245 // and passing image disparity values straight in with no changes. 00246 // 00247 // See Also: 00248 // triclopsRCDFloatToXYZ(), triclopsRCD8ToXYZ(), triclopsRCD16ToXYZ() 00249 // 00250 TriclopsError 00251 triclopsRCDMappedToXYZ( TriclopsContext context, 00252 int row, 00253 int col, 00254 unsigned char disp, 00255 float* x, 00256 float* y, 00257 float* z ); 00258 00259 // 00260 // Name: triclopsRCDFloatToXYZ 00261 // 00262 // Synopsis: 00263 // Converts image coordinates and a floating-point disparity value into true 00264 // 3D points. 00265 // 00266 // Input: 00267 // context - The stereo context. 00268 // row - The row of the input pixel. 00269 // col - The column of the input pixel. 00270 // disp - The disparity value of the input pixel. 00271 // 00272 // Output: 00273 // x - The x coordinate of the point represented by the input row 00274 // column disparity in the camera coordinate system. 00275 // y - The y coordinate of the point represented by the input row 00276 // column disparity in the camera coordinate system. 00277 // z - The z coordinate of the point represented by the input row 00278 // column disparity in the camera coordinate system. 00279 // 00280 // Returns: 00281 // TriclopsErrorOk - The operation succeeded. 00282 // InvalidContext - The input context was invalid. 00283 // 00284 // Description: 00285 // This function takes a floating-point disparity value and converts it to 00286 // XYZ coordinates. 00287 // 00288 // Remarks: 00289 // It is up to the user to supply valid pixel locations. Pixels which 00290 // have been invalidated may give negative results. 00291 // 00292 // Disparity offset MUST be applied to input disp values, if offset != 0, 00293 // in order to produce valid XYZ values. 00294 // 00295 // See Also: 00296 // triclopsRCDMappedToXYZ(), triclopsRCD8ToXYZ(), triclopsRCD16ToXYZ(), 00297 // triclopsGetDisparityOffset() 00298 // 00299 TriclopsError 00300 triclopsRCDFloatToXYZ( TriclopsContext context, 00301 float row, 00302 float col, 00303 float disp, 00304 float* x, 00305 float* y, 00306 float* z ); 00307 00308 // 00309 // Name: triclopsRCD8ToXYZ 00310 // 00311 // Synopsis: 00312 // Converts image coordinates and an *-bit disparity into true 3D points. 00313 // 00314 // Input: 00315 // context - The stereo context. 00316 // row - The row of the input pixel. 00317 // col - The column of the input pixel. 00318 // disp - The disparity value of the input pixel. 00319 // 00320 // Output: 00321 // x - The x coordinate of the point represented by the input row 00322 // column disparity in the camera coordinate system. 00323 // y - The y coordinate of the point represented by the input row 00324 // column disparity in the camera coordinate system. 00325 // z - The z coordinate of the point represented by the input row 00326 // column disparity in the camera coordinate system. 00327 // 00328 // Returns: 00329 // TriclopsErrorOk - The operation succeeded. 00330 // InvalidContext - The input context was invalid. 00331 // 00332 // Description: 00333 // When using this function, you should ensure that the values for the 00334 // Triclops disparity mapping feature are the same as the disparity range. 00335 // 00336 // Remarks: 00337 // It is up to the user to supply valid pixel locations. Pixels that have 00338 // been invalidated may give negative results. 00339 // 00340 // Disparity offset SHOULD NOT be applied to input disp values. In this 00341 // way, users can step through a disparity image calling this function 00342 // and passing image disparity values straight in with no changes. 00343 // 00344 // See Also: 00345 // triclopsRCDFloatToXYZ(), triclopsRCDMappedToXYZ(), triclopsRCD16ToXYZ(), 00346 // triclopsSetDisparity(), triclopsSetDisparityMapping(), 00347 // triclopsGetDisparityOffset() 00348 // 00349 TriclopsError 00350 triclopsRCD8ToXYZ( TriclopsContext context, 00351 int row, 00352 int col, 00353 unsigned char disp, 00354 float* x, 00355 float* y, 00356 float* z ); 00357 00358 // 00359 // Name: triclopsRCD16ToXYZ 00360 // 00361 // Synopsis: 00362 // Converts image coordinates and a 16-bit disparity into true 3D points. 00363 // 00364 // Input: 00365 // context - The stereo context. 00366 // row - The row of the input pixel. 00367 // col - The column of the input pixel. 00368 // disp - The disparity value of the input pixel. 00369 // 00370 // Output: 00371 // x - The x coordinate of the point represented by the input 00372 // row column disparity in the camera coordinate system. 00373 // y - The y coordinate of the point represented by the input 00374 // row column disparity in the camera coordinate system. 00375 // z - The z coordinate of the point represented by the input 00376 // row column disparity in the camera coordinate system. 00377 // 00378 // Returns: 00379 // TriclopsErrorOk - The operation succeeded. 00380 // InvalidContext - The input context was invalid. 00381 // 00382 // Description: 00383 // When using this function, you should ensure that the values for the 00384 // Triclops disparity mapping feature are the same as the disparity range. 00385 // 00386 // Remarks: 00387 // It is up to the user to supply valid pixel locations. Pixels that have 00388 // been invalidated may give negative results. 00389 // 00390 // Disparity offset SHOULD NOT be applied to input disp values. In this 00391 // way, users can step through a disparity image calling this function 00392 // and passing image disparity values straight in with no changes. 00393 // 00394 // See Also: 00395 // triclopsRCDFloatToXYZ(), triclopsRCDMappedToXYZ(), triclopsRCD8ToXYZ(), 00396 // triclopsSetDisparity(), triclopsSetDisparityMapping() 00397 // triclopsGetDisparityOffset() 00398 // 00399 // 00400 TriclopsError 00401 triclopsRCD16ToXYZ( TriclopsContext context, 00402 int row, 00403 int col, 00404 unsigned short disp, 00405 float* x, 00406 float* y, 00407 float* z ); 00408 00409 // 00410 // Name: triclopsXYZToRCD 00411 // 00412 // Synopsis: 00413 // Converts true 3D points into image coordinates. 00414 // 00415 // Input: 00416 // context - TriclopsContext set up for desired resolution. 00417 // x - X value of a point in the Triclops coordinate system. 00418 // y - Y value of a point in the Triclops coordinate system. 00419 // z - Z value of a point in the Triclops coordinate system. 00420 // 00421 // Output: 00422 // row - The row in a disparity image. 00423 // col - The column in a disparity image. 00424 // disp - The disparity value that would match the point specified in XYZ. 00425 // 00426 // Returns: 00427 // TriclopsErrorOk - The Operation succeeded. 00428 // TriclopsErrorInvalidContext - Context is not valid TriclopsContext. 00429 // TriclopsErrorInvalidRequest - An impossible XYZ value has been provided 00430 // (ie: negative Z). 00431 // 00432 // Description: 00433 // This function takes as input the XYZ position of a point in the Triclops 00434 // coordinate system, and determines what row, column, and disparity value 00435 // would result from a sensed point at XYZ. 00436 // 00437 TriclopsError 00438 triclopsXYZToRCD( TriclopsContext context, 00439 float x, 00440 float y, 00441 float z, 00442 float* row, 00443 float* col, 00444 float* disp ); 00445 00446 // 00447 // Name: triclopsRCDToWorldXYZ 00448 // 00449 // Synopsis: 00450 // Converts image coordinates and disparity values to world 3D points. 00451 // 00452 // Input: 00453 // context - The stereo context. 00454 // row - The row of the input pixel. 00455 // col - The column of the input pixel. 00456 // disp - The disparity value of the input pixel. 00457 // 00458 // Output: 00459 // x - The x coordinate of the corresponding 3D point in the world 00460 // coordinate system 00461 // y - The y coordinate of the corresponding 3D point in the world 00462 // coordinate system 00463 // z - The z coordinate of the corresponding 3D point in the world 00464 // coordinate system 00465 // 00466 // Returns: 00467 // TriclopsErrorOk - The operation succeeded. 00468 // InvalidContext - The input context was invalid. 00469 // 00470 // Description: 00471 // This function takes a pixel location and matching disparity value and 00472 // calculates the 3D position that this combination represents. The 00473 // position is calculated in the "world" coordinate system. That is to say, 00474 // the position is calculated in the Triclops coordinate system and then 00475 // transformed by the TriclopsContext transform to a new coordinate system. 00476 // 00477 // Remarks: 00478 // It is up to the user to supply valid disparity values. Values 00479 // taken from invalid pixels in the disparity image give negative 00480 // results. 00481 // 00482 // Disparity offset SHOULD NOT be applied to input disp values. In this 00483 // way, users can step through a disparity image calling this function 00484 // and passing image disparity values straight in with no changes. 00485 // 00486 // See Also: 00487 // triclopsRCDFloatToXYZ(), triclopsRCD8ToXYZ(), triclopsRCD16ToXYZ(), 00488 // triclopsRCDFloatToWorldXYZ(), triclopsRCD8ToWorldXYZ(), 00489 // triclopsRCD16ToWorldXYZ(), triclopsSetTriclopsToWorldTransform(), 00490 // triclopsGetTriclopsToWorldTransform(), triclopsGetDisparityOffset() 00491 // 00492 TriclopsError 00493 triclopsRCDToWorldXYZ( TriclopsContext context, 00494 float row, 00495 float col, 00496 float disp, 00497 float* x, 00498 float* y, 00499 float* z ); 00500 00501 // 00502 // Name: triclopsRCDMappedToWorldXYZ 00503 // 00504 // Synopsis: 00505 // Converts image coordinates with disparity values that have been mapped 00506 // using the disparity mapping function into world 3D points. 00507 // 00508 // Input: 00509 // context - The stereo context. 00510 // row - The row of the input pixel. 00511 // col - The column of the input pixel. 00512 // disp - The disparity value of the input pixel. 00513 // 00514 // Output: 00515 // x - The x coordinate of the point represented by the input row 00516 // column disparity in the camera coordinate system. 00517 // y - The y coordinate of the point represented by the input row 00518 // column disparity in the camera coordinate system. 00519 // z - The z coordinate of the point represented by the input row 00520 // column disparity in the camera coordinate system. 00521 // 00522 // Returns: 00523 // TriclopsErrorOk - The operation succeeded. 00524 // InvalidContext - The input context was invalid. 00525 // 00526 // Description: 00527 // This function takes disparity values that have been scaled by the 00528 // disparity mapping feature and transforms them into a "world" 00529 // coordinate system based on the transform recorded in the TriclopsContext. 00530 // 00531 // Remarks: 00532 // If you have set "Disparity Mapping" on you should use this function. 00533 // However, it is less efficient than the other XYZ conversion functions and 00534 // may have some round-off errors. It is preferable to set the disparity 00535 // mapping off. 00536 // 00537 // It is up to the user to supply valid disparity values, invalid 00538 // disparity values (as taken from an invalid pixel in the a disparity 00539 // image) may give negative results. 00540 // 00541 // Disparity offset SHOULD NOT be applied to input disp values. In this 00542 // way, users can step through a disparity image calling this function 00543 // and passing image disparity values straight in with no changes. 00544 // 00545 // See Also: 00546 // triclopsRCDFloatToXYZ(), triclopsRCD8ToXYZ(), triclopsRCD16ToXYZ() 00547 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00548 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00549 // triclopsSetTriclopsToWorldTransform(), triclopsGetTriclopsToWorldTransform() 00550 // triclopsGetDisparityOffset() 00551 // 00552 TriclopsError 00553 triclopsRCDMappedToWorldXYZ( TriclopsContext context, 00554 int row, 00555 int col, 00556 unsigned char disp, 00557 float* x, 00558 float* y, 00559 float* z ); 00560 00561 // 00562 // Name: triclopsRCDFloatToWorldXYZ 00563 // 00564 // Synopsis: 00565 // Converts an image location and a floating-point disparity value into a 00566 // world 3D point. 00567 // 00568 // Input: 00569 // context - The stereo context. 00570 // row - The row of the input pixel. 00571 // col - The column of the input pixel. 00572 // disp - The disparity value of the input pixel. 00573 // 00574 // Output: 00575 // x - The x coordinate of the corresponding 3D point 00576 // y - The y coordinate of the corresponding 3D point 00577 // z - The z coordinate of the corresponding 3D point 00578 // 00579 // Returns: 00580 // TriclopsErrorOk - The operation succeeded. 00581 // InvalidContext - The input context was invalid. 00582 // 00583 // Description: 00584 // This function takes a floating-point disparity value and converts it to 00585 // XYZ coordinates in world coordinates. 00586 // 00587 // Remarks: 00588 // The world coordinates are determined by transforming the point from the 00589 // Triclops coordinate system to the world coordinate system based on the 00590 // TriclopsContext transform. 00591 // 00592 // It is up to the user to supply valid disparity values. 00593 // 00594 // Disparity offset MUST be applied to input disp values, if offset != 0, 00595 // in order to produce valid XYZ values. 00596 // 00597 // See Also: 00598 // triclopsRCDMappedToXYZ(), triclopsRCD8ToXYZ(), triclopsRCD16ToXYZ() 00599 // triclopsRCDToWorldXYZ(), 00600 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00601 // triclopsSetTriclopsToWorldTransform(), triclopsGetTriclopsToWorldTransform() 00602 // triclopsGetDisparityOffset() 00603 // 00604 TriclopsError 00605 triclopsRCDFloatToWorldXYZ( TriclopsContext context, 00606 float row, 00607 float col, 00608 float disp, 00609 float* x, 00610 float* y, 00611 float* z ); 00612 00613 // 00614 // Name: triclopsRCD8ToWorldXYZ 00615 // 00616 // Synopsis: 00617 // Converts image coordinates and an 8-bit disparity into a world 3D point. 00618 // 00619 // Input: 00620 // context - The stereo context. 00621 // row - The row of the input pixel. 00622 // col - The column of the input pixel. 00623 // disp - The disparity value of the input pixel. 00624 // 00625 // Output: 00626 // x - The x coordinate of the corresponding 3D point 00627 // y - The y coordinate of the corresponding 3D point 00628 // z - The z coordinate of the corresponding 3D point 00629 // 00630 // Returns: 00631 // TriclopsErrorOk - The operation succeeded. 00632 // InvalidContext - The input context was invalid. 00633 // 00634 // Description: 00635 // This function takes an 8-bit disparity value and converts it to 00636 // XYZ coordinates in world coordinates. The world coordinates are determined 00637 // by transforming the point from the Triclops coordinate system to the 00638 // world coordinate system based on the TriclopsContext transform. 00639 // 00640 // Remarks: 00641 // It is up to the user to supply valid disparity values 00642 // 00643 // Disparity offset SHOULD NOT be applied to input disp values. In this 00644 // way, users can step through a disparity image calling this function 00645 // and passing image disparity values straight in with no changes. 00646 // 00647 // See Also: 00648 // triclopsRCDFloatToXYZ(), triclopsRCDMappedToXYZ(), triclopsRCD16ToXYZ(), 00649 // triclopsSetDisparity(), triclopsSetDisparityMapping() 00650 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00651 // triclopsRCD16ToWorldXYZ(), 00652 // triclopsSetTriclopsToWorldTransform(), triclopsGetTriclopsToWorldTransform() 00653 // triclopsGetDisparityOffset() 00654 // 00655 TriclopsError 00656 triclopsRCD8ToWorldXYZ( TriclopsContext context, 00657 int row, 00658 int col, 00659 unsigned char disp, 00660 float* x, 00661 float* y, 00662 float* z ); 00663 00664 // 00665 // Name: triclopsRCD16ToWorldXYZ 00666 // 00667 // Synopsis: 00668 // Converts image coordinates and a 16-bit disparity into a world 3D point. 00669 // 00670 // Input: 00671 // context - The stereo context. 00672 // row - The row of the input pixel. 00673 // col - The column of the input pixel. 00674 // disp - The disparity value of the input pixel. 00675 // 00676 // Output: 00677 // x - The x coordinate of the corresponding 3D point 00678 // y - The y coordinate of the corresponding 3D point 00679 // z - The z coordinate of the corresponding 3D point 00680 // 00681 // Returns: 00682 // TriclopsErrorOk - The operation succeeded. 00683 // InvalidContext - The input context was invalid. 00684 // 00685 // Description: 00686 // This function takes a 16-bit disparity value and converts it to 00687 // XYZ coordinates in world coordinates. The world coordinates are determined 00688 // by transforming the point from the Triclops coordinate system to the 00689 // world coordinate system based on the TriclopsContext transform. 00690 // 00691 // Remarks: 00692 // It is up to the user to supply valid disparity values 00693 // 00694 // Disparity offset SHOULD NOT be applied to input disp values. In this 00695 // way, users can step through a disparity image calling this function 00696 // and passing image disparity values straight in with no changes. 00697 // 00698 // See Also: 00699 // triclopsRCDFloatToXYZ(), triclopsRCDMappedToXYZ(), triclopsRCD8ToXYZ(), 00700 // triclopsRCD16ToXYZ(), 00701 // triclopsSetDisparity(), triclopsSetDisparityMapping() 00702 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00703 // triclopsRCD8ToWorldXYZ(), 00704 // triclopsSetTriclopsToWorldTransform(), triclopsGetTriclopsToWorldTransform() 00705 // triclopsGetDisparityOffset() 00706 // 00707 // 00708 TriclopsError 00709 triclopsRCD16ToWorldXYZ( TriclopsContext context, 00710 int row, 00711 int col, 00712 unsigned short disp, 00713 float* x, 00714 float* y, 00715 float* z ); 00716 00717 // 00718 // Name: triclopsWorldXYZToRCD 00719 // 00720 // Synopsis: 00721 // Converts world 3D points into image coordinates. 00722 // 00723 // Input: 00724 // context - TriclopsContext set up for desired resolution. 00725 // x - X value of a point in the World coordinate system. 00726 // y - Y value of a point in the World coordinate system. 00727 // z - Z value of a point in the World coordinate system. 00728 // 00729 // Output: 00730 // row - The row in a disparity image. 00731 // col - The column in a disparity image. 00732 // disp - The disparity value that would match the point specified in XYZ. 00733 // 00734 // Returns: 00735 // TriclopsErrorOk - The Operation succeeded. 00736 // TriclopsErrorInvalidContext - Context is not valid TriclopsContext. 00737 // TriclopsErrorInvalidRequest - An impossible XYZ value has been provided 00738 // (ie: negative Z). 00739 // 00740 // Description: 00741 // This function takes as input the XYZ position of a point in the World 00742 // coordinate system, moves the point to the Triclops coordinate system 00743 // (as described by the TriclopsContext transform), and determines what 00744 // row, column, and disparity value would result from the resulting point. 00745 // 00746 // See Also: 00747 // triclopsRCDFloatToXYZ(), triclopsRCDMappedToXYZ(), triclopsRCD8ToXYZ(), 00748 // triclopsSetDisparity(), triclopsSetDisparityMapping() 00749 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00750 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00751 // triclopsXYZToRCD(), 00752 // triclopsSetTriclopsToWorldTransform(), triclopsGetTriclopsToWorldTransform() 00753 // 00754 TriclopsError 00755 triclopsWorldXYZToRCD( TriclopsContext context, 00756 float x, 00757 float y, 00758 float z, 00759 float* row, 00760 float* col, 00761 float* disp ); 00762 00763 // 00764 // Name: triclopsSetTriclopsToWorldTransform() 00765 // 00766 // Synopsis: 00767 // Sets the Triclops to World transform. 00768 // 00769 // Input: 00770 // context - the TriclopsContext 00771 // transform - the 4x4 homogeneous transform 00772 // 00773 // Output: 00774 // none 00775 // 00776 // Returns: 00777 // TriclopsErrorOk - The Operation succeeded. 00778 // TriclopsErrorInvalidContext - Context is not valid TriclopsContext. 00779 // TriclopsErrorInvalidRequest - The provided transform matrix has 00780 // a singular rotation component 00781 // 00782 // Description: 00783 // This function sets the internal TriclopsContext transform to match the 00784 // provided transform. 00785 // 00786 // Remarks: 00787 // There are several things to note: 00788 // 00789 // 1. The transform is the Triclops-to-World transform. ie: when this 00790 // transform is applied to a Triclops point, it will change it to a world 00791 // point. 00792 // 00793 // 2. The transform must be of the approved format. This means it has a 3x3 00794 // rotational component that is orthonormal and the bottom row must be of 00795 // format (0 0 0 n). This function will try to normalize the rotational 00796 // component and clean up the bottom row of the matrix. One can verify 00797 // whether modifications to the transform were necessary by obtaining the 00798 // current transform using triclopsGetTriclopsToWorldTransform() and comparing. 00799 // 00800 // See Also: 00801 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00802 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00803 // triclopsWorldXYZToRCD(), triclopsGetTriclopsToWorldTransform() 00804 // triclopsGetTransformFromFile(), triclopsWriteTransformToFile() 00805 // 00806 TriclopsError 00807 triclopsSetTriclopsToWorldTransform( TriclopsContext context, 00808 TriclopsTransform transform ); 00809 00810 // 00811 // Name: triclopsGetTriclopsToWorldTransform() 00812 // 00813 // Synopsis: 00814 // Gets the Triclops to World transform. 00815 // 00816 // Input: 00817 // context - the TriclopsContext 00818 // 00819 // Output: 00820 // transform - the 4x4 homogeneous transform 00821 // 00822 // Returns: 00823 // TriclopsErrorOk - The Operation succeeded. 00824 // TriclopsErrorInvalidContext - Context is not valid TriclopsContext. 00825 // 00826 // Description: 00827 // This function fills in the provided TriclopsTransform structure with the 00828 // current contents of the Triclops to World transform for this 00829 // TriclopsContext 00830 // 00831 // See Also: 00832 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00833 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00834 // triclopsWorldXYZToRCD(), triclopsSetTriclopsToWorldTransform() 00835 // triclopsGetTransformFromFile(), triclopsWriteTransformToFile() 00836 // 00837 TriclopsError 00838 triclopsGetTriclopsToWorldTransform( TriclopsContext context, 00839 TriclopsTransform* transform ); 00840 00841 // 00842 // Name: triclopsGetTransformFromFile() 00843 // 00844 // Synopsis: 00845 // Loads the contents of a TriclopsTransform from the input file. 00846 // 00847 // Input: 00848 // fileName - name of the file from which to load the transform 00849 // 00850 // Output: 00851 // transform - the 4x4 homogeneous transform 00852 // 00853 // Returns: 00854 // TriclopsErrorOk - The Operation succeeded. 00855 // CorruptTransformFile - either the file is not found or it contains invalid fields. 00856 // 00857 // Description: 00858 // This function fills in the provided TriclopsTransform structure based on 00859 // the contents read from the specified file. If the specified file is not 00860 // found, contains invalid fields, the value of CorruptTransformFile will be 00861 // returned. 00862 // 00863 // See Also: 00864 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00865 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00866 // triclopsWorldXYZToRCD(), triclopsSetTriclopsToWorldTransform(), 00867 // triclopsGetTriclopsToWorldTransform(), triclopsWriteTransformToFile 00868 // 00869 TriclopsError 00870 triclopsGetTransformFromFile( char* fileName, 00871 TriclopsTransform* transform ); 00872 00873 // 00874 // Name: triclopsWriteTransformToFile() 00875 // 00876 // Synopsis: 00877 // Saves the contents of a TriclopsTransform to the output file. 00878 // 00879 // Input: 00880 // fileName - name of the file to which to save the transform 00881 // transform - the 4x4 homogeneous transform to save 00882 // 00883 // Output: 00884 // 00885 // Returns: 00886 // TriclopsErrorOk - The Operation succeeded. 00887 // TriclopsErrorInvalidContext - Context is not valid TriclopsContext. 00888 // 00889 // Description: 00890 // This function saves the contents of the specified transform to an 00891 // external file. 00892 // 00893 // See Also: 00894 // triclopsRCDToWorldXYZ(), triclopsRCDFloatToWorldXYZ(), 00895 // triclopsRCD8ToWorldXYZ(), triclopsRCD16ToWorldXYZ(), 00896 // triclopsWorldXYZToRCD(), triclopsSetTriclopsToWorldTransform(), 00897 // triclopsGetTriclopsToWorldTransform(), triclopsGetTransformFromFile 00898 // 00899 TriclopsError 00900 triclopsWriteTransformToFile( char* fileName, 00901 TriclopsTransform* transform ); 00902 00903 // 00904 // Name: triclopsCreateImage3d 00905 // 00906 // Description: 00907 // Allocates a TriclopsImage3d to the correct size as specified by 00908 // the resolution of the TriclopsContext 00909 // 00910 // Input: 00911 // context - The current TriclopsContext. 00912 // ppimage - Pointer to the address of the TriclopsImage3d structure to 00913 // allocate memory for. 00914 // 00915 // Returns: 00916 // TriclopsErrorOk - The operation succeeded. 00917 // TriclopsErrorSystemError - If there was a problem allocating the memory. 00918 // 00919 // See Also: 00920 // triclopsDestroyImage3d(), triclopsExtractImage3d(), 00921 // triclopsExtractWorldImage3d() 00922 // 00923 TriclopsError 00924 triclopsCreateImage3d( TriclopsContext context, 00925 TriclopsImage3d** ppimage ); 00926 00927 // 00928 // Name: triclopsDestroyImage3d 00929 // 00930 // Description: 00931 // Deallocates a TriclopsImage3d allocated by triclopsCreateImage3d() 00932 // 00933 // Input: 00934 // ppimage - Pointer to the address of the TriclopsImage3d structure to 00935 // destroy. 00936 // 00937 // See Also: 00938 // triclopsCreateImage3d(), triclopsExtractImage3d(), 00939 // triclopsExtractWorldImage3d() 00940 // 00941 void 00942 triclopsDestroyImage3d( TriclopsImage3d** ppimage ); 00943 00944 // 00945 // Name: triclopsExtractImage3d 00946 // 00947 // Description: 00948 // Creates a 3D image given the current disparity result of a TriclopsContext 00949 // 00950 // Input: 00951 // context - The current TriclopsContext. 00952 // pimage - Pointer to the TriclopsImage3d structure. 00953 // 00954 // Returns: 00955 // TriclopsErrorOk - The operation succeeded. 00956 // TriclopsErrorInvalidContext - If the context is invalid. 00957 // TriclopsErrorInvalidParameter - If there is a geometry mismatch between 00958 // the context and the TriclopsImage3d. 00959 // TriclopsErrorInvalidRequest - If the (subpixel) disparity image does 00960 // not match the current resolution. 00961 // 00962 // Remarks: 00963 // Invalid points will be assigned the value of (0,0,0) in the returned image. 00964 // 00965 // See Also: 00966 // triclopsDestroyImage3d(), triclopsCreateImage3d(), 00967 // triclopsExtractWorldImage3d() 00968 // 00969 TriclopsError 00970 triclopsExtractImage3d( TriclopsContext context, 00971 TriclopsImage3d* pimage ); 00972 00973 // 00974 // Name: triclopsExtractWorldImage3d 00975 // 00976 // Description: 00977 // Creates a 3D image given the current disparity result of a TriclopsContext 00978 // that is transformed to the world coordinate system 00979 // 00980 // Input: 00981 // context - The current TriclopsContext. 00982 // pimage - Pointer to the TriclopsImage3d structure. 00983 // 00984 // Returns: 00985 // TriclopsErrorOk - The operation succeeded. 00986 // TriclopsErrorInvalidContext - If the context is invalid. 00987 // TriclopsErrorInvalidParameter - If there is a geometry mismatch between 00988 // the context and the TriclopsImage3d. 00989 // TriclopsErrorInvalidRequest - If the (subpixel) disparity image does 00990 // not match the current resolution. 00991 // 00992 // Remarks: 00993 // Invalid points will be assigned the value of (0,0,0) in the returned image. 00994 // 00995 // See Also: 00996 // triclopsDestroyImage3d(), triclopsCreateImage3d(), 00997 // triclopsExtractImage3d() 00998 // 00999 TriclopsError 01000 triclopsExtractWorldImage3d( TriclopsContext context, 01001 TriclopsImage3d* pimage ); 01002 01003 01004 #ifdef __cplusplus 01005 } 01006 #endif 01007 01008 #endif // #ifndef TRICLOPS3D_H