OpenVDB: ConvexVoxelizer< GridType, Derived, InterruptType > Class Template Reference

OpenVDB 13.0.0

Loading...
Searching...
No Matches
ConvexVoxelizer< GridType, Derived, InterruptType > Class Template Reference

Base class used to generate a grid of type `GridType` containing a narrow-band level set representation of a convex region. More...

`#include <openvdb/tools/impl/ConvexVoxelizer.h>`

## Classes
class | XYRangeData
| Class that stores endpoints of a y range for each x value within a specified range and step size. More...

## Public Member Functions
| ConvexVoxelizer (GridPtr &grid, const bool &threaded=false, InterruptType *interrupter=nullptr)
| Constructor.
virtual | ~ConvexVoxelizer ()=default
ValueT | voxelSize () const
| Return the voxel size of the grid.
ValueT | halfWidth () const
| Return the half width of the narrow-band level set.

## Protected Types
using | ValueT = typename GridType::ValueType
using | Vec3T = math::Vec3<ValueT>
using | Vec2T = math::Vec2<ValueT>

## Protected Member Functions
void | iterate ()
| The function the derived class calls to create the level set, working in index space other than setting signed distance values.
void | setXYRangeData (const Index &)
| Determines the x bounds in index space of the convex region dilated by the half width. For each x value in index space, the y range in index space of the dilated region is computed. This function should store the data in `mXYData`.
bool | tileCanFit (const Index &) const
| Checks if the tile of a given dimension can possibly fit within the region.
ValueT | signedDistance (const Vec3T &) const
| Computes the signed distance from a point to the convex region in index space.
ValueT | tilePointSignedDistance (const Vec3T &p) const
| Computes the signed distance for tiles in index space, considering the center of the tile. This method is optional to override and defaults to `signedDistance`.

## Static Protected Member Functions
static ValueT | tileCeil (const ValueT &x, const ValueT &step)
| Rounds an input scalar up to the nearest valid ordinate of tile of a specified size.
template<typename T>
static ValueT | tileCeil (const ValueT &x, const T &step)
| Rounds an input scalar up to the nearest valid ordinate of tile of a specified size.
static ValueT | tileFloor (const ValueT &x, const ValueT &step)
| Rounds an input scalar down to the nearest valid ordinate of tile of a specified size.
template<typename T>
static ValueT | tileFloor (const ValueT &x, const T &step)
| Rounds an input scalar down to the nearest valid ordinate of tile of a specified size.
static ValueT | circleBottom (const ValueT &x0, const ValueT &y0, const ValueT &r, const ValueT &x)
| Computes the bottom y-coordinate of a circle at a given x position.
static ValueT | circleTop (const ValueT &x0, const ValueT &y0, const ValueT &r, const ValueT &x)
| Computes the top y-coordinate of a circle at a given x position.
static ValueT | sphereBottom (const ValueT &x0, const ValueT &y0, const ValueT &z0, const ValueT &r, const ValueT &x, const ValueT &y)
| Computes the bottom z-coordinate of a sphere at a given (x, y) position.
static ValueT | sphereTop (const ValueT &x0, const ValueT &y0, const ValueT &z0, const ValueT &r, const ValueT &x, const ValueT &y)
| Computes the top z-coordinate of a sphere at a given (x, y) position.

## Protected Attributes
std::function< bool(ValueT &, ValueT &, const ValueT &, const ValueT &)> | bottomTop
| Find where a vertical infinite line intersects a convex region dilated by the half width.
XYRangeData | mXYData

## Detailed Description

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>
class openvdb::v13_0::tools::ConvexVoxelizer< GridType, Derived, InterruptType >

Base class used to generate a grid of type `GridType` containing a narrow-band level set representation of a convex region.

Note
  `GridType::ValueType` must be a floating-point scalar.
  `Derived` is the derived class that implements the base class (curiously recurring template pattern).

