| RDB 2

queryFill.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 queryFill.hpp
26 * \author RIEGL LMS GmbH, Austria
27 * \brief Point fill query
28 * \version 2016-11-08/AW: Initial version
29 * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
30 * \version 2018-07-05/AW: Wrapper function bindBuffer() added
31 * \version 2020-01-17/AW: Wrapper function bindMember() added (#3497)
32 *
33 *******************************************************************************
34 */
35
36 #ifndef RIEGL_RDB_POINTCLOUD_QUERYFILL_HPP
37 #define RIEGL_RDB_POINTCLOUD_QUERYFILL_HPP
38
39 //---< INCLUDES >---------------------------------------------------------------
40
41 #include <memory>
42 #include <string>
43 #include <vector>
44 #include <cstdlib>
45 #include <cstdint>
46
47 #include "riegl/rdb/pointcloud/dataTypes.hpp"
48 #include "riegl/rdb/pointcloud/graphNode.hpp"
49 #include "riegl/rdb/pointcloud/pointcloudData.hpp"
50
51 //---< NAMESPACE >--------------------------------------------------------------
52
53 namespace riegl {
54 namespace rdb {
55 namespace pointcloud {
56
57 //---< CLASS QueryFill >--------------------------------------------------------
58 /*!
59 * \brief Point fill query
60 *
61 * This class can be used to set attributes of existing points to a (one)
62 * specific value (e.g. set "riegl.selected" to "1" for all points). This
63 * query is similar to using select() and update() except that it only accepts
64 * one value per point attribute and this value is copied to all points.
65 *
66 * \see riegl::rdb::Pointcloud::fill()
67 *
68 * \note You either must delete the query object or call close()
69 * __before__ the parent Pointcloud instance is closed/deleted!
70 */
71 class QueryFill
72 {
73 public:
74 /*!
75 * \brief Default constructor
76 *
77 * Creates a null query - i.e. the query cannot be used to modify points.
78 *
79 * \see riegl::rdb::Pointcloud::fill()
80 */
81 explicit QueryFill();
82
83 /*!
84 * \brief Constructor
85 *
86 * Creates a query prepared for modifying points.
87 *
88 * \note You cannot create new QueryFill objects this way,
89 * use riegl::rdb::Pointcloud::fill() instead.
90 */
91 explicit QueryFill(
92 riegl::rdb::PointcloudData *pointcloud,
93 const std::vector<GraphNode::ID> *nodes,
94 const std::string &filter
95 );
96
97 /*!
98 * \brief Check if query is not null
99 *
100 * \see valid()
101 */
102 operator bool() const;
103
104 /*!
105 * \brief Check if query is not null
106 *
107 * A null query cannot be used to read points.
108 */
109 bool valid() const;
110
111 /*!
112 * \brief Finish query
113 *
114 * Call this function when done with modifying points.
115 */
116 void close();
117
118 /*!
119 * \brief Bind attribute buffer
120 *
121 * Use this function to define a source buffer for a point attribute.
122 * Exactly one buffer can be defined for an attribute (i.e. only the
123 * most recently defined buffer will be used).
124 *
125 * The buffer is expected to be 1*s*d bytes large, where
126 * __s__ is the size of one element as defined by 'dataType' and
127 * __d__ is the number of attribute dimensions (elements).
128 *
129 * \note This function just stores the buffer pointer. So make
130 * sure that the buffer remains valid until you call next().
131 *
132 * \note If the value contained in the buffer is equal to the value
133 * of a point in the database, then the point is not updated.
134 * So if the values of all points are equal to the given value,
135 * then no points are updated and the point attribute revision
136 * stored at the primary index node will not change.
137 *
138 * \see riegl::rdb::pointcloud::PointAttributes
139 */
140 void bind(
141 const std::string &attribute, //!< [in] attribute name
142 const DataType dataType, //!< [in] buffer data type
143 const void *buffer //!< [in] buffer location
144 );
145
146 //! \copydoc bind()
147 template <typename ValueType>
148 void bindBuffer(
149 const std::string &attribute, //!< [in] attribute name
150 const ValueType &buffer //!< [in] buffer (data, pointer to data, std::array or std::vector)
151 )
152 {
153 bind(attribute, dataTypeOf(buffer), dataPointerOf(buffer));
154 }
155
156 /*!
157 * \brief Bind attribute buffer
158 *
159 * This is a variant of bindBuffer() that allows to bind a member variable
160 * of an object as attribute buffer.
161 *
162 * \see bindBuffer()
163 */
164 template <typename ObjectType, typename MemberPointer>
165 void bindMember(
166 const std::string &attribute, //!< [in] attribute name
167 const ObjectType &object, //!< [in] e.g. first object of container
168 const MemberPointer member //!< [in] object member variable pointer
169 )
170 {
171 bindBuffer(attribute, object.*member);
172 }
173
174 //! \copydoc bindMember()
175 template <typename ObjectType, typename MemberPointer>
176 void bindMember(
177 const std::string &attribute, //!< [in] attribute name
178 const ObjectType &object, //!< [in] e.g. first object of container
179 const MemberPointer member, //!< [in] object member variable pointer
180 const std::size_t index //!< [in] index for array-like object members
181 )
182 {
183 bindBuffer(attribute, (object.*member)[index]);
184 }
185
186 /*!
187 * \brief Fill points
188 *
189 * Use this function to actually read the point attributes from
190 * all defined buffers and update the points in the database.
191 *
192 * To process all points, you need to repeatedly call next() until it
193 * returns 0 (zero, see example 7). The number of points to process in
194 * one step is defined by 'count'. Please note that the actual number
195 * of processed points may be slightly different. To cancel processing
196 * just stop calling next() and cancel (rollback) the transaction.
197 *
198 * \note IEEE-754 "NaN" values contained in floating point source
199 * buffers are ignored and the attribute's default value is
200 * used instead. Furthermore IEEE-754 "Infinity" values will
201 * always cause next() to fail with error code 10414, i.e.
202 * riegl::rdb::Error::QueryAttributeValueOutOfRange.
203 *
204 * \note Since version 2.4.2, unit vector point attributes (e.g.
205 * "riegl.direction") are automatically normalized (divided
206 * by the vector length) on insertion. This is done for all
207 * point attributes that meet the following requirements:
208 * `length` is 3, `minimumValue` is -1, `maximumValue` is 1,
209 * `resolution` is not 1, `scaleFactor` is 1, `unitSymbol` is
210 * empty, `invalidValue` is undefined and `tags` contains the
211 * "direction" tag but not the "do-not-normalize" tag.
212 *
213 * \returns the number of points processed
214 */
215 std::uint32_t next(
216 std::uint32_t count //!< [in] number of points to process
217 );
218
219 /*!
220 * \brief Progress
221 *
222 * This function returns a coarse progress information in percent (0..100%).
223 * Since the total number of modified points is not known in advance, this
224 * value just reflects the progress of the (internal) index traversal.
225 */
226 std::uint32_t progress() const;
227
228 private:
229 struct Private;
230 std::shared_ptr<Private> data;
231 };
232
233 }}} // namespace riegl::rdb::pointcloud
234
235 #endif // RIEGL_RDB_POINTCLOUD_QUERYFILL_HPP
riegl::rdb::pointcloud::QueryFill::bindMember
void bindMember(const std::string &attribute, const ObjectType &object, const MemberPointer member, const std::size_t index)
Bind attribute buffer.
Definition: queryFill.hpp:176
riegl::rdb::pointcloud::DataType
DataType
Point attribute access data type.
Definition: dataTypes.hpp:56
riegl::rdb::pointcloud::QueryFill::next
std::uint32_t next(std::uint32_t count)
Fill points.
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::QueryFill::progress
std::uint32_t progress() const
Progress.
riegl::rdb::pointcloud::QueryFill::QueryFill
QueryFill()
Default constructor.
riegl::rdb::pointcloud::QueryFill::bind
void bind(const std::string &attribute, const DataType dataType, const void *buffer)
Bind attribute buffer.
riegl::rdb::pointcloud::QueryFill
Point fill query.
Definition: queryFill.hpp:71
graphNode.hpp
Index graph node.
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::pointcloud::dataTypeOf
DataType dataTypeOf()
Convenience wrapper for DataTypeOf class.
Definition: dataTypes.hpp:147
riegl::rdb::pointcloud::QueryFill::close
void close()
Finish query.
riegl::rdb::pointcloud::QueryFill::bindBuffer
void bindBuffer(const std::string &attribute, const ValueType &buffer)
Bind attribute buffer.
Definition: queryFill.hpp:148
riegl::rdb::pointcloud::QueryFill::bindMember
void bindMember(const std::string &attribute, const ObjectType &object, const MemberPointer member)
Bind attribute buffer.
Definition: queryFill.hpp:165
dataTypes.hpp
Point attribute access data types.
pointcloudData.hpp
Pointcloud class implementation details.
riegl::rdb::pointcloud::QueryFill::valid
bool valid() const
Check if query is not null.