JeVois  1.20
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
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 
20 #include <jevois/Image/RawImage.H>
21 
22 namespace jevois
23 {
24  namespace coords
25  {
26  /*! \defgroup coordhelpers Helper functions to convert coordinates from camera resolution to standardized
27 
28  Different machine vision algorithms in JeVois may be able to operate with different camera resolutions, such as
29  1280x1024, 320x240, or 176x144. When some item of interest is detected in the camera frame, one may often want
30  to send the coordinates of that thing to the serial port. This poses a problem if one were to directly send the
31  image coordinates of the item out, which is that now the receiver (e.g., an Arduino) needs to know which camera
32  image resolution was used, so that it can properly interpret these coordinates. For example, if the visual
33  attention (saliency) algorithm is running with 640x480 camera input, then a salient object at the center of the
34  camera's field of view would have coordinates 320,240. But if the same saliency algorithm is configured to
35  process 320x240 input video (so that it can run at a higher framerate), now an object at the center of the field
36  of view would have coordinates 160,120. If one connects an Arduino that controls, for example, a pan/tilt head
37  to JeVois, we need a way to communicate coordinates of target objects in the world independently of the video
38  resolution used by the camera.
39 
40  Thus, JeVois defines a standardized coordinate system, as follows:
41 
42  - center fo the camera's field of view is at x=0, y=0
43  - left edge of the camera image is always at x=-1000
44  - right edge of the camera image is always at x=1000
45  - top edge of the camera image is usually at y=-750
46  - bottom edge of the camera image is usually at y=750
47 
48  Note that the value of 750 here comes from the assumption of a 4:3 aspect ratio for the camera sensor, and is
49  actually defined in JEVOIS_CAMERA_ASPECT. All camera sensor resolutions use 4:3 aspect ratio and hence have y
50  values between -750 and 750, except for 1280x1024, which has y values between -800 and 800.
51 
52  When writing a machine vision algorithm that sends over serial the coordinates of things detected in the camera
53  frames, be sure to first transform those coordinates from image to standardized space.
54 
55  For more on how standardized coordinates are used to communicate with embedded controllers, and for 3D
56  coordinates, see \ref UserSerialStyle
57 
58  \ingroup utils */
59 
60  //! Aspect ratio of the JeVois camera
61  /*! \ingroup coordhelpers */
62 #ifdef JEVOIS_PRO
63 #define JEVOIS_CAMERA_ASPECT (16.0 / 9.0)
64 #else
65 #define JEVOIS_CAMERA_ASPECT (4.0 / 3.0)
66 #endif
67 
68  //! Transform coordinates in-place from camera to standardized, using a RawImage to establish image size
69  /*! The RawImage from the camera is used to specify pixel width and height of the camera image, and this is the
70  source coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000]
71  and y in [-750 ... 750].
72 
73  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
74  values over serial port.
75 
76  \ingroup coordhelpers */
77  void imgToStd(float & x, float & y, RawImage const & camimg, float const eps = 0.1F);
78 
79  //! Transform coordinates in-place from camera to standardized, using given image width and height
80  /*! The width and height are used to specify pixel width and height of the camera image, and this is the source
81  coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000] and y
82  in [-750 ... 750].
83 
84  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
85  values over serial port.
86 
87  \ingroup coordhelpers */
88  void imgToStd(float & x, float & y, unsigned int const width, unsigned int const height, float const eps = 0.1F);
89 
90  //! Transform X coordinate in-place from camera to standardized, using given image width and height
91  /*! The width is used to specify pixel width of the camera image, and this is the source
92  coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000].
93 
94  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
95  values over serial port.
96 
97  \ingroup coordhelpers */
98  void imgToStdX(float & x, unsigned int const width, float const eps = 0.1F);
99 
100  //! Transform Y coordinate in-place from camera to standardized, using given image width and height
101  /*! The height is used to specify pixel height of the camera image, and this is the source
102  coordinate system. The destination coordinate system is the standardized one, with y in [-750 ... 750].
103 
104  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
105  values over serial port.
106 
107  \ingroup coordhelpers */
108  void imgToStdY(float & y, unsigned int const height, float const eps = 0.1F);
109 
110  //! Transform size in-place from camera to standardized, using given image width and height
111  /*! Arguments w and h define the size of an object in pixels, which will be converted to standardized units. The
112  width and height are used to specify pixel width and height of the camera image, and this is the source
113  coordinate system. The destination coordinate system is the standardized one, with x in [-1000 ... 1000] and y
114  in [-750 ... 750].
115 
116  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
117  values over serial port.
118 
119  \ingroup coordhelpers */
120  void imgToStdSize(float & w, float & h, unsigned int const width, unsigned int const height,
121  float const eps = 0.1F);
122 
123  //! Transform coordinates in-place from standardized to image, using a RawImage to establish image size
124  /*! The RawImage would typically be from the camera is used to specify pixel width and height of the camera image,
125  and this is the destination coordinate system. The source coordinate system is the standardized one, with x in
126  [-1000 ... 1000] and y in [-750 ... 750].
127 
128  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
129  values over serial port.
130 
131  \ingroup coordhelpers */
132  void stdToImg(float & x, float & y, RawImage const & camimg, float const eps = 0.1F);
133 
134  //! Transform coordinates in-place from standardized to image, using a RawImage to establish image size
135  /*! The width and height would typically be from the camera and are used to specify pixel width and height of the
136  camera image, and this is the destination coordinate system. The source coordinate system is the standardized
137  one, with x in [-1000 ... 1000] and y in [-750 ... 750].
138 
139  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
140  values over serial port.
141 
142  \ingroup coordhelpers */
143  void stdToImg(float & x, float & y, unsigned int const width, unsigned int const height, float const eps = 0.1F);
144 
145  //! Transform size in-place from standardized to image, using a RawImage to establish image size
146  /*! Arguments w and h define the size of an object in standardized units, which will be converted to pixels. The
147  width and height would typically be from the camera and are used to specify pixel width and height of the
148  camera image, and this is the destination coordinate system. The source coordinate system is the standardized
149  one, with x in [-1000 ... 1000] and y in [-750 ... 750].
150 
151  eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
152  values over serial port.
153 
154  \ingroup coordhelpers */
155  void stdToImgSize(float & x, float & y, unsigned int const width, unsigned int const height,
156  float const eps = 0.1F);
157  }
158 }
159 
jevois::coords::imgToStdY
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
jevois::coords::stdToImgSize
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
RawImage.H
jevois::coords::imgToStdSize
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
jevois::coords::imgToStdX
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
jevois
Definition: Concepts.dox:1
F
float F
Definition: GUIhelper.C:2373
jevois::coords::stdToImg
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
jevois::coords::imgToStd
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
h
int h
Definition: GUIhelper.C:2373