| RDB 2

pointcloud.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 pointcloud.hpp
26 * \author RIEGL LMS GmbH, Austria
27 * \brief Main point cloud database class
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 2016-11-08/AW: New "fill query" (class QueryFill) added (#1926)
31 * \version 2016-11-14/AW: New "invert query" (class QueryInvert) added (#2406)
32 * \version 2016-11-16/AW: New function to output database statistics added
33 * \version 2017-03-21/AW: Database management interface added (#2550)
34 * \version 2017-08-22/AW: Added function to query database UUID (#2720)
35 * \version 2017-11-09/AW: Friend class 'PointAttributes' added
36 * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
37 * \version 2018-05-28/AW: New variant of create() that accepts a schema (#3109)
38 * \version 2018-09-20/AW: Fix order of included headers
39 * \version 2020-02-24/AW: New function to check if a database is empty (#3566)
40 * \version 2020-06-29/AW: Database changelog interface added (#3614)
41 * \version 2021-05-07/AW: Class Pointcloud is default constructible (#3887)
42 *
43 *******************************************************************************
44 */
45
46 #include "riegl/rdb.hpp"
47 #ifndef RIEGL_RDB_POINTCLOUD_HPP
48 #define RIEGL_RDB_POINTCLOUD_HPP
49
50 //---< INCLUDES >---------------------------------------------------------------
51
52 #include <memory>
53 #include <vector>
54 #include <cstdlib>
55
56 #include "riegl/rdb/pointcloud/changelog.hpp"
57 #include "riegl/rdb/pointcloud/dataTypes.hpp"
58 #include "riegl/rdb/pointcloud/createSettings.hpp"
59 #include "riegl/rdb/pointcloud/openSettings.hpp"
60 #include "riegl/rdb/pointcloud/management.hpp"
61 #include "riegl/rdb/pointcloud/metaData.hpp"
62 #include "riegl/rdb/pointcloud/pointAttribute.hpp"
63 #include "riegl/rdb/pointcloud/pointAttributes.hpp"
64 #include "riegl/rdb/pointcloud/transaction.hpp"
65 #include "riegl/rdb/pointcloud/transactions.hpp"
66 #include "riegl/rdb/pointcloud/queryInsert.hpp"
67 #include "riegl/rdb/pointcloud/queryUpdate.hpp"
68 #include "riegl/rdb/pointcloud/querySelect.hpp"
69 #include "riegl/rdb/pointcloud/queryRemove.hpp"
70 #include "riegl/rdb/pointcloud/queryStat.hpp"
71 #include "riegl/rdb/pointcloud/queryFill.hpp"
72 #include "riegl/rdb/pointcloud/queryInvert.hpp"
73
74 //---< NAMESPACE >--------------------------------------------------------------
75
76 namespace riegl {
77 namespace rdb {
78
79 //---< CLASS Pointcloud >-------------------------------------------------------
80 /*!
81 * \brief Main point cloud database class
82 *
83 * Use this class to create or open a point cloud database and insert, update
84 * or query points.
85 *
86 * \note All functions of this class throw an Exception of class
87 * riegl::rdb::Error in case of troubles.
88 */
89 class Pointcloud
90 {
91 //______________________________________________________________________________
92 //
93 //! \name Constructors and destructor
94 //! \{
95 public:
96 /*!
97 * \brief Create Pointcloud instance
98 *
99 * This creates a new Pointcloud object instance. To actually access or
100 * create a point cloud database file, you must call open() or create().
101 *
102 * Each Pointcloud instance may only be accessed from one thread/process at
103 * a time. Opening the same database using different Pointcloud instances
104 * (in the same or different thread or process) is allowed.
105 *
106 * \note The implicit copy-constructor and assignment-operators will yield
107 * to multiple instances pointing to the same database file. This
108 * is okay, as long as you do not intend to use both instances in
109 * different threads simultaneously.
110 *
111 * \see Pointcloud::create()
112 * \see Pointcloud::open()
113 */
114 explicit Pointcloud(Context context = Context());
115
116 /*!
117 * \brief Destroy Pointcloud instance
118 *
119 * \note If there are multiple Pointcloud instances pointing to the same
120 * file (see constructor notes), then the database file will be
121 * closed when the last Pointcloud instance is deleted.
122 */
123 ~Pointcloud();
124 //! \}
125 //______________________________________________________________________________
126 //
127 //! \name Database Access
128 //! \{
129 public:
130 /*!
131 * \brief Create new database
132 *
133 * This function creates a new (empty) database. If the given
134 * database already exists, it will be overwritten (unless it is
135 * opened by other clients, in which case the creation will fail).
136 * The target folder must exist - it is not created automatically.
137 * If the database could not be created, an exception is thrown.
138 */
139 void create(
140 const std::string &location, //!< [in] database location (filename)
141 const pointcloud::CreateSettings &settings //!< [in] database creation settings
142 );
143
144 /*!
145 * \brief Create new database
146 *
147 * \copydoc create()
148 *
149 * Additionally, all required point attributes and metadata entries as defined
150 * by the schema are added to the database. The schema is given in JSON format,
151 * details see riegl::rdb::pointcloud::Management::validate(). If 'optionals'
152 * is 'true', then also the optional point attributes and metadata entries
153 * are added to the database.
154 *
155 * \note
156 * Only RIEGL default point attributes and metadata entries are supported.
157 * Metadata entries are added but have no value (empty string).
158 *
159 * \note
160 * If the schema defines a primary point attribute, then it overrides
161 * the primary point attribute defined in the 'settings' parameter.
162 *
163 * \see riegl::rdb::pointcloud::Management::validate()
164 */
165 void create(
166 const std::string &location, //!< [in] database location (filename)
167 const pointcloud::CreateSettings &settings, //!< [in] database creation settings
168 const std::string &schema, //!< [in] database schema (JSON format)
169 const bool optionals=false //!< [in] true: include optional items
170 );
171
172 /*!
173 * \brief Open existing database
174 *
175 * Open existing database location.
176 * If the given database does not exist, an exception is thrown.
177 */
178 void open(
179 const std::string &location, //!< [in] database location (filename)
180 const pointcloud::OpenSettings &settings //!< [in] database open settings
181 );
182
183 /*!
184 * \brief Close database
185 *
186 * Close database file and release all internal resources.
187 * This function fails if there are pending transactions.
188 *
189 * \note Keep in mind to close all queries __before__
190 * you close or delete the database instance!
191 */
192 void close();
193
194 /*!
195 * \brief Check if a database is open
196 * \returns true if a database is open
197 */
198 bool isOpen() const;
199
200 /*!
201 * \brief Check if a database is empty
202 * \returns true if the database contains no points or no database is open
203 */
204 bool isEmpty() const;
205
206 /*!
207 * \brief Get database file's UUID
208 * \returns the Universally Unique Identifier of the database file
209 *
210 * \note Database files created with rdblib prior version 2.1.2 do
211 * not have a UUID. In this case the "nil" UUID is returned.
212 * If no database is opened, an empty string is returned.
213 */
214 std::string getUUID() const;
215
216 /*!
217 * \brief File statistics and debugging information
218 *
219 * This function returns statistics and debugging information about
220 * the database file which is intended for factory usage only (i.e.
221 * the format may change at any time and the content is undocumented).
222 */
223 std::string inspect(const std::uint8_t format);
224
225 /*!
226 * \brief Clear internal data cache
227 *
228 * This function clears (flushes) the internal data cache and reduces
229 * memory consumption as much as possible.
230 */
231 void clearCache();
232 //! \}
233 //______________________________________________________________________________
234 //
235 //! \name Database Management
236 //! \{
237 public:
238 /*!
239 * \brief Basic point cloud management interface
240 * \see riegl::rdb::pointcloud::Management
241 */
242 pointcloud::Management &management();
243 const pointcloud::Management &management() const; //!< \copydoc management()
244
245 /*!
246 * \brief Manage point cloud changelog
247 * \see riegl::rdb::pointcloud::Changelog
248 */
249 pointcloud::Changelog &changelog();
250 const pointcloud::Changelog &changelog() const; //!< \copydoc changelog()
251
252 /*!
253 * \brief Manage point cloud meta data
254 * \see riegl::rdb::pointcloud::MetaData
255 */
256 pointcloud::MetaData &metaData();
257 const pointcloud::MetaData &metaData() const; //!< \copydoc metaData()
258
259 /*!
260 * \brief Manage point attributes
261 * \see riegl::rdb::pointcloud::PointAttributes
262 */
263 pointcloud::PointAttributes &pointAttribute();
264 const pointcloud::PointAttributes &pointAttribute() const; //!< \copydoc pointAttribute()
265
266 /*!
267 * \brief Manage point cloud transactions
268 * \see riegl::rdb::pointcloud::Transactions
269 */
270 pointcloud::Transactions &transaction();
271 const pointcloud::Transactions &transaction() const; //!< \copydoc transaction()
272 //! \}
273 //______________________________________________________________________________
274 //
275 //! \name Point Queries
276 //! \{
277 public:
278 /*!
279 * \brief Insert points
280 *
281 * This function creates a new query object that can be used to
282 * insert (new) points into the database.
283 *
284 * \see riegl::rdb::pointcloud::QueryInsert
285 */
286 pointcloud::QueryInsert insert();
287
288 /*!
289 * \brief Update points
290 *
291 * This function creates a new query object that can be used to
292 * update (modify) attributes of existing points.
293 *
294 * \see riegl::rdb::pointcloud::QueryUpdate
295 */
296 pointcloud::QueryUpdate update();
297
298 /*!
299 * \brief Select points
300 *
301 * This function creates a new query object that can be used to
302 * select (read) attributes of existing points.<br>
303 * The optional filter expression can be used to select particular
304 * points - if no filter is given, all points will be loaded.<br>
305 *
306 * __Filter expression operators:__
307 *
308 * | operator | meaning |
309 * | :------: | ---------------------------------------- |
310 * | == | equality (left == right) |
311 * | != | inequality (left != right) |
312 * | < | less than (left < right) |
313 * | <= | less than or equal to (left <= right) |
314 * | > | greater than (left > right) |
315 * | >= | greater than or equal to (left >= right) |
316 * | && | conjunction (left && right) |
317 * | \|\| | disjunction (left \|\| right) |
318 * | % | unsigned modulo (left % right) |
319 *
320 * __Filter expression syntax:__
321 *
322 * - _constant_ = _integer_ | _double_ | _variable_ > ':' > ('minimum' | 'maximum' | 'default' | 'invalid')
323 * - _variable_ = [a-zA-Z] > ([0-9a-zA-Z] | '_' | '.')*
324 * - _operand_ = _constant_ | _variable_ | _expression_
325 * - _expression_ = (_operand_)? > _operator_ > _operand_
326 *
327 * __Filter expression examples:__
328 *
329 * - "" (empty string means "all points")
330 * - "amplitude > 5.0"
331 * - "(reflectance > 0.0) && (selected == 1)"
332 * - "point_count != point_count:invalid"
333 * - "(id % 2) == 0"
334 *
335 * __Stored filters:__
336 *
337 * Filters can also be stored in the metadata as `riegl.stored_filters`.
338 * All activated filters of this list will be applied in addition to the
339 * filter specified by the application (conjunction). To temporarily ignore
340 * (override) all stored filters, insert `"!!"` at the beginning or end of
341 * the filter string (e.g. `"!! riegl.id == 1"` or `"riegl.id == 1 !!"`).
342 *
343 * \note The resolution of a point attribute is used as a tolerance when comparing
344 * attribute values with constants (i.e. constants are rounded to the nearest
345 * multiple of the attribute resolution before comparison).
346 *
347 * \see riegl::rdb::pointcloud::QuerySelect
348 */
349 pointcloud::QuerySelect select(
350 const std::string &filter = std::string() //!< [in] optional point filter expression
351 );
352
353 /*!
354 * \brief Select points by index node
355 *
356 * \copydetails select()
357 *
358 * Instead of loading all points of the point cloud this variant just loads
359 * the points contained in a single node. See notes about LOD for details.
360 */
361 pointcloud::QuerySelect select(
362 const pointcloud::GraphNode::ID &node, //!< [in] ID of index graph node
363 const std::string &filter = std::string() //!< [in] optional point filter expression
364 );
365
366 /*!
367 * \brief Select points by index nodes
368 *
369 * \copydetails select()
370 *
371 * Instead of loading all points of the point cloud this variant just loads
372 * the points contained in the given nodes. See notes about LOD for details.
373 */
374 pointcloud::QuerySelect select(
375 const std::vector<pointcloud::GraphNode::ID> &nodes, //!< [in] IDs of index graph nodes
376 const std::string &filter = std::string() //!< [in] optional point filter expression
377 );
378
379 /*!
380 * \brief Fill points
381 *
382 * This function creates a new query object that can be used to
383 * set (modify) attributes of existing points.
384 *
385 * Please have a look at select() for details about the filter expression.
386 *
387 * \see riegl::rdb::pointcloud::QueryFill
388 */
389 pointcloud::QueryFill fill(
390 const std::string &filter = std::string() //!< [in] optional point filter expression
391 );
392
393 /*!
394 * \brief Fill points by index node
395 *
396 * \copydetails fill()
397 *
398 * Instead of modifying all points of the point cloud this variant just modifies
399 * the points contained in a single node. See notes about LOD for details.
400 */
401 pointcloud::QueryFill fill(
402 const pointcloud::GraphNode::ID &node, //!< [in] ID of index graph node
403 const std::string &filter = std::string() //!< [in] optional point filter expression
404 );
405
406 /*!
407 * \brief Fill points by index nodes
408 *
409 * \copydetails fill()
410 *
411 * Instead of modifying all points of the point cloud this variant just modifies
412 * the points contained in the given nodes. See notes about LOD for details.
413 */
414 pointcloud::QueryFill fill(
415 const std::vector<pointcloud::GraphNode::ID> &nodes, //!< [in] IDs of index graph nodes
416 const std::string &filter = std::string() //!< [in] optional point filter expression
417 );
418
419 /*!
420 * \brief Invert points
421 *
422 * This function creates a new query object that can be used to
423 * invert attributes of existing points.
424 *
425 * Please have a look at select() for details about the filter expression.
426 *
427 * \see riegl::rdb::pointcloud::QueryInvert
428 */
429 pointcloud::QueryInvert invert(
430 const std::string &filter = std::string() //!< [in] optional point filter expression
431 );
432
433 /*!
434 * \brief Invert points by index node
435 *
436 * \copydetails invert()
437 *
438 * Instead of inverting all points of the point cloud this variant just inverts
439 * the points contained in a single node. See notes about LOD for details.
440 */
441 pointcloud::QueryInvert invert(
442 const pointcloud::GraphNode::ID &node, //!< [in] ID of index graph node
443 const std::string &filter = std::string() //!< [in] optional point filter expression
444 );
445
446 /*!
447 * \brief Invert points by index nodes
448 *
449 * \copydetails invert()
450 *
451 * Instead of inverting all points of the point cloud this variant just inverts
452 * the points contained in the given nodes. See notes about LOD for details.
453 */
454 pointcloud::QueryInvert invert(
455 const std::vector<pointcloud::GraphNode::ID> &nodes, //!< [in] IDs of index graph nodes
456 const std::string &filter = std::string() //!< [in] optional point filter expression
457 );
458
459 /*!
460 * \brief Remove points
461 *
462 * This function creates a new query object that can be used to
463 * remove (delete) existing points.
464 *
465 * \see riegl::rdb::pointcloud::QueryRemove
466 */
467 pointcloud::QueryRemove remove();
468
469 /*!
470 * \brief Query point statistics
471 *
472 * This function creates a new query object that can be used to
473 * get point attribute statistics like minimum and maximum value.
474 *
475 * \see riegl::rdb::pointcloud::QueryStat
476 */
477 pointcloud::QueryStat stat();
478 //! \}
479 //______________________________________________________________________________
480 //
481 private:
482 friend class riegl::rdb::pointcloud::PointAttributes;
483 std::shared_ptr<riegl::rdb::PointcloudData> data;
484
485 #ifdef RIEGL_RDB_POINTCLOUD_IMPLEMENTATION_DETAILS
486 RIEGL_RDB_POINTCLOUD_IMPLEMENTATION_DETAILS
487 #endif
488 };
489
490 }} // namespace riegl::rdb
491
492 #endif // RIEGL_RDB_POINTCLOUD_HPP
riegl::rdb::pointcloud::QueryStat
Point statistics query.
Definition: queryStat.hpp:69
riegl::rdb::pointcloud::Transactions
Manage point cloud transactions.
Definition: transactions.hpp:68
createSettings.hpp
Database create settings.
queryStat.hpp
Point statistics query.
riegl::rdb::pointcloud::PointAttributes
Manage point attributes.
Definition: pointAttributes.hpp:83
riegl::rdb::Pointcloud::transaction
pointcloud::Transactions & transaction()
Manage point cloud transactions.
riegl::rdb::Pointcloud::~Pointcloud
~Pointcloud()
Destroy Pointcloud instance.
riegl::rdb::Pointcloud::pointAttribute
pointcloud::PointAttributes & pointAttribute()
Manage point attributes.
riegl::rdb::Context
Library context.
Definition: context.hpp:75
querySelect.hpp
Point select query.
riegl::rdb::Pointcloud::fill
pointcloud::QueryFill fill(const std::string &filter=std::string())
Fill points.
metaData.hpp
Manage point cloud meta data.
riegl::rdb::Pointcloud::close
void close()
Close database.
riegl::rdb::Pointcloud::insert
pointcloud::QueryInsert insert()
Insert points.
riegl::rdb::Pointcloud::management
pointcloud::Management & management()
Basic point cloud management interface.
riegl::rdb::Pointcloud::Pointcloud
Pointcloud(Context context=Context())
Create Pointcloud instance.
riegl::rdb::pointcloud::GraphNode::ID
std::uint32_t ID
Definition: graphNode.hpp:78
queryFill.hpp
Point fill query.
transaction.hpp
Point cloud transaction.
management.hpp
Basic point cloud management interface.
riegl::rdb::Pointcloud::isEmpty
bool isEmpty() const
Check if a database is empty.
queryRemove.hpp
Point remove query.
riegl::rdb::Pointcloud::metaData
pointcloud::MetaData & metaData()
Manage point cloud meta data.
riegl::rdb::pointcloud::QueryFill
Point fill query.
Definition: queryFill.hpp:71
riegl::rdb::Pointcloud
Main point cloud database class.
Definition: pointcloud.hpp:89
riegl::rdb::Pointcloud::isOpen
bool isOpen() const
Check if a database is open.
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::Pointcloud::changelog
pointcloud::Changelog & changelog()
Manage point cloud changelog.
riegl::rdb::Pointcloud::select
pointcloud::QuerySelect select(const std::string &filter=std::string())
Select points.
riegl::rdb::pointcloud::QueryInsert
Point insert query.
Definition: queryInsert.hpp:67
riegl::rdb::pointcloud::OpenSettings
Database open settings.
Definition: openSettings.hpp:61
pointAttribute.hpp
Point attribute description.
riegl::rdb::pointcloud::CreateSettings
Database create settings.
Definition: createSettings.hpp:67
riegl::rdb::Pointcloud::getUUID
std::string getUUID() const
Get database file&#39;s UUID.
riegl::rdb::Pointcloud::create
void create(const std::string &location, const pointcloud::CreateSettings &settings)
Create new database.
queryInsert.hpp
Point insert query.
riegl::rdb::pointcloud::QuerySelect
Point select query.
Definition: querySelect.hpp:69
queryInvert.hpp
Point invert query.
riegl::rdb::pointcloud::QueryInvert
Point invert query.
Definition: queryInvert.hpp:77
riegl::rdb::Pointcloud::inspect
std::string inspect(const std::uint8_t format)
File statistics and debugging information.
riegl::rdb::Pointcloud::open
void open(const std::string &location, const pointcloud::OpenSettings &settings)
Open existing database.
rdb.hpp
Main RDB library include file.
riegl::rdb::pointcloud::QueryUpdate
Point update query.
Definition: queryUpdate.hpp:66
riegl::rdb::pointcloud::Changelog
Manage point cloud changelog.
Definition: changelog.hpp:76
pointAttributes.hpp
Manage point attributes.
riegl::rdb::pointcloud::QueryRemove
Point remove query.
Definition: queryRemove.hpp:65
changelog.hpp
Manage point cloud changelog.
transactions.hpp
Manage point cloud transactions.
openSettings.hpp
Database open settings.
dataTypes.hpp
Point attribute access data types.
riegl::rdb::Pointcloud::invert
pointcloud::QueryInvert invert(const std::string &filter=std::string())
Invert points.
riegl::rdb::Pointcloud::update
pointcloud::QueryUpdate update()
Update points.
riegl::rdb::Pointcloud::clearCache
void clearCache()
Clear internal data cache.
riegl::rdb::Pointcloud::stat
pointcloud::QueryStat stat()
Query point statistics.
queryUpdate.hpp
Point update query.
riegl::rdb::pointcloud::Management
Basic point cloud management interface.
Definition: management.hpp:64
riegl::rdb::pointcloud::MetaData
Manage point cloud meta data.
Definition: metaData.hpp:66