JeVois  1.22
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Loading...
Searching...
No Matches
Coordinates.H
Go to the documentation of this file.
1// ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2//
3// JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4// California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5//
6// This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7// redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8// Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9// without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10// License for more details. You should have received a copy of the GNU General Public License along with this program;
11// if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12//
13// Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14// Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15// ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16/*! \file */
17
18#pragma once
19
21
22//! Main namespace for all JeVois classes and functions
23/*! See [Topics](http://jevois.org/doc/html/topics.html) for more details. */
24namespace jevois
25{
26 //! Namespace for helper functions to convert coordinates from camera resolution to standardized
27 /*! See \ref coordhelpers for more details. */
28 namespace coords
29 {
30 /*! \defgroup coordhelpers Helper functions to convert coordinates from camera resolution to standardized
31
32 Different machine vision algorithms in JeVois may be able to operate with different camera resolutions, such as
33 1280x1024, 320x240, or 176x144. When some item of interest is detected in the camera frame, one may often want
34 to send the coordinates of that thing to the serial port. This poses a problem if one were to directly send the
35 image coordinates of the item out, which is that now the receiver (e.g., an Arduino) needs to know which camera
36 image resolution was used, so that it can properly interpret these coordinates. For example, if the visual
37 attention (saliency) algorithm is running with 640x480 camera input, then a salient object at the center of the
38 camera's field of view would have coordinates 320,240. But if the same saliency algorithm is configured to
39 process 320x240 input video (so that it can run at a higher framerate), now an object at the center of the field
40 of view would have coordinates 160,120. If one connects an Arduino that controls, for example, a pan/tilt head
41 to JeVois, we need a way to communicate coordinates of target objects in the world independently of the video
42 resolution used by the camera.
43
44 Thus, JeVois defines a standardized coordinate system, as follows:
45
46 - center fo the camera's field of view is at x=0, y=0
47 - left edge of the camera image is always at x=-1000
48 - right edge of the camera image is always at x=1000
49 - top edge of the camera image is usually at y=-750
50 - bottom edge of the camera image is usually at y=750
51
52 Note that the value of 750 here comes from the assumption of a 4:3 aspect ratio for the camera sensor, and is
53 actually defined in JEVOIS_CAMERA_ASPECT. All camera sensor resolutions use 4:3 aspect ratio and hence have y
54 values between -750 and 750, except for 1280x1024, which has y values between -800 and 800.
55
56 When writing a machine vision algorithm that sends over serial the coordinates of things detected in the camera
57 frames, be sure to first transform those coordinates from image to standardized space.
58
59 For more on how standardized coordinates are used to communicate with embedded controllers, and for 3D
60 coordinates, see \ref UserSerialStyle
61
62 \ingroup utils */
63
64 //! Aspect ratio of the JeVois camera
65 /*! \ingroup coordhelpers */
66#ifdef JEVOIS_PRO
67#define JEVOIS_CAMERA_ASPECT (16.0 / 9.0)
68#else
69#define JEVOIS_CAMERA_ASPECT (4.0 / 3.0)
70#endif
71
72 //! Transform coordinates in-place from camera to standardized, using a RawImage to establish image size
73 /*! The RawImage from the camera is used to specify pixel width and height of the camera image, and this is the
74 source coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000]
75 and y in [-750 ... 750].
76
77 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
78 values over serial port.
79
80 \ingroup coordhelpers */
81 void imgToStd(float & x, float & y, RawImage const & camimg, float const eps = 0.1F);
82
83 //! Transform coordinates in-place from camera to standardized, using given image width and height
84 /*! The width and height are used to specify pixel width and height of the camera image, and this is the source
85 coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000] and y
86 in [-750 ... 750].
87
88 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
89 values over serial port.
90
91 \ingroup coordhelpers */
92 void imgToStd(float & x, float & y, unsigned int const width, unsigned int const height, float const eps = 0.1F);
93
94 //! Transform X coordinate in-place from camera to standardized, using given image width and height
95 /*! The width is used to specify pixel width of the camera image, and this is the source
96 coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000].
97
98 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
99 values over serial port.
100
101 \ingroup coordhelpers */
102 void imgToStdX(float & x, unsigned int const width, float const eps = 0.1F);
103
104 //! Transform Y coordinate in-place from camera to standardized, using given image width and height
105 /*! The height is used to specify pixel height of the camera image, and this is the source
106 coordinate system. The destination coordinate system is the standardized one, with y in [-750 ... 750].
107
108 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
109 values over serial port.
110
111 \ingroup coordhelpers */
112 void imgToStdY(float & y, unsigned int const height, float const eps = 0.1F);
113
114 //! Transform size in-place from camera to standardized, using given image width and height
115 /*! Arguments w and h define the size of an object in pixels, which will be converted to standardized units. The
116 width and height are used to specify pixel width and height of the camera image, and this is the source
117 coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000] and y
118 in [-750 ... 750].
119
120 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
121 values over serial port.
122
123 \ingroup coordhelpers */
124 void imgToStdSize(float & w, float & h, unsigned int const width, unsigned int const height,
125 float const eps = 0.1F);
126
127 //! Transform coordinates in-place from standardized to image, using a RawImage to establish image size
128 /*! The RawImage would typically be from the camera is used to specify pixel width and height of the camera image,
129 and this is the destination coordinate system. The source coordinate system is the standardized one, with x in
130 [-1000 ... 1000] and y in [-750 ... 750].
131
132 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
133 values over serial port.
134
135 \ingroup coordhelpers */
136 void stdToImg(float & x, float & y, RawImage const & camimg, float const eps = 0.1F);
137
138 //! Transform coordinates in-place from standardized to image, using a RawImage to establish image size
139 /*! The width and height would typically be from the camera and are used to specify pixel width and height of the
140 camera image, and this is the destination coordinate system. The source coordinate system is the standardized
141 one, with x in [-1000 ... 1000] and y in [-750 ... 750].
142
143 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
144 values over serial port.
145
146 \ingroup coordhelpers */
147 void stdToImg(float & x, float & y, unsigned int const width, unsigned int const height, float const eps = 0.1F);
148
149 //! Transform size in-place from standardized to image, using a RawImage to establish image size
150 /*! Arguments w and h define the size of an object in standardized units, which will be converted to pixels. The
151 width and height would typically be from the camera and are used to specify pixel width and height of the
152 camera image, and this is the destination coordinate system. The source coordinate system is the standardized
153 one, with x in [-1000 ... 1000] and y in [-750 ... 750].
154
155 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
156 values over serial port.
157
158 \ingroup coordhelpers */
159 void stdToImgSize(float & x, float & y, unsigned int const width, unsigned int const height,
160 float const eps = 0.1F);
161 }
162}
163
int h
Definition GUIhelper.C:2520
void imgToStdX(float &x, unsigned int const width, float const eps=0.1F)
Transform X coordinate in-place from camera to standardized, using given image width and height.
Definition Coordinates.C:36
void stdToImg(float &x, float &y, RawImage const &camimg, float const eps=0.1F)
Transform coordinates in-place from standardized to image, using a RawImage to establish image size.
Definition Coordinates.C:60
void imgToStdY(float &y, unsigned int const height, float const eps=0.1F)
Transform Y coordinate in-place from camera to standardized, using given image width and height.
Definition Coordinates.C:43
void imgToStd(float &x, float &y, RawImage const &camimg, float const eps=0.1F)
Transform coordinates in-place from camera to standardized, using a RawImage to establish image size.
Definition Coordinates.C:22
void imgToStdSize(float &w, float &h, unsigned int const width, unsigned int const height, float const eps=0.1F)
Transform size in-place from camera to standardized, using given image width and height.
Definition Coordinates.C:50
void stdToImgSize(float &x, float &y, unsigned int const width, unsigned int const height, float const eps=0.1F)
Transform size in-place from standardized to image, using a RawImage to establish image size.
Definition Coordinates.C:74
Main namespace for all JeVois classes and functions.
Definition Concepts.dox:2