Point Cloud Library (PCL)  1.10.0-dev
image_depth.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2011 Willow Garage, Inc.
6  * Copyright (c) 2012-, Open Perception, Inc.
7  *
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted provided that the following conditions
12  * are met:
13  *
14  * * Redistributions of source code must retain the above copyright
15  * notice, this list of conditions and the following disclaimer.
16  * * Redistributions in binary form must reproduce the above
17  * copyright notice, this list of conditions and the following
18  * disclaimer in the documentation and/or other materials provided
19  * with the distribution.
20  * * Neither the name of the copyright holder(s) nor the names of its
21  * contributors may be used to endorse or promote products derived
22  * from this software without specific prior written permission.
23  *
24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
30  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
34  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35  * POSSIBILITY OF SUCH DAMAGE.
36  *
37  */
38 
39 #pragma once
40 
41 #include <chrono>
42 
43 #include <pcl/pcl_config.h>
44 #include <pcl/pcl_exports.h>
45 #include <pcl/io/boost.h>
46 
47 #include<pcl/io/image_metadata_wrapper.h>
48 
49 namespace pcl
50 {
51  namespace io
52  {
53  /** \brief This class provides methods to fill a depth or disparity image.
54  */
56  {
57  public:
60 
61  using Clock = std::chrono::high_resolution_clock;
62  using Timestamp = std::chrono::high_resolution_clock::time_point;
63 
64  /** \brief Constructor
65  * \param[in] depth_metadata the actual data from the OpenNI library
66  * \param[in] baseline the baseline of the "stereo" camera, i.e. the distance between the projector and the IR camera for
67  * Primesense like cameras. e.g. 7.5cm for PSDK5 and PSDK6 reference design.
68  * \param[in] focal_length focal length of the "stereo" frame.
69  * \param[in] shadow_value defines which values in the depth data are indicating shadow (resulting from the parallax between projector and IR camera)
70  * \param[in] no_sample_value defines which values in the depth data are indicating that no depth (disparity) could be determined .
71  * \attention The focal length may change, depending whether the depth stream is registered/mapped to the RGB stream or not.
72  */
73  DepthImage (FrameWrapper::Ptr depth_metadata, float baseline, float focal_length, std::uint64_t shadow_value, std::uint64_t no_sample_value);
74  DepthImage (FrameWrapper::Ptr depth_metadata, float baseline, float focal_length, std::uint64_t shadow_value, std::uint64_t no_sample_value, Timestamp time);
75 
76  /** \brief Destructor. Never throws an exception. */
77  ~DepthImage ();
78 
79  /** \brief method to access the internal data structure from OpenNI. If the data is accessed just read-only, then this method is faster than a fillXXX method
80  * \return the actual depth data of type openni::VideoFrameRef.
81  */
82  const FrameWrapper::Ptr
83  getMetaData () const;
84 
85  /** \brief fills a user given block of memory with the disparity values with additional nearest-neighbor down-scaling.
86  * \param[in] width the width of the desired disparity image.
87  * \param[in] height the height of the desired disparity image.
88  * \param[in,out] disparity_buffer the float pointer to the actual memory buffer to be filled with the disparity values.
89  * \param[in] line_step if only a rectangular sub region of the buffer needs to be filled, then line_step is the
90  * width in bytes (not floats) of the original width of the depth buffer.
91  */
92  void
93  fillDisparityImage (unsigned width, unsigned height, float* disparity_buffer, unsigned line_step = 0) const;
94 
95  /** \brief fills a user given block of memory with the disparity values with additional nearest-neighbor down-scaling.
96  * \param[in] width width the width of the desired depth image.
97  * \param[in] height height the height of the desired depth image.
98  * \param[in,out] depth_buffer the float pointer to the actual memory buffer to be filled with the depth values.
99  * \param[in] line_step if only a rectangular sub region of the buffer needs to be filled, then line_step is the
100  * width in bytes (not floats) of the original width of the depth buffer.
101  */
102  void
103  fillDepthImage (unsigned width, unsigned height, float* depth_buffer, unsigned line_step = 0) const;
104 
105  /** \brief fills a user given block of memory with the raw values with additional nearest-neighbor down-scaling.
106  * \param[in] width width the width of the desired raw image.
107  * \param[in] height height the height of the desired raw image.
108  * \param[in,out] depth_buffer the unsigned short pointer to the actual memory buffer to be filled with the raw values.
109  * \param[in] line_step if only a rectangular sub region of the buffer needs to be filled, then line_step is the
110  * width in bytes (not floats) of the original width of the depth buffer.
111  */
112  void
113  fillDepthImageRaw (unsigned width, unsigned height, unsigned short* depth_buffer, unsigned line_step = 0) const;
114 
115  /** \brief method to access the baseline of the "stereo" frame that was used to retrieve the depth image.
116  * \return baseline in meters
117  */
118  float
119  getBaseline () const;
120 
121  /** \brief method to access the focal length of the "stereo" frame that was used to retrieve the depth image.
122  * \return focal length in pixels
123  */
124  float
125  getFocalLength () const;
126 
127  /** \brief method to access the shadow value, that indicates pixels lying in shadow in the depth image.
128  * \return shadow value
129  */
130  std::uint64_t
131  getShadowValue () const;
132 
133  /** \brief method to access the no-sample value, that indicates pixels where no disparity could be determined for the depth image.
134  * \return no-sample value
135  */
136  std::uint64_t
137  getNoSampleValue () const;
138 
139  /** \return the width of the depth image */
140  unsigned
141  getWidth () const;
142 
143  /** \return the height of the depth image */
144  unsigned
145  getHeight () const;
146 
147  /** \return an ascending id for the depth frame
148  * \attention not necessarily synchronized with other streams
149  */
150  unsigned
151  getFrameID () const;
152 
153  /** \return a ascending timestamp for the depth frame
154  * \attention its not the system time, thus can not be used directly to synchronize different sensors.
155  * But definitely synchronized with other streams
156  */
157  std::uint64_t
158  getTimestamp () const;
159 
160  Timestamp
161  getSystemTimestamp () const;
162 
163  // Get a const pointer to the raw depth buffer
164  const unsigned short*
165  getData ();
166 
167  // Data buffer size in bytes
168  int
169  getDataSize () const;
170 
171  // Size of each row, including any padding
172  inline unsigned
173  getStep() const
174  {
175  return (getDataSize() / getHeight());
176  }
177 
178  protected:
180 
181  float baseline_;
183  std::uint64_t shadow_value_;
184  std::uint64_t no_sample_value_;
186  };
187 
188 }} // namespace
std::chrono::high_resolution_clock Clock
Definition: image_depth.h:61
pcl::io::FrameWrapper::Ptr wrapper_
Definition: image_depth.h:179
std::uint64_t shadow_value_
Definition: image_depth.h:183
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
shared_ptr< FrameWrapper > Ptr
shared_ptr< DepthImage > Ptr
Definition: image_depth.h:58
This class provides methods to fill a depth or disparity image.
Definition: image_depth.h:55
unsigned getStep() const
Definition: image_depth.h:173
std::chrono::high_resolution_clock::time_point Timestamp
Definition: image_depth.h:62
shared_ptr< const DepthImage > ConstPtr
Definition: image_depth.h:59
std::uint64_t no_sample_value_
Definition: image_depth.h:184
Timestamp timestamp_
Definition: image_depth.h:185
boost::shared_ptr< T > shared_ptr
Alias for boost::shared_ptr.
Definition: pcl_macros.h:90
#define PCL_EXPORTS
Definition: pcl_macros.h:253