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