00001 00002 /*************************************************************************** 00003 * rectinfo.h - Rectification info file format 00004 * 00005 * Created: Tue Oct 30 11:19:35 2007 00006 * Copyright 2007 Tim Niemueller [www.niemueller.de] 00007 * 00008 ****************************************************************************/ 00009 00010 /* This program is free software; you can redistribute it and/or modify 00011 * it under the terms of the GNU General Public License as published by 00012 * the Free Software Foundation; either version 2 of the License, or 00013 * (at your option) any later version. A runtime exception applies to 00014 * this software (see LICENSE.GPL_WRE file mentioned below for details). 00015 * 00016 * This program is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 * GNU Library General Public License for more details. 00020 * 00021 * Read the full text in the LICENSE.GPL_WRE file in the doc directory. 00022 */ 00023 00024 #ifndef __FIREVISION_FVUTILS_RECTIFICATION_RECTINFO_H_ 00025 #define __FIREVISION_FVUTILS_RECTIFICATION_RECTINFO_H_ 00026 00027 #pragma pack(push,4) 00028 00029 #ifndef __STDC_LIMIT_MACROS 00030 #define __STDC_LIMIT_MACROS 00031 #endif 00032 #include <stdint.h> 00033 00034 #define FIREVISION_RECTINFO_MAGIC 0xFF03 00035 #define FIREVISION_RECTINFO_CURVER 2 00036 00037 #define FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH 32 00038 00039 namespace firevision { 00040 #if 0 /* just to make Emacs auto-indent happy */ 00041 } 00042 #endif 00043 00044 /** Header for a rectification information file (rectinfo). 00045 * The header defines the basic parameters needed to correctly interpret the 00046 * following rectification file data. 00047 * 00048 * It defines a content specific header for the FireVision data file format (fvff). 00049 * 00050 * The header defines a magic by which a rectinfo can be identified. This is 00051 * always FF03 (exactly in that order, no matter on the host systems endianess, 00052 * this has to be stored literally) for FireVision File Format 03. The version 00053 * is stored as a sequential number. This version has to be changed whenever either 00054 * the header or the file data format changes. The file defines the endianess of the 00055 * supplied data, which is important since the mapping in general has to be stored 00056 * at least to 2-byte-sized data fields. There are several reserved bits that may 00057 * be used later to store flags. 00058 * 00059 * The header also carries a globally unique ID of the camera. This allows for checking 00060 * if the file is used for the correct camera. This should be an EUI-64 number supplied 00061 * by the camera, for instance the IEEE1394 GUID. If that is not available for your 00062 * camera type use another distinguishing criterion like a serial number. If even that 00063 * cannot be queried from the camera make one up, for instance a checksum of the 00064 * robot name which carries the camera or even the (shortened) name itself. 00065 * The camera model is stored as a string and can also be used to discriminate a 00066 * specific camera. It can also be used for an easier identification of the camera 00067 * this file belongs to. 00068 * 00069 * Directly following this header the first rectification info is stored. Each info 00070 * has it's own per-info header defining the size of the info which can be read as 00071 * offset to the next info block (if there is one). This is followed by more reserved 00072 * bits. All reserved bits have to be set to zero. 00073 * 00074 * The general layout of the file is the following: 00075 * @code 00076 * rectinfo_header_t (file header, at least one block) 00077 * rectinfo_block_header_t (info block header, defining size S) 00078 * [rectinfo_TYPE_block_header_t (type-specific block header) 00079 * <data> of size S - sizeof(type-specific-header). 00080 * optional: 00081 * rectinfo_block_header_t n 00082 * <data> of block n 00083 * @endcode 00084 * 00085 * The first version supports only rectification lookup tables (rectlut, rectification LUT). 00086 * For this the block type is set to FIREVISION_RECTINFO_TYPE_LUT_16x16, because each 00087 * mapping consists of two uint16_t values. 00088 */ 00089 typedef struct _rectinfo_header_t { 00090 uint64_t guid; /**< GUID of camera */ 00091 char camera_model[FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH]; /**< camera model */ 00092 } rectinfo_header_t; 00093 00094 00095 /** The per-image rectification info block header. 00096 * A type can be given for the the following data. See rectinfo_block_type_t for the 00097 * possible types. The reserved bits may not be used and have to be set to zero. 00098 * There is also a total size of this info block in bytes. This has to include any 00099 * type specific header and all data stored in that block. 00100 * This maybe used for ignoring info blocks of unknown types and proceeding to the next 00101 * block (if there is one). 00102 * This header is usually followed by another block type specific header. This depends 00103 * on the type of data, see rectinfo_block_type_t. 00104 * A camera identifier is given to specify the image of the camera system. This is 00105 * necessary for instance if all rectificion info blocks of a stereo camera are named 00106 * in one file. The interpretation of this field depends on the used camera. Use the 00107 * constants defined by rectinfo_camera_t whenever possible. If that does not match your 00108 * situtation you may as well use custom IDs. The range [200:220] has been reserved 00109 * for this kind of IDs. 00110 */ 00111 typedef struct _rectinfo_block_header_t { 00112 uint32_t camera : 8; /**< camera, as specified per rectinfo_camera_t */ 00113 uint32_t reserved : 24; /**< reserved for future use */ 00114 } rectinfo_block_header_t; 00115 00116 00117 /** Block header for rectification LUTs wit 16-bit values. 00118 * The width and height of the rectification LUT is given. The LUT is assumed to be a 00119 * mapping of pixel coordinates in an image to coordinates in the unrectified image. 00120 * So following this header there have to be exactly width * height cells of 00121 * type rectinfo_lut_16x16_entry_t. 00122 * The rectification then works by iterating of the resulting image and the LUT at 00123 * the same time. For each pixel in the resulting image the pixel mentioned by the 00124 * coordinates in the LUT cell from the original image is copied. 00125 * The maximum LUT size and pixel coordinate values are 65535 (value that can be stored 00126 * in a 16 bit unsigned integer). 00127 */ 00128 typedef struct _rectinfo_lut_16x16_block_header_t { 00129 uint16_t width; /**< width of the LUT file and image */ 00130 uint16_t height; /**< height of the LUT file and image */ 00131 } rectinfo_lut_16x16_block_header_t; 00132 00133 /** Data type used to build a rectification LUT. 00134 * The values are stored in the endianess of the host system. 00135 * The LUT has to be stored in memory line by line (height number of lines), each has 00136 * width number of reclut_lut_entry_t cells. Each cell represents one pixel in the rectified 00137 * image. The coordinates point to pixel coordinates in the unrectified image. 00138 * A simple rectification can thus iterate over the rectified image and the rectification 00139 * LUT and copy the pixel at the coordinates given by the LUT cell to the current 00140 * pixel of the rectified image. 00141 */ 00142 typedef struct _rectinfo_lut_16x16_entry_t { 00143 uint16_t x; /**< map to x pixel coordinate */ 00144 uint16_t y; /**< map to y pixel coordinate */ 00145 } rectinfo_lut_16x16_entry_t; 00146 00147 00148 /** Rectification info block type. 00149 * An info block may come in different types, probably mainly depending on the data type 00150 * but also the data structure may change in future versions. 00151 */ 00152 typedef enum _rectinfo_block_type_t { 00153 /* supported by file version 1: */ 00154 FIREVISION_RECTINFO_TYPE_INVALID = 0, /**< invalid */ 00155 FIREVISION_RECTINFO_TYPE_LUT_16x16 = 1 /**< Rectification LUT with 16 bit values, 00156 see rectinfo_lut_16x16_block_header_t */ 00157 } rectinfo_block_type_t; 00158 00159 00160 /** Rectification camera. 00161 * This describes the camera this info block belongs to. This is especially important 00162 * if rectification information of multiple images is stored for one camera, e.g. for 00163 * a stereo camera. The interpretation of this information heavily depends on the 00164 * used camera type. For single-lens cameras use main as the camera identifier. 00165 */ 00166 typedef enum _rectinfo_camera_t { 00167 /* supported by file version 1: */ 00168 FIREVISION_RECTINFO_CAMERA_MAIN = 0, /**< Main image */ 00169 FIREVISION_RECTINFO_CAMERA_LEFT = 1, /**< Left image */ 00170 FIREVISION_RECTINFO_CAMERA_RIGHT = 2, /**< Right image */ 00171 FIREVISION_RECTINFO_CAMERA_CENTER = 3, /**< Center image */ 00172 FIREVISION_RECTINFO_CAMERA_TOP = 4 /**< Top image */ 00173 } rectinfo_camera_t; 00174 00175 /** Rectification camera strings. 00176 * Follows the index in rectinfo_camera_t and gives a string for each of the 00177 * cameras. 00178 */ 00179 extern const char* rectinfo_camera_strings[]; 00180 00181 extern const char* rectinfo_type_strings[]; 00182 00183 } // end namespace firevision 00184 00185 #pragma pack(pop) 00186 #endif