| RDB 2

createSettings.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 createSettings.hpp
26 * \author RIEGL LMS GmbH, Austria
27 * \brief Database create settings
28 * \version 2015-10-14/AW: Initial version
29 * \version 2016-07-13/AW: Documentation of 'chunkSizeLOD' updated
30 * \version 2016-09-22/AW: Parameter 'cacheSize' changed from 32 to 64 bit type
31 * \version 2016-12-20/AW: New functions to load/save settings from/to JSON
32 * \version 2017-03-28/AW: Documentation of JSON load/save functions updated
33 * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
34 * \version 2019-01-15/AW: Parameter 'chunkMode' added
35 * \version 2019-01-18/AW: Parameter 'lodMode' added
36 * \version 2019-02-15/AW: Fix C++ API wrapper of CreateSettings class
37 * \version 2019-10-30/AW: Parameter 'optimizePointID' added (#3458)
38 * \version 2020-02-21/AW: Class 'CreateSettings' is now context-free (#3544)
39 * \version 2024-11-29/AW: Parameter 'pointInsertMode' added (#5339)
40 *
41 *******************************************************************************
42 */
43
44 #ifndef RIEGL_RDB_POINTCLOUD_CREATESETTINGS_HPP
45 #define RIEGL_RDB_POINTCLOUD_CREATESETTINGS_HPP
46
47 //---< INCLUDES >---------------------------------------------------------------
48
49 #include <string>
50 #include <cstdlib>
51
52 #include "riegl/rdb/context.hpp"
53 #include "riegl/rdb/pointcloud/pointAttribute.hpp"
54
55 //---< NAMESPACE >--------------------------------------------------------------
56
57 namespace riegl {
58 namespace rdb {
59 namespace pointcloud {
60
61 //---< CLASS CreateSettings >---------------------------------------------------
62 /*!
63 * \brief Database create settings
64 *
65 * This class defines settings for creating a new point cloud database.
66 */
67 class CreateSettings
68 {
69 public:
70 /*!
71 * \brief Primary point attribute
72 *
73 * The primary point attribute defines the attribute that is used
74 * to sort and index the points. Usually the 3D point coordinates are
75 * used for that. The primary attribute is automatically added to the
76 * point cloud (using Pointcloud::attributeAdd()) and cannot be deleted.
77 *
78 * \see riegl::rdb::pointcloud::PointAttributes
79 */
80 riegl::rdb::pointcloud::PointAttribute primaryAttribute;
81
82 public:
83 /*!
84 * \brief Point chunk mode
85 *
86 * Points are internally organized in chunks (primary point attribute index
87 * tree leaves). The size of a chunk (in the dimension of the primary point
88 * attribute) may either be fixed (predefined) or adapted automatically so
89 * that the number of points in a chunk does not exceed a certain limit. In
90 * both cases, the "size" is defined by parameter CreateSettings::chunkSize
91 * and parameter CreateSettings::chunkMode defines the meaning of the value.
92 */
93 enum ChunkMode
94 {
95 /*!
96 * the chunk size defines the maximum number of points per chunk
97 * (the default mode)
98 */
99 POINT_COUNT = 1,
100
101 /*!
102 * the chunk size defines the edge length of a chunk as 2^N times
103 * resolution of the primary point attribute
104 */
105 EDGE_LENGTH = 2
106 };
107
108 /*!
109 * \brief Point chunk mode
110 *
111 * Details see: CreateSettings::ChunkMode
112 *
113 * Default: CreateSettings::POINT_COUNT
114 */
115 std::uint32_t chunkMode;
116
117 /*!
118 * \brief Point chunk size
119 *
120 * Details see: CreateSettings::ChunkMode
121 *
122 * Default: 65536 points
123 */
124 std::uint32_t chunkSize;
125
126 public:
127 /*!
128 * \brief Level of detail mode
129 *
130 * A tree structure is used to sort and organize the point cloud. To create
131 * a coarse representation of the point cloud (level of detail = "LOD"), a
132 * number of equally distributed points is extracted from the tree leaf
133 * nodes and copied to the parent nodes.
134 *
135 * The parameter CreateSettings::chunkSizeLOD defines how many points to
136 * extract for LOD whereas the meaning of the value and the LOD creation
137 * algorithm are defined by the parameter CreateSettings::lodMode.
138 */
139 enum LodMode
140 {
141 /*!
142 * the LOD size defines the number of points to copy as a fraction of
143 * the total (original) number of points. So if the original point count
144 * is for example 19820526 and the size is set to 20%, then the number
145 * of LOD points to add is 3964106 (rounded) and the final total number
146 * of points is 23784632 (actual value may differ a little bit).
147 */
148 THINOUT = 1,
149
150 /*!
151 * the LOD size defines the number of binary subdivisions of the LOD
152 * node's volume in each dimension. So if the primary point attribute
153 * for example has a length of 2 (2D data) and the LOD size is set to 8,
154 * then each LOD node is divided into 2^8 * 2^8 = 2^(8*2) = 2^16 = 65536
155 * sub-volumes. All points of the node's immediate sub-nodes that fall
156 * into one of the sub-volumes are merged to a single point and stored
157 * in the LOD node. The method to merge the attribute values of a group
158 * of points can be defined for each point attribute separately (details
159 * see class PointAttribute).
160 */
161 COMBINE = 2
162 };
163
164 /*!
165 * \brief Level of detail mode
166 *
167 * Details see: CreateSettings::LodMode
168 *
169 * Default: CreateSettings::THINOUT
170 */
171 std::uint32_t lodMode;
172
173 /*!
174 * \brief Level of detail size
175 *
176 * Details see: CreateSettings::LodMode
177 *
178 * To disable LOD generation, set this parameter to zero (no matter which
179 * LOD mode is used).
180 *
181 * Default: 20 (i.e. 20% of the original point count).
182 *
183 * \note In RDB library versions before 2.0.850 this parameter had a
184 * different meaning. To retain compatibility, the parameter was
185 * not renamed to e.g. 'overheadLOD' - hence the strange name.
186 */
187 std::uint32_t chunkSizeLOD;
188
189 public:
190 /*!
191 * \brief Point cache size
192 *
193 * The database engine may buffer read and write operations in an
194 * internal cache. This value defines the cache size in bytes (octets).
195 *
196 * Default: 500 MB
197 */
198 std::uint64_t cacheSize;
199
200 /*!
201 * \brief Data compression level
202 *
203 * The database automatically compresses point data before it is
204 * stored. The compression level defines the compression quality,
205 * i.e. higher values produce smaller files.
206 *
207 * Range: 0..100 (i.e. percent)
208 * Default: 10%
209 */
210 std::uint8_t compressionLevel;
211
212 /*!
213 * \brief Point ID optimization
214 *
215 * Enable this option to apply optimizations to the point ID
216 * attribute (riegl.id) that can result in smaller files.
217 *
218 * Default: false
219 *
220 * \note No optimizations are applied when:
221 * - points were inserted in a previous transaction
222 * - buffers for the point ID (riegl.id) or dynamic point attributes
223 * (e.g. "riegl.selected", "riegl.visible") are passed to the insert
224 * query (QueryInsert class)
225 *
226 * \warning When optimizations are enabled, the point ID no longer
227 * reflects the order in which the points were inserted.
228 */
229 bool optimizePointID;
230
231 /*!
232 * \brief Point insert mode
233 *
234 * This setting specifies how points are to be inserted into the database.
235 *
236 * Supported values:
237 * - "single-pass" (default)
238 * Points are sorted and inserted into the internal index structure
239 * each time QueryInsert::next() is called. This is suitable for
240 * scenarios where the same objects are only scanned once or just
241 * a few times (e.g in TLS or MLS).
242 *
243 * - "multi-pass"
244 * Points are sorted and inserted into the internal index structure
245 * after the last call to QueryInsert::next() when the transaction is
246 * committed. This is suitable for scenarios where the same objects are
247 * scanned multiple times (e.g. in ALS or ULS when the system passes
248 * over the same area several times without toggling data acquisition).
249 * This mode is only supported for 3D point clouds (e.g. when the
250 * primary point attribute is "riegl.xyz") and when no points have
251 * been inserted before. Otherwise "single-pass" mode is used instead.
252 * This mode implies "optimizePointID" and point IDs are not returned
253 * by the insert query.
254 *
255 * \note It is recommended to only check whether the string starts with one of
256 * the above values and to ignore all subsequent characters (mode-specific
257 * parameters may be added after the mode name in the future).
258 */
259 std::string pointInsertMode;
260
261 public:
262 ~CreateSettings();
263
264 /*!
265 * \brief Default constructor
266 *
267 * All properties are set to default values.
268 */
269 CreateSettings();
270
271 /// \deprecated since 2.2.3 - use the context-free constructors instead
272 explicit CreateSettings(riegl::rdb::Context &context);
273
274 /*!
275 * \brief Copy constructor
276 *
277 * All properties are copied from the given settings object.
278 */
279 CreateSettings(const CreateSettings &settings);
280
281 /*!
282 * \brief Assignment operator
283 *
284 * All properties are copied from the given settings object.
285 */
286 CreateSettings& operator=(const CreateSettings &settings);
287
288 /*!
289 * \brief Load settings from JSON string
290 *
291 * This function parses the given JSON string and applies all available
292 * properties - missing properties are silently ignored (i.e. the value
293 * remains unchanged). When parsing the JSON string fails, an exception
294 * is thrown.
295 *
296 * Example JSON string:
297 *
298 * {
299 * "primary_attribute": {
300 * "name": "riegl.xyz",
301 * "title": "XYZ",
302 * "description": "Cartesian point coordinates wrt. application coordinate system (0: X, 1: Y, 2: Z)",
303 * "unit_symbol": "m",
304 * "length": 3,
305 * "resolution": 0.00025,
306 * "minimum_value": -535000.0,
307 * "maximum_value": 535000.0,
308 * "default_value": 0.0,
309 * "storage_class": "variable",
310 * "compression_options": "shuffle",
311 * "scale_factor": 1.0
312 * },
313 * "chunk_mode": "point_count",
314 * "chunk_size": 65536,
315 * "lod_mode": "thinout",
316 * "chunk_size_lod": 20,
317 * "cache_size": 524288000,
318 * "compression_level": 10,
319 * "optimize_point_id": false,
320 * "point_insert_mode": "single-pass"
321 * }
322 */
323 void load(const std::string &json);
324
325 /*!
326 * \brief Save settings to JSON string
327 * \see load()
328 */
329 std::string save() const;
330
331 private:
332 friend class CreateSettingsWrapper;
333 void *data;
334 };
335
336 }}} // namespace riegl::rdb::pointcloud
337
338 #endif // RIEGL_RDB_POINTCLOUD_CREATESETTINGS_HPP
riegl::rdb::pointcloud::CreateSettings::ChunkMode
ChunkMode
Point chunk mode.
Definition: createSettings.hpp:93
riegl::rdb::pointcloud::CreateSettings::primaryAttribute
riegl::rdb::pointcloud::PointAttribute primaryAttribute
Primary point attribute.
Definition: createSettings.hpp:80
riegl::rdb::pointcloud::CreateSettings::chunkMode
std::uint32_t chunkMode
Point chunk mode.
Definition: createSettings.hpp:115
riegl::rdb::pointcloud::CreateSettings::LodMode
LodMode
Level of detail mode.
Definition: createSettings.hpp:139
riegl::rdb::Context
Library context.
Definition: context.hpp:75
riegl::rdb::pointcloud::CreateSettings::chunkSizeLOD
std::uint32_t chunkSizeLOD
Level of detail size.
Definition: createSettings.hpp:187
riegl::rdb::pointcloud::CreateSettings::COMBINE
Definition: createSettings.hpp:161
riegl::rdb::pointcloud::CreateSettings::~CreateSettings
~CreateSettings()
riegl::rdb::pointcloud::CreateSettings::lodMode
std::uint32_t lodMode
Level of detail mode.
Definition: createSettings.hpp:171
riegl::rdb::pointcloud::CreateSettings::compressionLevel
std::uint8_t compressionLevel
Data compression level.
Definition: createSettings.hpp:210
context.hpp
RDB library context.
riegl::rdb::pointcloud::CreateSettings::chunkSize
std::uint32_t chunkSize
Point chunk size.
Definition: createSettings.hpp:124
riegl::rdb::pointcloud::CreateSettings::optimizePointID
bool optimizePointID
Point ID optimization.
Definition: createSettings.hpp:229
riegl::rdb::pointcloud::CreateSettings::THINOUT
Definition: createSettings.hpp:148
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
pointAttribute.hpp
Point attribute description.
riegl::rdb::pointcloud::CreateSettings::EDGE_LENGTH
Definition: createSettings.hpp:105
riegl::rdb::pointcloud::CreateSettings
Database create settings.
Definition: createSettings.hpp:67
riegl::rdb::pointcloud::CreateSettings::POINT_COUNT
Definition: createSettings.hpp:99
riegl::rdb::pointcloud::CreateSettings::CreateSettingsWrapper
friend class CreateSettingsWrapper
Definition: createSettings.hpp:332
riegl::rdb::pointcloud::CreateSettings::save
std::string save() const
Save settings to JSON string.
riegl::rdb::pointcloud::CreateSettings::pointInsertMode
std::string pointInsertMode
Point insert mode.
Definition: createSettings.hpp:259
riegl::rdb::pointcloud::PointAttribute
Point attribute description.
Definition: pointAttribute.hpp:120
riegl::rdb::pointcloud::CreateSettings::load
void load(const std::string &json)
Load settings from JSON string.
riegl::rdb::pointcloud::CreateSettings::operator=
CreateSettings & operator=(const CreateSettings &settings)
Assignment operator.
riegl::rdb::pointcloud::CreateSettings::CreateSettings
CreateSettings()
Default constructor.
riegl::rdb::pointcloud::CreateSettings::cacheSize
std::uint64_t cacheSize
Point cache size.
Definition: createSettings.hpp:198