Volume Tools Manual

Table of Contents

• About
• Commands
• Tools
• Further Reading

About

Volumes can be created and edited with specific commands and functions provided in the maxon::VolumeToolsInterface.

Commands

These commands can be used to handle volume data (see Commands Manual):

• maxon::CommandClasses::VOLUMETOMESH : Converts a VolumeObject into a PolygonObject. See VOLUMETOMESHSETTINGS.
• maxon::CommandClasses::MESHTOVOLUME : Converts a PolygonObject into a VolumeObject LevelSet. See MESHTOVOLUMESETTINGS.
• maxon::CommandClasses::VOLUMEBOOLE : Performs a boolean operation on VolumeObjects (SDF). See BOOLESETTINGS, BOOLTYPE.
• maxon::CommandClasses::MIX : Performs a mix operation on Fog VolumeObjects (Fog). See MIXSETTINGS. ::MIXTYPE.
• maxon::CommandClasses::PARTICLESTOVOLUME : Converts Particle Objects and TP groups to A VolumeObject LevelSet. See PARTICLESTOVOLUMESETTINGS.
• maxon::CommandClasses::SPLINETOVOLUME : Converts Spline Objects to A VolumeObject LevelSet. See SPLINETOVOLUMESETTINGS.
• maxon::CommandClasses::FILTER : FilterSettings a float grid VolumeObject. See FILTERSETTINGS.
• maxon::CommandClasses::SDFFILTER : Filters a float grid SDF VolumeObject. See SDFFILTERSETTINGS.
• maxon::CommandClasses::SDFTOFOG : Converts a SDF Volume to a Fog Volume. See SDFTOFOGSETTINGS.
• maxon::CommandClasses::FOGTOSDF : Converts a Fog Volume to a SDF Volume. See FOGTOSDFSETTINGS.
• maxon::CommandClasses::RESAMPLE : Resamples a Volume to a new grid size. See RESAMPLESETTINGS, RESAMPLEINTERPOLATIONTYPE.
• maxon::CommandClasses::FIELDTOVOLUME : Converts a Field to a Fog Volume. See FIELDTOVOLUMESETTINGS.
• maxon::CommandClasses::CREATESPHEREVOLUME : Creates a sphere volume. See CREATESPHEREVOLUMESETTINGS.
• maxon::CommandClasses::CREATEPLATONICVOLUME : Creates a platonic volume. See CREATEPLATONICVOLUMESETTINGS.

The maxon::VolumeCommandData structure has these members:

• maxon::VolumeCommandData::op
• maxon::VolumeCommandData::reference
• maxon::VolumeCommandData::doc
• maxon::VolumeCommandData::bt
• maxon::VolumeCommandData::masks
• maxon::VolumeCommandData::result
• maxon::VolumeCommandData::splineData
• maxon::VolumeCommandData::fieldMask
• maxon::VolumeCommandData::targetGridMatrix

  // This example performs multiple commands to turn the
  // given polygon objects into volumes, to perform a
  // boolean operation on these volumes and to create
  // a polygon hull for the result volume.
 
  VolumeObject* volumeObjectA = nullptr;
  VolumeObject* volumeObjectB = nullptr;
  VolumeObject* resultVolume  = nullptr;
 
  MAXON_SCOPE
  {
    // make volume objects
 
    maxon::LegacyCommandDataRef context = maxon::LegacyCommandDataClasses::VOLUMEDATA().Create() iferr_return;
 
    maxon::BaseArray<BaseObject*> sourceObjects;
    sourceObjects.Append(polyObjectA) iferr_return;
    sourceObjects.Append(polyObjectB) iferr_return;
 
    maxon::VolumeCommandData data;
    data.op = &sourceObjects;
    const maxon::Int dataIndex = 0;
 
    context.Set(MESHTOVOLUMESETTINGS::GRIDSIZE, 10.0) iferr_return;
    context.SetLegacyData<maxon::VolumeCommandData>(data, dataIndex) iferr_return;
 
    const auto command = maxon::CommandClasses::MESHTOVOLUME();
    const maxon::COMMANDRESULT res = context.Invoke(command, false) iferr_return;
    if (res != maxon::COMMANDRESULT::OK)
      return maxon::OK;
 
    const maxon::VolumeCommandData& result = context.GetLegacyData<maxon::VolumeCommandData>(dataIndex) iferr_return;
 
    if (result.result.GetCount() == 2)
    {
      volumeObjectA = static_cast<VolumeObject*>(result.result[0]);
      volumeObjectB = static_cast<VolumeObject*>(result.result[1]);
    }
  }
 
  MAXON_SCOPE
  {
    // perform bool operation
 
    maxon::LegacyCommandDataRef context = maxon::LegacyCommandDataClasses::VOLUMEDATA().Create() iferr_return;
 
    maxon::BaseArray<BaseObject*> sourceObjects;
    sourceObjects.Append(volumeObjectA) iferr_return;
    sourceObjects.Append(volumeObjectB) iferr_return;
 
    maxon::VolumeCommandData data;
    data.op = &sourceObjects;
    const maxon::Int dataIndex = 0;
    // 1 equals BOOLTYPE::DIFF
    context.Set(BOOLESETTINGS::BOOLETYPE, 1) iferr_return;
    context.SetLegacyData<maxon::VolumeCommandData>(data, dataIndex) iferr_return;
 
    const auto command = maxon::CommandClasses::BOOLE();
    const maxon::COMMANDRESULT res = context.Invoke(command, false) iferr_return;
    if (res != maxon::COMMANDRESULT::OK)
      return maxon::OK;
 
    const maxon::VolumeCommandData& result = context.GetLegacyData<maxon::VolumeCommandData>(dataIndex) iferr_return;
 
    if (result.result.GetCount() == 1)
    {
      resultVolume = static_cast<VolumeObject*>(result.result[0]);
    }
  }
 
  MAXON_SCOPE
  {
    // create mesh
 
    maxon::LegacyCommandDataRef context = maxon::LegacyCommandDataClasses::VOLUMEDATA().Create() iferr_return;
 
    maxon::BaseArray<BaseObject*> sourceObjects;
    sourceObjects.Append(resultVolume) iferr_return;
 
    maxon::VolumeCommandData data;
    data.op = &sourceObjects;
    const maxon::Int dataIndex = 0;
    context.SetLegacyData<maxon::VolumeCommandData>(data, dataIndex) iferr_return;
 
    const auto command = maxon::CommandClasses::VOLUMETOMESH();
    const maxon::COMMANDRESULT res = context.Invoke(command, false) iferr_return;
    if (res != maxon::COMMANDRESULT::OK)
      return maxon::OK;
 
    const maxon::VolumeCommandData& result = context.GetLegacyData<maxon::VolumeCommandData>(dataIndex) iferr_return;
 
    if (result.result.GetCount() == 1)
    {
      BaseObject* const object = result.result[0];
      doc->InsertObject(object, nullptr, nullptr);
    }
  }
 
  // free data
  VolumeObject::Free(resultVolume);
  VolumeObject::Free(volumeObjectA);
  VolumeObject::Free(volumeObjectB);

