Point Cloud Library (PCL)  1.9.1
real_sense_grabber.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2015-, Open Perception, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of the copyright holder(s) nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  */
37 
38 #ifndef PCL_IO_REAL_SENSE_GRABBER_H
39 #define PCL_IO_REAL_SENSE_GRABBER_H
40 
41 #include <boost/thread/thread.hpp>
42 #include <boost/thread/mutex.hpp>
43 
44 #include <pcl/io/grabber.h>
45 #include <pcl/point_cloud.h>
46 #include <pcl/point_types.h>
47 #include <pcl/common/time.h>
48 
49 namespace pcl
50 {
51 
52  namespace io
53  {
54 
55  template <typename T> class Buffer;
56 
57  namespace real_sense
58  {
59  class RealSenseDevice;
60  }
61 
62  }
63 
64  class PCL_EXPORTS RealSenseGrabber : public Grabber
65  {
66 
67  public:
68 
69  typedef
70  void (sig_cb_real_sense_point_cloud)
72 
73  typedef
74  void (sig_cb_real_sense_point_cloud_rgba)
76 
77  /** A descriptor for capturing mode.
78  *
79  * Consists of framerate and resolutions of depth and color streams.
80  * Serves two purposes: to describe the desired capturing mode when
81  * creating a grabber, and to list the available modes supported by the
82  * grabber (see getAvailableModes()). In the first case setting some
83  * fields to zero means "don't care", i.e. the grabber is allowed to
84  * decide itself which concrete values to use. */
85  struct PCL_EXPORTS Mode
86  {
87  unsigned int fps;
88  unsigned int depth_width;
89  unsigned int depth_height;
90  unsigned int color_width;
91  unsigned int color_height;
92 
93  /** Set all fields to zero (i.e. "don't care"). */
94  Mode ();
95 
96  /** Set desired framerate, the rest is "don't care". */
97  Mode (unsigned int fps);
98 
99  /** Set desired depth resolution, the rest is "don't care". */
100  Mode (unsigned int depth_width, unsigned int depth_height);
101 
102  /** Set desired framerate and depth resolution, the rest is "don't
103  * care". */
104  Mode (unsigned int fps, unsigned int depth_width, unsigned int depth_height);
105 
106  /** Set desired depth and color resolution, the rest is "don't
107  * care". */
108  Mode (unsigned int depth_width, unsigned int depth_height, unsigned int color_width, unsigned int color_height);
109 
110  /** Set desired framerate, depth and color resolution. */
111  Mode (unsigned int fps, unsigned int depth_width, unsigned int depth_height, unsigned int color_width, unsigned int color_height);
112 
113  bool
115  };
116 
118  {
119  RealSense_None = 0,
120  RealSense_Median = 1,
121  RealSense_Average = 2,
122  };
123 
124  /** Create a grabber for a RealSense device.
125  *
126  * The grabber "captures" the device, making it impossible for other
127  * grabbers to interact with it. The device is "released" when the
128  * grabber is destructed.
129  *
130  * This will throw pcl::io::IOException if there are no free devices
131  * that match the supplied \a device_id.
132  *
133  * \param[in] device_id device identifier, which can be a serial number,
134  * a zero-based index (with '#' prefix), or an empty string (to select
135  * the first available device)
136  * \param[in] mode desired framerate and stream resolution (see Mode).
137  * If the default is supplied, then the mode closest to VGA at 30 Hz
138  * will be chosen.
139  * \param[in] strict if set to \c true, an exception will be thrown if
140  * device does not support exactly the mode requested. Otherwise the
141  * closest available mode is selected. */
142  RealSenseGrabber (const std::string& device_id = "", const Mode& mode = Mode (), bool strict = false);
143 
144  virtual
145  ~RealSenseGrabber () throw ();
146 
147  virtual void
148  start ();
149 
150  virtual void
151  stop ();
152 
153  virtual bool
154  isRunning () const;
155 
156  virtual std::string
157  getName () const
158  {
159  return (std::string ("RealSenseGrabber"));
160  }
161 
162  virtual float
163  getFramesPerSecond () const;
164 
165  /** Set the confidence threshold for depth data.
166  *
167  * Valid range is [0..15]. Discarded points will have their coordinates
168  * set to NaNs). */
169  void
170  setConfidenceThreshold (unsigned int threshold);
171 
172  /** Enable temporal filtering of the depth data received from the device.
173  *
174  * The window size parameter is not relevant for `RealSense_None`
175  * filtering type.
176  *
177  * \note if the grabber is running and the new parameters are different
178  * from the current parameters, grabber will be restarted. */
179  void
180  enableTemporalFiltering (TemporalFilteringType type, size_t window_size);
181 
182  /** Disable temporal filtering. */
183  void
184  disableTemporalFiltering ();
185 
186  /** Get the serial number of device captured by the grabber. */
187  const std::string&
188  getDeviceSerialNumber () const;
189 
190  /** Get a list of capturing modes supported by the PXC device
191  * controlled by this grabber.
192  *
193  * \param[in] only_depth list depth-only modes
194  *
195  * \note: this list exclude modes where framerates of the depth and
196  * color streams do not match. */
197  std::vector<Mode>
198  getAvailableModes (bool only_depth = false) const;
199 
200  /** Set desired capturing mode.
201  *
202  * \note if the grabber is running and the new mode is different the
203  * one requested previously, grabber will be restarted. */
204  void
205  setMode (const Mode& mode, bool strict = false);
206 
207  /** Get currently active capturing mode.
208  *
209  * \note: capturing mode is selected when start() is called; output of
210  * this function before grabber was started is undefined. */
211  const Mode&
212  getMode () const
213  {
214  return (mode_selected_);
215  }
216 
217  private:
218 
219  void
220  run ();
221 
222  void
223  createDepthBuffer ();
224 
225  void
226  selectMode ();
227 
228  /** Compute a score which indicates how different is a given mode is from
229  * the mode requested by the user.
230  *
231  * Importance of factors: fps > depth resolution > color resolution. The
232  * lower the score the better. */
233  float
234  computeModeScore (const Mode& mode);
235 
236  // Signals to indicate whether new clouds are available
237  boost::signals2::signal<sig_cb_real_sense_point_cloud>* point_cloud_signal_;
238  boost::signals2::signal<sig_cb_real_sense_point_cloud_rgba>* point_cloud_rgba_signal_;
239 
240  boost::shared_ptr<pcl::io::real_sense::RealSenseDevice> device_;
241 
242  bool is_running_;
243  unsigned int confidence_threshold_;
244 
245  TemporalFilteringType temporal_filtering_type_;
246  size_t temporal_filtering_window_size_;
247 
248  /// Capture mode requested by the user at construction time
249  Mode mode_requested_;
250 
251  /// Whether or not selected capture mode should strictly match what the user
252  /// has requested
253  bool strict_;
254 
255  /// Capture mode selected by grabber (among the modes supported by the
256  /// device), computed and stored on start()
257  Mode mode_selected_;
258 
259  /// Indicates whether there are subscribers for PointXYZ signal, computed
260  /// and stored on start()
261  bool need_xyz_;
262 
263  /// Indicates whether there are subscribers for PointXYZRGBA signal,
264  /// computed and stored on start()
265  bool need_xyzrgba_;
266 
267  EventFrequency frequency_;
268  mutable boost::mutex fps_mutex_;
269 
270  boost::thread thread_;
271 
272  /// Depth buffer to perform temporal filtering of the depth images
273  boost::shared_ptr<pcl::io::Buffer<unsigned short> > depth_buffer_;
274 
275  };
276 
277 }
278 
279 #endif /* PCL_IO_REAL_SENSE_GRABBER_H */
280 
pcl::RealSenseGrabber::Mode
A descriptor for capturing mode.
Definition: real_sense_grabber.h:85
pcl
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
point_types.h
pcl::RealSenseGrabber
Definition: real_sense_grabber.h:64
pcl::Grabber
Grabber interface for PCL 1.x device drivers.
Definition: grabber.h:58
pcl::RealSenseGrabber::Mode::color_width
unsigned int color_width
Definition: real_sense_grabber.h:90
pcl::RealSenseGrabber::getMode
const Mode & getMode() const
Get currently active capturing mode.
Definition: real_sense_grabber.h:212
pcl::RealSenseGrabber::Mode::depth_width
unsigned int depth_width
Definition: real_sense_grabber.h:88
pcl::EventFrequency
A helper class to measure frequency of a certain event.
Definition: time.h:151
pcl::RealSenseGrabber::Mode::fps
unsigned int fps
Definition: real_sense_grabber.h:87
pcl::RealSenseGrabber::TemporalFilteringType
TemporalFilteringType
Definition: real_sense_grabber.h:117
std
Definition: multi_grid_octree_data.hpp:45
pcl::PointCloud::ConstPtr
boost::shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:429
time.h
pcl::RealSenseGrabber::Mode::color_height
unsigned int color_height
Definition: real_sense_grabber.h:91
pcl::operator==
bool operator==(const PCLHeader &lhs, const PCLHeader &rhs)
Definition: PCLHeader.h:46
pcl::RealSenseGrabber::Mode::depth_height
unsigned int depth_height
Definition: real_sense_grabber.h:89