rectinfo.h

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