Example of derived level set sphere class
  template <typename GridType>
  class SphereVoxelizer : public ConvexVoxelizer<GridType, SphereVoxelizer<GridType>>
  {
  using GridPtr = typename GridType::Ptr;
  using BaseT = ConvexVoxelizer<GridType, SphereVoxelizer<GridType>>;
  using BaseT::mXYData;
  using BaseT::tileCeil;
  using ValueT = typename BaseT::ValueT;
  using Vec3T = typename BaseT::Vec3T;
  public:
  friend class ConvexVoxelizer<GridType, SphereVoxelizer<GridType>>;
  SphereVoxelizer(GridPtr& grid, const bool& threaded = true)
  : BaseT(grid, threaded)
  {
  }
  template <typename ScalarT>
  void
  operator()(const math::Vec3<ScalarT>& pt, const ScalarT& r)
  {
  static_assert(std::is_floating_point<ScalarT>::value);
  if (r <= 0)
  return;
  initialize<ScalarT>(pt, r);
  BaseT::iterate();
  }
  private:
  inline ValueT
  signedDistance(const Vec3T& p) const
  {
  return (p - mPt).length() - mRad;
  }
  inline void
  setXYRangeData(const Index& step = 1)
  {
  mXYData.reset(mX - mORad, mX + mORad, step);
  for (ValueT x = tileCeil(mX - mORad, step); x <= mX + mORad; x += step)
  mXYData.expandYRange(x, BaseT::circleBottom(mX, mY, mORad, x),
  BaseT::circleTop(mX, mY, mORad, x));
  }
  std::function<bool(ValueT&, ValueT&, const ValueT&, const ValueT&)> sphereBottomTop =
  [this](ValueT& zb, ValueT& zt, const ValueT& x, const ValueT& y)
  {
  zb = BaseT::sphereBottom(mX, mY, mZ, mORad, x, y);
  zt = BaseT::sphereTop(mX, mY, mZ, mORad, x, y);
  return std::isfinite(zb) && std::isfinite(zt);
  };
  template <typename ScalarT>
  inline void
  initialize(const math::Vec3<ScalarT>& pt, const ScalarT& r)
  {
  const ValueT vx = BaseT::voxelSize(),
  hw = BaseT::halfWidth();
  // sphere data in index space
  mPt = Vec3T(pt)/vx;
  mRad = ValueT(r)/vx;
  mX = mPt.x(); mY = mPt.y(); mZ = mPt.z();
  // padded radius used to populate the outer halfwidth of the sdf
  mORad = mRad + hw;
  BaseT::bottomTop = sphereBottomTop;
  }
  Vec3T mPt;
  ValueT mRad, mORad, mX, mY, mZ;
  };
  // usage:
  // initialize level set grid with voxel size 0.1 and half width 3.0
  FloatGrid::Ptr grid = createLevelSet<GridT>(0.1f, 3.0f);
  // populate grid with a sphere centered at (0, 1, 2) and radius 5
  SphereVoxelizer<FloatGrid> op(grid);
  op(Vec3s(0.0f, 1.0f, 2.0f), 5.0f);
  openvdb::v13_0::Grid< FloatTree >::Ptr
  SharedPtr< Grid > Ptr
  Definition Grid.h:573
  openvdb::v13_0::math::Vec3
  Definition Vec3.h:25
  openvdb::v13_0::math::Vec3::x
  T & x()
  Reference to the component, e.g. v.x() = 4.5f;.
  Definition Vec3.h:86
  openvdb::v13_0::tools::ConvexVoxelizer::XYRangeData::reset
  void reset(const ValueT &xmin, const ValueT &xmax, const Index &step=1)
  Resets the x range to span a given interval with a specific step size. This initializes all y ranges ...
  Definition ConvexVoxelizer.h:577
  openvdb::v13_0::tools::ConvexVoxelizer::XYRangeData::expandYRange
  void expandYRange(const ValueT &x, const ValueT &ymin, const ValueT &ymax)
  Expands the y range for a given x value by updating the minimum and maximum y values if the new ones ...
  Definition ConvexVoxelizer.h:470
  openvdb::v13_0::tools::ConvexVoxelizer::tileCeil
  static ValueT tileCeil(const ValueT &x, const ValueT &step)
  Rounds an input scalar up to the nearest valid ordinate of tile of a specified size.
  Definition ConvexVoxelizer.h:327
  openvdb::v13_0::tools::ConvexVoxelizer::Vec3T
  math::Vec3< ValueT > Vec3T
  Definition ConvexVoxelizer.h:185
  openvdb::v13_0::tools::ConvexVoxelizer::ValueT
  typename GridType::ValueType ValueT
  Definition ConvexVoxelizer.h:184
  openvdb::v13_0::tools::ConvexVoxelizer::setXYRangeData
  void setXYRangeData(const Index &)
  Determines the x bounds in index space of the convex region dilated by the half width....
  Definition ConvexVoxelizer.h:272
  openvdb::v13_0::tools::ConvexVoxelizer::mXYData
  XYRangeData mXYData
  Definition ConvexVoxelizer.h:780
  openvdb::v13_0::tools::ConvexVoxelizer::ConvexVoxelizer
  ConvexVoxelizer(GridPtr &grid, const bool &threaded=false, InterruptType *interrupter=nullptr)
  Constructor.
  Definition ConvexVoxelizer.h:201
  openvdb::v13_0::tools::ConvexVoxelizer::signedDistance
  ValueT signedDistance(const Vec3T &) const
  Computes the signed distance from a point to the convex region in index space.
  Definition ConvexVoxelizer.h:290
  openvdb::v13_0::math::Vec3s
  Vec3< float > Vec3s
  Definition Vec3.h:664
  openvdb::v13_0::tools::bool
  OutGridT const XformOp bool bool
  Definition ValueTransformer.h:610
  openvdb::v13_0::tools::op
  OutGridT XformOp & op
  Definition ValueTransformer.h:140
  openvdb::v13_0::tools::threaded
  OutGridT XformOp bool threaded
  Definition ValueTransformer.h:140
  openvdb::v13_0::Index
  Index32 Index
  Definition Types.h:34
  openvdb::v13_0::initialize
  OPENVDB_IMPORT void initialize()
  Global registration of native Grid, Transform, Metadata and Point attribute types....
  openvdb::v13_0::createLevelSet
  GridType::Ptr createLevelSet(Real voxelSize=1.0, Real halfWidth=LEVEL_SET_HALF_WIDTH)
  Create a new grid of type GridType classified as a "Level Set", i.e., a narrow-band level set.
  Definition Grid.h:1772