Tools

The maxon::VolumeToolsInterface provides multiple functions to handle volumes.

Load volumes from files:

• maxon::VolumeToolsInterface::LoadVDBFile(): Loads the volumes from the given file.
• maxon::VolumeToolsInterface::LoadGridIntoVolume(): Loads the grid from the file into the given volume.
• maxon::VolumeToolsInterface::LoadAllGridsIntoVolumes(): Loads all grids from the file.
• maxon::VolumeToolsInterface::GetGridNamesFromFile(): Returns an array of grid names from the given file.
• maxon::VolumeToolsInterface::GetMetaDataFromFile(): Returns metadata from the given vdb file.
• maxon::VolumeToolsInterface::SaveVDBFile(): Saves the volumes to the given file.

See also maxon::VolumeInterface::CreateFromFile() (VolumeInterface Manual).

Volume operations:

• maxon::VolumeToolsInterface::BoolVolumes(): Returns the result of the boolean operation of the two given volumes. See BOOLTYPE.
• maxon::VolumeToolsInterface::MixVolumes(): Returns the result of mixing the two given volumes. See ::MIXTYPE.
• maxon::VolumeToolsInterface::NormalizeVectorVolume(): Returns the normalized vector volume from the given vector volume.
• maxon::VolumeToolsInterface::ApplySDFFilterToVolume(): Returns the filtered volume for the given filter settings. See maxon::SDFFilterSettings.
• maxon::VolumeToolsInterface::ApplyFilterToVolume(): Returns the filtered volume for the given filter settings. See maxon::FilterSettings.
• maxon::VolumeToolsInterface::RotateVectorVolume(): Returns the rotated vector volume.
• maxon::VolumeToolsInterface::MixVectorVolumes(): Returns the result of mixing the given two vector volumes.
• maxon::VolumeToolsInterface::BlendVolumes(): Returns the result of blending the two given volumes.

Volume creation:

• maxon::VolumeToolsInterface::CreateNewFloat32Volume(): Returns a new maxon::Float32 volume.
• maxon::VolumeToolsInterface::CreateNewVector32Volume(): Returns a new maxon::Vector32 volume.
• maxon::VolumeToolsInterface::CreateCurlVolume(): Returns a volume representing the curl of a vector volume.
• maxon::VolumeToolsInterface::CreateMeanCurvatureVolume(): Returns the curvature volume from the given numeric volume.
• maxon::VolumeToolsInterface::MeshToVolume(): Returns the volume for the given PolygonObject.
• maxon::VolumeToolsInterface::PointsToVolume(): Returns the volume for the given points.
• maxon::VolumeToolsInterface::CreateGradientVolume(): Returns a gradient volume from the given volume.
• maxon::VolumeToolsInterface::CreateSphereVolume(): Returns a spherical SDF volume.
• maxon::VolumeToolsInterface::CreatePlatonicVolume(): Returns a SDF volume of a platonic shape.
• maxon::VolumeToolsInterface::ConvertFieldsToVolume(): Returns the volume for the given field. See maxon::FieldSampleData.
• maxon::VolumeToolsInterface::ConvertFieldsToVectorVolume(): Returns a vector volume created from the given field object or field list (see MoGraph Overview).
• maxon::VolumeToolsInterface::ConvertVectorToFog(): Returns a fog volume based on the given vector volume.
• maxon::VolumeToolsInterface::CreateMaskFromField(): Returns a volume mask from the given field. See maxon::FieldSampleData.

