OpenVDB  12.0.0
PointRasterizeSDF.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 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 #include <openvdb/util/Assert.h>
54 
55 #include <unordered_map>
56 
57 #include <tbb/task_group.h>
58 #include <tbb/parallel_reduce.h>
59 
60 namespace openvdb {
62 namespace OPENVDB_VERSION_NAME {
63 namespace points {
64 
65 /// @brief Narrow band sphere stamping with a uniform radius.
66 /// @details Rasterizes points into a level set using basic sphere stamping with
67 /// a uniform radius. The radius parameter is given in world space units and
68 /// is applied to every point to generate a fixed surface mask and consequent
69 /// distance values.
70 /// @param points the point data grid to rasterize
71 /// @param radius the world space radius of every point
72 /// @param halfband the half band width
73 /// @param transform the target transform for the surface
74 /// @param filter a filter to apply to points
75 /// @param interrupter optional interrupter
76 /// @return The signed distance field.
77 template <typename PointDataGridT,
78  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
79  typename FilterT = NullFilter,
80  typename InterrupterT = util::NullInterrupter>
81 typename SdfT::Ptr
82 rasterizeSpheres(const PointDataGridT& points,
83  const Real radius,
84  const Real halfband = LEVEL_SET_HALF_WIDTH,
85  math::Transform::Ptr transform = nullptr,
86  const FilterT& filter = NullFilter(),
87  InterrupterT* interrupter = nullptr);
88 
89 /// @brief Narrow band sphere stamping with a varying radius.
90 /// @details Rasterizes points into a level set using basic sphere stamping with
91 /// a variable radius. The radius string parameter expects a point attribute
92 /// of type RadiusT to exist.
93 /// @param points the point data grid to rasterize
94 /// @param radius the name of the radius attribute
95 /// @param scale an optional scale to apply to each per point radius
96 /// @param halfband the half band width
97 /// @param transform the target transform for the surface
98 /// @param filter a filter to apply to points
99 /// @param interrupter optional interrupter
100 /// @return The signed distance field.
101 template <typename PointDataGridT,
102  typename RadiusT = float,
103  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
104  typename FilterT = NullFilter,
105  typename InterrupterT = util::NullInterrupter>
106 typename SdfT::Ptr
107 rasterizeSpheres(const PointDataGridT& points,
108  const std::string& radius,
109  const Real scale = 1.0,
110  const Real halfband = LEVEL_SET_HALF_WIDTH,
111  math::Transform::Ptr transform = nullptr,
112  const FilterT& filter = NullFilter(),
113  InterrupterT* interrupter = nullptr);
114 
115 /// @brief Narrow band sphere stamping with a uniform radius and closest point
116 /// attribute transfer.
117 /// @details Rasterizes points into a level set using basic sphere stamping with
118 /// a uniform radius. The radius parameter is given in world space units and
119 /// is applied to every point to generate a fixed surface mask and consequent
120 /// distance values. Every voxel's closest point is used to transfer each
121 /// attribute in the attributes parameter to a new grid of matching topology.
122 /// The destination types of these grids is equal to the ValueConverter result
123 /// of the attribute type applied to the PointDataGridT.
124 /// @note The AttributeTypes template parameter should be a TypeList of the
125 /// required or possible attributes types. i.e. TypeList<int, float, double>.
126 /// A runtime error will be thrown if no equivalent type for a given attribute
127 //// is found in the AttributeTypes TypeList.
128 /// @param points the point data grid to rasterize
129 /// @param radius the world space radius of every point
130 /// @param attributes list of attributes to transfer
131 /// @param halfband the half band width
132 /// @param transform the target transform for the surface
133 /// @param filter a filter to apply to points
134 /// @param interrupter optional interrupter
135 /// @return A vector of grids. The signed distance field is guaranteed to be
136 /// first and at the type specified by SdfT. Successive grids are the closest
137 /// point attribute grids. These grids are guaranteed to have a topology
138 /// and transform equal to the surface.
139 template <typename PointDataGridT,
140  typename AttributeTypes,
141  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
142  typename FilterT = NullFilter,
143  typename InterrupterT = util::NullInterrupter>
145 rasterizeSpheres(const PointDataGridT& points,
146  const Real radius,
147  const std::vector<std::string>& attributes,
148  const Real halfband = LEVEL_SET_HALF_WIDTH,
149  math::Transform::Ptr transform = nullptr,
150  const FilterT& filter = NullFilter(),
151  InterrupterT* interrupter = nullptr);
152 
153 /// @brief Narrow band sphere stamping with a varying radius and closest point
154 /// attribute transfer.
155 /// @details Rasterizes points into a level set using basic sphere stamping with
156 /// a variable radius. The radius string parameter expects a point attribute
157 /// of type RadiusT to exist. Every voxel's closest point is used to transfer
158 /// each attribute in the attributes parameter to a new grid of matching
159 /// topology. The destination types of these grids is equal to the
160 /// ValueConverter result of the attribute type applied to the PointDataGridT.
161 /// @note The AttributeTypes template parameter should be a TypeList of the
162 /// required or possible attributes types. i.e. TypeList<int, float, double>.
163 /// A runtime error will be thrown if no equivalent type for a given attribute
164 //// is found in the AttributeTypes TypeList.
165 /// @param points the point data grid to rasterize
166 /// @param radius the name of the radius attribute
167 /// @param attributes list of attributes to transfer
168 /// @param scale scale to apply to each per point radius
169 /// @param halfband the half band width
170 /// @param transform the target transform for the surface
171 /// @param filter a filter to apply to points
172 /// @param interrupter optional interrupter
173 /// @return A vector of grids. The signed distance field is guaranteed to be
174 /// first and at the type specified by SdfT. Successive grids are the closest
175 /// point attribute grids. These grids are guaranteed to have a topology
176 /// and transform equal to the surface.
177 template <typename PointDataGridT,
178  typename AttributeTypes,
179  typename RadiusT = float,
180  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
181  typename FilterT = NullFilter,
182  typename InterrupterT = util::NullInterrupter>
184 rasterizeSpheres(const PointDataGridT& points,
185  const std::string& radius,
186  const std::vector<std::string>& attributes,
187  const Real scale = 1.0,
188  const Real halfband = LEVEL_SET_HALF_WIDTH,
189  math::Transform::Ptr transform = nullptr,
190  const FilterT& filter = NullFilter(),
191  InterrupterT* interrupter = nullptr);
192 
193 /// @brief Smoothed point distribution based sphere stamping with a uniform radius.
194 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
195 /// stamping with a uniform radius. The radius and search radius parameters
196 /// are given in world space units and are applied to every point to generate
197 /// a fixed surface mask and consequent distance values. The search radius is
198 /// each points points maximum contribution to the target level set. The search
199 /// radius should always have a value equal to or larger than the point radius.
200 /// @warning The width of the exterior half band *may* be smaller than the
201 /// specified half band if the search radius is less than the equivalent
202 /// world space halfband distance.
203 /// @param points the point data grid to rasterize
204 /// @param radius the world space radius of every point
205 /// @param searchRadius the maximum search distance of every point
206 /// @param halfband the half band width
207 /// @param transform the target transform for the surface
208 /// @param filter a filter to apply to points
209 /// @param interrupter optional interrupter
210 /// @return The signed distance field.
211 template <typename PointDataGridT,
212  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
213  typename FilterT = NullFilter,
214  typename InterrupterT = util::NullInterrupter>
215 typename SdfT::Ptr
216 rasterizeSmoothSpheres(const PointDataGridT& points,
217  const Real radius,
218  const Real searchRadius,
219  const Real halfband = LEVEL_SET_HALF_WIDTH,
220  math::Transform::Ptr transform = nullptr,
221  const FilterT& filter = NullFilter(),
222  InterrupterT* interrupter = nullptr);
223 
224 /// @brief Smoothed point distribution based sphere stamping with a varying radius.
225 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
226 /// stamping with a variable radius. The radius string parameter expects a
227 /// point attribute of type RadiusT to exist. The radiusScale parameter is
228 /// multiplier for radius values held on the radius attribute. The searchRadius
229 /// parameter remains a fixed size value which represents each points points
230 /// maximum contribution to the target level set. The radius scale and search
231 /// radius parameters are given in world space units and are applied to every
232 /// point to generate a fixed surface mask and consequent distance values. The
233 /// search radius should always have a value equal to or larger than the point
234 /// radii.
235 /// @warning The width of the exterior half band *may* be smaller than the
236 /// specified half band if the search radius is less than the equivalent
237 /// world space halfband distance.
238 /// @param points the point data grid to rasterize
239 /// @param radius the attribute containing the world space radius
240 /// @param radiusScale the scale applied to every world space radius value
241 /// @param searchRadius the maximum search distance of every point
242 /// @param halfband the half band width
243 /// @param transform the target transform for the surface
244 /// @param filter a filter to apply to points
245 /// @param interrupter optional interrupter
246 /// @return The signed distance field.
247 template <typename PointDataGridT,
248  typename RadiusT = float,
249  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
250  typename FilterT = NullFilter,
251  typename InterrupterT = util::NullInterrupter>
252 typename SdfT::Ptr
253 rasterizeSmoothSpheres(const PointDataGridT& points,
254  const std::string& radius,
255  const Real radiusScale,
256  const Real searchRadius,
257  const Real halfband = LEVEL_SET_HALF_WIDTH,
258  math::Transform::Ptr transform = nullptr,
259  const FilterT& filter = NullFilter(),
260  InterrupterT* interrupter = nullptr);
261 
262 /// @brief Smoothed point distribution based sphere stamping with a uniform
263 /// radius and closest point attribute transfer.
264 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
265 /// stamping with a uniform radius. The radius and search radius parameters
266 /// are given in world space units and are applied to every point to generate
267 /// a fixed surface mask and consequent distance values. The search radius is
268 /// each points points maximum contribution to the target level set. The
269 /// search radius should always be larger than the point radius. Every voxel's
270 /// closest point is used to transfer each attribute in the attributes
271 /// parameter to a new grid of matching topology. The destination types of
272 /// these grids is equal to the ValueConverter result of the attribute type
273 /// applied to the PointDataGridT.
274 /// @note The AttributeTypes template parameter should be a TypeList of the
275 /// required or possible attributes types. i.e. TypeList<int, float, double>.
276 /// A runtime error will be thrown if no equivalent type for a given attribute
277 /// is found in the AttributeTypes TypeList.
278 /// @warning The width of the exterior half band *may* be smaller than the
279 /// specified half band if the search radius is less than the equivalent
280 /// world space halfband distance.
281 /// @param points the point data grid to rasterize
282 /// @param radius the world space radius of every point
283 /// @param searchRadius the maximum search distance of every point
284 /// @param attributes list of attributes to transfer
285 /// @param halfband the half band width
286 /// @param transform the target transform for the surface
287 /// @param filter a filter to apply to points
288 /// @param interrupter optional interrupter
289 /// @return A vector of grids. The signed distance field is guaranteed to be
290 /// first and at the type specified by SdfT. Successive grids are the closest
291 /// point attribute grids. These grids are guaranteed to have a topology
292 /// and transform equal to the surface.
293 template <typename PointDataGridT,
294  typename AttributeTypes,
295  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
296  typename FilterT = NullFilter,
297  typename InterrupterT = util::NullInterrupter>
299 rasterizeSmoothSpheres(const PointDataGridT& points,
300  const Real radius,
301  const Real searchRadius,
302  const std::vector<std::string>& attributes,
303  const Real halfband = LEVEL_SET_HALF_WIDTH,
304  math::Transform::Ptr transform = nullptr,
305  const FilterT& filter = NullFilter(),
306  InterrupterT* interrupter = nullptr);
307 
308 /// @brief Smoothed point distribution based sphere stamping with a varying
309 /// radius and closest point attribute transfer.
310 /// @details Rasterizes points into a level set using [Zhu Bridson 05] sphere
311 /// stamping with a variable radius. The radius string parameter expects a
312 /// point attribute of type RadiusT to exist. The radiusScale parameter is
313 /// multiplier for radius values held on the radius attribute. The searchRadius
314 /// parameter remains a fixed size value which represents each points points
315 /// maximum contribution to the target level set. The radius scale and search
316 /// radius parameters are given in world space units and are applied to every
317 /// point to generate a fixed surface mask and consequent distance values. The
318 /// search radius should always have a value equal to or larger than the point
319 /// radii. Every voxel's closest point is used to transfer each attribute in
320 /// the attributes parameter to a new grid of matching topology. The
321 /// destination types of these grids is equal to the ValueConverter result of
322 /// the attribute type applied to the PointDataGridT.
323 /// @note The AttributeTypes template parameter should be a TypeList of the
324 /// required or possible attributes types. i.e. TypeList<int, float, double>.
325 /// A runtime error will be thrown if no equivalent type for a given attribute
326 //// is found in the AttributeTypes TypeList.
327 /// @warning The width of the exterior half band *may* be smaller than the
328 /// specified half band if the search radius is less than the equivalent
329 /// world space halfband distance.
330 /// @param points the point data grid to rasterize
331 /// @param radius the attribute containing the world space radius
332 /// @param radiusScale the scale applied to every world space radius value
333 /// @param searchRadius the maximum search distance of every point
334 /// @param attributes list of attributes to transfer
335 /// @param halfband the half band width
336 /// @param transform the target transform for the surface
337 /// @param filter a filter to apply to points
338 /// @param interrupter optional interrupter
339 /// @return A vector of grids. The signed distance field is guaranteed to be
340 /// first and at the type specified by SdfT. Successive grids are the closest
341 /// point attribute grids. These grids are guaranteed to have a topology
342 /// and transform equal to the surface.
343 template <typename PointDataGridT,
344  typename AttributeTypes,
345  typename RadiusT = float,
346  typename SdfT = typename PointDataGridT::template ValueConverter<float>::Type,
347  typename FilterT = NullFilter,
348  typename InterrupterT = util::NullInterrupter>
350 rasterizeSmoothSpheres(const PointDataGridT& points,
351  const std::string& radius,
352  const Real radiusScale,
353  const Real searchRadius,
354  const std::vector<std::string>& attributes,
355  const Real halfband = LEVEL_SET_HALF_WIDTH,
356  math::Transform::Ptr transform = nullptr,
357  const FilterT& filter = NullFilter(),
358  InterrupterT* interrupter = nullptr);
359 
360 } // namespace points
361 } // namespace OPENVDB_VERSION_NAME
362 } // namespace openvdb
363 
365 
366 #endif //OPENVDB_POINTS_RASTERIZE_SDF_HAS_BEEN_INCLUDED
Framework methods for rasterizing PointDataGrid data to Trees.
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:508
Defined various multi-threaded utility functions for trees.
static const Real LEVEL_SET_HALF_WIDTH
Definition: Types.h:461
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
MatType scale(const Vec3< typename MatType::value_type > &s)
Return a matrix that scales by s.
Definition: Mat.h:615
Definition: Exceptions.h:13
double Real
Definition: Types.h:60
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
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:121
Functions to perform multi threaded reductions and analysis of arbitrary point attribute types...
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
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:218