VolumeInterface Manual

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:

// 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);
Definition: lib_volumeobject.h:41
void SetVolume(const maxon::VolumeInterface *volumeObj)
static VolumeObject * Alloc()
Definition: lib_volumeobject.h:53
static MAXON_METHOD Result< Volume > CreateFromFile(const Url &url, Float scale, Int gridIndex)
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
const char * doc
Definition: pyerrors.h:226
#define iferr_return
Definition: resultbase.h:1524

The grid settings are accessed with:

// 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 maxon::GRIDCLASS gridClass = volume.GetGridClass();
DiagnosticOutput("@ (@)", gridName, gridClass);
}
Definition: string.h:1237
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
GRIDCLASS
Volume Classes.
Definition: volume.h:33

Iterator

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

// 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
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
pos.x = coord.x;
pos.y = coord.y;
pos.z = coord.z;
pos = transform * pos;
DiagnosticOutput("World space coordinates: @", pos);
}
PyObject * value
Definition: abstract.h:715
Definition: volumeiterators.h:28
void Py_ssize_t * pos
Definition: dictobject.h:50
for(i=0;i< length;i++)
Definition: unicodeobject.h:61
maxon::Float32 Float32
Definition: ge_sys_math.h:64
static auto Create(ARGS &&... args)
Definition: apibase.h:2818
A vector consisting of three components X, Y and Z.
Definition: vec.h:21
T y
Definition: vec.h:40
T x
Definition: vec.h:39
T z
Definition: vec.h:41

Accessor

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

Volume data is accessed with:

// 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
volume.SetGridClass(maxon::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
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);
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);
Definition: volumeaccessors.h:24
static MAXON_METHOD Result< Volume > CreateNewFloat32Volume(Float32 background)
FOG
Definition: ge_prepass.h:2
maxon::Float64 Float64
Definition: ge_sys_math.h:63
maxon::Float Float
Definition: ge_sys_math.h:62
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:190
MAXON_ATTRIBUTE_FORCE_INLINE void SinCos(Float32 val, Float32 &sn, Float32 &cs)
Calculates both sine and cosine of a value.
Definition: apibasemath.h:486
GRIDCLASS
Volume Classes.
Definition: ge_prepass.h:1922
Matrix MatrixScale(const Vector &s)
Definition: c4d_tools.h:283
The maxon namespace contains all declarations of the MAXON API.
Definition: autoweight.h:14
VOLUMESAMPLER
Definition: volumeaccessors.h:16

Further Reading