Point Cloud Library (PCL)  1.7.2
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 #pragma once
39 #include <pcl/pcl_config.h>
40 
41 #ifndef PCL_IO_IMAGE_DEPTH_H_
42 #define PCL_IO_IMAGE_DEPTH_H_
43 
44 #include <pcl/pcl_exports.h>
45 #include <pcl/io/boost.h>
46 #include <boost/chrono.hpp>
47 
48 #include<pcl/io/image_metadata_wrapper.h>
49 
50 namespace pcl
51 {
52  namespace io
53  {
54  /** \brief This class provides methods to fill a depth or disparity image.
55  */
56  class PCL_EXPORTS DepthImage
57  {
58  public:
59  typedef boost::shared_ptr<DepthImage> Ptr;
60  typedef boost::shared_ptr<const DepthImage> ConstPtr;
61 
62  typedef boost::chrono::high_resolution_clock Clock;
63  typedef boost::chrono::high_resolution_clock::time_point Timestamp;
64 
65  /** \brief Constructor
66  * \param[in] depth_meta_data the actual data from the OpenNI library
67  * \param[in] baseline the baseline of the "stereo" camera, i.e. the distance between the projector and the IR camera for
68  * Primesense like cameras. e.g. 7.5cm for PSDK5 and PSDK6 reference design.
69  * \param[in] focal_length focal length of the "stereo" frame.
70  * \param[in] shadow_value defines which values in the depth data are indicating shadow (resulting from the parallax between projector and IR camera)
71  * \param[in] no_sample_value defines which values in the depth data are indicating that no depth (disparity) could be determined .
72  * \attention The focal length may change, depending whether the depth stream is registered/mapped to the RGB stream or not.
73  */
74  DepthImage (FrameWrapper::Ptr depth_metadata, float baseline, float focal_length, pcl::uint64_t shadow_value, pcl::uint64_t no_sample_value);
75  DepthImage (FrameWrapper::Ptr depth_metadata, float baseline, float focal_length, pcl::uint64_t shadow_value, pcl::uint64_t no_sample_value, Timestamp time);
76 
77  /** \brief Destructor. Never throws an exception. */
78  ~DepthImage ();
79 
80  /** \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
81  * \return the actual depth data of type openni::VideoFrameRef.
82  */
83  const FrameWrapper::Ptr
84  getMetaData () const;
85 
86  /** \brief fills a user given block of memory with the disparity values with additional nearest-neighbor down-scaling.
87  * \param[in] width the width of the desired disparity image.
88  * \param[in] height the height of the desired disparity image.
89  * \param[in,out] disparity_buffer the float pointer to the actual memory buffer to be filled with the disparity values.
90  * \param[in] line_step if only a rectangular sub region of the buffer needs to be filled, then line_step is the
91  * width in bytes (not floats) of the original width of the depth buffer.
92  */
93  void
94  fillDisparityImage (unsigned width, unsigned height, float* disparity_buffer, unsigned line_step = 0) const;
95 
96  /** \brief fills a user given block of memory with the disparity values with additional nearest-neighbor down-scaling.
97  * \param[in] width width the width of the desired depth image.
98  * \param[in] height height the height of the desired depth image.
99  * \param[in,out] depth_buffer the float pointer to the actual memory buffer to be filled with the depth values.
100  * \param[in] line_step if only a rectangular sub region of the buffer needs to be filled, then line_step is the
101  * width in bytes (not floats) of the original width of the depth buffer.
102  */
103  void
104  fillDepthImage (unsigned width, unsigned height, float* depth_buffer, unsigned line_step = 0) const;
105 
106  /** \brief fills a user given block of memory with the raw values with additional nearest-neighbor down-scaling.
107  * \param[in] width width the width of the desired raw image.
108  * \param[in] height height the height of the desired raw image.
109  * \param[in,out] depth_buffer the unsigned short pointer to the actual memory buffer to be filled with the raw values.
110  * \param[in] line_step if only a rectangular sub region of the buffer needs to be filled, then line_step is the
111  * width in bytes (not floats) of the original width of the depth buffer.
112  */
113  void
114  fillDepthImageRaw (unsigned width, unsigned height, unsigned short* depth_buffer, unsigned line_step = 0) const;
115 
116  /** \brief method to access the baseline of the "stereo" frame that was used to retrieve the depth image.
117  * \return baseline in meters
118  */
119  float
120  getBaseline () const;
121 
122  /** \brief method to access the focal length of the "stereo" frame that was used to retrieve the depth image.
123  * \return focal length in pixels
124  */
125  float
126  getFocalLength () const;
127 
128  /** \brief method to access the shadow value, that indicates pixels lying in shadow in the depth image.
129  * \return shadow value
130  */
131  pcl::uint64_t
132  getShadowValue () const;
133 
134  /** \brief method to access the no-sample value, that indicates pixels where no disparity could be determined for the depth image.
135  * \return no-sample value
136  */
137  pcl::uint64_t
138  getNoSampleValue () const;
139 
140  /** \return the width of the depth image */
141  unsigned
142  getWidth () const;
143 
144  /** \return the height of the depth image */
145  unsigned
146  getHeight () const;
147 
148  /** \return an ascending id for the depth frame
149  * \attention not necessarily synchronized with other streams
150  */
151  unsigned
152  getFrameID () const;
153 
154  /** \return a ascending timestamp for the depth frame
155  * \attention its not the system time, thus can not be used directly to synchronize different sensors.
156  * But definitely synchronized with other streams
157  */
158  pcl::uint64_t
159  getTimestamp () const;
160 
161  Timestamp
162  getSystemTimestamp () const;
163 
164  // Get a const pointer to the raw depth buffer
165  const unsigned short*
166  getData ();
167 
168  // Data buffer size in bytes
169  int
170  getDataSize () const;
171 
172  // Size of each row, including any padding
173  inline unsigned
174  getStep() const
175  {
176  return (getDataSize() / getHeight());
177  }
178 
179  protected:
181 
182  float baseline_;
184  pcl::uint64_t shadow_value_;
185  pcl::uint64_t no_sample_value_;
187  };
188 
189 }} // namespace
190 
191 #endif // PCL_IO_IMAGE_DEPTH_H_
boost::chrono::high_resolution_clock Clock
Definition: image_depth.h:62
pcl::uint64_t no_sample_value_
Definition: image_depth.h:185
boost::shared_ptr< FrameWrapper > Ptr
pcl::io::FrameWrapper::Ptr wrapper_
Definition: image_depth.h:180
pcl::uint64_t shadow_value_
Definition: image_depth.h:184
boost::shared_ptr< DepthImage > Ptr
Definition: image_depth.h:59
boost::chrono::high_resolution_clock::time_point Timestamp
Definition: image_depth.h:63
unsigned getStep() const
Definition: image_depth.h:174
This class provides methods to fill a depth or disparity image.
Definition: image_depth.h:56
boost::shared_ptr< const DepthImage > ConstPtr
Definition: image_depth.h:60
Timestamp timestamp_
Definition: image_depth.h:186