OpenVDB  12.0.0
PointStatistics.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: Apache-2.0
3 //
4 /// @author Nick Avramoussis
5 ///
6 /// @file PointStatistics.h
7 ///
8 /// @brief Functions to perform multi threaded reductions and analysis of
9 /// arbitrary point attribute types. Each function imposes various
10 /// requirements on the point ValueType (such as expected operators) and
11 /// supports arbitrary point filters.
12 ///
13 
14 #ifndef OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
15 #define OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
16 
17 #include "PointDataGrid.h"
18 
19 #include <openvdb/openvdb.h>
20 #include <openvdb/Types.h>
21 #include <openvdb/math/Math.h>
23 #include <openvdb/util/Assert.h>
24 
25 #include <tbb/parallel_reduce.h>
26 #include <tbb/parallel_for.h>
27 
28 namespace openvdb {
30 namespace OPENVDB_VERSION_NAME {
31 namespace points {
32 
33 /// @brief Evaluates the minimum and maximum values of a point attribute.
34 /// @details Performs parallel reduction by comparing values using their less
35 /// than and greater than operators. If the PointDataGrid is empty or the
36 /// filter evalutes to empty, zeroVal<ValueT>() is returned for both values.
37 /// @note The ValueT of the attribute must be copy constructible. This method
38 /// will throw if the templated ValueT does not match the given attribute.
39 /// For vectors and matrices, this results in per component comparisons.
40 /// See evalExtents for magnitudes or more custom control.
41 /// @warning if "P" is provided, the result is undefined.
42 /// @param points the point tree
43 /// @param attribute the attribute to reduce
44 /// @param filter a filter to apply to points
45 /// @return min,max value pair
46 template <typename ValueT,
47  typename CodecT = UnknownCodec,
48  typename FilterT = NullFilter,
49  typename PointDataTreeT>
50 std::pair<ValueT, ValueT>
51 evalMinMax(const PointDataTreeT& points,
52  const std::string& attribute,
53  const FilterT& filter = NullFilter());
54 
55 /// @brief Evaluates the average value of a point attribute.
56 /// @details Performs parallel reduction by cumulative moving average. The
57 /// reduction arithmetic and return value precision evaluates to:
58 /// ConvertElementType<ValueT, double>::Type
59 /// which, for POD and VDB math types, is ValueT at double precision. If the
60 /// PointDataGrid is empty or the filter evalutes to empty, zeroVal<ValueT>()
61 /// is returned.
62 /// @note The ConvertElementType of the attribute must be copy constructible,
63 /// support the same type + - * operators and * / operators from a double.
64 /// This method will throw if ValueT does not match the given attribute. The
65 /// function is deterministic.
66 /// @warning if "P" is provided, the result is undefined.
67 /// @param points the point tree
68 /// @param attribute the attribute to reduce
69 /// @param filter a filter to apply to points
70 /// @return the average value
71 template <typename ValueT,
72  typename CodecT = UnknownCodec,
73  typename FilterT = NullFilter,
74  typename PointDataTreeT>
76 evalAverage(const PointDataTreeT& points,
77  const std::string& attribute,
78  const FilterT& filter = NullFilter());
79 
80 /// @brief Evaluates the total value of a point attribute.
81 /// @details Performs parallel reduction by summing all values. The reduction
82 /// arithmetic and return value precision evaluates to:
83 /// PromoteType<ValueT>::Highest
84 /// which, for POD and VDB math types, is ValueT at its highest bit precision.
85 /// If the PointDataGrid is empty or the filter evalutes to empty,
86 /// zeroVal<ValueT>() is returned.
87 /// @note The PromoteType of the attribute must be copy constructible, support
88 /// the same type + operator. This method will throw if ValueT does not match
89 /// the given attribute. The function is deterministic.
90 /// @warning if "P" is provided, the result is undefined.
91 /// @param points the point tree
92 /// @param attribute the attribute to reduce
93 /// @param filter a filter to apply to points
94 /// @return the total value
95 template <typename ValueT,
96  typename CodecT = UnknownCodec,
97  typename FilterT = NullFilter,
98  typename PointDataTreeT>
100 accumulate(const PointDataTreeT& points,
101  const std::string& attribute,
102  const FilterT& filter = NullFilter());
103 
104 /// @brief Evaluates the minimum and maximum values of a point attribute and
105 /// returns whether the values are valid. Optionally constructs localised
106 /// min and max value trees.
107 /// @details Performs parallel reduction by comparing values using their less
108 /// than and greater than operators. This method will return true if min and
109 /// max have been set, false otherwise (when no points existed or a filter
110 /// evaluated to empty).
111 /// @note The ValueT of the attribute must also be copy constructible. This
112 /// method will throw if the templated ValueT does not match the given
113 /// attribute. For vectors and matrices, this results in per component
114 /// comparisons. See evalExtents for magnitudes or more custom control.
115 /// @warning if "P" is provided, the result is undefined.
116 /// @param points the point tree
117 /// @param attribute the attribute to reduce
118 /// @param min the computed min value
119 /// @param max the computed max value
120 /// @param filter a filter to apply to points
121 /// @param minTree if provided, builds a tiled tree of localised min results
122 /// @param maxTree if provided, builds a tiled tree of localised max results
123 /// @return true if min and max have been set, false otherwise. Can be false if
124 /// no points were processed or if the tree was empty.
125 template <typename ValueT,
126  typename CodecT = UnknownCodec,
127  typename FilterT = NullFilter,
128  typename PointDataTreeT>
129 bool evalMinMax(const PointDataTreeT& points,
130  const std::string& attribute,
131  ValueT& min,
132  ValueT& max,
133  const FilterT& filter = NullFilter(),
134  typename PointDataTreeT::template ValueConverter<ValueT>::Type* minTree = nullptr,
135  typename PointDataTreeT::template ValueConverter<ValueT>::Type* maxTree = nullptr);
136 
137 /// @brief Evaluates the average value of a point attribute and returns whether
138 /// the value is valid. Optionally constructs localised average value trees.
139 /// @details Performs parallel reduction by cumulative moving average. The
140 /// reduction arithmetic and return value precision evaluates to:
141 /// ConvertElementType<ValueT, double>::Type
142 /// which, for POD and VDB math types, is ValueT at double precision. This
143 /// method will return true average has been set, false otherwise (when no
144 /// points existed or a filter evaluated to empty).
145 /// @note The ConvertElementType of the attribute must be copy constructible,
146 /// support the same type + - * operators and * / operators from a double.
147 /// This method will throw if ValueT does not match the given attribute. The
148 /// function is deterministic.
149 /// @warning if "P" is provided, the result is undefined.
150 /// @param points the point tree
151 /// @param attribute the attribute to reduce
152 /// @param average the computed averaged value at double precision
153 /// @param filter a filter to apply to points
154 /// @param averageTree if provided, builds a tiled tree of localised avg results.
155 /// @return true if average has been set, false otherwise. Can be false if
156 /// no points were processed or if the tree was empty.
157 /// @par Example:
158 /// @code
159 /// using namespace openvdb;
160 /// using namespace openvdb::points
161 ///
162 /// // average and store per leaf values in a new tree
163 /// ConvertElementType<uint8_t, double>::Type avg; // evaluates to double
164 /// PointDataTree::ValueConverter<decltype(avg)>::Type avgTree; // double tree of averages
165 /// bool success = evalAverage<uint8_t>(tree, "attrib", avg, NullFilter(), &avgTree);
166 /// @endcode
167 template <typename ValueT,
168  typename CodecT = UnknownCodec,
169  typename FilterT = NullFilter,
170  typename PointDataTreeT,
171  typename ResultTreeT = typename ConvertElementType<ValueT, double>::Type>
172 bool evalAverage(const PointDataTreeT& points,
173  const std::string& attribute,
175  const FilterT& filter = NullFilter(),
176  typename PointDataTreeT::template ValueConverter<ResultTreeT>::Type* averageTree = nullptr);
177 
178 /// @brief Evaluates the total value of a point attribute and returns whether
179 /// the value is valid. Optionally constructs localised total value trees.
180 /// @details Performs parallel reduction by summing all values. The reduction
181 /// arithmetic and return value precision evaluates to:
182 /// PromoteType<ValueT>::Highest
183 /// which, for POD and VDB math types, is ValueT at its highest bit precision.
184 /// This method will return true total has been set, false otherwise (when no
185 /// points existed or a filter evaluated to empty).
186 /// @note The PromoteType of the attribute must be copy constructible, support
187 /// the same type + operator. This method will throw if ValueT does not match
188 /// the given attribute. The function is deterministic.
189 /// @warning if "P" is provided, the result is undefined.
190 /// @param points the point tree
191 /// @param attribute the attribute to reduce
192 /// @param total the computed total value
193 /// @param filter a filter to apply to points
194 /// @param totalTree if provided, builds a tiled tree of localised total results.
195 /// @return true if total has been set, false otherwise. Can be false if
196 /// no points were processed or if the tree was empty.
197 /// @par Example:
198 /// @code
199 /// using namespace openvdb;
200 /// using namespace openvdb::points;
201 ///
202 /// // accumulate and store per leaf values in a new tree
203 /// PromoteType<uint8_t>::Highest total; // evaluates to uint64_t
204 /// PointDataTree::ValueConverter<decltype(total)>::Type totalTree; // uint64_t tree of totals
205 /// bool success = accumulate<uint8_t>(tree, "attrib", total, NullFilter(), &totalTree);
206 /// @endcode
207 template <typename ValueT,
208  typename CodecT = UnknownCodec,
209  typename FilterT = NullFilter,
210  typename PointDataTreeT,
211  typename ResultTreeT = typename PromoteType<ValueT>::Highest>
212 bool accumulate(const PointDataTreeT& points,
213  const std::string& attribute,
214  typename PromoteType<ValueT>::Highest& total,
215  const FilterT& filter = NullFilter(),
216  typename PointDataTreeT::template ValueConverter<ResultTreeT>::Type* totalTree = nullptr);
217 
218 } // namespace points
219 } // namespace OPENVDB_VERSION_NAME
220 } // namespace openvdb
221 
223 
224 #endif // OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
typename TypeT< 64ul >::type Highest
Definition: Types.h:371
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
bool evalMinMax(const PointDataTreeT &points, const std::string &attribute, ValueT &min, ValueT &max, const FilterT &filter=NullFilter(), typename PointDataTreeT::template ValueConverter< ValueT >::Type *minTree=nullptr, typename PointDataTreeT::template ValueConverter< ValueT >::Type *maxTree=nullptr)
Evaluates the minimum and maximum values of a point attribute and returns whether the values are vali...
Definition: PointStatisticsImpl.h:281
const std::enable_if<!VecTraits< T >::IsVec, T >::type & max(const T &a, const T &b)
Definition: Composite.h:110
bool accumulate(const PointDataTreeT &points, const std::string &attribute, typename PromoteType< ValueT >::Highest &total, const FilterT &filter=NullFilter(), typename PointDataTreeT::template ValueConverter< ResultTreeT >::Type *totalTree=nullptr)
Evaluates the total value of a point attribute and returns whether the value is valid. Optionally constructs localised total value trees.
Definition: PointStatisticsImpl.h:409
Definition: Exceptions.h:13
bool evalAverage(const PointDataTreeT &points, const std::string &attribute, typename ConvertElementType< ValueT, double >::Type &average, const FilterT &filter=NullFilter(), typename PointDataTreeT::template ValueConverter< ResultTreeT >::Type *averageTree=nullptr)
Evaluates the average value of a point attribute and returns whether the value is valid...
Definition: PointStatisticsImpl.h:298
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
SubT Type
Definition: Types.h:320
const std::enable_if<!VecTraits< T >::IsVec, T >::type & min(const T &a, const T &b)
Definition: Composite.h:106
A LeafManager manages a linear array of pointers to a given tree&#39;s leaf nodes, as well as optional au...
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:121
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:218