vpClassifyVolume(3)

💖 vpClassifyVolume — bestie edition 💖

okay so we're deep in the VolPack(3) library functions manual and today's main character is vpClassifyVolume, the glow-up your volume data has been waiting for. buckle up 🎀

---

✨ NAME ✨

vpClassifyVolume, vpDestroyClassifiedVolume — make a preclassified volume so rendering goes zoom zoom, and then yeet it when you're done. it's giving "prep once, slay forever" 💅

---

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpClassifyVolume(vpc)
    vpContext *vpc;

vpResult
vpDestroyClassifyVolume(vpc)
    vpContext *vpc;

---

🦋 ARGUMENTS 🦋

• vpc — your VolPack context, the one you got from vpCreateContext. she's the whole personality of this operation fr fr.

---

👑 DESCRIPTION 👑

so vpClassifyVolume computes a preclassified volume for the fast rendering algorithm. what even is that? it's an internal data structure that's optimized purely for rendering speed — like, it's the version of your data that's dressed and ready for the runway instead of still in pajamas. 🫶

here's the order of operations, bestie, don't skip steps:

1. define a voxel array — that's vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField, and vpSetRawVoxels.
2. initialize it — either with vpVolumeNormals or your own user-defined routine.
3. define an opacity transfer function with vpSetClassifierTable. non-negotiable, she needs it.
4. set the minimum opacity threshold with the VP_MIN_VOXEL_OPACITY parameter to vpSeti.

and then you can call vpClassifyVolume.

alsooo, there are two alternative routines that compute a preclassified volume directly — one from a 3D scalar array and one from a sequence of scalar scanlines. the whole point of those is to avoid allocating a giant 3D voxel array (see vpClassifyScalars(3) and vpClassifyScanline(3)). lowkey a resource-saving moment ✨

---

🎀 what it actually does

vpClassifyVolume classifies and processes the data in the voxel array and creates a separate preclassified volume. the preclassified data is stored in a run-length encoded format, and voxels whose opacities are less than or equal to the minimum opacity threshold get discarded. bye, irrelevant data 👋

normally, three copies of the preclassified volume are created — one for each of the three principal viewing axes. but if you only need one or two copies for your required range of viewpoints, you can call vpSeti with one or more of these parameters to say which copies you actually need:

• VP_VIEW_X_AXIS
• VP_VIEW_Y_AXIS
• VP_VIEW_Z_AXIS

using these parameters is not recommended unless swap space is lacking. so like... only if you're desperate, bestie 😭

---

🌈 min-max octree moment

if a min-max octree is present in the rendering context (see vpCreateMinMaxOctree(3)) then it gets used to accelerate computation of the preclassified volume. it's genuinely advantageous to create a min-max octree if you're gonna classify the same volume data multiple times — like with different opacity transfer functions. same data, different fits, iconic 💜

---

⭐ the rules, no cap

once vpClassifyVolume is finished, the original voxel array is no longer necessary for rendering — as long as the opacity transfer function and the volume data don't change.

if any changes are made, then the preclassified volume must be explicitly recomputed by calling vpClassifyVolume again. no shortcuts.

only one preclassified volume may be stored in a rendering context at a time. calling vpClassifyVolume causes any existing preclassified volume to be destroyed. gone. ghosted. 💀

and vpDestroyClassifiedVolume? she destroys the current preclassified volume and frees the associated space. the respectful breakup we all deserve. 🧚

---

💅 STATE VARIABLES 💅

you can pull info about the current preclassified volume with these state variable codes (see vpGeti(3)):

• VP_VIEW_X_SIZE
• VP_VIEW_Y_SIZE
• VP_VIEW_Z_SIZE
• VP_VIEW_X_AXIS
• VP_VIEW_Y_AXIS
• VP_VIEW_Z_AXIS

---

🚨 ERRORS 🚨

the normal return value is VP_OK. these are the error return values that can happen instead, and yes we're listing every single one:

• VPERROR_BAD_VOXEL — the voxel size or the voxel fields have not been specified, or have been incorrectly specified. 🙈
• VPERROR_BAD_VOLUME — the volume array or volume dimensions have not been specified, or the size of the volume array doesn't match the volume dimensions. 💀
• VPERROR_BAD_CLASSIFIER — the opacity transfer function tables have invalid sizes, or are associated with invalid voxel fields, or have been incorrectly specified. 😭

---

🔥 SEE ALSO 🔥

VolPack(3), vpCreateContext(3), vpSetClassifierTable(3), vpClassifyScalars(3), vpClassifyScanline(3)

---

and that's the whole page, bestie 💖 this came straight out of the VolPack crew, vpClassifyVolume(3), library functions manual energy. now go classify something and eat 🍓✨