Point Cloud Library (PCL)  1.8.0
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 
115  {
116  RealSense_None = 0,
117  RealSense_Median = 1,
118  RealSense_Average = 2,
119  };
120 
121  /** Create a grabber for a RealSense device.
122  *
123  * The grabber "captures" the device, making it impossible for other
124  * grabbers to interact with it. The device is "released" when the
125  * grabber is destructed.
126  *
127  * This will throw pcl::io::IOException if there are no free devices
128  * that match the supplied \a device_id.
129  *
130  * \param[in] device_id device identifier, which can be a serial number,
131  * a zero-based index (with '#' prefix), or an empty string (to select
132  * the first available device)
133  * \param[in] mode desired framerate and stream resolution (see Mode).
134  * If the default is supplied, then the mode closest to VGA at 30 Hz
135  * will be chosen.
136  * \param[in] strict if set to \c true, an exception will be thrown if
137  * device does not support exactly the mode requsted. Otherwise the
138  * closest available mode is selected. */
139  RealSenseGrabber (const std::string& device_id = "", const Mode& mode = Mode (), bool strict = false);
140 
141  virtual
142  ~RealSenseGrabber () throw ();
143 
144  virtual void
145  start ();
146 
147  virtual void
148  stop ();
149 
150  virtual bool
151  isRunning () const;
152 
153  virtual std::string
154  getName () const
155  {
156  return (std::string ("RealSenseGrabber"));
157  }
158 
159  virtual float
160  getFramesPerSecond () const;
161 
162  /** Set the confidence threshold for depth data.
163  *
164  * Valid range is [0..15]. Discarded points will have their coordinates
165  * set to NaNs). */
166  void
167  setConfidenceThreshold (unsigned int threshold);
168 
169  /** Enable temporal filtering of the depth data received from the device.
170  *
171  * The window size parameter is not relevant for `RealSense_None`
172  * filtering type.
173  *
174  * \note if the grabber is running and the new parameters are different
175  * from the current parameters, grabber will be restarted. */
176  void
177  enableTemporalFiltering (TemporalFilteringType type, size_t window_size);
178 
179  /** Disable temporal filtering. */
180  void
181  disableTemporalFiltering ();
182 
183  /** Get the serial number of device captured by the grabber. */
184  const std::string&
185  getDeviceSerialNumber () const;
186 
187  /** Get a list of capturing modes supported by the PXC device
188  * controlled by this grabber.
189  *
190  * \param[in] only_depth list depth-only modes
191  *
192  * \note: this list exclude modes where framerates of the depth and
193  * color streams do not match. */
194  std::vector<Mode>
195  getAvailableModes (bool only_depth = false) const;
196 
197  /** Set desired capturing mode.
198  *
199  * \note if the grabber is running and the new mode is different the
200  * one requested previously, grabber will be restarted. */
201  void
202  setMode (const Mode& mode, bool strict = false);
203 
204  /** Get currently active capturing mode.
205  *
206  * \note: capturing mode is selected when start() is called; output of
207  * this function before grabber was started is undefined. */
208  const Mode&
209  getMode () const
210  {
211  return (mode_selected_);
212  }
213 
214  private:
215 
216  void
217  run ();
218 
219  void
220  createDepthBuffer ();
221 
222  void
223  selectMode ();
224 
225  /** Compute a score which indicates how different is a given mode is from
226  * the mode requested by the user.
227  *
228  * Importance of factors: fps > depth resolution > color resolution. The
229  * lower the score the better. */
230  float
231  computeModeScore (const Mode& mode);
232 
233  // Signals to indicate whether new clouds are available
234  boost::signals2::signal<sig_cb_real_sense_point_cloud>* point_cloud_signal_;
235  boost::signals2::signal<sig_cb_real_sense_point_cloud_rgba>* point_cloud_rgba_signal_;
236 
237  boost::shared_ptr<pcl::io::real_sense::RealSenseDevice> device_;
238 
239  bool is_running_;
240  unsigned int confidence_threshold_;
241 
242  TemporalFilteringType temporal_filtering_type_;
243  size_t temporal_filtering_window_size_;
244 
245  /// Capture mode requested by the user at construction time
246  Mode mode_requested_;
247 
248  /// Whether or not selected capture mode should strictly match what the user
249  /// has requested
250  bool strict_;
251 
252  /// Capture mode selected by grabber (among the modes supported by the
253  /// device), computed and stored on start()
254  Mode mode_selected_;
255 
256  /// Indicates whether there are subscribers for PointXYZ signal, computed
257  /// and stored on start()
258  bool need_xyz_;
259 
260  /// Indicates whether there are subscribers for PointXYZRGBA signal,
261  /// computed and stored on start()
262  bool need_xyzrgba_;
263 
264  EventFrequency frequency_;
265  mutable boost::mutex fps_mutex_;
266 
267  boost::thread thread_;
268 
269  /// Depth buffer to perform temporal filtering of the depth images
270  boost::shared_ptr<pcl::io::Buffer<unsigned short> > depth_buffer_;
271 
272  };
273 
274 }
275 
276 bool
278 
279 #endif /* PCL_IO_REAL_SENSE_GRABBER_H */
280 
A descriptor for capturing mode.
A helper class to measure frequency of a certain event.
Definition: time.h:151
Grabber interface for PCL 1.x device drivers.
Definition: grabber.h:58
Defines all the PCL implemented PointT point type structures.
boost::shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:429
const Mode & getMode() const
Get currently active capturing mode.
bool operator==(const PCLHeader &lhs, const PCLHeader &rhs)
Definition: PCLHeader.h:46
Define methods for measuring time spent in code blocks.