## Member Typedef Documentation

## ◆ ValueT

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

using ValueT = typename GridType::ValueType
| protected

## ◆ Vec2T

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

using Vec2T = math::Vec2<ValueT>
| protected

## ◆ Vec3T

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

using Vec3T = math::Vec3<ValueT>
| protected

## Constructor & Destructor Documentation

## ◆ ConvexVoxelizer()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ConvexVoxelizer | ( | GridPtr & | grid,
|  | const bool & | threaded = false,
|  | InterruptType * | interrupter = nullptr )
| inline

Constructor.

Parameters

  grid | scalar grid to populate the level set in
  threaded | center of the sphere in world units
  interrupter | pointer to optional interrupter. Use template argument util::NullInterrupter if no interruption is desired.

Note
  The voxel size and half width are determined from the input grid, meaning the voxel size and background value need to be set prior to voxelization

## ◆ ~ConvexVoxelizer()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

virtual ~ConvexVoxelizer | ( |  | ) |
| virtualdefault

## Member Function Documentation

## ◆ circleBottom()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT circleBottom | ( | const ValueT & | x0,
|  | const ValueT & | y0,
|  | const ValueT & | r,
|  | const ValueT & | x )
| inlinestaticprotected

Computes the bottom y-coordinate of a circle at a given x position.

Parameters

  x0 | X-coordinate of the circle's center.
  y0 | Y-coordinate of the circle's center.
  r | Radius of the circle.
  x | X-coordinate for which to compute the bottom y-coordinate.

Returns
  The y-coordinate at the bottom of the circle for the given x position.

## ◆ circleTop()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT circleTop | ( | const ValueT & | x0,
|  | const ValueT & | y0,
|  | const ValueT & | r,
|  | const ValueT & | x )
| inlinestaticprotected

Computes the top y-coordinate of a circle at a given x position.

Parameters

  x0 | X-coordinate of the circle's center.
  y0 | Y-coordinate of the circle's center.
  r | Radius of the circle.
  x | X-coordinate for which to compute the top y-coordinate.

Returns
  The y-coordinate at the top of the circle for the given x position.

## ◆ halfWidth()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT halfWidth | ( |  | ) | const
| inline

Return the half width of the narrow-band level set.

## ◆ iterate()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

void iterate | ( |  | ) |
| inlineprotected

The function the derived class calls to create the level set, working in index space other than setting signed distance values.

Note
  This function handles both parallel and serial iterations. If running in serial mode, it flood fills the tile topology immediately; otherwise, it avoids duplicating nontrivial tree topology over multiple threads. This method also checks for background tiles that are too thin to fit and delegates accordingly.

## ◆ setXYRangeData()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

void setXYRangeData | ( | const Index & |  | ) |
| inlineprotected

Determines the x bounds in index space of the convex region dilated by the half width. For each x value in index space, the y range in index space of the dilated region is computed. This function should store the data in `mXYData`.

Parameters

  step | The step size for setting the XY range data, defaults to 1.

Note
  Function to be implemented by derived classes to set XY range data. This function is called at most 4 times within `iterate()`.

## ◆ signedDistance()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT signedDistance | ( | const Vec3T & |  | ) | const
| inlineprotected

Computes the signed distance from a point to the convex region in index space.

Parameters

  p | The point in 3D space for which to compute the signed distance.

## ◆ sphereBottom()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT sphereBottom | ( | const ValueT & | x0,
|  | const ValueT & | y0,
|  | const ValueT & | z0,
|  | const ValueT & | r,
|  | const ValueT & | x,
|  | const ValueT & | y )
| inlinestaticprotected

Computes the bottom z-coordinate of a sphere at a given (x, y) position.

Parameters

  x0 | X-coordinate of the sphere's center.
  y0 | Y-coordinate of the sphere's center.
  z0 | Z-coordinate of the sphere's center.
  r | Radius of the sphere.
  x | X-coordinate for which to compute the bottom z-coordinate.
  y | Y-coordinate for which to compute the bottom z-coordinate.

