Fawkes API  Fawkes Development Version
rectinfo.h
1 
2 /***************************************************************************
3  * rectinfo.h - Rectification info file format
4  *
5  * Created: Tue Oct 30 11:19:35 2007
6  * Copyright 2007 Tim Niemueller [www.niemueller.de]
7  *
8  ****************************************************************************/
9 
10 /* This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version. A runtime exception applies to
14  * this software (see LICENSE.GPL_WRE file mentioned below for details).
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Library General Public License for more details.
20  *
21  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
22  */
23 
24 #ifndef __FIREVISION_FVUTILS_RECTIFICATION_RECTINFO_H_
25 #define __FIREVISION_FVUTILS_RECTIFICATION_RECTINFO_H_
26 
27 #pragma pack(push,4)
28 
29 #ifndef __STDC_LIMIT_MACROS
30 #define __STDC_LIMIT_MACROS
31 #endif
32 #include <stdint.h>
33 
34 #define FIREVISION_RECTINFO_MAGIC 0xFF03
35 #define FIREVISION_RECTINFO_CURVER 2
36 
37 #define FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH 32
38 
39 namespace firevision {
40 #if 0 /* just to make Emacs auto-indent happy */
41 }
42 #endif
43 
44 /** Header for a rectification information file (rectinfo).
45  * The header defines the basic parameters needed to correctly interpret the
46  * following rectification file data.
47  *
48  * It defines a content specific header for the FireVision data file format (fvff).
49  *
50  * The header defines a magic by which a rectinfo can be identified. This is
51  * always FF03 (exactly in that order, no matter on the host systems endianess,
52  * this has to be stored literally) for FireVision File Format 03. The version
53  * is stored as a sequential number. This version has to be changed whenever either
54  * the header or the file data format changes. The file defines the endianess of the
55  * supplied data, which is important since the mapping in general has to be stored
56  * at least to 2-byte-sized data fields. There are several reserved bits that may
57  * be used later to store flags.
58  *
59  * The header also carries a globally unique ID of the camera. This allows for checking
60  * if the file is used for the correct camera. This should be an EUI-64 number supplied
61  * by the camera, for instance the IEEE1394 GUID. If that is not available for your
62  * camera type use another distinguishing criterion like a serial number. If even that
63  * cannot be queried from the camera make one up, for instance a checksum of the
64  * robot name which carries the camera or even the (shortened) name itself.
65  * The camera model is stored as a string and can also be used to discriminate a
66  * specific camera. It can also be used for an easier identification of the camera
67  * this file belongs to.
68  *
69  * Directly following this header the first rectification info is stored. Each info
70  * has it's own per-info header defining the size of the info which can be read as
71  * offset to the next info block (if there is one). This is followed by more reserved
72  * bits. All reserved bits have to be set to zero.
73  *
74  * The general layout of the file is the following:
75  * @code
76  * rectinfo_header_t (file header, at least one block)
77  * rectinfo_block_header_t (info block header, defining size S)
78  * [rectinfo_TYPE_block_header_t (type-specific block header)
79  * <data> of size S - sizeof(type-specific-header).
80  * optional:
81  * rectinfo_block_header_t n
82  * <data> of block n
83  * @endcode
84  *
85  * The first version supports only rectification lookup tables (rectlut, rectification LUT).
86  * For this the block type is set to FIREVISION_RECTINFO_TYPE_LUT_16x16, because each
87  * mapping consists of two uint16_t values.
88  */
89 typedef struct _rectinfo_header_t {
90  uint64_t guid; /**< GUID of camera */
91  char camera_model[FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH]; /**< camera model */
93 
94 
95 /** The per-image rectification info block header.
96  * A type can be given for the the following data. See rectinfo_block_type_t for the
97  * possible types. The reserved bits may not be used and have to be set to zero.
98  * There is also a total size of this info block in bytes. This has to include any
99  * type specific header and all data stored in that block.
100  * This maybe used for ignoring info blocks of unknown types and proceeding to the next
101  * block (if there is one).
102  * This header is usually followed by another block type specific header. This depends
103  * on the type of data, see rectinfo_block_type_t.
104  * A camera identifier is given to specify the image of the camera system. This is
105  * necessary for instance if all rectificion info blocks of a stereo camera are named
106  * in one file. The interpretation of this field depends on the used camera. Use the
107  * constants defined by rectinfo_camera_t whenever possible. If that does not match your
108  * situtation you may as well use custom IDs. The range [200:220] has been reserved
109  * for this kind of IDs.
110  */
111 typedef struct _rectinfo_block_header_t {
112  uint32_t camera : 8; /**< camera, as specified per rectinfo_camera_t */
113  uint32_t reserved : 24; /**< reserved for future use */
115 
116 
117 /** Block header for rectification LUTs wit 16-bit values.
118  * The width and height of the rectification LUT is given. The LUT is assumed to be a
119  * mapping of pixel coordinates in an image to coordinates in the unrectified image.
120  * So following this header there have to be exactly width * height cells of
121  * type rectinfo_lut_16x16_entry_t.
122  * The rectification then works by iterating of the resulting image and the LUT at
123  * the same time. For each pixel in the resulting image the pixel mentioned by the
124  * coordinates in the LUT cell from the original image is copied.
125  * The maximum LUT size and pixel coordinate values are 65535 (value that can be stored
126  * in a 16 bit unsigned integer).
127  */
129  uint16_t width; /**< width of the LUT file and image */
130  uint16_t height; /**< height of the LUT file and image */
132 
133 /** Data type used to build a rectification LUT.
134  * The values are stored in the endianess of the host system.
135  * The LUT has to be stored in memory line by line (height number of lines), each has
136  * width number of reclut_lut_entry_t cells. Each cell represents one pixel in the rectified
137  * image. The coordinates point to pixel coordinates in the unrectified image.
138  * A simple rectification can thus iterate over the rectified image and the rectification
139  * LUT and copy the pixel at the coordinates given by the LUT cell to the current
140  * pixel of the rectified image.
141  */
143  uint16_t x; /**< map to x pixel coordinate */
144  uint16_t y; /**< map to y pixel coordinate */
146 
147 
148 /** Rectification info block type.
149  * An info block may come in different types, probably mainly depending on the data type
150  * but also the data structure may change in future versions.
151  */
152 typedef enum _rectinfo_block_type_t {
153  /* supported by file version 1: */
154  FIREVISION_RECTINFO_TYPE_INVALID = 0, /**< invalid */
155  FIREVISION_RECTINFO_TYPE_LUT_16x16 = 1 /**< Rectification LUT with 16 bit values,
156  see rectinfo_lut_16x16_block_header_t */
157 } rectinfo_block_type_t;
158 
159 
160 /** Rectification camera.
161  * This describes the camera this info block belongs to. This is especially important
162  * if rectification information of multiple images is stored for one camera, e.g. for
163  * a stereo camera. The interpretation of this information heavily depends on the
164  * used camera type. For single-lens cameras use main as the camera identifier.
165  */
166 typedef enum _rectinfo_camera_t {
167  /* supported by file version 1: */
168  FIREVISION_RECTINFO_CAMERA_MAIN = 0, /**< Main image */
169  FIREVISION_RECTINFO_CAMERA_LEFT = 1, /**< Left image */
170  FIREVISION_RECTINFO_CAMERA_RIGHT = 2, /**< Right image */
171  FIREVISION_RECTINFO_CAMERA_CENTER = 3, /**< Center image */
172  FIREVISION_RECTINFO_CAMERA_TOP = 4 /**< Top image */
173 } rectinfo_camera_t;
174 
175 /** Rectification camera strings.
176  * Follows the index in rectinfo_camera_t and gives a string for each of the
177  * cameras.
178  */
179 extern const char* rectinfo_camera_strings[];
180 
181 extern const char* rectinfo_type_strings[];
182 
183 } // end namespace firevision
184 
185 #pragma pack(pop)
186 #endif
uint16_t height
height of the LUT file and image
Definition: rectinfo.h:130
char camera_model[FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH]
camera model
Definition: rectinfo.h:91
uint16_t width
width of the LUT file and image
Definition: rectinfo.h:129
uint64_t guid
GUID of camera.
Definition: rectinfo.h:90
Block header for rectification LUTs wit 16-bit values.
Definition: rectinfo.h:128
The per-image rectification info block header.
Definition: rectinfo.h:111
Data type used to build a rectification LUT.
Definition: rectinfo.h:142
uint32_t reserved
reserved for future use
Definition: rectinfo.h:113
uint32_t camera
camera, as specified per rectinfo_camera_t
Definition: rectinfo.h:112
uint16_t y
map to y pixel coordinate
Definition: rectinfo.h:144
Header for a rectification information file (rectinfo).
Definition: rectinfo.h:89
uint16_t x
map to x pixel coordinate
Definition: rectinfo.h:143