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