Returns
  The z-coordinate at the bottom of the sphere for the given (x, y) position.

## ◆ sphereTop()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT sphereTop | ( | const ValueT & | x0,
|  | const ValueT & | y0,
|  | const ValueT & | z0,
|  | const ValueT & | r,
|  | const ValueT & | x,
|  | const ValueT & | y )
| inlinestaticprotected

Computes the top z-coordinate of a sphere at a given (x, y) position.

Parameters

  x0 | X-coordinate of the sphere's center.
  y0 | Y-coordinate of the sphere's center.
  z0 | Z-coordinate of the sphere's center.
  r | Radius of the sphere.
  x | X-coordinate for which to compute the top z-coordinate.
  y | Y-coordinate for which to compute the top z-coordinate.

Returns
  The z-coordinate at the top of the sphere for the given (x, y) position.

## ◆ tileCanFit()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

bool tileCanFit | ( | const Index & |  | ) | const
| inlineprotected

Checks if the tile of a given dimension can possibly fit within the region.

The derived class does not need to implement it if the default behavior is acceptable, which assumes a tile can always possibly fit.

Parameters

  dim | The dimension of the tile in which to check if the tile fits.

Note
  This is meant as a short-circuting method: if a tile of a given dimension can't fit then `iterate` will not try to populate the level set with background tiles of this dimension.

Returns
  true if the tile can possibly fit; otherwise false.

## ◆ tileCeil() [1/2]

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>
template<typename T>

ValueT tileCeil | ( | const ValueT & | x,
|  | const T & | step )
| inlinestaticprotected

Rounds an input scalar up to the nearest valid ordinate of tile of a specified size.

Template Parameters

  T | Any integral type (int, unsigned int, size_t, etc.)

Parameters

  x | Input value.
  step | Tile step size.

Returns
  The ceiling of the value based on the tile size.

## ◆ tileCeil() [2/2]

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT tileCeil | ( | const ValueT & | x,
|  | const ValueT & | step )
| inlinestaticprotected

Rounds an input scalar up to the nearest valid ordinate of tile of a specified size.

Parameters

  x | Input value.
  step | Tile step size.

Returns
  The ceiling of the value based on the tile size.

## ◆ tileFloor() [1/2]

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>
template<typename T>

ValueT tileFloor | ( | const ValueT & | x,
|  | const T & | step )
| inlinestaticprotected

Rounds an input scalar down to the nearest valid ordinate of tile of a specified size.

Template Parameters

  T | Any integral type (int, unsigned int, size_t, etc.)

Parameters

  x | Input value.
  step | Tile step size.

Returns
  The ceiling of the value based on the tile size.

## ◆ tileFloor() [2/2]

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT tileFloor | ( | const ValueT & | x,
|  | const ValueT & | step )
| inlinestaticprotected

Rounds an input scalar down to the nearest valid ordinate of tile of a specified size.

Parameters

  x | Input value.
  step | Tile step size.

Returns
  The ceiling of the value based on the tile size.

## ◆ tilePointSignedDistance()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT tilePointSignedDistance | ( | const Vec3T & | p | ) | const
| inlineprotected

Computes the signed distance for tiles in index space, considering the center of the tile. This method is optional to override and defaults to `signedDistance`.

Parameters

  p | The point at the center of the tile in 3D space.

Note
  This can be useful for cases that build objects from multiple primitives, e.g. dilated mesh is built by constructing and unioning open prisms and open tube wedges. A tile might not fully fit in an open prism but might fit in the union of a prism and wedge, and so in this case it might make sense to use the sdf for an offset triangle on tiles during the open prism scan.

## ◆ voxelSize()

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

ValueT voxelSize | ( |  | ) | const
| inline

Return the voxel size of the grid.

## Member Data Documentation

## ◆ bottomTop

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

std::function<bool(ValueT&, ValueT&, const ValueT&, const ValueT&)> bottomTop
| protected

Initial value:
=
[](ValueT&, ValueT&, const ValueT&, const ValueT&) { return false; }

Find where a vertical infinite line intersects a convex region dilated by the half width.

Parameters

  [out] | zb | Reference to the z ordinate where the bottom intersection occurs.
  [out] | zt | Reference to the z ordinate where the top intersection occurs.
  [in] | x | The x ordinate of the infinite line.
  [in] | y | The y ordinate of the infinite line.

Returns
  true if an intersection occurs; otherwise false.

Note
  The derived class can override this lambda to implement different behavior for degenerate cases.

## ◆ mXYData

template<typename GridType, typename Derived, typename InterruptType = util::NullInterrupter>

XYRangeData mXYData
| protected