RDB 2
pointAttribute.hpp
Go to the documentation of this file.
1 /*
2  *******************************************************************************
3  *
4  * Copyright 2021 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 pointAttribute.hpp
26  * \author RIEGL LMS GmbH, Austria
27  * \brief Point attribute description
28  * \version 2015-10-14/AW: Initial version
29  * \version 2016-11-28/AW: Compression options added (#2423)
30  * \version 2016-12-20/AW: New functions to load/save settings from/to JSON
31  * \version 2017-03-22/AW: Point attribute scale factor added (#2552)
32  * \version 2017-03-28/AW: Documentation of JSON load/save functions updated
33  * \version 2017-11-09/AW: New function to suggest buffer data type (#2587)
34  * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
35  * \version 2018-03-09/AW: New attribute property "invalid value" added (#3047)
36  * \version 2018-06-22/AW: Attribute length type changed to uint32 (#3117)
37  * \version 2018-07-05/AW: Add string conversion operator function
38  * \version 2019-01-21/AW: New attribute property "lod settings" added
39  * \version 2019-02-15/AW: Fix C++ API wrapper of PointAttribute class
40  * \version 2020-02-21/AW: Class 'PointAttribute' is now context-free (#3544)
41  *
42  *******************************************************************************
43  */
44 
45 #ifndef RIEGL_RDB_POINTCLOUD_POINTATTRIBUTE_HPP
46 #define RIEGL_RDB_POINTCLOUD_POINTATTRIBUTE_HPP
47 
48 //---< INCLUDES >---------------------------------------------------------------
49 
50 #include <limits>
51 #include <string>
52 #include <cstdint>
53 
54 #include "riegl/rdb/context.hpp"
56 
57 //---< NAMESPACE >--------------------------------------------------------------
58 
59 namespace riegl {
60 namespace rdb {
61 namespace pointcloud {
62 
63 //---< CLASS PointAttribute >---------------------------------------------------
64 /*!
65  * \brief Point attribute description
66  *
67  * This class describes a point attribute. The database uses this
68  * information for internal attribute representation and compression.
69  *
70  * While the name is a unique identifier, the description holds some
71  * text that client programs might display the user in some way. Also
72  * the physical unit is not used by the database but can be presented
73  * to the user (see PointAttribute::unitSymbol).
74  *
75  * To avoid point attribute name conflicts, the names (not the titles)
76  * shall contain a namespace prefix. Namespace and attribute name are
77  * separated by a dot (".", e.g. "riegl.xyz"). The default namespace
78  * "riegl" is used if no namespace is given.
79  *
80  * \remarks
81  *
82  * If the attribute is a vector (i.e. length > 1), then you might append
83  * a zero-based vector element index to the attribute name when inserting,
84  * updating or selecting points. Example: use "rgb[0]" to access the red
85  * color component (0), the green (1) and blue (2) components are not read
86  * or modified in this case.
87  *
88  * Furthermore, the minimum, maximum and default values are applied to all
89  * elements of vectors and the vector length must be in the range [1..100000].
90  *
91  * PointAttribute::defaultValue is returned when reading a point attribute
92  * that has never been written before. The value must be between minimum and
93  * maximum (both inclusive).
94  *
95  * PointAttribute::invalidValue may be used to define a value that represents
96  * an invalid/undefined/unknown value. The value must be between minimum and
97  * maximum (both inclusive) and must be a multiple of the resolution value.
98  * The value may be equal to the default value and you may use "NaN" (not a
99  * number) to signal that there is no "invalid value".
100  *
101  * \note
102  *
103  * Attribute names may only contain following ASCII characters:
104  *
105  * - a-z
106  * - A-Z
107  * - 0-9
108  * - .
109  * - _
110  *
111  * Attribute title, description and unit symbol may contain any UTF-8 character.
112  *
113  * \see riegl::rdb::pointcloud::PointAttributes
114  */
116 {
117 public:
118  /*!
119  * \brief Data Storage Class
120  *
121  * The storage class gives a hint about how often a point attribute
122  * is expected to change. This might be helpful for the database to
123  * optimize data structures for speed or file size.
124  */
126  {
127  CONSTANT = 1, //!< value cannot be changed
128  VARIABLE = 2, //!< value can change from time to time
129  DYNAMIC = 3 //!< value is likely to be changed often
130  };
131 
132  /*!
133  * \brief Data Compression Options
134  *
135  * The data of all point attributes is compressed with the settings defined
136  * during the database creation (see class CreateSettings). Additionally,
137  * the data may be pre-processed using one or more of the following methods:
138  */
140  {
141  DEFAULT = 0, //!< nothing special, just use default compression algorithm
142  DELTA = 1, //!< calculate differences between two consecutive values
143  SHUFFLE = 2, //!< shuffle bytes of point attribute values
144  DELTA_SHUFFLE = 3 //!< calculate differences and shuffle bytes
145  };
146 
147  std::string name; //!< unique attribute name (for queries) \see details of class PointAttribute
148  std::string title; //!< attribute title (for display)
149  std::string description; //!< attribute description (for display)
150  std::string unitSymbol; //!< physical unit symbol (e.g. "m", "rad", "K")
151  uint32_t length; //!< number of dimensions/elements (1: scalar, >1: vector, e.g. 3 for point coordinates)
152  double resolution; //!< expected value resolution
153  double minimumValue; //!< theoretical minimum value
154  double maximumValue; //!< theoretical maximum value
155  double defaultValue; //!< default value (minimum <= default <= maximum)
156  double invalidValue; //!< invalid value (minimum <= invalid <= maximum, use "not-a-number" if there is no invalid value)
157  uint8_t storageClass; //!< storage class \see enum StorageClass
158  uint8_t compressionOptions; //!< options additional to default compression
159 
160  /*!
161  * \brief Level of detail settings
162  *
163  * This field defines the method to be used to generate level of detail
164  * data (LOD) for this point attribute. Depending on the LOD mode defined
165  * during database creation (see CreateSettings::LodMode), several LOD
166  * methods are available. A list of all methods and their settings can
167  * be found in file "/manual/riegl_rdb_lod_methods.json" in the RDB SDK.
168  */
169  std::string lodSettings;
170 
171  /*!
172  * \brief optional scale factor applied to real numbers (i.e. resolution not equal to 1.0)
173  *
174  * - reading points: resultValue = originalValue * scaleFactor
175  * - writing points: storedValue = givenValue / scaleFactor
176  */
177  double scaleFactor;
178 
179 public:
180  ~PointAttribute();
181 
182  /*!
183  * \brief Default constructor
184  *
185  * All properties are set to default values.
186  */
187  explicit PointAttribute(
188  const std::string &name = "none",
189  const std::string &title = "none",
190  const std::string &description = "",
191  const std::string &unitSymbol = "",
192  const uint32_t &length = 0,
193  const double &resolution = 1.0,
194  const double &minimumValue = 0.0,
195  const double &maximumValue = 0.0,
196  const double &defaultValue = 0.0,
197  const uint8_t &storageClass = CONSTANT,
198  const uint8_t &compressionOptions = DEFAULT,
199  const double &scaleFactor = 1.0,
200  const double &invalidValue = std::numeric_limits<double>::quiet_NaN(),
201  const std::string &lodSettings = "default"
202  );
203 
204  /// \deprecated since 2.2.3 - use the context-free constructors instead
205  explicit PointAttribute(riegl::rdb::Context &context);
206 
207  /*!
208  * \brief Copy constructor
209  *
210  * All properties are copied from the given attribute object.
211  */
212  PointAttribute(const PointAttribute &attribute);
213 
214  /*!
215  * \brief Assignment operator
216  *
217  * All properties are copied from the given attribute object.
218  */
219  PointAttribute& operator=(const PointAttribute &attribute);
220 
221  //__________________________________________________________________________
222  /*!
223  * \brief Copy assignment
224  *
225  * This function is mainly for backward compatibility reasons. You may
226  * also use the copy constructor or copy assignment operator instead.
227  */
228  void assign(PointAttribute &target) const
229  {
230  target = *this;
231  }
232 
233  //__________________________________________________________________________
234  /*!
235  * \brief Get attribute name and vector index from attribute descriptor
236  *
237  * This function decodes the given attribute descriptor into attribute name and attribute
238  * vector index. The optional vector index is enclosed in square brackets and follows the
239  * point attribute name. If no vector index is given, then index -1 is returned. If the
240  * vector index cannot be interpreted as a single positive integer value, then an empty
241  * name and index -2 is returned.
242  *
243  * Examples:
244  * descriptor | name | index
245  * ------------|-------|-------
246  * "xyz" | "xyz" | -1
247  * "xyz[0]" | "xyz" | 0
248  * "rgb[1]" | "rgb" | 1
249  */
250  static void decodeDescriptor(
251  const std::string &descriptor, //!< [in] attribute descriptor, e.g. "xyz", "rgb[1]"
252  std::string &name, //!< [out] attribute name, e.g. "xyz", "rgb"
253  int32_t &index //!< [out] attribute vector index, e.g. -1, 1
254  );
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  * "name": "riegl.reflectance",
268  * "title": "Reflectance",
269  * "description": "Target surface reflectance",
270  * "unit_symbol": "dB",
271  * "length": 1,
272  * "resolution": 0.01,
273  * "minimum_value": -327.68,
274  * "maximum_value": 327.67,
275  * "default_value": 0.0,
276  * "invalid_value": null,
277  * "storage_class": "variable",
278  * "compression_options": "shuffle",
279  * "lod_settings": "default",
280  * "scale_factor": 1.0
281  * }
282  */
283  void load(const std::string &json);
284 
285  /*!
286  * \brief Save settings to JSON string
287  * \see load()
288  */
289  std::string save() const;
290 
291  /*!
292  * \brief Get buffer data type
293  *
294  * This function suggests a data type that is suitable to
295  * construct a buffer for storing values of this attribute.
296  *
297  * The suggestion is based on the resolution, minimumValue
298  * and maximumValue properties, all others are ignored.
299  */
301 
302  //! \brief Get attribute name
303  operator const std::string&() const { return name; }
304 
305 private:
306  friend class PointAttributeWrapper;
307  void *data;
308 };
309 
310 }}} // namespace riegl::rdb::pointcloud
311 
312 #endif // RIEGL_RDB_POINTCLOUD_POINTATTRIBUTE_HPP
nothing special, just use default compression algorithm
DataType
Point attribute access data type.
Definition: dataTypes.hpp:55
Library context.
Definition: context.hpp:70
shuffle bytes of point attribute values
static void decodeDescriptor(const std::string &descriptor, std::string &name, int32_t &index)
Get attribute name and vector index from attribute descriptor.
std::string name
unique attribute name (for queries)
double minimumValue
theoretical minimum value
calculate differences and shuffle bytes
double scaleFactor
optional scale factor applied to real numbers (i.e. resolution not equal to 1.0)
double defaultValue
default value (minimum <= default <= maximum)
std::string lodSettings
Level of detail settings.
void assign(PointAttribute &target) const
Copy assignment.
RDB library context.
std::string description
attribute description (for display)
void load(const std::string &json)
Load settings from JSON string.
uint32_t length
number of dimensions/elements (1: scalar, >1: vector, e.g. 3 for point coordinates) ...
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
value can change from time to time
Point attribute description.
double invalidValue
invalid value (minimum <= invalid <= maximum, use "not-a-number" if there is no invalid value) ...
uint8_t compressionOptions
options additional to default compression
calculate differences between two consecutive values
PointAttribute(const std::string &name="none", const std::string &title="none", const std::string &description="", const std::string &unitSymbol="", const uint32_t &length=0, const double &resolution=1.0, const double &minimumValue=0.0, const double &maximumValue=0.0, const double &defaultValue=0.0, const uint8_t &storageClass=CONSTANT, const uint8_t &compressionOptions=DEFAULT, const double &scaleFactor=1.0, const double &invalidValue=std::numeric_limits< double >::quiet_NaN(), const std::string &lodSettings="default")
Default constructor.
value is likely to be changed often
std::string unitSymbol
physical unit symbol (e.g. "m", "rad", "K")
std::string title
attribute title (for display)
std::string save() const
Save settings to JSON string.
CompressionOptions
Data Compression Options.
riegl::rdb::pointcloud::DataType dataType() const
Get buffer data type.
Point attribute access data types.
PointAttribute & operator=(const PointAttribute &attribute)
Assignment operator.
double maximumValue
theoretical maximum value
double resolution
expected value resolution