RDB 2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
queryFill.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 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 
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>
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>
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>
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
void bindMember(const std::string &attribute, const ObjectType &object, const MemberPointer member, const std::size_t index)
Bind attribute buffer.
Definition: queryFill.hpp:176
DataType
Point attribute access data type.
Definition: dataTypes.hpp:56
std::uint32_t next(std::uint32_t count)
Fill points.
ValueType * dataPointerOf(ValueType *const value)
Get pointer to variable or to data in a std::array or vector container.
Definition: dataTypes.hpp:176
QueryFill()
Default constructor.
void bind(const std::string &attribute, const DataType dataType, const void *buffer)
Bind attribute buffer.
std::uint32_t progress() const
Progress.
Index graph node.
DataType dataTypeOf()
Convenience wrapper for DataTypeOf class.
Definition: dataTypes.hpp:147
void bindBuffer(const std::string &attribute, const ValueType &buffer)
Bind attribute buffer.
Definition: queryFill.hpp:148
void bindMember(const std::string &attribute, const ObjectType &object, const MemberPointer member)
Bind attribute buffer.
Definition: queryFill.hpp:165
bool valid() const
Check if query is not null.
Point attribute access data types.
Pointcloud class implementation details.