OpenVDB  11.0.0
PointRasterizeSDF.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 PointRasterizeSDF.h
7 ///
8 /// @brief Transfer schemes for rasterizing point positional and radius data to
9 /// signed distance fields with optional closest point attribute transfers.
10 /// All methods support arbitrary target linear transformations, fixed or
11 /// varying point radius, filtering of point data and arbitrary types for
12 /// attribute transferring.
13 ///
14 /// @details There are two main transfer implementations; rasterizeSpheres and
15 /// rasterizeSmoothSpheres. The prior performs trivial narrow band stamping
16 /// of spheres for each point, where as the latter calculates an averaged
17 /// position of influence per voxel as described in:
18 /// [Animating Sand as a Fluid - Zhu Bridson 05].
19 ///
20 /// rasterizeSpheres() is an extremely fast and efficient way to produce both a
21 /// valid symmetrical narrow band level set and transfer attributes using
22 /// closest point lookups.
23 ///
24 /// rasterizeSmoothSpheres() produces smoother, more blended connections
25 /// between points which is ideal for generating a more artistically pleasant
26 /// surface directly from point distributions. It aims to avoid typical post
27 /// filtering operations used to smooth surface volumes. Note however that
28 /// rasterizeSmoothSpheres may not necessarily produce a *symmetrical* narrow
29 /// band level set; the exterior band may be smaller than desired depending on
30 /// the search radius. The surface can be rebuilt or resized if necessary.
31 /// The same closet point algorithm is used to transfer attributes.
32 ///
33 /// In general, it is recommended to consider post rebuilding/renormalizing the
34 /// generated surface using either tools::levelSetRebuild() or
35 /// tools::LevelSetTracker::normalize() tools::LevelSetTracker::resize().
36 ///
37 /// @note These methods use the framework provided in PointTransfer.h
38 ///
39 
40 #ifndef OPENVDB_POINTS_RASTERIZE_SDF_HAS_BEEN_INCLUDED
41 #define OPENVDB_POINTS_RASTERIZE_SDF_HAS_BEEN_INCLUDED
42 
43 #include "PointDataGrid.h"
44 #include "PointTransfer.h"
45 #include "PointStatistics.h"
46 
47 #include <openvdb/openvdb.h>
48 #include <openvdb/Types.h>
49 #include <openvdb/tools/Prune.h>
51 #include <openvdb/thread/Threading.h>
53 
54 #include <unordered_map>
55 
56 #include <tbb/task_group.h>
57 #include <tbb/parallel_reduce.h>
58 
59 namespace openvdb {
61 namespace OPENVDB_VERSION_NAME {
62 namespace points {
63 
64 /// @brief Narrow band sphere stamping with a uniform radius.
65 /// @details Rasterizes points into a level set using basic sphere stamping with
66 /// a uniform radius. The radius parameter is given in world space units and
67 /// is applied to every point to generate a fixed surface mask and consequent
68 /// distance values.
69 /// @param points the point data grid to rasterize
70 /// @param radius the world space radius of every point
71 /// @param halfband the half band width
72 /// @param transform the target transform for the surface
73 /// @param filter a filter to apply to points
74 /// @param interrupter optional interrupter
75 /// @return The signed distance field.
76 template <typename PointDataGridT,
77  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
78  typename FilterT = NullFilter,
79  typename InterrupterT = util::NullInterrupter>
80 typename SdfT::Ptr
81 rasterizeSpheres(const PointDataGridT& points,
82  const Real radius,
83  const Real halfband = LEVEL_SET_HALF_WIDTH,
84  math::Transform::Ptr transform = nullptr,
85  const FilterT& filter = NullFilter(),
86  InterrupterT* interrupter = nullptr);
87 
88 /// @brief Narrow band sphere stamping with a varying radius.
89 /// @details Rasterizes points into a level set using basic sphere stamping with
90 /// a variable radius. The radius string parameter expects a point attribute
91 /// of type RadiusT to exist.
92 /// @param points the point data grid to rasterize
93 /// @param radius the name of the radius attribute
94 /// @param scale an optional scale to apply to each per point radius
95 /// @param halfband the half band width
96 /// @param transform the target transform for the surface
97 /// @param filter a filter to apply to points
98 /// @param interrupter optional interrupter
99 /// @return The signed distance field.
100 template <typename PointDataGridT,
101  typename RadiusT = float,
102  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
103  typename FilterT = NullFilter,
104  typename InterrupterT = util::NullInterrupter>
105 typename SdfT::Ptr
106 rasterizeSpheres(const PointDataGridT& points,
107  const std::string& radius,
108  const Real scale = 1.0,
109  const Real halfband = LEVEL_SET_HALF_WIDTH,
110  math::Transform::Ptr transform = nullptr,
111  const FilterT& filter = NullFilter(),
112  InterrupterT* interrupter = nullptr);
113 
114 /// @brief Narrow band sphere stamping with a uniform radius and closest point
115 /// attribute transfer.
116 /// @details Rasterizes points into a level set using basic sphere stamping with
117 /// a uniform radius. The radius parameter is given in world space units and
118 /// is applied to every point to generate a fixed surface mask and consequent
119 /// distance values. Every voxel's closest point is used to transfer each
120 /// attribute in the attributes parameter to a new grid of matching topology.
121 /// The destination types of these grids is equal to the ValueConverter result
122 /// of the attribute type applied to the PointDataGridT.
123 /// @note The AttributeTypes template parameter should be a TypeList of the
124 /// required or possible attributes types. i.e. TypeList<int, float, double>.
125 /// A runtime error will be thrown if no equivalent type for a given attribute
126 //// is found in the AttributeTypes TypeList.
127 /// @param points the point data grid to rasterize
128 /// @param radius the world space radius of every point
129 /// @param attributes list of attributes to transfer
130 /// @param halfband the half band width
131 /// @param transform the target transform for the surface
132 /// @param filter a filter to apply to points
133 /// @param interrupter optional interrupter
134 /// @return A vector of grids. The signed distance field is guaranteed to be
135 /// first and at the type specified by SdfT. Successive grids are the closest
136 /// point attribute grids. These grids are guaranteed to have a topology
137 /// and transform equal to the surface.
138 template <typename PointDataGridT,
139  typename AttributeTypes,
140  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
141  typename FilterT = NullFilter,
142  typename InterrupterT = util::NullInterrupter>
144 rasterizeSpheres(const PointDataGridT& points,
145  const Real radius,
146  const std::vector<std::string>& attributes,
147  const Real halfband = LEVEL_SET_HALF_WIDTH,
148  math::Transform::Ptr transform = nullptr,
149  const FilterT& filter = NullFilter(),
150  InterrupterT* interrupter = nullptr);
151 
152 /// @brief Narrow band sphere stamping with a varying radius and closest point
153 /// attribute transfer.
154 /// @details Rasterizes points into a level set using basic sphere stamping with
155 /// a variable radius. The radius string parameter expects a point attribute
156 /// of type RadiusT to exist. Every voxel's closest point is used to transfer
157 /// each attribute in the attributes parameter to a new grid of matching
158 /// topology. The destination types of these grids is equal to the
159 /// ValueConverter result of the attribute type applied to the PointDataGridT.
160 /// @note The AttributeTypes template parameter should be a TypeList of the
161 /// required or possible attributes types. i.e. TypeList<int, float, double>.
162 /// A runtime error will be thrown if no equivalent type for a given attribute
163 //// is found in the AttributeTypes TypeList.
164 /// @param points the point data grid to rasterize
165 /// @param radius the name of the radius attribute
166 /// @param attributes list of attributes to transfer
167 /// @param scale scale to apply to each per point radius
168 /// @param halfband the half band width
169 /// @param transform the target transform for the surface
170 /// @param filter a filter to apply to points
171 /// @param interrupter optional interrupter
172 /// @return A vector of grids. The signed distance field is guaranteed to be
173 /// first and at the type specified by SdfT. Successive grids are the closest
174 /// point attribute grids. These grids are guaranteed to have a topology
175 /// and transform equal to the surface.
176 template <typename PointDataGridT,
177  typename AttributeTypes,
178  typename RadiusT = float,
179  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
180  typename FilterT = NullFilter,
181  typename InterrupterT = util::NullInterrupter>
183 rasterizeSpheres(const PointDataGridT& points,
184  const std::string& radius,
185  const std::vector<std::string>& attributes,
186  const Real scale = 1.0,
187  const Real halfband = LEVEL_SET_HALF_WIDTH,
188  math::Transform::Ptr transform = nullptr,
189  const FilterT& filter = NullFilter(),
190  InterrupterT* interrupter = nullptr);
191 
192 /// @brief Smoothed point distribution based sphere stamping with a uniform radius.
193 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
194 /// stamping with a uniform radius. The radius and search radius parameters
195 /// are given in world space units and are applied to every point to generate
196 /// a fixed surface mask and consequent distance values. The search radius is
197 /// each points points maximum contribution to the target level set. The search
198 /// radius should always have a value equal to or larger than the point radius.
199 /// @warning The width of the exterior half band *may* be smaller than the
200 /// specified half band if the search radius is less than the equivalent
201 /// world space halfband distance.
202 /// @param points the point data grid to rasterize
203 /// @param radius the world space radius of every point
204 /// @param searchRadius the maximum search distance of every point
205 /// @param halfband the half band width
206 /// @param transform the target transform for the surface
207 /// @param filter a filter to apply to points
208 /// @param interrupter optional interrupter
209 /// @return The signed distance field.
210 template <typename PointDataGridT,
211  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
212  typename FilterT = NullFilter,
213  typename InterrupterT = util::NullInterrupter>
214 typename SdfT::Ptr
215 rasterizeSmoothSpheres(const PointDataGridT& points,
216  const Real radius,
217  const Real searchRadius,
218  const Real halfband = LEVEL_SET_HALF_WIDTH,
219  math::Transform::Ptr transform = nullptr,
220  const FilterT& filter = NullFilter(),
221  InterrupterT* interrupter = nullptr);
222 
223 /// @brief Smoothed point distribution based sphere stamping with a varying radius.
224 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
225 /// stamping with a variable radius. The radius string parameter expects a
226 /// point attribute of type RadiusT to exist. The radiusScale parameter is
227 /// multiplier for radius values held on the radius attribute. The searchRadius
228 /// parameter remains a fixed size value which represents each points points
229 /// maximum contribution to the target level set. The radius scale and search
230 /// radius parameters are given in world space units and are applied to every
231 /// point to generate a fixed surface mask and consequent distance values. The
232 /// search radius should always have a value equal to or larger than the point
233 /// radii.
234 /// @warning The width of the exterior half band *may* be smaller than the
235 /// specified half band if the search radius is less than the equivalent
236 /// world space halfband distance.
237 /// @param points the point data grid to rasterize
238 /// @param radius the attribute containing the world space radius
239 /// @param radiusScale the scale applied to every world space radius value
240 /// @param searchRadius the maximum search distance of every point
241 /// @param halfband the half band width
242 /// @param transform the target transform for the surface
243 /// @param filter a filter to apply to points
244 /// @param interrupter optional interrupter
245 /// @return The signed distance field.
246 template <typename PointDataGridT,
247  typename RadiusT = float,
248  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
249  typename FilterT = NullFilter,
250  typename InterrupterT = util::NullInterrupter>
251 typename SdfT::Ptr
252 rasterizeSmoothSpheres(const PointDataGridT& points,
253  const std::string& radius,
254  const Real radiusScale,
255  const Real searchRadius,
256  const Real halfband = LEVEL_SET_HALF_WIDTH,
257  math::Transform::Ptr transform = nullptr,
258  const FilterT& filter = NullFilter(),
259  InterrupterT* interrupter = nullptr);
260 
261 /// @brief Smoothed point distribution based sphere stamping with a uniform
262 /// radius and closest point attribute transfer.
263 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
264 /// stamping with a uniform radius. The radius and search radius parameters
265 /// are given in world space units and are applied to every point to generate
266 /// a fixed surface mask and consequent distance values. The search radius is
267 /// each points points maximum contribution to the target level set. The
268 /// search radius should always be larger than the point radius. Every voxel's
269 /// closest point is used to transfer each attribute in the attributes
270 /// parameter to a new grid of matching topology. The destination types of
271 /// these grids is equal to the ValueConverter result of the attribute type
272 /// applied to the PointDataGridT.
273 /// @note The AttributeTypes template parameter should be a TypeList of the
274 /// required or possible attributes types. i.e. TypeList<int, float, double>.
275 /// A runtime error will be thrown if no equivalent type for a given attribute
276 /// is found in the AttributeTypes TypeList.
277 /// @warning The width of the exterior half band *may* be smaller than the
278 /// specified half band if the search radius is less than the equivalent
279 /// world space halfband distance.
280 /// @param points the point data grid to rasterize
281 /// @param radius the world space radius of every point
282 /// @param searchRadius the maximum search distance of every point
283 /// @param attributes list of attributes to transfer
284 /// @param halfband the half band width
285 /// @param transform the target transform for the surface
286 /// @param filter a filter to apply to points
287 /// @param interrupter optional interrupter
288 /// @return A vector of grids. The signed distance field is guaranteed to be
289 /// first and at the type specified by SdfT. Successive grids are the closest
290 /// point attribute grids. These grids are guaranteed to have a topology
291 /// and transform equal to the surface.
292 template <typename PointDataGridT,
293  typename AttributeTypes,
294  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
295  typename FilterT = NullFilter,
296  typename InterrupterT = util::NullInterrupter>
298 rasterizeSmoothSpheres(const PointDataGridT& points,
299  const Real radius,
300  const Real searchRadius,
301  const std::vector<std::string>& attributes,
302  const Real halfband = LEVEL_SET_HALF_WIDTH,
303  math::Transform::Ptr transform = nullptr,
304  const FilterT& filter = NullFilter(),
305  InterrupterT* interrupter = nullptr);
306 
307 /// @brief Smoothed point distribution based sphere stamping with a varying
308 /// radius and closest point attribute transfer.
309 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
310 /// stamping with a variable radius. The radius string parameter expects a
311 /// point attribute of type RadiusT to exist. The radiusScale parameter is
312 /// multiplier for radius values held on the radius attribute. The searchRadius
313 /// parameter remains a fixed size value which represents each points points
314 /// maximum contribution to the target level set. The radius scale and search
315 /// radius parameters are given in world space units and are applied to every
316 /// point to generate a fixed surface mask and consequent distance values. The
317 /// search radius should always have a value equal to or larger than the point
318 /// radii. Every voxel's closest point is used to transfer each attribute in
319 /// the attributes parameter to a new grid of matching topology. The
320 /// destination types of these grids is equal to the ValueConverter result of
321 /// the attribute type applied to the PointDataGridT.
322 /// @note The AttributeTypes template parameter should be a TypeList of the
323 /// required or possible attributes types. i.e. TypeList<int, float, double>.
324 /// A runtime error will be thrown if no equivalent type for a given attribute
325 //// is found in the AttributeTypes TypeList.
326 /// @warning The width of the exterior half band *may* be smaller than the
327 /// specified half band if the search radius is less than the equivalent
328 /// world space halfband distance.
329 /// @param points the point data grid to rasterize
330 /// @param radius the attribute containing the world space radius
331 /// @param radiusScale the scale applied to every world space radius value
332 /// @param searchRadius the maximum search distance of every point
333 /// @param attributes list of attributes to transfer
334 /// @param halfband the half band width
335 /// @param transform the target transform for the surface
336 /// @param filter a filter to apply to points
337 /// @param interrupter optional interrupter
338 /// @return A vector of grids. The signed distance field is guaranteed to be
339 /// first and at the type specified by SdfT. Successive grids are the closest
340 /// point attribute grids. These grids are guaranteed to have a topology
341 /// and transform equal to the surface.
342 template <typename PointDataGridT,
343  typename AttributeTypes,
344  typename RadiusT = float,
345  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
346  typename FilterT = NullFilter,
347  typename InterrupterT = util::NullInterrupter>
349 rasterizeSmoothSpheres(const PointDataGridT& points,
350  const std::string& radius,
351  const Real radiusScale,
352  const Real searchRadius,
353  const std::vector<std::string>& attributes,
354  const Real halfband = LEVEL_SET_HALF_WIDTH,
355  math::Transform::Ptr transform = nullptr,
356  const FilterT& filter = NullFilter(),
357  InterrupterT* interrupter = nullptr);
358 
359 } // namespace points
360 } // namespace OPENVDB_VERSION_NAME
361 } // namespace openvdb
362 
364 
365 #endif //OPENVDB_POINTS_RASTERIZE_SDF_HAS_BEEN_INCLUDED
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
Functions to perform multi threaded reductions and analysis of arbitrary point attribute types....
Framework methods for rasterizing PointDataGrid data to Trees.
Defined various multi-threaded utility functions for trees.
MatType scale(const Vec3< typename MatType::value_type > &s)
Return a matrix that scales by s.
Definition: Mat.h:615
GridPtrVec rasterizeSmoothSpheres(const PointDataGridT &points, const std::string &radius, const Real radiusScale, const Real searchRadius, const std::vector< std::string > &attributes, const Real halfband=LEVEL_SET_HALF_WIDTH, math::Transform::Ptr transform=nullptr, const FilterT &filter=NullFilter(), InterrupterT *interrupter=nullptr)
Smoothed point distribution based sphere stamping with a varying radius and closest point attribute t...
Definition: PointRasterizeSDFImpl.h:1299
GridPtrVec rasterizeSpheres(const PointDataGridT &points, const std::string &radius, const std::vector< std::string > &attributes, const Real scale=1.0, const Real halfband=LEVEL_SET_HALF_WIDTH, math::Transform::Ptr transform=nullptr, const FilterT &filter=NullFilter(), InterrupterT *interrupter=nullptr)
Narrow band sphere stamping with a varying radius and closest point attribute transfer.
Definition: PointRasterizeSDFImpl.h:1145
static const Real LEVEL_SET_HALF_WIDTH
Definition: Types.h:461
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:508
NumericAttributeTypes::Append< Vec3AttributeTypes >::Append< Mat3AttributeTypes >::Append< Mat4AttributeTypes >::Append< QuatAttributeTypes >::Append< points::GroupAttributeArray >::Append< points::StringAttributeArray >::Append< points::TypedAttributeArray< bool > > AttributeTypes
The attribute array types which OpenVDB will register by default.
Definition: openvdb.h:186
double Real
Definition: Types.h:60
Definition: Exceptions.h:13
#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:212