RDB 2
pointcloud.hpp
Go to the documentation of this file.
1 /*
2  *******************************************************************************
3  *
4  * Copyright 2024 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 
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  */
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  */
243  const pointcloud::Management &management() const; //!< \copydoc management()
244 
245  /*!
246  * \brief Manage point cloud changelog
247  * \see riegl::rdb::pointcloud::Changelog
248  */
250  const pointcloud::Changelog &changelog() const; //!< \copydoc changelog()
251 
252  /*!
253  * \brief Manage point cloud meta data
254  * \see riegl::rdb::pointcloud::MetaData
255  */
257  const pointcloud::MetaData &metaData() const; //!< \copydoc metaData()
258 
259  /*!
260  * \brief Manage point attributes
261  * \see riegl::rdb::pointcloud::PointAttributes
262  */
264  const pointcloud::PointAttributes &pointAttribute() const; //!< \copydoc pointAttribute()
265 
266  /*!
267  * \brief Manage point cloud transactions
268  * \see riegl::rdb::pointcloud::Transactions
269  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
478 //! \}
479 //______________________________________________________________________________
480 //
481 private:
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
Point statistics query.
Definition: queryStat.hpp:69
Manage point cloud transactions.
Database create settings.
Point statistics query.
pointcloud::Transactions & transaction()
Manage point cloud transactions.
~Pointcloud()
Destroy Pointcloud instance.
pointcloud::PointAttributes & pointAttribute()
Manage point attributes.
Library context.
Definition: context.hpp:75
Point select query.
pointcloud::QueryFill fill(const std::string &filter=std::string())
Fill points.
Manage point cloud meta data.
void close()
Close database.
pointcloud::QueryInsert insert()
Insert points.
pointcloud::Management & management()
Basic point cloud management interface.
Pointcloud(Context context=Context())
Create Pointcloud instance.
Point fill query.
Point cloud transaction.
Basic point cloud management interface.
bool isEmpty() const
Check if a database is empty.
Point remove query.
pointcloud::MetaData & metaData()
Manage point cloud meta data.
Main point cloud database class.
Definition: pointcloud.hpp:89
bool isOpen() const
Check if a database is open.
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
pointcloud::Changelog & changelog()
Manage point cloud changelog.
pointcloud::QuerySelect select(const std::string &filter=std::string())
Select points.
Point attribute description.
std::string getUUID() const
Get database file&#39;s UUID.
void create(const std::string &location, const pointcloud::CreateSettings &settings)
Create new database.
Point insert query.
Point invert query.
std::string inspect(const std::uint8_t format)
File statistics and debugging information.
void open(const std::string &location, const pointcloud::OpenSettings &settings)
Open existing database.
Main RDB library include file.
Manage point cloud changelog.
Definition: changelog.hpp:76
Manage point attributes.
Manage point cloud changelog.
Manage point cloud transactions.
Database open settings.
Point attribute access data types.
pointcloud::QueryInvert invert(const std::string &filter=std::string())
Invert points.
pointcloud::QueryUpdate update()
Update points.
void clearCache()
Clear internal data cache.
pointcloud::QueryStat stat()
Query point statistics.
Point update query.
Basic point cloud management interface.
Definition: management.hpp:64
Manage point cloud meta data.
Definition: metaData.hpp:66