| RDB 2

querySelect.hpp
Go to the documentation of this file.
1 /*
2 *******************************************************************************
3 *
4 * Copyright 2025 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
48 #include "riegl/rdb/pointcloud/dataTypes.hpp"
49 #include "riegl/rdb/pointcloud/graphNode.hpp"
50 #include "riegl/rdb/pointcloud/pointcloudData.hpp"
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 */
69 class QuerySelect
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>
142 void bindBuffer(
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>
153 void bindBuffer(
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>
173 void bindMember(
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>
187 void bindMember(
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
riegl::rdb::pointcloud::QuerySelect::close
void close()
Finish query.
riegl::rdb::pointcloud::DataType
DataType
Point attribute access data type.
Definition: dataTypes.hpp:56
riegl::rdb::pointcloud::dataPointerOf
ValueType * dataPointerOf(ValueType *const value)
Get pointer to variable or to data in a std::array or vector container.
Definition: dataTypes.hpp:176
riegl::rdb::pointcloud::QuerySelect::bind
void bind(const std::string &attribute, const DataType dataType, void *buffer, const std::int32_t stride=0)
Bind attribute buffer.
riegl::rdb::pointcloud::QuerySelect::bindBuffer
void bindBuffer(const std::string &attribute, ValueType *buffer, const std::int32_t stride=0)
Bind attribute buffer.
Definition: querySelect.hpp:153
graphNode.hpp
Index graph node.
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::pointcloud::QuerySelect::bindBuffer
void bindBuffer(const std::string &attribute, ValueType &buffer, const std::int32_t stride=0)
Bind attribute buffer.
Definition: querySelect.hpp:142
riegl::rdb::pointcloud::dataTypeOf
DataType dataTypeOf()
Convenience wrapper for DataTypeOf class.
Definition: dataTypes.hpp:147
riegl::rdb::pointcloud::QuerySelect
Point select query.
Definition: querySelect.hpp:69
riegl::rdb::pointcloud::QuerySelect::QuerySelect
QuerySelect()
Default constructor.
riegl::rdb::pointcloud::QuerySelect::next
std::uint32_t next(std::uint32_t count)
Select points.
riegl::rdb::pointcloud::QuerySelect::valid
bool valid() const
Check if query is not null.
riegl::rdb::pointcloud::QuerySelect::bindMember
void bindMember(const std::string &attribute, ObjectType &object, const MemberPointer member, const std::size_t index)
Bind attribute buffer.
Definition: querySelect.hpp:187
dataTypes.hpp
Point attribute access data types.
pointcloudData.hpp
Pointcloud class implementation details.
riegl::rdb::pointcloud::QuerySelect::bindMember
void bindMember(const std::string &attribute, ObjectType &object, const MemberPointer member)
Bind attribute buffer.
Definition: querySelect.hpp:173
riegl::rdb::pointcloud::QuerySelect::progress
std::uint32_t progress() const
Progress.