RDB 2
querySelect.hpp
Go to the documentation of this file.
1 /*
2  *******************************************************************************
3  *
4  * Copyright 2023 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 <cstdlib>
46 #include <cstdint>
47 
51 
52 //---< NAMESPACE >--------------------------------------------------------------
53 
54 namespace riegl {
55 namespace rdb {
56 namespace pointcloud {
57 
58 //---< CLASS QuerySelect >------------------------------------------------------
59 /*!
60  * \brief Point select query
61  *
62  * This class can be used to select (read) attributes of existing points.
63  *
64  * \see riegl::rdb::Pointcloud::select()
65  *
66  * \note You either must delete the query object or call close()
67  * __before__ the parent Pointcloud instance is closed/deleted!
68  */
70 {
71 public:
72  /*!
73  * \brief Default constructor
74  *
75  * Creates a null query - i.e. the query cannot be used to read points.
76  *
77  * \see riegl::rdb::Pointcloud::select()
78  */
79  explicit QuerySelect();
80 
81  /*!
82  * \brief Constructor
83  *
84  * Creates a query prepared for reading points.
85  *
86  * \note You cannot create new QuerySelect objects this way,
87  * use riegl::rdb::Pointcloud::select() instead.
88  */
89  explicit QuerySelect(
90  riegl::rdb::PointcloudData *pointcloud,
91  const std::vector<GraphNode::ID> *nodes,
92  const std::string &filter
93  );
94 
95  /*!
96  * \brief Check if query is not null
97  *
98  * \see valid()
99  */
100  operator bool() const;
101 
102  /*!
103  * \brief Check if query is not null
104  *
105  * A null query cannot be used to read points.
106  */
107  bool valid() const;
108 
109  /*!
110  * \brief Finish query
111  *
112  * Call this function when done with reading points.
113  */
114  void close();
115 
116  /*!
117  * \brief Bind attribute buffer
118  *
119  * Use this function to define a target buffer for a point attribute.
120  * Exactly one buffer can be defined for an attribute (i.e. only the
121  * most recently defined buffer will be used).
122  *
123  * The buffer is expected to be n*s*d bytes large, where
124  * __n__ is the number of points defined in next(),
125  * __s__ is the size of one element as defined by 'dataType' and
126  * __d__ is the number of attribute dimensions (elements).
127  *
128  * \note This function just stores the buffer pointer. So make
129  * sure that the buffer remains valid until you call next().
130  *
131  * \see riegl::rdb::pointcloud::PointAttributes
132  */
133  void bind(
134  const std::string &attribute, //!< [in] attribute name
135  const DataType dataType, //!< [in] buffer data type
136  void *buffer, //!< [in] buffer location
137  const std::int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
138  );
139 
140  //! \copydoc bind()
141  template <typename ValueType>
143  const std::string &attribute, //!< [in] attribute name
144  ValueType &buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
145  const std::int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
146  )
147  {
148  bind(attribute, dataTypeOf(buffer), dataPointerOf(buffer), stride);
149  }
150 
151  //! \copydoc bind()
152  template <typename ValueType>
154  const std::string &attribute, //!< [in] attribute name
155  ValueType *buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
156  const std::int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
157  )
158  {
159  bind(attribute, dataTypeOf(buffer), buffer, stride);
160  }
161 
162  /*!
163  * \brief Bind attribute buffer
164  *
165  * This is a variant of bindBuffer() that allows to bind a member variable
166  * of an object as attribute buffer. The object can be part of a container
167  * that stores the objects contiguously (e.g. std::vector, std::array) and
168  * the stride is automatically derived from the object size.
169  *
170  * \see bindBuffer()
171  */
172  template <typename ObjectType, typename MemberPointer>
174  const std::string &attribute, //!< [in] attribute name
175  ObjectType &object, //!< [in] e.g. first object of container
176  const MemberPointer member //!< [in] object member variable pointer
177  )
178  {
179  bindBuffer(
180  attribute, object.*member,
181  static_cast<std::int32_t>(sizeof(ObjectType))
182  );
183  }
184 
185  //! \copydoc bindMember()
186  template <typename ObjectType, typename MemberPointer>
188  const std::string &attribute, //!< [in] attribute name
189  ObjectType &object, //!< [in] e.g. first object of container
190  const MemberPointer member, //!< [in] object member variable pointer
191  const std::size_t index //!< [in] index for array-like object members
192  )
193  {
194  bindBuffer(
195  attribute, (object.*member)[index],
196  static_cast<std::int32_t>(sizeof(ObjectType))
197  );
198  }
199 
200  /*!
201  * \brief Select points
202  *
203  * Use this function to actually read the selected points from
204  * database and copy the attributes to the defined buffers.
205  *
206  * Afterwards you may re-use the buffers or define new buffers
207  * with bind() and call next() again until all points have been
208  * read (i.e. next() returns zero).
209  *
210  * If no buffers were bound, calling next() is still valid. This can be
211  * used for counting points - either all or just those that meet some
212  * filter criteria. If no filter is specified the total point count is
213  * equal to what you get with riegl::rdb::Pointcloud::stat().
214  *
215  * \returns the number of points read
216  */
217  std::uint32_t next(
218  std::uint32_t count //!< [in] size of target buffers in terms of points
219  );
220 
221  /*!
222  * \brief Progress
223  *
224  * This function returns a coarse progress information in percent (0..100%).
225  * Since the total number of returned points is not known in advance, this
226  * value just reflects the progress of the (internal) index traversal.
227  *
228  * \note When the select query is used to count points (i.e. no buffers
229  * were bound), then this function always returns 0%.
230  */
231  std::uint32_t progress() const;
232 
233 private:
234  struct Private;
235  std::shared_ptr<Private> data;
236 };
237 
238 }}} // namespace riegl::rdb::pointcloud
239 
240 #endif // RIEGL_RDB_POINTCLOUD_QUERYSELECT_HPP
bool valid() const
Check if query is not null.
DataType
Point attribute access data type.
Definition: dataTypes.hpp:56
ValueType * dataPointerOf(ValueType *const value)
Get pointer to variable or to data in a std::array or vector container.
Definition: dataTypes.hpp:176
void bind(const std::string &attribute, const DataType dataType, void *buffer, const std::int32_t stride=0)
Bind attribute buffer.
void bindBuffer(const std::string &attribute, ValueType *buffer, const std::int32_t stride=0)
Bind attribute buffer.
std::uint32_t progress() const
Progress.
Index graph node.
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
void bindBuffer(const std::string &attribute, ValueType &buffer, const std::int32_t stride=0)
Bind attribute buffer.
DataType dataTypeOf()
Convenience wrapper for DataTypeOf class.
Definition: dataTypes.hpp:147
QuerySelect()
Default constructor.
std::uint32_t next(std::uint32_t count)
Select points.
void bindMember(const std::string &attribute, ObjectType &object, const MemberPointer member, const std::size_t index)
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.