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
riegl::rdb::pointcloud::PointAttribute::DELTA
calculate differences between two consecutive values
Definition: pointAttribute.hpp:142
riegl::rdb::pointcloud::PointAttribute::~PointAttribute
~PointAttribute()
riegl::rdb::pointcloud::PointAttribute
Point attribute description.
Definition: pointAttribute.hpp:115
riegl::rdb::pointcloud::PointAttribute::DEFAULT
nothing special, just use default compression algorithm
Definition: pointAttribute.hpp:141
riegl::rdb::pointcloud::PointAttribute::SHUFFLE
shuffle bytes of point attribute values
Definition: pointAttribute.hpp:143
riegl::rdb::pointcloud::PointAttribute::decodeDescriptor
static void decodeDescriptor(const std::string &descriptor, std::string &name, int32_t &index)
Get attribute name and vector index from attribute descriptor.
riegl::rdb::pointcloud::PointAttribute::invalidValue
double invalidValue
invalid value (minimum <= invalid <= maximum, use "not-a-number" if there is no invalid value)
Definition: pointAttribute.hpp:156
riegl::rdb::pointcloud::PointAttribute::minimumValue
double minimumValue
theoretical minimum value
Definition: pointAttribute.hpp:153
context.hpp
RDB library context.
riegl::rdb::pointcloud::PointAttribute::assign
void assign(PointAttribute &target) const
Copy assignment.
Definition: pointAttribute.hpp:228
riegl::rdb::pointcloud::PointAttribute::scaleFactor
double scaleFactor
optional scale factor applied to real numbers (i.e. resolution not equal to 1.0)
Definition: pointAttribute.hpp:177
riegl
RIEGL Laser Measurement Systems GmbH, Austria.
Definition: context.hpp:48
riegl::rdb::pointcloud::PointAttribute::defaultValue
double defaultValue
default value (minimum <= default <= maximum)
Definition: pointAttribute.hpp:155
riegl::rdb::pointcloud::PointAttribute::unitSymbol
std::string unitSymbol
physical unit symbol (e.g. "m", "rad", "K")
Definition: pointAttribute.hpp:150
riegl::rdb::pointcloud::PointAttribute::CONSTANT
value cannot be changed
Definition: pointAttribute.hpp:127
riegl::rdb::pointcloud::PointAttribute::compressionOptions
uint8_t compressionOptions
options additional to default compression
Definition: pointAttribute.hpp:158
riegl::rdb::pointcloud::PointAttribute::DELTA_SHUFFLE
calculate differences and shuffle bytes
Definition: pointAttribute.hpp:144
riegl::rdb::pointcloud::PointAttribute::load
void load(const std::string &json)
Load settings from JSON string.
riegl::rdb::pointcloud::PointAttribute::CompressionOptions
CompressionOptions
Data Compression Options.
Definition: pointAttribute.hpp:139
riegl::rdb::pointcloud::PointAttribute::save
std::string save() const
Save settings to JSON string.
riegl::rdb::pointcloud::PointAttribute::storageClass
uint8_t storageClass
storage class
Definition: pointAttribute.hpp:157
riegl::rdb::pointcloud::PointAttribute::VARIABLE
value can change from time to time
Definition: pointAttribute.hpp:128
dataTypes.hpp
Point attribute access data types.
riegl::rdb::pointcloud::PointAttribute::resolution
double resolution
expected value resolution
Definition: pointAttribute.hpp:152
riegl::rdb::pointcloud::PointAttribute::DYNAMIC
value is likely to be changed often
Definition: pointAttribute.hpp:129
riegl::rdb::pointcloud::PointAttribute::length
uint32_t length
number of dimensions/elements (1: scalar, >1: vector, e.g. 3 for point coordinates)
Definition: pointAttribute.hpp:151
riegl::rdb::pointcloud::PointAttribute::StorageClass
StorageClass
Data Storage Class.
Definition: pointAttribute.hpp:125
riegl::rdb::pointcloud::PointAttribute::title
std::string title
attribute title (for display)
Definition: pointAttribute.hpp:148
riegl::rdb::pointcloud::PointAttribute::dataType
riegl::rdb::pointcloud::DataType dataType() const
Get buffer data type.
riegl::rdb::pointcloud::PointAttribute::operator=
PointAttribute & operator=(const PointAttribute &attribute)
Assignment operator.
riegl::rdb::pointcloud::PointAttribute::description
std::string description
attribute description (for display)
Definition: pointAttribute.hpp:149
riegl::rdb::pointcloud::PointAttribute::PointAttribute
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.
riegl::rdb::pointcloud::PointAttribute::maximumValue
double maximumValue
theoretical maximum value
Definition: pointAttribute.hpp:154
riegl::rdb::pointcloud::PointAttribute::lodSettings
std::string lodSettings
Level of detail settings.
Definition: pointAttribute.hpp:169
riegl::rdb::pointcloud::DataType
DataType
Point attribute access data type.
Definition: dataTypes.hpp:55
riegl::rdb::pointcloud::PointAttribute::name
std::string name
unique attribute name (for queries)
Definition: pointAttribute.hpp:147
riegl::rdb::Context
Library context.
Definition: context.hpp:70
riegl::rdb::pointcloud::PointAttribute::PointAttributeWrapper
friend class PointAttributeWrapper
Definition: pointAttribute.hpp:306