Point Cloud Library (PCL)  1.9.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
buffers.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2014-, 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_BUFFERS_H
39 #define PCL_IO_BUFFERS_H
40 
41 #include <vector>
42 #include <limits>
43 #include <cassert>
44 
45 #include <boost/cstdint.hpp>
46 #include <boost/thread/mutex.hpp>
47 
48 namespace pcl
49 {
50 
51  namespace io
52  {
53 
54  /** An abstract base class for fixed-size data buffers.
55  *
56  * A new chunk of data can be inserted using the push() method; the data
57  * elements stored in the buffer can be accessed using operator[]().
58  *
59  * Concrete implementations of this interface (such as AverageBuffer or
60  * MedianBuffer) may perform arbitrary data processing under the hood and
61  * provide access to certain quantities computed based on the input data
62  * rather than the data themselves.
63  *
64  * \author Sergey Alexandrov
65  * \ingroup io */
66  template <typename T>
67  class Buffer
68  {
69 
70  public:
71 
72  typedef T value_type;
73 
74  virtual
75  ~Buffer ();
76 
77  /** Access an element at a given index. */
78  virtual T
79  operator[] (size_t idx) const = 0;
80 
81  /** Insert a new chunk of data into the buffer.
82  *
83  * Note that the \a data parameter is not `const`-qualified. This is
84  * done to allow deriving classes to implement no-copy data insertion,
85  * where the data is "stolen" from the input argument. */
86  virtual void
87  push (std::vector<T>& data) = 0;
88 
89  /** Get the size of the buffer. */
90  inline size_t
91  size () const
92  {
93  return (size_);
94  }
95 
96  protected:
97 
98  Buffer (size_t size);
99 
100  const size_t size_;
101 
102  };
103 
104  /** A simple buffer that only stores data.
105  *
106  * The buffer is thread-safe. */
107  template <typename T>
108  class SingleBuffer : public Buffer<T>
109  {
110 
111  public:
112 
113  /** Construct a buffer of given size. */
114  SingleBuffer (size_t size);
115 
116  virtual
117  ~SingleBuffer ();
118 
119  virtual T
120  operator[] (size_t idx) const;
121 
122  virtual void
123  push (std::vector<T>& data);
124 
125  private:
126 
127  std::vector<T> data_;
128  mutable boost::mutex data_mutex_;
129 
130  using Buffer<T>::size_;
131 
132  };
133 
134  /** A buffer that computes running window median of the data inserted.
135  *
136  * The buffer and window sizes are specified at construction time. The
137  * buffer size defines the number of elements in each data chunk that is
138  * inserted in the buffer. The window size is the number of last data
139  * chunks that are considered for median computation. The median is
140  * computed separately for 1st, 2nd, etc. element in data chunks.
141  *
142  * The data can contain invalid elements. For integral types zeros are
143  * assumed to be invalid elements, whereas for floating-point types it is
144  * quiet NaN. Invalid elements are ignored when computing median.
145  *
146  * The buffer is thread-safe. */
147  template <typename T>
148  class MedianBuffer : public Buffer<T>
149  {
150 
151  public:
152 
153  /** Construct a buffer of given size with given running window size.
154  *
155  * \param[in] size buffer size
156  * \param[in] window_size running window size over which the median
157  * value should be computed (0..255) */
158  MedianBuffer (size_t size, unsigned char window_size);
159 
160  virtual
161  ~MedianBuffer ();
162 
163  /** Access an element at a given index.
164  *
165  * This operation is constant time. */
166  virtual T
167  operator[] (size_t idx) const;
168 
169  /** Insert a new chunk of data into the buffer.
170  *
171  * This operation is linear in buffer size and window size.
172  *
173  * \param[in] data input data chunk, the memory will be "stolen" */
174  virtual void
175  push (std::vector<T>& data);
176 
177  private:
178 
179  /** Compare two data elements.
180  *
181  * Invalid value is assumed to be larger than everything else. If both values
182  * are invalid, they are assumed to be equal.
183  *
184  * \return -1 if \c a < \c b, 0 if \c a == \c b, 1 if \c a > \c b */
185  static int compare (T a, T b);
186 
187  const unsigned char window_size_;
188  const unsigned char midpoint_;
189 
190  /// Data pushed into the buffer (last window_size_ chunks), logically
191  /// organized as a circular buffer
192  std::vector<std::vector<T> > data_;
193 
194  /// Index of the last pushed data chunk in the data_ circular buffer
195  unsigned char data_current_idx_;
196 
197  /// Indices that the argsort function would produce for data_ (with
198  /// dimensions swapped)
199  std::vector<std::vector<unsigned char> > data_argsort_indices_;
200 
201  /// Number of invalid values in the buffer
202  std::vector<unsigned char> data_invalid_count_;
203 
204  mutable boost::mutex data_mutex_;
205 
206  using Buffer<T>::size_;
207 
208  };
209 
210  /** A buffer that computes running window average of the data inserted.
211  *
212  * The buffer and window sizes are specified at construction time. The
213  * buffer size defines the number of elements in each data chunk that is
214  * inserted in the buffer. The window size is the number of last data
215  * chunks that are considered for average computation. The average is
216  * computed separately for 1st, 2nd, etc. element in data chunks.
217  *
218  * The data can contain invalid elements. For integral types zeros are
219  * assumed to be invalid elements, whereas for floating-point types it is
220  * quiet NaN. Invalid elements are ignored when computing average.
221  *
222  * The buffer is thread-safe. */
223  template <typename T>
224  class AverageBuffer : public Buffer<T>
225  {
226 
227  public:
228 
229  /** Construct a buffer of given size with given running window size.
230  *
231  * \param[in] size buffer size
232  * \param[in] window_size running window size over which the median
233  * value should be computed (0..255) */
234  AverageBuffer (size_t size, unsigned char window_size);
235 
236  virtual
237  ~AverageBuffer ();
238 
239  /** Access an element at a given index.
240  *
241  * This operation is constant time. */
242  virtual T
243  operator[] (size_t idx) const;
244 
245  /** Insert a new chunk of data into the buffer.
246  *
247  * This operation is linear in buffer size.
248  *
249  * \param[in] data input data chunk, the memory will be "stolen" */
250  virtual void
251  push (std::vector<T>& data);
252 
253  private:
254 
255  const unsigned char window_size_;
256 
257  /// Data pushed into the buffer (last window_size_ chunks), logically
258  /// organized as a circular buffer
259  std::vector<std::vector<T> > data_;
260 
261  /// Index of the last pushed data chunk in the data_ circular buffer
262  unsigned char data_current_idx_;
263 
264  /// Current sum of the buffer
265  std::vector<T> data_sum_;
266 
267  /// Number of invalid values in the buffer
268  std::vector<unsigned char> data_invalid_count_;
269 
270  mutable boost::mutex data_mutex_;
271 
272  using Buffer<T>::size_;
273 
274  };
275 
276  }
277 
278 }
279 
280 #include <pcl/io/impl/buffers.hpp>
281 
282 #endif /* PCL_IO_BUFFERS_H */
283 
A buffer that computes running window average of the data inserted.
Definition: buffers.h:224
Buffer(size_t size)
Definition: buffers.hpp:68
AverageBuffer(size_t size, unsigned char window_size)
Construct a buffer of given size with given running window size.
Definition: buffers.hpp:225
virtual ~SingleBuffer()
Definition: buffers.hpp:86
MedianBuffer(size_t size, unsigned char window_size)
Construct a buffer of given size with given running window size.
Definition: buffers.hpp:107
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
virtual ~MedianBuffer()
Definition: buffers.hpp:133
SingleBuffer(size_t size)
Construct a buffer of given size.
Definition: buffers.hpp:79
A buffer that computes running window median of the data inserted.
Definition: buffers.h:148
virtual T operator[](size_t idx) const =0
Access an element at a given index.
A simple buffer that only stores data.
Definition: buffers.h:108
const size_t size_
Definition: buffers.h:100
virtual void push(std::vector< T > &data)
Insert a new chunk of data into the buffer.
Definition: buffers.hpp:146
virtual T operator[](size_t idx) const
Access an element at a given index.
Definition: buffers.hpp:248
virtual T operator[](size_t idx) const
Access an element at a given index.
Definition: buffers.hpp:138
virtual void push(std::vector< T > &data)
Insert a new chunk of data into the buffer.
Definition: buffers.hpp:258
virtual T operator[](size_t idx) const
Access an element at a given index.
Definition: buffers.hpp:91
virtual void push(std::vector< T > &data)
Insert a new chunk of data into the buffer.
Definition: buffers.hpp:98
virtual ~AverageBuffer()
Definition: buffers.hpp:243
An abstract base class for fixed-size data buffers.
Definition: buffers.h:67
size_t size() const
Get the size of the buffer.
Definition: buffers.h:91
virtual ~Buffer()
Definition: buffers.hpp:74
virtual void push(std::vector< T > &data)=0
Insert a new chunk of data into the buffer.