RDB 2
createSettings.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 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  *
40  *******************************************************************************
41  */
42 
43 #ifndef RIEGL_RDB_POINTCLOUD_CREATESETTINGS_HPP
44 #define RIEGL_RDB_POINTCLOUD_CREATESETTINGS_HPP
45 
46 //---< INCLUDES >---------------------------------------------------------------
47 
48 #include <cstdlib>
49 
50 #include "riegl/rdb/context.hpp"
52 
53 //---< NAMESPACE >--------------------------------------------------------------
54 
55 namespace riegl {
56 namespace rdb {
57 namespace pointcloud {
58 
59 //---< CLASS CreateSettings >---------------------------------------------------
60 /*!
61  * \brief Database create settings
62  *
63  * This class defines settings for creating a new point cloud database.
64  */
66 {
67 public:
68  /*!
69  * \brief Primary point attribute
70  *
71  * The primary point attribute defines the attribute that is used
72  * to sort and index the points. Usually the 3D point coordinates are
73  * used for that. The primary attribute is automatically added to the
74  * point cloud (using Pointcloud::attributeAdd()) and cannot be deleted.
75  *
76  * \see riegl::rdb::pointcloud::PointAttributes
77  */
79 
80 public:
81  /*!
82  * \brief Point chunk mode
83  *
84  * Points are internally organized in chunks (primary point attribute index
85  * tree leaves). The size of a chunk (in the dimension of the primary point
86  * attribute) may either be fixed (predefined) or adapted automatically so
87  * that the number of points in a chunk does not exceed a certain limit. In
88  * both cases, the "size" is defined by parameter CreateSettings::chunkSize
89  * and parameter CreateSettings::chunkMode defines the meaning of the value.
90  */
91  enum ChunkMode
92  {
93  /*!
94  * the chunk size defines the maximum number of points per chunk
95  * (the default mode)
96  */
98 
99  /*!
100  * the chunk size defines the edge length of a chunk as 2^N times
101  * resolution of the primary point attribute
102  */
104  };
105 
106  /*!
107  * \brief Point chunk mode
108  *
109  * Details see: CreateSettings::ChunkMode
110  *
111  * Default: CreateSettings::POINT_COUNT
112  */
113  std::uint32_t chunkMode;
114 
115  /*!
116  * \brief Point chunk size
117  *
118  * Details see: CreateSettings::ChunkMode
119  *
120  * Default: 65536 points
121  */
122  std::uint32_t chunkSize;
123 
124 public:
125  /*!
126  * \brief Level of detail mode
127  *
128  * A tree structure is used to sort and organize the point cloud. To create
129  * a coarse representation of the point cloud (level of detail = "LOD"), a
130  * number of equally distributed points is extracted from the tree leaf
131  * nodes and copied to the parent nodes.
132  *
133  * The parameter CreateSettings::chunkSizeLOD defines how many points to
134  * extract for LOD whereas the meaning of the value and the LOD creation
135  * algorithm are defined by the parameter CreateSettings::lodMode.
136  */
137  enum LodMode
138  {
139  /*!
140  * the LOD size defines the number of points to copy as a fraction of
141  * the total (original) number of points. So if the original point count
142  * is for example 19820526 and the size is set to 20%, then the number
143  * of LOD points to add is 3964106 (rounded) and the final total number
144  * of points is 23784632 (actual value may differ a little bit).
145  */
146  THINOUT = 1,
147 
148  /*!
149  * the LOD size defines the number of binary subdivisions of the LOD
150  * node's volume in each dimension. So if the primary point attribute
151  * for example has a length of 2 (2D data) and the LOD size is set to 8,
152  * then each LOD node is divided into 2^8 * 2^8 = 2^(8*2) = 2^16 = 65536
153  * sub-volumes. All points of the node's immediate sub-nodes that fall
154  * into one of the sub-volumes are merged to a single point and stored
155  * in the LOD node. The method to merge the attribute values of a group
156  * of points can be defined for each point attribute separately (details
157  * see class PointAttribute).
158  */
160  };
161 
162  /*!
163  * \brief Level of detail mode
164  *
165  * Details see: CreateSettings::LodMode
166  *
167  * Default: CreateSettings::THINOUT
168  */
169  std::uint32_t lodMode;
170 
171  /*!
172  * \brief Level of detail size
173  *
174  * Details see: CreateSettings::LodMode
175  *
176  * To disable LOD generation, set this parameter to zero (no matter which
177  * LOD mode is used).
178  *
179  * Default: 20 (i.e. 20% of the original point count).
180  *
181  * \note In RDB library versions before 2.0.850 this parameter had a
182  * different meaning. To retain compatibility, the parameter was
183  * not renamed to e.g. 'overheadLOD' - hence the strange name.
184  */
185  std::uint32_t chunkSizeLOD;
186 
187 public:
188  /*!
189  * \brief Point cache size
190  *
191  * The database engine may buffer read and write operations in an
192  * internal cache. This value defines the cache size in bytes (octets).
193  *
194  * Default: 500 MB
195  */
196  std::uint64_t cacheSize;
197 
198  /*!
199  * \brief Data compression level
200  *
201  * The database automatically compresses point data before it is
202  * stored. The compression level defines the compression quality,
203  * i.e. higher values produce smaller files.
204  *
205  * Range: 0..100 (i.e. percent)
206  * Default: 10%
207  */
208  std::uint8_t compressionLevel;
209 
210  /*!
211  * \brief Point ID optimization
212  *
213  * Enable this option to apply optimizations to the point ID
214  * attribute (riegl.id) that can result in smaller files.
215  *
216  * Default: false
217  *
218  * \note No optimizations are applied when:
219  * - points were inserted in a previous transaction
220  * - buffers for the point ID (riegl.id) or dynamic point attributes
221  * (e.g. "riegl.selected", "riegl.visible") are passed to the insert
222  * query (QueryInsert class)
223  *
224  * \warning When optimizations are enabled, the point ID no longer
225  * reflects the order in which the points were inserted.
226  */
228 
229 public:
230  ~CreateSettings();
231 
232  /*!
233  * \brief Default constructor
234  *
235  * All properties are set to default values.
236  */
237  CreateSettings();
238 
239  /// \deprecated since 2.2.3 - use the context-free constructors instead
240  explicit CreateSettings(riegl::rdb::Context &context);
241 
242  /*!
243  * \brief Copy constructor
244  *
245  * All properties are copied from the given settings object.
246  */
247  CreateSettings(const CreateSettings &settings);
248 
249  /*!
250  * \brief Assignment operator
251  *
252  * All properties are copied from the given settings object.
253  */
254  CreateSettings& operator=(const CreateSettings &settings);
255 
256  /*!
257  * \brief Load settings from JSON string
258  *
259  * This function parses the given JSON string and applies all available
260  * properties - missing properties are silently ignored (i.e. the value
261  * remains unchanged). When parsing the JSON string fails, an exception
262  * is thrown.
263  *
264  * Example JSON string:
265  *
266  * {
267  * "primary_attribute": {
268  * "name": "riegl.xyz",
269  * "title": "XYZ",
270  * "description": "Cartesian point coordinates wrt. application coordinate system (0: X, 1: Y, 2: Z)",
271  * "unit_symbol": "m",
272  * "length": 3,
273  * "resolution": 0.00025,
274  * "minimum_value": -535000.0,
275  * "maximum_value": 535000.0,
276  * "default_value": 0.0,
277  * "storage_class": "variable",
278  * "compression_options": "shuffle",
279  * "scale_factor": 1.0
280  * },
281  * "chunk_mode": "point_count",
282  * "chunk_size": 65536,
283  * "lod_mode": "thinout",
284  * "chunk_size_lod": 20,
285  * "cache_size": 524288000,
286  * "compression_level": 10,
287  * "optimize_point_id": false
288  * }
289  */
290  void load(const std::string &json);
291 
292  /*!
293  * \brief Save settings to JSON string
294  * \see load()
295  */
296  std::string save() const;
297 
298 private:
299  friend class CreateSettingsWrapper;
300  void *data;
301 };
302 
303 }}} // namespace riegl::rdb::pointcloud
304 
305 #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.
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.