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