RDB 2
createSettings.hpp
Go to the documentation of this file.
1 /*
2  *******************************************************************************
3  *
4  * Copyright 2024 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"
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  */
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  */
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  */
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  */
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  */
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  */
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::PointAttribute primaryAttribute
Primary point attribute.
std::uint32_t chunkMode
Point chunk mode.
Library context.
Definition: context.hpp:75
std::uint32_t chunkSizeLOD
Level of detail size.
std::uint32_t lodMode
Level of detail mode.
std::uint8_t compressionLevel
Data compression level.
RDB library context.
std::string save() const
Save settings to JSON string.
std::uint32_t chunkSize
Point chunk size.
bool optimizePointID
Point ID optimization.
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
Point attribute description.
std::string pointInsertMode
Point insert mode.
Point attribute description.
void load(const std::string &json)
Load settings from JSON string.
CreateSettings & operator=(const CreateSettings &settings)
Assignment operator.
CreateSettings()
Default constructor.
std::uint64_t cacheSize
Point cache size.