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
39namespace 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 */
86typedef 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 */
150typedef 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 */
163typedef 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 */
176extern const char *rectinfo_camera_strings[];
177
178extern const char *rectinfo_type_strings[];
179
180} // end namespace firevision
181
182#pragma pack(pop)
183#endif
The per-image rectification info block header.
Definition: rectinfo.h:109
uint32_t reserved
reserved for future use
Definition: rectinfo.h:111
uint32_t camera
camera, as specified per rectinfo_camera_t
Definition: rectinfo.h:110
Header for a rectification information file (rectinfo).
Definition: rectinfo.h:87
char camera_model[FIREVISION_RECTINFO_CAMERA_MODEL_MAXLENGTH]
camera model
Definition: rectinfo.h:89
uint64_t guid
GUID of camera.
Definition: rectinfo.h:88
Block header for rectification LUTs wit 16-bit values.
Definition: rectinfo.h:126
uint16_t height
height of the LUT file and image
Definition: rectinfo.h:128
uint16_t width
width of the LUT file and image
Definition: rectinfo.h:127
Data type used to build a rectification LUT.
Definition: rectinfo.h:141
uint16_t y
map to y pixel coordinate
Definition: rectinfo.h:143
uint16_t x
map to x pixel coordinate
Definition: rectinfo.h:142