Fawkes API
Fawkes Development Version
vision_master.cpp
1
2
/***************************************************************************
3
* vision_master.cpp - FireVision Vision Master
4
*
5
* Created: Wed May 30 10:52:08 2007
6
* Copyright 2006-2009 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
#include <fvutils/base/vision_master.h>
25
26
using namespace
fawkes
;
27
28
namespace
firevision
{
29
#if 0
/* just to make Emacs auto-indent happy */
30
}
31
#endif
32
33
/** @class VisionMaster <fvutils/base/vision_master.h>
34
* Vision Master.
35
* The vision master shall be the entry point for vision plugins. It shall
36
* allow for requesting cameras that are opened in a central place such that
37
* the very same camera can be used in multiple plugins.
38
*
39
* It shall also be responsible for the central timing of all vision threads.
40
*
41
* @author Tim Niemueller
42
*
43
* @fn Camera * VisionMaster::register_for_camera(const char *camera_string, Thread *thread, colorspace_t cspace=YUV422_PLANAR) = 0
44
* Register thread for camera.
45
* This will register a relation between the given thread and the camera identified
46
* by the camera string. If the requested camera has not been opened before this
47
* is done and the camera is started. If that fails for whatever reason an exception
48
* is thrown. In that case the thread is not registered with the vision master.
49
* If the camera is available the thread is registered with the vision master. From
50
* then on it is woken up whenever new image data is available and it will wait for
51
* the thread to finished computation on that very image. It is a critical error
52
* that can not be recovered if the thread fails for whatever reason. If there is
53
* a critical error condition in the vision thread it must not stop execution
54
* but just the computation.
55
* @param camera_string camera that can be used by CameraFactory to open a
56
* camera.
57
* @param thread thread to register for this camera
58
* @param cspace the colorspace in which the images should be provided for the
59
* camera. Note that using images in different formats at the same time can cause
60
* a severe performance penalty. The default is to produce YUV422_PLANAR images,
61
* which is used in the FireVision framework as main image format.
62
* @return a pointer to the requested camera. Note that this may not be
63
* of the C++ type that you may expect for the requested camera, but it may
64
* have layers of indirection. For example when opening a USB camera you could
65
* get a shared memory camera to share the camera (image) with multiple threads.
66
* Note that using CS_UNKNOWN shall have the similar result as using
67
* register_for_raw_camera().
68
*
69
* @fn Camera * VisionMaster::register_for_raw_camera(const char *camera_string, Thread *thread)
70
* Register thread for camera.
71
* This will register a relation between the given thread and the camera identified
72
* by the camera string similar to register_for_camera(). However, unlike
73
* register_for_camera() this method will provide access to the raw camera
74
* implementation, without possibly proxies. Once you gathered the camera, you
75
* can dynamically cast it to the expected camera type (or use the template method
76
* instead. Raw access to a camera is only granted for a single thread.
77
* Note that you may not call capture() or dispose() on the camera, this will
78
* still be done by the vision master, as the camera may be used by other
79
* threads that registered for the camera with register_for_camera().
80
* @param camera_string camera that can be used by CameraFactory to open a
81
* camera.
82
* @param thread thread to register for this camera
83
* @return raw camera instance, which can by dynamically casted to the expected type.
84
*
85
* @fn void VisionMaster::unregister_thread(Thread *thread) = 0
86
* Unregister a thread.
87
* The thread is unregistered and it is removed from the internal structures. The
88
* thread is no longer called for new image material that can be processed.
89
*
90
* If the unregistered thread was the last thread accessing the camera, it shall
91
* be held open for a specified time, such that if the thread is just being
92
* restarted the camera does not have to be re-opened. The time to wait is
93
* defined by the implementation.
94
* @param thread thread to unregister
95
*
96
* @fn CameraControl * VisionMaster::acquire_camctrl(const char *cam_string)
97
* Retrieve a CameraControl for the specified camera string.
98
* This control (if available) can be used to control certain aspects of the Camera.
99
* The \p cam_string argument either is the string that has been used to register
100
* for a particular camera, or it is a string denoting a camera control by itself.
101
* In the former case the vision master will look if the camera has been registered,
102
* and then checks if the camera provides a camera control. If so the control is
103
* returned. Note that it might implement multiple different camera controls. If
104
* you want a specific camera control use one of the template methods to get a
105
* correctly typed and verified control. If no camera that matches the \p cam_string
106
* is found, the vision master will try to instantiate a new camera control using
107
* the \p cam_string as argument to the CameraControlFactory.
108
* @param cam_string Camera argument string, see method description for details
109
* @return a pointer to the requested CameraControl.
110
* @throws Exception no camera was found matching the \p cam_string and the factory
111
* could not instantiate a camera control with the given string.
112
*
113
* @fn CameraControl * VisionMaster::acquire_camctrl(const char *cam_string, const std::type_info &typeinf)
114
* Retrieve a CameraControl for the specified camera string and type info.
115
* This utility method is used by the template methods to instantiate the cameras
116
* with a specified intended type.
117
* @param cam_string Camera argument string, see method description for details
118
* @param typeinf type info for intended camera control type
119
* @return a pointer to the requested CameraControl.
120
* @throws Exception no camera was found matching the \p cam_string and the factory
121
* could not instantiate a camera control with the given string.
122
*
123
* @fn void VisionMaster::release_camctrl(CameraControl *cc)
124
* Release a camera control.
125
* This has to be called when you are done with the camera control. This will
126
* release the control and it is no longer valid. The vision master might collect
127
* the memory that has been used for the control.
128
* @param cc camera control instance to release
129
*/
130
131
/** Virtual empty destructor. */
132
VisionMaster::~VisionMaster()
133
{
134
}
135
136
}
// end namespace firevision
fawkes
Fawkes library namespace.
firevision
Definition:
vision_master.h:32
src
libs
fvutils
base
vision_master.cpp
Generated by
1.8.13