RDB 2
queryInsert.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 queryInsert.hpp
26  * \author RIEGL LMS GmbH, Austria
27  * \brief Point insert query
28  * \version 2015-10-14/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  * \version 2020-02-27/AW: Add bindId() for "riegl.id" data buffers (#3576)
33  *
34  *******************************************************************************
35  */
36 
37 #ifndef RIEGL_RDB_POINTCLOUD_QUERYINSERT_HPP
38 #define RIEGL_RDB_POINTCLOUD_QUERYINSERT_HPP
39 
40 //---< INCLUDES >---------------------------------------------------------------
41 
42 #include <memory>
43 #include <string>
44 #include <cstdint>
47 
48 //---< NAMESPACE >--------------------------------------------------------------
49 
50 namespace riegl {
51 namespace rdb {
52 namespace pointcloud {
53 
54 //---< CLASS QueryInsert >------------------------------------------------------
55 /*!
56  * \brief Point insert query
57  *
58  * This class can be used to insert (new) points into the database.
59  *
60  * \see riegl::rdb::Pointcloud::insert()
61  *
62  * \note You either must delete the query object or call close()
63  * __before__ the parent Pointcloud instance is closed/deleted!
64  */
66 {
67 public:
68  /*!
69  * \brief Default constructor
70  *
71  * Creates a null query - i.e. the query cannot be used to insert points.
72  *
73  * \see riegl::rdb::Pointcloud::insert()
74  */
75  explicit QueryInsert();
76 
77  /*!
78  * \brief Constructor
79  *
80  * Creates a query prepared for inserting points.
81  *
82  * \note You cannot create new QueryInsert objects this way,
83  * use riegl::rdb::Pointcloud::insert() instead.
84  */
85  explicit QueryInsert(riegl::rdb::PointcloudData *pointcloud);
86 
87  /*!
88  * \brief Check if query is not null
89  *
90  * \see valid()
91  */
92  operator bool() const;
93 
94  /*!
95  * \brief Check if query is not null
96  *
97  * A null query cannot be used to insert points.
98  */
99  bool valid() const;
100 
101  /*!
102  * \brief Finish query
103  *
104  * Call this function when done with inserting points.
105  */
106  void close();
107 
108  /*!
109  * \brief Bind attribute buffer
110  *
111  * Use this function to define a source buffer for a point attribute.
112  * Exactly one buffer can be defined for an attribute (i.e. only the
113  * most recently defined buffer will be used).
114  *
115  * You can but don't need to define a buffer for each attribute. If
116  * no buffer is defined for an attribute, the attribute's default
117  * value will be used instead.
118  *
119  * The buffer is expected to be n*s*d bytes large, where
120  * __n__ is the number of points defined in next(),
121  * __s__ is the size of one element as defined by 'dataType' and
122  * __d__ is the number of attribute dimensions (elements).
123  *
124  * \note This function just stores the buffer pointer - it does
125  * __NOT__ copy the data contained in the buffer. So make
126  * sure that the buffer remains valid until you call next().
127  *
128  * \see riegl::rdb::pointcloud::PointAttributes
129  */
130  void bind(
131  const std::string &attribute, //!< [in] attribute name
132  const DataType dataType, //!< [in] buffer data type
133  const void *buffer, //!< [in] buffer location
134  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
135  );
136 
137  /*!
138  * \brief Bind point id buffer
139  *
140  * If you provide a buffer for the point identifier attribute ("riegl.id"),
141  * then it will receive the identifiers of the inserted points (PID). Each
142  * point is assigned a unique PID on insertion. The PID starts at 1 for the
143  * first point and is incremented by 1 for each subsequent point (so that
144  * the PID reflects the insertion order of the points).
145  *
146  * \see bind()
147  */
148  void bindId(
149  const DataType dataType, //!< [in] buffer data type
150  void *buffer, //!< [in] buffer location
151  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
152  );
153 
154  //! \copydoc bind()
155  template <typename ValueType>
157  const std::string &attribute, //!< [in] attribute name
158  const ValueType &buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
159  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
160  )
161  {
162  bind(attribute, dataTypeOf(buffer), dataPointerOf(buffer), stride);
163  }
164 
165  /*!
166  * \copydoc bindId()
167  * \see bindBuffer()
168  */
169  template <typename ValueType>
171  ValueType &buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
172  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
173  )
174  {
175  bindId(dataTypeOf(buffer), dataPointerOf(buffer), stride);
176  }
177 
178  /*!
179  * \copydoc bindId()
180  * \see bindBuffer()
181  */
182  template <typename ValueType>
184  ValueType *buffer, //!< [in] buffer (data, pointer to data, std::array or std::vector)
185  const int32_t stride = 0 //!< [in] bytes between beginnings of successive elements (0: auto)
186  )
187  {
188  bindId(dataTypeOf(buffer), buffer, stride);
189  }
190 
191  /*!
192  * \brief Bind attribute buffer
193  *
194  * This is a variant of bindBuffer() that allows to bind a member variable
195  * of an object as attribute buffer. The object can be part of a container
196  * that stores the objects contiguously (e.g. std::vector, std::array) and
197  * the stride is automatically derived from the object size.
198  *
199  * \see bindBuffer()
200  */
201  template <typename ObjectType, typename MemberPointer>
203  const std::string &attribute, //!< [in] attribute name
204  const ObjectType &object, //!< [in] e.g. first object of container
205  const MemberPointer member //!< [in] object member variable pointer
206  )
207  {
208  bindBuffer(
209  attribute, object.*member,
210  static_cast<int32_t>(sizeof(ObjectType))
211  );
212  }
213 
214  /*!
215  * \copydoc bindId()
216  * \see bindMember()
217  */
218  template <typename ObjectType, typename MemberPointer>
220  ObjectType &object, //!< [in] e.g. first object of container
221  MemberPointer member //!< [in] object member variable pointer
222  )
223  {
224  bindIdBuffer(
225  object.*member,
226  static_cast<int32_t>(sizeof(ObjectType))
227  );
228  }
229 
230  //! \copydoc bindMember()
231  template <typename ObjectType, typename MemberPointer>
233  const std::string &attribute, //!< [in] attribute name
234  const ObjectType &object, //!< [in] e.g. first object of container
235  const MemberPointer member, //!< [in] object member variable pointer
236  const size_t index //!< [in] index for array-like object members
237  )
238  {
239  bindBuffer(
240  attribute, (object.*member)[index],
241  static_cast<int32_t>(sizeof(ObjectType))
242  );
243  }
244 
245  /*!
246  * \copydoc bindId()
247  * \see bindMember()
248  */
249  template <typename ObjectType, typename MemberPointer>
251  ObjectType &object, //!< [in] e.g. first object of container
252  MemberPointer member, //!< [in] object member variable pointer
253  const size_t index //!< [in] index for array-like object members
254  )
255  {
256  bindIdBuffer(
257  (object.*member)[index],
258  static_cast<int32_t>(sizeof(ObjectType))
259  );
260  }
261 
262  /*!
263  * \brief Insert points
264  *
265  * Use this function to actually read the point attributes from
266  * all defined buffers and insert the points into the database.
267  *
268  * Afterwards you may re-fill the buffers or define new buffers
269  * with bind() and call next() again until all points have been
270  * inserted.
271  *
272  * \note IEEE-754 "NaN" values contained in floating point source
273  * buffers are ignored and the attribute's default value is
274  * used instead. Furthermore IEEE-754 "Infinity" values will
275  * always cause next() to fail with error code 10414, i.e.
276  * riegl::rdb::Error::QueryAttributeValueOutOfRange.
277  *
278  * \returns the number of points inserted
279  */
280  uint32_t next(
281  uint32_t count //!< [in] size of source buffers in terms of points
282  );
283 
284 private:
285  struct Private;
286  std::shared_ptr<Private> data;
287 };
288 
289 }}} // namespace riegl::rdb::pointcloud
290 
291 #endif // RIEGL_RDB_POINTCLOUD_QUERYINSERT_HPP
riegl::rdb::pointcloud::QueryInsert::bindIdMember
void bindIdMember(ObjectType &object, MemberPointer member, const size_t index)
Bind point id buffer.
Definition: queryInsert.hpp:250
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::pointcloud::QueryInsert::bindMember
void bindMember(const std::string &attribute, const ObjectType &object, const MemberPointer member, const size_t index)
Bind attribute buffer.
Definition: queryInsert.hpp:232
riegl::rdb::pointcloud::QueryInsert::close
void close()
Finish query.
riegl::rdb::pointcloud::dataTypeOf
DataType dataTypeOf()
Convenience wrapper for DataTypeOf class.
Definition: dataTypes.hpp:146
riegl::rdb::pointcloud::QueryInsert::bindIdMember
void bindIdMember(ObjectType &object, MemberPointer member)
Bind point id buffer.
Definition: queryInsert.hpp:219
riegl::rdb::pointcloud::QueryInsert::QueryInsert
QueryInsert()
Default constructor.
riegl::rdb::pointcloud::QueryInsert::bind
void bind(const std::string &attribute, const DataType dataType, const void *buffer, const int32_t stride=0)
Bind attribute buffer.
dataTypes.hpp
Point attribute access data types.
riegl::rdb::pointcloud::QueryInsert
Point insert query.
Definition: queryInsert.hpp:65
riegl::rdb::pointcloud::QueryInsert::bindMember
void bindMember(const std::string &attribute, const ObjectType &object, const MemberPointer member)
Bind attribute buffer.
Definition: queryInsert.hpp:202
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:175
riegl::rdb::pointcloud::QueryInsert::bindIdBuffer
void bindIdBuffer(ValueType &buffer, const int32_t stride=0)
Bind point id buffer.
Definition: queryInsert.hpp:170
riegl::rdb::pointcloud::QueryInsert::bindBuffer
void bindBuffer(const std::string &attribute, const ValueType &buffer, const int32_t stride=0)
Bind attribute buffer.
Definition: queryInsert.hpp:156
pointcloudData.hpp
Pointcloud class implementation details.
riegl::rdb::pointcloud::QueryInsert::valid
bool valid() const
Check if query is not null.
riegl::rdb::pointcloud::QueryInsert::bindIdBuffer
void bindIdBuffer(ValueType *buffer, const int32_t stride=0)
Bind point id buffer.
Definition: queryInsert.hpp:183
riegl::rdb::pointcloud::QueryInsert::bindId
void bindId(const DataType dataType, void *buffer, const int32_t stride=0)
Bind point id buffer.
riegl::rdb::pointcloud::QueryInsert::next
uint32_t next(uint32_t count)
Insert points.
riegl::rdb::pointcloud::DataType
DataType
Point attribute access data type.
Definition: dataTypes.hpp:55