| RDB 2

management.hpp
Go to the documentation of this file.
1 /*
2 *******************************************************************************
3 *
4 * Copyright 2025 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
49 #include "riegl/rdb/pointcloud/pointcloudData.hpp"
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 */
64 class Management
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
riegl::rdb::pointcloud::Management::vacuum
void vacuum(Progress progress=nullptr, void *userdata=nullptr)
Optimize database file.
progress.hpp
Operation progress feedback tools.
riegl::rdb::pointcloud::Management::getLodMode
std::uint32_t getLodMode() const
Query level of detail mode.
riegl::rdb::pointcloud::Management::vacuum
void vacuum(Callable &&progress)
Optimize database file.
Definition: management.hpp:133
riegl::rdb::Progress
void(* Progress)(std::uint8_t progress, void *userdata)
Progress callback function type.
Definition: progress.hpp:67
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::pointcloud::Management::vacuum
void vacuum(void(Receiver::*progress)(std::uint8_t), Receiver &receiver)
Optimize database file.
Definition: management.hpp:148
riegl::rdb::pointcloud::Management::setChunkSizeLOD
void setChunkSizeLOD(const std::uint32_t value)
Modify level of detail size.
riegl::rdb::pointcloud::Management::validate
void validate(const std::string &schema, const bool strict=false) const
Validate database file.
riegl::rdb::pointcloud::Management::vacuum
void vacuum(void(Receiver::*progress)(std::uint8_t) const, const Receiver &receiver)
Optimize database file.
Definition: management.hpp:161
riegl::rdb::pointcloud::Management::getChunkSizeLOD
std::uint32_t getChunkSizeLOD() const
Query level of detail size.
riegl::rdb::pointcloud::Management::Management
Management(riegl::rdb::PointcloudData *pointcloud)
Constructor.
pointcloudData.hpp
Pointcloud class implementation details.
riegl::rdb::pointcloud::Management::setLodMode
void setLodMode(const std::uint32_t value)
Modify level of detail mode.
riegl::rdb::pointcloud::Management::finalize
void finalize()
Dismiss database history.
riegl::rdb::pointcloud::Management
Basic point cloud management interface.
Definition: management.hpp:64