OpenVDB: openvdb/points/PointStatistics.h Source File

OpenVDB 11.0.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: 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>
22#include <openvdb/tree/LeafManager.h>
23
24#include <tbb/parallel_reduce.h>
25#include <tbb/parallel_for.h>
26
27namespace openvdb {
28 OPENVDB_USE_VERSION_NAMESPACE
29namespace OPENVDB_VERSION_NAME {
30namespace 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
45template <typename ValueT,
46 typename CodecT = UnknownCodec,
47 typename FilterT = NullFilter,
48 typename PointDataTreeT>
49std::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
70template <typename ValueT,
71 typename CodecT = UnknownCodec,
72 typename FilterT = NullFilter,
73 typename PointDataTreeT>
74typename ConvertElementType<ValueT, double>::Type
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
94template <typename ValueT,
95 typename CodecT = UnknownCodec,
96 typename FilterT = NullFilter,
97 typename PointDataTreeT>
98typename PromoteType<ValueT>::Highest
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.
124template <typename ValueT,
125 typename CodecT = UnknownCodec,
126 typename FilterT = NullFilter,
127 typename PointDataTreeT>
128bool 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
166template <typename ValueT,
167 typename CodecT = UnknownCodec,
168 typename FilterT = NullFilter,
169 typename PointDataTreeT,
170 typename ResultTreeT = typename ConvertElementType<ValueT, double>::Type>
171bool evalAverage(const PointDataTreeT& points,
172 const std::string& attribute,
173 typename ConvertElementType<ValueT, double>::Type& average,
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
206template <typename ValueT,
207 typename CodecT = UnknownCodec,
208 typename FilterT = NullFilter,
209 typename PointDataTreeT,
210 typename ResultTreeT = typename PromoteType<ValueT>::Highest>
211bool 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
221#include "impl/PointStatisticsImpl.h"
222
223#endif // OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
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::v11_0::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::v11_0::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::v11_0::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:212