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