RDB 2
pointcloud.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 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  * \see riegl::rdb::pointcloud::QuerySelect
344  */
346  const std::string &filter = std::string() //!< [in] optional point filter expression
347  );
348 
349  /*!
350  * \brief Select points by index node
351  *
352  * \copydetails select()
353  *
354  * Instead of loading all points of the point cloud this variant just loads
355  * the points contained in a single node. See notes about LOD for details.
356  */
358  const pointcloud::GraphNode::ID &node, //!< [in] ID of index graph node
359  const std::string &filter = std::string() //!< [in] optional point filter expression
360  );
361 
362  /*!
363  * \brief Select points by index nodes
364  *
365  * \copydetails select()
366  *
367  * Instead of loading all points of the point cloud this variant just loads
368  * the points contained in the given nodes. See notes about LOD for details.
369  */
371  const std::vector<pointcloud::GraphNode::ID> &nodes, //!< [in] IDs of index graph nodes
372  const std::string &filter = std::string() //!< [in] optional point filter expression
373  );
374 
375  /*!
376  * \brief Fill points
377  *
378  * This function creates a new query object that can be used to
379  * set (modify) attributes of existing points.
380  *
381  * Please have a look at select() for details about the filter expression.
382  *
383  * \see riegl::rdb::pointcloud::QueryFill
384  */
386  const std::string &filter = std::string() //!< [in] optional point filter expression
387  );
388 
389  /*!
390  * \brief Fill points by index node
391  *
392  * \copydetails fill()
393  *
394  * Instead of modifying all points of the point cloud this variant just modifies
395  * the points contained in a single node. See notes about LOD for details.
396  */
398  const pointcloud::GraphNode::ID &node, //!< [in] ID of index graph node
399  const std::string &filter = std::string() //!< [in] optional point filter expression
400  );
401 
402  /*!
403  * \brief Fill points by index nodes
404  *
405  * \copydetails fill()
406  *
407  * Instead of modifying all points of the point cloud this variant just modifies
408  * the points contained in the given nodes. See notes about LOD for details.
409  */
411  const std::vector<pointcloud::GraphNode::ID> &nodes, //!< [in] IDs of index graph nodes
412  const std::string &filter = std::string() //!< [in] optional point filter expression
413  );
414 
415  /*!
416  * \brief Invert points
417  *
418  * This function creates a new query object that can be used to
419  * invert attributes of existing points.
420  *
421  * Please have a look at select() for details about the filter expression.
422  *
423  * \see riegl::rdb::pointcloud::QueryInvert
424  */
426  const std::string &filter = std::string() //!< [in] optional point filter expression
427  );
428 
429  /*!
430  * \brief Invert points by index node
431  *
432  * \copydetails invert()
433  *
434  * Instead of inverting all points of the point cloud this variant just inverts
435  * the points contained in a single node. See notes about LOD for details.
436  */
438  const pointcloud::GraphNode::ID &node, //!< [in] ID of index graph node
439  const std::string &filter = std::string() //!< [in] optional point filter expression
440  );
441 
442  /*!
443  * \brief Invert points by index nodes
444  *
445  * \copydetails invert()
446  *
447  * Instead of inverting all points of the point cloud this variant just inverts
448  * the points contained in the given nodes. See notes about LOD for details.
449  */
451  const std::vector<pointcloud::GraphNode::ID> &nodes, //!< [in] IDs of index graph nodes
452  const std::string &filter = std::string() //!< [in] optional point filter expression
453  );
454 
455  /*!
456  * \brief Remove points
457  *
458  * This function creates a new query object that can be used to
459  * remove (delete) existing points.
460  *
461  * \see riegl::rdb::pointcloud::QueryRemove
462  */
464 
465  /*!
466  * \brief Query point statistics
467  *
468  * This function creates a new query object that can be used to
469  * get point attribute statistics like minimum and maximum value.
470  *
471  * \see riegl::rdb::pointcloud::QueryStat
472  */
474 //! \}
475 //______________________________________________________________________________
476 //
477 private:
479  std::shared_ptr<riegl::rdb::PointcloudData> data;
480 
481 #ifdef RIEGL_RDB_POINTCLOUD_IMPLEMENTATION_DETAILS
482  RIEGL_RDB_POINTCLOUD_IMPLEMENTATION_DETAILS
483 #endif
484 };
485 
486 }} // namespace riegl::rdb
487 
488 #endif // RIEGL_RDB_POINTCLOUD_HPP
riegl::rdb::Pointcloud::open
void open(const std::string &location, const pointcloud::OpenSettings &settings)
Open existing database.
transactions.hpp
Manage point cloud transactions.
riegl::rdb::Pointcloud::insert
pointcloud::QueryInsert insert()
Insert points.
riegl::rdb::Pointcloud::create
void create(const std::string &location, const pointcloud::CreateSettings &settings)
Create new database.
queryInsert.hpp
Point insert query.
queryInvert.hpp
Point invert query.
riegl::rdb::Pointcloud::transaction
pointcloud::Transactions & transaction()
Manage point cloud transactions.
riegl::rdb::Pointcloud::~Pointcloud
~Pointcloud()
Destroy Pointcloud instance.
riegl::rdb::Pointcloud::clearCache
void clearCache()
Clear internal data cache.
queryFill.hpp
Point fill query.
riegl::rdb::pointcloud::MetaData
Manage point cloud meta data.
Definition: metaData.hpp:66
riegl::rdb::Pointcloud::management
pointcloud::Management & management()
Basic point cloud management interface.
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::pointcloud::OpenSettings
Database open settings.
Definition: openSettings.hpp:61
pointAttributes.hpp
Manage point attributes.
riegl::rdb::Pointcloud::stat
pointcloud::QueryStat stat()
Query point statistics.
metaData.hpp
Manage point cloud meta data.
querySelect.hpp
Point select query.
riegl::rdb::Pointcloud::invert
pointcloud::QueryInvert invert(const std::string &filter=std::string())
Invert points.
riegl::rdb::pointcloud::Transactions
Manage point cloud transactions.
Definition: transactions.hpp:68
riegl::rdb::pointcloud::Management
Basic point cloud management interface.
Definition: management.hpp:64
riegl::rdb::pointcloud::GraphNode::ID
std::uint32_t ID
Definition: graphNode.hpp:78
riegl::rdb::Pointcloud
Main point cloud database class.
Definition: pointcloud.hpp:89
riegl::rdb::Pointcloud::remove
pointcloud::QueryRemove remove()
Remove points.
transaction.hpp
Point cloud transaction.
riegl::rdb::pointcloud::QueryStat
Point statistics query.
Definition: queryStat.hpp:69
riegl::rdb::Pointcloud::isEmpty
bool isEmpty() const
Check if a database is empty.
riegl::rdb::pointcloud::QueryRemove
Point remove query.
Definition: queryRemove.hpp:65
rdb.hpp
Main RDB library include file.
management.hpp
Basic point cloud management interface.
riegl::rdb::Pointcloud::getUUID
std::string getUUID() const
Get database file's UUID.
riegl::rdb::Pointcloud::fill
pointcloud::QueryFill fill(const std::string &filter=std::string())
Fill points.
dataTypes.hpp
Point attribute access data types.
riegl::rdb::Pointcloud::close
void close()
Close database.
riegl::rdb::pointcloud::PointAttributes
Manage point attributes.
Definition: pointAttributes.hpp:83
riegl::rdb::pointcloud::QueryInsert
Point insert query.
Definition: queryInsert.hpp:67
openSettings.hpp
Database open settings.
riegl::rdb::Pointcloud::isOpen
bool isOpen() const
Check if a database is open.
riegl::rdb::pointcloud::QueryUpdate
Point update query.
Definition: queryUpdate.hpp:66
riegl::rdb::Pointcloud::Pointcloud
Pointcloud(Context context=Context())
Create Pointcloud instance.
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
queryUpdate.hpp
Point update query.
riegl::rdb::pointcloud::QueryInvert
Point invert query.
Definition: queryInvert.hpp:77
riegl::rdb::Pointcloud::select
pointcloud::QuerySelect select(const std::string &filter=std::string())
Select points.
riegl::rdb::pointcloud::CreateSettings
Database create settings.
Definition: createSettings.hpp:65
riegl::rdb::Pointcloud::changelog
pointcloud::Changelog & changelog()
Manage point cloud changelog.
riegl::rdb::pointcloud::Changelog
Manage point cloud changelog.
Definition: changelog.hpp:76
changelog.hpp
Manage point cloud changelog.
riegl::rdb::Pointcloud::inspect
std::string inspect(const std::uint8_t format)
File statistics and debugging information.
riegl::rdb::Pointcloud::pointAttribute
pointcloud::PointAttributes & pointAttribute()
Manage point attributes.
pointAttribute.hpp
Point attribute description.
createSettings.hpp
Database create settings.
riegl::rdb::Pointcloud::update
pointcloud::QueryUpdate update()
Update points.
riegl::rdb::pointcloud::QuerySelect
Point select query.
Definition: querySelect.hpp:69
riegl::rdb::Context
Library context.
Definition: context.hpp:75
queryStat.hpp
Point statistics query.