RDB 2
management.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 management.hpp
26  * \author RIEGL LMS GmbH, Austria
27  * \brief Basic point cloud management interface
28  * \version 2017-03-21/AW: Initial version
29  * \version 2017-04-13/AW: Functions finalize() and vacuum() added
30  * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
31  * \version 2018-05-25/AW: Function validate() added (#3109)
32  * \version 2019-01-18/AW: Parameter 'lodMode' added
33  * \version 2020-03-30/AW: Function validate() is const (#3579)
34  *
35  *******************************************************************************
36  */
37 
38 #ifndef RIEGL_RDB_POINTCLOUD_MANAGEMENT_HPP
39 #define RIEGL_RDB_POINTCLOUD_MANAGEMENT_HPP
40 
41 //---< INCLUDES >---------------------------------------------------------------
42 
43 #include <memory>
44 #include <string>
45 #include <vector>
46 #include <cstdint>
48 #include "riegl/rdb/progress.hpp"
49 
50 //---< NAMESPACE >--------------------------------------------------------------
51 
52 namespace riegl {
53 namespace rdb {
54 namespace pointcloud {
55 
56 //---< CLASS Management >-------------------------------------------------------
57 /*!
58  * \brief Basic point cloud management interface
59  *
60  * \see riegl::rdb::Pointcloud::management()
61  */
63 {
64 public:
65  /*!
66  * \brief Constructor
67  * \note You cannot create new Management objects directly,
68  * use riegl::rdb::Pointcloud::management() instead.
69  */
70  explicit Management(riegl::rdb::PointcloudData* pointcloud);
71 
72  /*!
73  * \brief Query level of detail mode
74  * \see riegl::rdb::pointcloud::CreateSettings::LodMode
75  */
76  uint32_t getLodMode() const;
77 
78  /*!
79  * \brief Modify level of detail mode
80  * \see riegl::rdb::pointcloud::CreateSettings::LodMode
81  */
82  void setLodMode(const uint32_t value);
83 
84  /*!
85  * \brief Query level of detail size
86  * \see riegl::rdb::pointcloud::CreateSettings::LodMode
87  */
88  uint32_t getChunkSizeLOD() const;
89 
90  /*!
91  * \brief Modify level of detail size
92  * \see riegl::rdb::pointcloud::CreateSettings::LodMode
93  */
94  void setChunkSizeLOD(const uint32_t value);
95 
96  /*!
97  * \brief Dismiss database history
98  *
99  * This function deletes all transactions except the first (database
100  * creation) and the current transaction (last committed or restored).
101  * Please note that this operation only removes the transactions from
102  * the database history and releases the related data blocks in the
103  * database file so that they can be re-used by subsequent transactions.
104  * However the database file size will not decrease unless you call
105  * vacuum().
106  */
107  void finalize();
108 
109  /*!
110  * \brief Optimize database file
111  *
112  * This function reorganizes the data blocks in the database file so
113  * that there are no (or as few as possible) unused blocks (gaps).
114  * This is especially helpful after deleting point attributes or
115  * calling finalize().
116  *
117  * \note This might be a lengthy operation and no other client can
118  * access the database in the meantime, not even to read.
119  */
120  void vacuum(
121  Progress progress = nullptr, //!< [in] vacuum progress callback function
122  void *userdata = nullptr //!< [in] progress callback function user data
123  );
124 
125  /*!
126  * \brief Optimize database file
127  *
128  * Overloaded vacuum() that takes any callable type as progress callback.
129  */
130  template<typename Callable>
131  void vacuum(Callable &&progress)
132  {
133  typedef typename std::decay<Callable>::type CallableType;
134  this->vacuum(
135  &progress_proxy_callable<CallableType>,
136  const_cast<CallableType*>(&progress)
137  );
138  }
139 
140  /*!
141  * \brief Optimize database file
142  *
143  * Overloaded vacuum() that takes a progress callback method of an object.
144  */
145  template<typename Receiver>
146  void vacuum(void (Receiver::*progress)(uint8_t), Receiver &receiver)
147  {
148  auto userdata = std::make_pair(progress, &receiver);
149  this->vacuum(&progress_proxy_receiver<Receiver>, &userdata);
150  }
151 
152  /*!
153  * \brief Optimize database file
154  *
155  * Overloaded vacuum() that takes a constant progress callback method
156  * of a constant object.
157  */
158  template<typename Receiver>
159  void vacuum(void (Receiver::*progress)(uint8_t) const, const Receiver &receiver)
160  {
161  auto userdata = std::make_pair(progress, &receiver);
162  this->vacuum(&progress_proxy_receiver<Receiver>, &userdata);
163  }
164 
165  /*!
166  * \brief Validate database file
167  *
168  * This function checks whether the database corresponds to the given schema.
169  * The schema contains a list of required and optional point attributes and
170  * metadata entries and is given in JSON format. Primary point attributes
171  * are marked with a "*", optional attributes or metadata entries are
172  * marked with a "?" appended to the name, all other items are required.
173  *
174  * The database must at least contain all primary and required point attributes
175  * and all required metadata entries to correspond to the schema. If "strict"
176  * is "true", then the database additionally is not allowed to contain extra
177  * point attributes or metadata entries that are not listed in the schema.
178  *
179  * If the database does not correspond to the schema, an exception
180  * is thrown and the reason can be found in the exception details.
181  *
182  * Example schema JSON string:
183  *
184  * {
185  * "extension": "rdbx",
186  * "attributes": [
187  * "riegl.xyz*",
188  * "riegl.timestamp",
189  * "riegl.class?"
190  * ],
191  * "metadata": [
192  * "riegl.geo_tag",
193  * "riegl.device?"
194  * ]
195  * }
196  */
197  void validate(
198  const std::string &schema, //!< [in] database schema (JSON)
199  const bool strict=false //!< [in] true: strict mode
200  ) const;
201 
202 private:
203  riegl::rdb::PointcloudData *data;
204 
205  template<typename Callable>
206  static void progress_proxy_callable(uint8_t progress, void *userdata)
207  {
208  try
209  {
210  Callable &callback = *reinterpret_cast<Callable*>(userdata);
211  callback(progress); // = invoke original callback
212  }
213  catch(...)
214  {
215  // ignore all errors
216  }
217  }
218 
219  template<typename Receiver>
220  static void progress_proxy_receiver(uint8_t progress, void *userdata)
221  {
222  try
223  {
224  typedef void (Receiver::*Function)(uint8_t); // just a shortcut...
225  auto data(reinterpret_cast<std::pair<Function, Receiver*>*>(userdata));
226  (*data->second.*data->first)(progress); // = invoke original callback
227  }
228  catch(...)
229  {
230  // ignore all errors
231  }
232  }
233 };
234 
235 }}} // namespace riegl::rdb::pointcloud
236 
237 #endif // RIEGL_RDB_POINTCLOUD_MANAGEMENT_HPP
void vacuum(Progress progress=nullptr, void *userdata=nullptr)
Optimize database file.
Operation progress feedback tools.
uint32_t getLodMode() const
Query level of detail mode.
void(* Progress)(uint8_t progress, void *userdata)
Progress callback function type.
Definition: progress.hpp:66
void vacuum(Callable &&progress)
Optimize database file.
Definition: management.hpp:131
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
void setLodMode(const uint32_t value)
Modify level of detail mode.
void vacuum(void(Receiver::*progress)(uint8_t) const, const Receiver &receiver)
Optimize database file.
Definition: management.hpp:159
void validate(const std::string &schema, const bool strict=false) const
Validate database file.
void vacuum(void(Receiver::*progress)(uint8_t), Receiver &receiver)
Optimize database file.
Definition: management.hpp:146
uint32_t getChunkSizeLOD() const
Query level of detail size.
Management(riegl::rdb::PointcloudData *pointcloud)
Constructor.
Pointcloud class implementation details.
void setChunkSizeLOD(const uint32_t value)
Modify level of detail size.
void finalize()
Dismiss database history.
Basic point cloud management interface.
Definition: management.hpp:62