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 /** Header for a rectification information file (rectinfo).
00040  * The header defines the basic parameters needed to correctly interpret the
00041  * following rectification file data.
00042  *
00043  * It defines a content specific header for the FireVision data file format (fvff).
00044  *
00045  * The header defines a magic by which a rectinfo can be identified. This is
00046  * always FF03 (exactly in that order, no matter on the host systems endianess,
00047  * this has to be stored literally) for FireVision File Format 03. The version
00048  * is stored as a sequential number. This version has to be changed whenever either
00049  * the header or the file data format changes. The file defines the endianess of the
00050  * supplied data, which is important since the mapping in general has to be stored
00051  * at least to 2-byte-sized data fields. There are several reserved bits that may
00052  * be used later to store flags.
00053  *
00054  * The header also carries a globally unique ID of the camera. This allows for checking
00055  * if the file is used for the correct camera. This should be an EUI-64 number supplied
00056  * by the camera, for instance the IEEE1394 GUID. If that is not available for your
00057  * camera type use another distinguishing criterion like a serial number. If even that
00058  * cannot be queried from the camera make one up, for instance a checksum of the
00059  * robot name which carries the camera or even the (shortened) name itself.
00060  * The camera model is stored as a string and can also be used to discriminate a
00061  * specific camera. It can also be used for an easier identification of the camera
00062  * this file belongs to.
00063  *
00064  * Directly following this header the first rectification info is stored. Each info
00065  * has it's own per-info header defining the size of the info which can be read as
00066  * offset to the next info block (if there is one). This is followed by more reserved
00067  * bits. All reserved bits have to be set to zero.
00068  *
00069  * The general layout of the file is the following:
00070  * @code
00071  *   rectinfo_header_t        (file header, at least one block)
00072  *   rectinfo_block_header_t  (info block header, defining size S)
00073  *   [rectinfo_TYPE_block_header_t  (type-specific block header)
00074  *   <data> of size S - sizeof(type-specific-header).
00075  *   optional:
00076  *   rectinfo_block_header_t n
00077  *   <data> of block n
00078  * @endcode
00079  *
00080  * The first version supports only rectification lookup tables (rectlut, rectification LUT).
00081  * For this the block type is set to FIREVISION_RECTINFO_TYPE_LUT_16x16, because each
00082  * mapping consists of two uint16_t values.
00083  */
00084 typedef struct _rectinfo_header_t {
00085   uint64_t guid;                /**< GUID of camera */
00086   char     camera_model[FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH]; /**< camera model */
00087 } rectinfo_header_t;
00088
00089 
00090 /** The per-image rectification info block header.
00091  * A type can be given for the the following data. See rectinfo_block_type_t for the
00092  * possible types. The reserved bits may not be used and have to be set to zero.
00093  * There is also a total size of this info block in bytes. This has to include any
00094  * type specific header and all data stored in that block.
00095  * This maybe used for ignoring info blocks of unknown types and proceeding to the next
00096  * block (if there is one).
00097  * This header is usually followed by another block type specific header. This depends
00098  * on the type of data, see rectinfo_block_type_t.
00099  * A camera identifier is given to specify the image of the camera system. This is
00100  * necessary for instance if all rectificion info blocks of a stereo camera are named
00101  * in one file. The interpretation of this field depends on the used camera. Use the
00102  * constants defined by rectinfo_camera_t whenever possible. If that does not match your
00103  * situtation you may as well use custom IDs. The range [200:220] has been reserved
00104  * for this kind of IDs.
00105  */
00106 typedef struct _rectinfo_block_header_t {
00107   uint32_t camera     :  8;     /**< camera, as specified per rectinfo_camera_t */
00108   uint32_t reserved   : 24;     /**< reserved for future use */
00109 } rectinfo_block_header_t;
00110
00111 
00112 /** Block header for rectification LUTs wit 16-bit values.
00113  * The width and height of the rectification LUT is given. The LUT is assumed to be a
00114  * mapping of pixel coordinates in an image to coordinates in the unrectified image.
00115  * So following this header there have to be exactly width * height cells of
00116  * type rectinfo_lut_16x16_entry_t.
00117  * The rectification then works by iterating of the resulting image and the LUT at
00118  * the same time. For each pixel in the resulting image the pixel mentioned by the
00119  * coordinates in the LUT cell from the original image is copied.
00120  * The maximum LUT size and pixel coordinate values are 65535 (value that can be stored
00121  * in a 16 bit unsigned integer).
00122  */
00123 typedef struct _rectinfo_lut_16x16_block_header_t {
00124   uint16_t width;               /**< width of the LUT file and image */
00125   uint16_t height;              /**< height of the LUT file and image */
00126 } rectinfo_lut_16x16_block_header_t;
00127 
00128 /** Data type used to build a rectification LUT.
00129  * The values are stored in the endianess of the host system.
00130  * The LUT has to be stored in memory line by line (height number of lines), each has
00131  * width number of reclut_lut_entry_t cells. Each cell represents one pixel in the rectified
00132  * image. The coordinates point to pixel coordinates in the unrectified image.
00133  * A simple rectification can thus iterate over the rectified image and the rectification
00134  * LUT and copy the pixel at the coordinates given by the LUT cell to the current
00135  * pixel of the rectified image.
00136  */
00137 typedef struct _rectinfo_lut_16x16_entry_t {
00138   uint16_t x;   /**< map to x pixel coordinate */
00139   uint16_t y;   /**< map to y pixel coordinate */
00140 } rectinfo_lut_16x16_entry_t;
00141
00142 
00143 /** Rectification info block type.
00144  * An info block may come in different types, probably mainly depending on the data type
00145  * but also the data structure may change in future versions.
00146  */
00147 typedef enum _rectinfo_block_type_t {
00148   /* supported by file version 1: */
00149   FIREVISION_RECTINFO_TYPE_INVALID  = 0,        /**< invalid */
00150   FIREVISION_RECTINFO_TYPE_LUT_16x16  = 1       /**< Rectification LUT with 16 bit values,
00151                                                    see rectinfo_lut_16x16_block_header_t */
00152 } rectinfo_block_type_t;
00153
00154 
00155 /** Rectification camera.
00156  * This describes the camera this info block belongs to. This is especially important
00157  * if rectification information of multiple images is stored for one camera, e.g. for
00158  * a stereo camera. The interpretation of this information heavily depends on the
00159  * used camera type. For single-lens cameras use main as the camera identifier.
00160  */
00161 typedef enum _rectinfo_camera_t {
00162   /* supported by file version 1: */
00163   FIREVISION_RECTINFO_CAMERA_MAIN    = 0,       /**< Main image */
00164   FIREVISION_RECTINFO_CAMERA_LEFT    = 1,       /**< Left image */
00165   FIREVISION_RECTINFO_CAMERA_RIGHT   = 2,       /**< Right image */
00166   FIREVISION_RECTINFO_CAMERA_CENTER  = 3,       /**< Center image */
00167   FIREVISION_RECTINFO_CAMERA_TOP     = 4        /**< Top image */
00168 } rectinfo_camera_t;
00169 
00170 /** Rectification camera strings.
00171  * Follows the index in rectinfo_camera_t and gives a string for each of the
00172  * cameras.
00173  */
00174 extern const char* rectinfo_camera_strings[];
00175
00176 extern const char* rectinfo_type_strings[];
00177
00178 #pragma pack(pop)
00179 #endif