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