RDB 2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
querySelect.hpp
Go to the documentation of this file.
1 /*
2  *******************************************************************************
3  *
4  * Copyright 2021 RIEGL Laser Measurement Systems
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  *
18  * SPDX-License-Identifier: Apache-2.0
19  *
20  *******************************************************************************
21  */
22 /*!
23  *******************************************************************************
24  *
25  * \file querySelect.hpp
26  * \author RIEGL LMS GmbH, Austria
27  * \brief Point select query
28  * \version 2015-10-14/AW: Initial version
29  * \version 2016-11-04/AW: Allow to read from multiple nodes at once (#2368)
30  * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
31  * \version 2018-07-05/AW: Wrapper function bindBuffer() added
32  * \version 2020-01-17/AW: Wrapper function bindMember() added (#3497)
33  *
34  *******************************************************************************
35  */
36 
37 #ifndef RIEGL_RDB_POINTCLOUD_QUERYSELECT_HPP
38 #define RIEGL_RDB_POINTCLOUD_QUERYSELECT_HPP
39 
40 //---< INCLUDES >---------------------------------------------------------------
41 
42 #include <memory>
43 #include <string>
44 #include <vector>
45 #include <cstdint>
46 
50 
51 //---< NAMESPACE >--------------------------------------------------------------
52 
53 namespace riegl {
54 namespace rdb {
55 namespace pointcloud {
56 
57 //---< CLASS QuerySelect >------------------------------------------------------
58 /*!
59  * \brief Point select query
60  *
61  * This class can be used to select (read) attributes of existing points.
62  *
63  * \see riegl::rdb::Pointcloud::select()
64  *
65  * \note You either must delete the query object or call close()
66  * __before__ the parent Pointcloud instance is closed/deleted!
67  */
69 {
70 public:
71  /*!
72  * \brief Default constructor
73  *
74  * Creates a null query - i.e. the query cannot be used to read points.
75  *
76  * \see riegl::rdb::Pointcloud::select()
77  */
78  explicit QuerySelect();
79 
80  /*!
81  * \brief Constructor
82  *
83  * Creates a query prepared for reading points.
84  *
85  * \note You cannot create new QuerySelect objects this way,
86  * use riegl::rdb::Pointcloud::select() instead.
87  */
88  explicit QuerySelect(
89  riegl::rdb::PointcloudData *pointcloud,
90  const std::vector<GraphNode::ID> *nodes,
91  const std::string &filter
92  );
93 
94  /*!
95  * \brief Check if query is not null
96  *
97  * \see valid()
98  */
99  operator bool() const;
100 
101  /*!
102  * \brief Check if query is not null
103  *
104  * A null query cannot be used to read points.
105  */
106  bool valid() const;
107 
108  /*!
109  * \brief Finish query
110  *
111  * Call this function when done with reading points.
112  */
113  void close();
114 
115  /*!
116  * \brief Bind attribute buffer
117  *
118  * Use this function to define a target buffer for a point attribute.
119  * Exactly one buffer can be defined for an attribute (i.e. only the
120  * most recently defined buffer will be used).
121  *
122  * The buffer is expected to be n*s*d bytes large, where
123  * __n__ is the number of points defined in next(),
124  * __s__ is the size of one element as defined by 'dataType' and
125  * __d__ is the number of attribute dimensions (elements).
126  *
127  * \note This function just stores the buffer pointer. So make
128  * sure that the buffer remains valid until you call next().
129  *
130  * \see riegl::rdb::pointcloud::PointAttributes
131  */
132  void bind(
133  const std::string &attribute, //!< [in] attribute name
134  const DataType dataType, //!< [in] buffer data type
135  void *buffer, //!< [in] buffer location
136  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
137  );
138 
139  //! \copydoc bind()
140  template <typename ValueType>
142  const std::string &attribute, //!< [in] attribute name
143  ValueType &buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
144  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
145  )
146  {
147  bind(attribute, dataTypeOf(buffer), dataPointerOf(buffer), stride);
148  }
149 
150  //! \copydoc bind()
151  template <typename ValueType>
153  const std::string &attribute, //!< [in] attribute name
154  ValueType *buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
155  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
156  )
157  {
158  bind(attribute, dataTypeOf(buffer), buffer, stride);
159  }
160 
161  /*!
162  * \brief Bind attribute buffer
163  *
164  * This is a variant of bindBuffer() that allows to bind a member variable
165  * of an object as attribute buffer. The object can be part of a container
166  * that stores the objects contiguously (e.g. std::vector, std::array) and
167  * the stride is automatically derived from the object size.
168  *
169  * \see bindBuffer()
170  */
171  template <typename ObjectType, typename MemberPointer>
173  const std::string &attribute, //!< [in] attribute name
174  ObjectType &object, //!< [in] e.g. first object of container
175  const MemberPointer member //!< [in] object member variable pointer
176  )
177  {
178  bindBuffer(
179  attribute, object.*member,
180  static_cast<int32_t>(sizeof(ObjectType))
181  );
182  }
183 
184  //! \copydoc bindMember()
185  template <typename ObjectType, typename MemberPointer>
187  const std::string &attribute, //!< [in] attribute name
188  ObjectType &object, //!< [in] e.g. first object of container
189  const MemberPointer member, //!< [in] object member variable pointer
190  const size_t index //!< [in] index for array-like object members
191  )
192  {
193  bindBuffer(
194  attribute, (object.*member)[index],
195  static_cast<int32_t>(sizeof(ObjectType))
196  );
197  }
198 
199  /*!
200  * \brief Select points
201  *
202  * Use this function to actually read the selected points from
203  * database and copy the attributes to the defined buffers.
204  *
205  * Afterwards you may re-use the buffers or define new buffers
206  * with bind() and call next() again until all points have been
207  * read (i.e. next() returns zero).
208  *
209  * If no buffers were bound, calling next() is still valid. This can be
210  * used for counting points - either all or just those that meet some
211  * filter criteria. If no filter is specified the total point count is
212  * equal to what you get with riegl::rdb::Pointcloud::stat().
213  *
214  * \returns the number of points read
215  */
216  uint32_t next(
217  uint32_t count //!< [in] size of target buffers in terms of points
218  );
219 
220  /*!
221  * \brief Progress
222  *
223  * This function returns a coarse progress information in percent (0..100%).
224  * Since the total number of returned points is not known in advance, this
225  * value just reflects the progress of the (internal) index traversal.
226  *
227  * \note When the select query is used to count points (i.e. no buffers
228  * were bound), then this function always returns 0%.
229  */
230  uint32_t progress() const;
231 
232 private:
233  struct Private;
234  std::shared_ptr<Private> data;
235 };
236 
237 }}} // namespace riegl::rdb::pointcloud
238 
239 #endif // RIEGL_RDB_POINTCLOUD_QUERYSELECT_HPP
bool valid() const
Check if query is not null.
void bind(const std::string &attribute, const DataType dataType, void *buffer, const int32_t stride=0)
Bind attribute buffer.
uint32_t next(uint32_t count)
Select points.
DataType
Point attribute access data type.
Definition: dataTypes.hpp:55
void bindBuffer(const std::string &attribute, ValueType *buffer, const int32_t stride=0)
Bind attribute buffer.
ValueType * dataPointerOf(ValueType *const value)
Get pointer to variable or to data in a std::array or vector container.
Definition: dataTypes.hpp:175
Index graph node.
DataType dataTypeOf()
Convenience wrapper for DataTypeOf class.
Definition: dataTypes.hpp:146
QuerySelect()
Default constructor.
uint32_t progress() const
Progress.
void bindMember(const std::string &attribute, ObjectType &object, const MemberPointer member, const size_t index)
Bind attribute buffer.
void bindBuffer(const std::string &attribute, ValueType &buffer, const int32_t stride=0)
Bind attribute buffer.
Point attribute access data types.
Pointcloud class implementation details.
void bindMember(const std::string &attribute, ObjectType &object, const MemberPointer member)
Bind attribute buffer.