Volume conversion:

• maxon::VolumeToolsInterface::VolumeToMesh(): Returns the PolygonObject surface for the given volume.
• maxon::VolumeToolsInterface::ResampleVolume(): Returns the resampled volume.
• maxon::VolumeToolsInterface::ConvertSDFToFog(): Returns the fog volume for the given SDF volume.
• maxon::VolumeToolsInterface::ConvertFogToSDF(): Returns the SDF volume for the given fog volume.

  // This example uses multiple tools to turn the
  // given polygon objects into volumes, to perform a
  // boolean operation on these volumes and to create
  // a polygon hull for the result volume.
 
  // lambda funtion to convert the given PolygonObject to a VolumeRef
  auto PolyToVolume = [](PolygonObject* const poly) -> maxon::Result<maxon::Volume>
                      {
                        iferr_scope;
 
                        // check polygon object data
 
                        const Vector*   const points = poly->GetPointR();
                        const CPolygon* const polys  = poly->GetPolygonR();
 
                        const maxon::Bool noPoints = points == nullptr;
                        const maxon::Bool noPolys  = polys == nullptr;
                        if (noPoints || noPolys)
                          return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
                        // get polygon object data
 
                        const Int32  pointCount = poly->GetPointCount();
                        const Int32  polyCount  = poly->GetPolygonCount();
                        const Matrix objectMatrix = poly->GetMg();
 
 
                        const maxon::COLLECTION_RESIZE_FLAGS flags = maxon::COLLECTION_RESIZE_FLAGS::ON_GROW_UNINITIALIZED;
 
                        // point array
                        maxon::BaseArray<maxon::Vector> volPoints;
                        volPoints.Resize(pointCount, flags) iferr_return;
 
                        // copy point data
                        for (Int32 pointIndex = 0; pointIndex < pointCount; ++pointIndex)
                          volPoints[pointIndex] = objectMatrix * points[pointIndex];
 
                        // polygon array
                        maxon::BaseArray<maxon::VolumeConversionPolygon> volPolys;
                        volPolys.Resize(polyCount, flags) iferr_return;
 
                        // copy polygon data
                        for (Int32 polyIndex = 0; polyIndex < polyCount; polyIndex++)
                        {
                          volPolys[polyIndex] = *reinterpret_cast<const maxon::VolumeConversionPolygon*>(&polys[polyIndex]);
 
                          if (polys[polyIndex].IsTriangle())
                            volPolys[polyIndex].SetTriangle();
                        }
 
                        const maxon::ThreadInterface* const thread = maxon::ThreadRef::GetCurrentThread().GetPointer();
                        if (thread == nullptr)
                          return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
                        const maxon::ThreadRef threadRef = const_cast<maxon::ThreadInterface*>(thread);
                        return maxon::VolumeToolsInterface::MeshToVolume(volPoints, volPolys, objectMatrix, 10.0, 10, 10, threadRef);
                      };
 
  // convert polygon objects to volumes
 
  const maxon::Volume volumeA = PolyToVolume(polyObjectA) iferr_return;
  const maxon::Volume volumeB = PolyToVolume(polyObjectB) iferr_return;
 
  // perform bool
  const maxon::Volume resultVolume = maxon::VolumeToolsInterface::BoolVolumes(volumeA, volumeB, BOOLTYPE::DIFF) iferr_return;
 
  // result to mesh
  PolygonObject* const mesh = maxon::VolumeToolsInterface::VolumeToMesh(resultVolume, 10.0, 10.0) iferr_return;
  if (mesh == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(mesh, nullptr, nullptr);

  // This example creates a vector volume from the given field object.
 
  // prepare conversion
 
  maxon::FieldSampleData sampleData;
  sampleData.doc = doc;
  sampleData.fieldList  = nullptr;
  sampleData.fieldOwner = fieldObject;
  sampleData.extraTransform = fieldObject->GetMg();
  sampleData.flags = FIELDLAYER_FLAG::NONE;
 
  maxon::Range<maxon::Vector> sampleBox;
  sampleBox.minValue = maxon::Vector { -100.0 };
  sampleBox.maxValue = maxon::Vector { 100.0 };
 
  maxon::ThreadRef   thread;
  const maxon::Float gridSize = 10.0;
 
  // convert
  const maxon::Volume volume = maxon::VolumeToolsInterface::ConvertFieldsToVectorVolume(sampleData, gridSize, sampleBox, thread, nullptr, nullptr) iferr_return;
 
  // make volume object
  VolumeObject* const volumeObject = VolumeObject::Alloc();
  if (volumeObject == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(volumeObject, nullptr, nullptr);
 
  // store volume data
  volumeObject->SetVolume(volume);

Further Reading

• Volumes Overview
• Commands Manual