Loading...
Searching...
No Matches
PointStatistics.h
Go to the documentation of this file.
// Copyright Contributors to the OpenVDB Project
// SPDX-License-Identifier: MPL-2.0
//
/// @author Nick Avramoussis
///
/// @file PointStatistics.h
///
/// @brief Functions to perform multi threaded reductions and analysis of
/// arbitrary point attribute types. Each function imposes various
/// requirements on the point ValueType (such as expected operators) and
/// supports arbitrary point filters.
///
#ifndef OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
#define OPENVDB_POINTS_STATISTICS_HAS_BEEN_INCLUDED
#include "PointDataGrid.h"
#include <openvdb/openvdb.h>
#include <openvdb/Types.h>
#include <openvdb/math/Math.h>
#include <openvdb/tree/LeafManager.h>
#include <tbb/parallel_reduce.h>
#include <tbb/parallel_for.h>
namespace openvdb {
OPENVDB_USE_VERSION_NAMESPACE
namespace OPENVDB_VERSION_NAME {
namespace points {
/// @brief Evaluates the minimum and maximum values of a point attribute.
/// @details Performs parallel reduction by comparing values using their less
/// than and greater than operators. If the PointDataGrid is empty or the
/// filter evalutes to empty, zeroVal<ValueT>() is returned for both values.
/// @note The ValueT of the attribute must be copy constructible. This method
/// will throw if the templated ValueT does not match the given attribute.
/// For vectors and matrices, this results in per component comparisons.
/// See evalExtents for magnitudes or more custom control.
/// @warning if "P" is provided, the result is undefined.
/// @param points the point tree
/// @param attribute the attribute to reduce
/// @param filter a filter to apply to points
/// @return min,max value pair
template <typename ValueT,
typename CodecT = UnknownCodec,
typename FilterT = NullFilter,
typename PointDataTreeT>
std::pair<ValueT, ValueT>
evalMinMax(const PointDataTreeT& points,
const std::string& attribute,
const FilterT& filter = NullFilter());
/// @brief Evaluates the average value of a point attribute.
/// @details Performs parallel reduction by cumulative moving average. The
/// reduction arithmetic and return value precision evaluates to:
/// ConvertElementType<ValueT, double>::Type
/// which, for POD and VDB math types, is ValueT at double precision. If the
/// PointDataGrid is empty or the filter evalutes to empty, zeroVal<ValueT>()
/// is returned.
/// @note The ConvertElementType of the attribute must be copy constructible,
/// support the same type + - * operators and * / operators from a double.
/// This method will throw if ValueT does not match the given attribute. The
/// function is deterministic.
/// @warning if "P" is provided, the result is undefined.
/// @param points the point tree
/// @param attribute the attribute to reduce
/// @param filter a filter to apply to points
/// @return the average value
template <typename ValueT,
typename CodecT = UnknownCodec,
typename FilterT = NullFilter,
typename PointDataTreeT>
typename ConvertElementType<ValueT, double>::Type
evalAverage(const PointDataTreeT& points,
const std::string& attribute,
const FilterT& filter = NullFilter());
/// @brief Evaluates the total value of a point attribute.
/// @details Performs parallel reduction by summing all values. The reduction
/// arithmetic and return value precision evaluates to:
/// PromoteType<ValueT>::Highest
/// which, for POD and VDB math types, is ValueT at its highest bit precision.
/// If the PointDataGrid is empty or the filter evalutes to empty,
/// zeroVal<ValueT>() is returned.
/// @note The PromoteType of the attribute must be copy constructible, support
/// the same type + operator. This method will throw if ValueT does not match
/// the given attribute. The function is deterministic.
/// @warning if "P" is provided, the result is undefined.
/// @param points the point tree
/// @param attribute the attribute to reduce
/// @param filter a filter to apply to points
/// @return the total value
template <typename ValueT,
typename CodecT = UnknownCodec,
typename FilterT = NullFilter,
typename PointDataTreeT>
typename PromoteType<ValueT>::Highest
accumulate(const PointDataTreeT& points,
const std::string& attribute,
const FilterT& filter = NullFilter());
/// @brief Evaluates the minimum and maximum values of a point attribute and
/// returns whether the values are valid. Optionally constructs localised
/// min and max value trees.
/// @details Performs parallel reduction by comparing values using their less
/// than and greater than operators. This method will return true if min and
/// max have been set, false otherwise (when no points existed or a filter
/// evaluated to empty).
/// @note The ValueT of the attribute must also be copy constructible. This
/// method will throw if the templated ValueT does not match the given
/// attribute. For vectors and matrices, this results in per component
/// comparisons. See evalExtents for magnitudes or more custom control.
/// @warning if "P" is provided, the result is undefined.
/// @param points the point tree
/// @param attribute the attribute to reduce
/// @param min the computed min value
/// @param max the computed max value
/// @param filter a filter to apply to points
/// @param minTree if provided, builds a tiled tree of localised min results
/// @param maxTree if provided, builds a tiled tree of localised max results
/// @return true if min and max have been set, false otherwise. Can be false if
/// no points were processed or if the tree was empty.
template <typename ValueT,
typename CodecT = UnknownCodec,
typename FilterT = NullFilter,
typename PointDataTreeT>
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);
/// @brief Evaluates the average value of a point attribute and returns whether
/// the value is valid. Optionally constructs localised average value trees.
/// @details Performs parallel reduction by cumulative moving average. The
/// reduction arithmetic and return value precision evaluates to:
/// ConvertElementType<ValueT, double>::Type
/// which, for POD and VDB math types, is ValueT at double precision. This
/// method will return true average has been set, false otherwise (when no
/// points existed or a filter evaluated to empty).
/// @note The ConvertElementType of the attribute must be copy constructible,
/// support the same type + - * operators and * / operators from a double.
/// This method will throw if ValueT does not match the given attribute. The
/// function is deterministic.
/// @warning if "P" is provided, the result is undefined.
/// @param points the point tree
/// @param attribute the attribute to reduce
/// @param average the computed averaged value at double precision
/// @param filter a filter to apply to points
/// @param averageTree if provided, builds a tiled tree of localised avg results.
/// @return true if average has been set, false otherwise. Can be false if
/// no points were processed or if the tree was empty.
/// @par Example:
/// @code
/// using namespace openvdb;
/// using namespace openvdb::points
///
/// // average and store per leaf values in a new tree
/// ConvertElementType<uint8_t, double>::Type avg; // evaluates to double
/// PointDataTree::ValueConverter<decltype(avg)>::Type avgTree; // double tree of averages
/// bool success = evalAverage<uint8_t>(tree, "attrib", avg, NullFilter(), &avgTree);
/// @endcode
template <typename ValueT,
typename CodecT = UnknownCodec,
typename FilterT = NullFilter,
typename PointDataTreeT,
typename ResultTreeT = typename ConvertElementType<ValueT, double>::Type>
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);
/// @brief Evaluates the total value of a point attribute and returns whether
/// the value is valid. Optionally constructs localised total value trees.
/// @details Performs parallel reduction by summing all values. The reduction
/// arithmetic and return value precision evaluates to:
/// PromoteType<ValueT>::Highest
/// which, for POD and VDB math types, is ValueT at its highest bit precision.
/// This method will return true total has been set, false otherwise (when no
/// points existed or a filter evaluated to empty).
/// @note The PromoteType of the attribute must be copy constructible, support
/// the same type + operator. This method will throw if ValueT does not match
/// the given attribute. The function is deterministic.
/// @warning if "P" is provided, the result is undefined.
/// @param points the point tree
/// @param attribute the attribute to reduce
/// @param total the computed total value
/// @param filter a filter to apply to points
/// @param totalTree if provided, builds a tiled tree of localised total results.
/// @return true if total has been set, false otherwise. Can be false if
/// no points were processed or if the tree was empty.
/// @par Example:
/// @code
/// using namespace openvdb;
/// using namespace openvdb::points;
///
/// // accumulate and store per leaf values in a new tree
/// PromoteType<uint8_t>::Highest total; // evaluates to uint64_t
/// PointDataTree::ValueConverter<decltype(total)>::Type totalTree; // uint64_t tree of totals
/// bool success = accumulate<uint8_t>(tree, "attrib", total, NullFilter(), &totalTree);
/// @endcode
template <typename ValueT,
typename CodecT = UnknownCodec,
typename FilterT = NullFilter,
typename PointDataTreeT,
typename ResultTreeT = typename PromoteType<ValueT>::Highest>
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);
} // namespace points
} // namespace OPENVDB_VERSION_NAME
} // namespace openvdb
#include "impl/PointStatisticsImpl.h"
#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
Types.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
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