VolumeInterface Manual

Table of Contents

• About
• VolumeInterface
• Iterator
• Accessor
• Further Reading

About

A maxon::VolumeInterface is used to store and handle volume data. It is typically obtained from a VolumeObject, see VolumeObject Manual.

VolumeInterface

Volume information can be stored in a file:

• maxon::VolumeInterface::LoadFromFile(): Loads a volume from the given file.
• maxon::VolumeInterface::WriteToFile(): Writes the volume to the given file.
• maxon::VolumeInterface::CreateFromFile(): Static function loading volume data from a *.vdb file.

  // This example loads a grid from the given vdb file
  // and inserts it into the BaseDocument using a VolumeObject.
 
  const maxon::Int    gridIndex = 0;
  const maxon::Volume volume = maxon::VolumeInterface::CreateFromFile(volumeUrl, 1.0, gridIndex) iferr_return;
 
  // create VolumeObject
  VolumeObject* const volumeObj = VolumeObject::Alloc();
  if (volumeObj == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(volumeObj, nullptr, nullptr);
 
  // insert volume
  volumeObj->SetVolume(volume);

The grid settings are accessed with:

• maxon::VolumeInterface::HasGrid(): Returns true if a grid is attached.
• maxon::VolumeInterface::GetGridType(): Returns the grid type (GRIDTYPE).
• maxon::VolumeInterface::GetGridClass(): Returns the grid class (GRIDCLASS).
• maxon::VolumeInterface::SetGridClass(): Sets the grid class.
• maxon::VolumeInterface::GetGridTransform(): Returns the grid transformation matrix.
• maxon::VolumeInterface::SetGridTransform(): Sets the grid transformation matrix.
• maxon::VolumeInterface::GetGridName(): Returns the grid name.
• maxon::VolumeInterface::SetGridName(): Sets the grid name.
• maxon::VolumeInterface::GetWorldBoundingBox(): Returns the bounding box of all active voxels.
• maxon::VolumeInterface::GetActiveVoxelDim(): Returns the active voxel dimensions.
• maxon::VolumeInterface::GetActiveVoxelCount(): Returns the number of active voxels.
• maxon::VolumeInterface::GetBackground(): Returns the background value of the grid.
• maxon::VolumeInterface::GetMemUsage(): Returns the size of the memory used.
• maxon::VolumeInterface::GetMinMaxValues(): Returns the Min and Max values of the volume.

  // This example prints some data on the volumes grid.
 
  // get volume
  const maxon::Volume volume = volumeObject->GetVolume();
 
  // check grid
  if (volume.HasGrid())
  {
    const maxon::String gridName  = volume.GetGridName();
    const GRIDCLASS     gridClass = volume.GetGridClass();
 
    DiagnosticOutput("@ (@)", gridName, gridClass);
  }

Iterator

The data stored in a volume is accessed with the maxon::GridIteratorInterface iterator:

• maxon::GridIteratorInterface::Init(): Initializes the iterator with the given volume.
• maxon::GridIteratorInterface::GetVolume(): Returns the referenced volume.
• maxon::GridIteratorInterface::GetValue(): Returns the current value.
• maxon::GridIteratorInterface::GetCoords(): Returns the current position.
• maxon::GridIteratorInterface::IsNotAtEnd(): Returns true if the iterator is not yet at its end.
• maxon::GridIteratorInterface::StepNext(): Steps to the next active voxel.
• maxon::GridIteratorInterface::GetVoxelLevel(): Returns the tree level of the current voxel.

  // This example iterates over the active cells of the given volume.
 
  // get volume
  const maxon::Volume volume = volumeObject->GetVolume();
 
  // get matrix
  const maxon::Matrix transform = volume.GetGridTransform();
 
  // create iterator
  maxon::GridIteratorRef<maxon::Float32, maxon::ITERATORTYPE::ON> iterator = maxon::GridIteratorRef<maxon::Float32, maxon::ITERATORTYPE::ON>::Create() iferr_return;
  iterator.Init(volume) iferr_return;
 
  // iterate
  for (; iterator.IsNotAtEnd(); iterator.StepNext())
  {
    // get value
    const Float32 value = iterator.GetValue();
    // get coordinates
    const maxon::IntVector32 coord = iterator.GetCoords();
 
    DiagnosticOutput("@: @", coord, value);
 
    // get world space coordinates
    Vector pos;
    pos.x = coord.x;
    pos.y = coord.y;
    pos.z = coord.z;
    pos = transform * pos;
 
    DiagnosticOutput("World space coordinates: @", pos);
  }

Accessor

The grid accessor can be used to both retrieve and set the volume data:

• maxon::GridAccessorInterface::Create(): Creates a new instance.
• maxon::GridAccessorInterface::Init(): Initializes the accessor to read the given volume.
• maxon::GridAccessorInterface::InitWithWriteAccess(): Initializes the accessor to read and write the given volume.

Volume data is accessed with:

• maxon::GridAccessorInterface::GetValue(): Returns the value for the given coordinates or position.
• maxon::GridAccessorInterface::GetCoords(): Returns the coordinates for the given position.
• maxon::GridAccessorInterface::SetSampler(): Sets the sample (see maxon::VOLUMESAMPLER).
• maxon::GridAccessorInterface::SetValue(): Sets the value at the given coordinates.
• maxon::GridAccessorInterface::SetValueOnly(): Sets the value at the given coordinates without activating the voxel.
• maxon::GridAccessorInterface::SetActiveState(): Sets the active state of the voxel at the given coordinates.
• maxon::GridAccessorInterface::GetActiveState(): Returns the active state of the voxel at the given coordinates.

  // This example creates a new VolumeObject and a new volume.
  // It uses the GridAccessor to set values of the volume.
 
  // create VolumeObject
  VolumeObject* const volumeObj = VolumeObject::Alloc();
  if (volumeObj == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(volumeObj, nullptr, nullptr);
 
  // create volume
  maxon::Volume volume = maxon::VolumeToolsInterface::CreateNewFloat32Volume(0.0) iferr_return;
 
  volume.SetGridClass(GRIDCLASS::FOG) iferr_return;
  volume.SetGridName("Example Grid"_s);
  const Vector        scaleFactor { 10.0 };
  const maxon::Matrix scaleMatrix = MatrixScale(scaleFactor);
  volume.SetGridTransform(scaleMatrix) iferr_return;
 
  // create accessor
  maxon::GridAccessorRef<Float32> access = maxon::GridAccessorRef<Float32>::Create() iferr_return;
  access.InitWithWriteAccess(volume, maxon::VOLUMESAMPLER::NEAREST) iferr_return;
 
  // set values in the shape of a helix
 
  Float       offset = 0.0;
  const Float scale  = 100.0;
  const Float scaleY = 10.0;
 
  while (offset < 50.0)
  {
    Float64 sin;
    Float64 cos;
    maxon::SinCos(offset, sin, cos);
 
    maxon::IntVector32 pos;
    pos.x = maxon::Int32(sin * scale);
    pos.z = maxon::Int32(cos * scale);
    pos.y = maxon::Int32(offset * scaleY);
 
    // set value
    access.SetValue(pos, 10.0) iferr_return;
 
    offset = offset + 0.01;
  }
 
  // insert volume
  volumeObj->SetVolume(volume);

Further Reading

• Volumes Overview
• VolumeObject Manual