vpOctreeMask(3)

💖 vpOctreeMask — bestie, it's the octree mask girlie 💖

okay so real quick, this is vpOctreeMask(3) from the Library Functions Manual and she's a VolPack function, which means she lives in <volpack.h> and she's about to make your volume rendering ✨make sense✨.

✨ NAME ✨

vpOctreeMask — compute a mask representing one level of a min-max octree 🦋

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpOctreeMask(vpc, array, array_size, max_level)
    vpContext *vpc;
    unsigned char *array;
    int array_size;
    int max_level;

🎀 ARGUMENTS 🎀

• vpc — the VolPack context you got from vpCreateContext. your main character.
• array — a 3D array where the mask gets stored. it's the ✨vessel✨.
• array_size — how big array is, in bytes. don't lie to her.
• max_level — the maximum octree level to descend to. how deep are we going bestie 🕳️

💅 DESCRIPTION 💅

So vpOctreeMask is the performance debugging bestie. Like, when you're rendering volumes with a min-max octree, the octree is what helps figure out which voxels are transparent. and ngl, the time it takes to make that determination can be minimized by picking the right range parameters for vpMinMaxOctreeThreshold and the right node size parameters for vpCreateMinMaxOctree. vpOctreeMask hands you the info to figure out whether a given set of parameters is actually slaying or not.

The output goes into a 3D array of bytes that has the same dimensions as the volume — yes, even though each element is only one byte, no matter how big a voxel is. for every voxel in the volume, vpOctreeMask sets the matching byte in the output array to one of exactly three values:

• 0 — the voxel is definitely transparent. ghosted. not here. 👻
• 255 — the voxel may be non-transparent. it might be somebody.
• 128 — the voxel may be non-transparent and there's more detailed info available at unvisited levels of the octree. it's giving "there's more, keep looking" 🔍

The max_level argument says the deepest level of the octree to be visited — and just so we're clear, the root level is level 0. (yes, we count from zero here, it's giving programmer.)

A suggested way to use this: compute an octree with some particular set of parameters, then call vpOctreeMask with several different values for max_level. for each resulting mask array, look at slices (or literally create a volume rendering! 🔥) and see how accurately the mask captures the general shape of the data in the original volume. The best set of parameters gives you a mask that captures the general shape without an excessively small value for the minimum octree node size — because that would result in a very large data structure and a whole lot of traversal overhead. like, not worth it, babe.

😭 ERRORS 😭

The normal return value is VP_OK. 💖 The following error return values are possible:

• VPERROR_BAD_SIZE — there's no octree, or the output array has the wrong size. one of those. wrong vibe either way.
• VPERROR_BAD_VOXEL — the voxel size or the voxel fields haven't been specified, or they've been incorrectly specified. 🙈
• VPERROR_BAD_CLASSIFIER — the opacity transfer function tables have invalid sizes, or they're associated with invalid voxel fields, or they've been incorrectly specified. the classifier said no 💀

👑 SEE ALSO 👑

• VolPack(3)
• vpCreateContext(3)
• vpCreateMinMaxOctree(3)

okay that's the whole page bestie, go forth and mask responsibly 🫶

this has been your girl from the VolPack library — mwah, periodt 💅✨