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