OpenVDB 12.1.0

Loading...
Searching...
No Matches
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>
22#include <openvdb/tree/LeafManager.h>
23#include <openvdb/util/Assert.h>
24
25#include <tbb/parallel_reduce.h>
26#include <tbb/parallel_for.h>
27
28 namespace openvdb {
29 OPENVDB_USE_VERSION_NAMESPACE
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>
50std::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>
75 typename ConvertElementType<ValueT, double>::Type
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>
99 typename PromoteType<ValueT>::Highest
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,
174 typename ConvertElementType<ValueT, double>::Type& average,
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
222#include "impl/PointStatisticsImpl.h"
223
224#endif // OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
Assert.h
LeafManager.h
A LeafManager manages a linear array of pointers to a given tree's leaf nodes, as well as optional au...
Math.h
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
PointDataGrid.h
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
PointStatisticsImpl.h
openvdb::v12_1::points::accumulate
PromoteType< ValueT >::Highest accumulate(const PointDataTreeT &points, const std::string &attribute, const FilterT &filter=NullFilter())
Evaluates the total value of a point attribute.
Definition PointStatisticsImpl.h:530
openvdb::v12_1::points::evalMinMax
std::pair< ValueT, ValueT > evalMinMax(const PointDataTreeT &points, const std::string &attribute, const FilterT &filter=NullFilter())
Evaluates the minimum and maximum values of a point attribute.
Definition PointStatisticsImpl.h:498
openvdb::v12_1::points::evalAverage
ConvertElementType< ValueT, double >::Type evalAverage(const PointDataTreeT &points, const std::string &attribute, const FilterT &filter=NullFilter())
Evaluates the average value of a point attribute.
Definition PointStatisticsImpl.h:515
openvdb
Definition Exceptions.h:13
Types.h
openvdb.h
OPENVDB_VERSION_NAME
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition version.h.in:121
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition version.h.in:218