vpExtract(3)

💖 vpExtract — bestie, let's pull one lil field out of a 3D volume ✨

okay so. this is the vpExtract(3) page from the VolPack library, and no cap, it's genuinely useful — it yanks one field out of a rectangular region of a volume and hands it to you in your own array. let's get into it 🫶

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpExtract(vpc, volume_type, x0, y0, z0, x1, y1, z1, field, dst,
        dst_size, dst_xstride, dst_ystride, dst_zstride)
    vpContext *vpc;
    int volume_type;
    int x0, y0, z0;
    int x1, y1, z1;
    int field;
    void *dst;
    int dst_size;
    int dst_xstride, dst_ystride, dst_zstride;

she's got a LOT of arguments. i know. breathe. we'll go one by one 💅

🎀 ARGUMENTS 🎀

• vpc — your VolPack context, the one you got from vpCreateContext. your main character struct 💜
• volume_type — a code telling her which volume data structure to extract the region from. your options are VP_RAW_VOLUME, VP_CLASSIFIED_VOLUME, VP_CLX_VOLUME, VP_CLY_VOLUME or VP_CLZ_VOLUME.
• x0, y0, z0 — the origin of the extracted region, in the voxel array. where we start, bestie 📍
• x1, y1, z1 — the opposite corner of the extracted region, also in the voxel array. where we stop ✋
• field — a voxel field number identifying which field to extract, OR one of these special codes: VP_OPACITY_FIELD, VP_CORRECTED_OPAC_FIELD, VP_COLOR_FIELD. choose your fighter ⭐
• dst — the destination array. where the goodies land 🍓
• dst_size — size of the destination array, in bytes. yes it's checking, and honestly? she should be.
• dst_xstride, dst_ystride, dst_zstride — strides (in bytes) for the X, Y and Z dimensions of the destination array. literally the walk-pattern through your array 🌈

✨ DESCRIPTION ✨

vpExtract is used to extract one field from a rectangular region of the 3D voxel array or the preclassified volume, and store the result in a separate array. it is also possible to retrieve computed voxel opacities or colors. it's giving "surgical little grabby hands" 🔥

the volume_type argument is used to choose which data structure the region should be extracted from. the choices are:

• VP_RAW_VOLUME — extract from the 3D voxel array (see vpSetRawVoxels(3)).
• VP_CLASSIFIED_VOLUME — extract from the preclassified volume (see vpClassifyVolume(3)). there are three copies of the voxel data in the preclassified volume, one for each principal viewing axis. the copy which will result in the fastest access (best memory stride) is selected. she picks the fastest one for you, because she's an icon like that 👑
• VP_CLX_VOLUME — extract from the preclassified volume used for X-axis viewing.
• VP_CLY_VOLUME — extract from the preclassified volume used for Y-axis viewing.
• VP_CLZ_VOLUME — extract from the preclassified volume used for Z-axis viewing.

the last three choices for the volume_type argument are usually used only for debugging. so like, niche. iykyk 🐛

the next six arguments give the coordinates of the corners of the extracted region in the volume. the coordinates are indexes into the array. no floaty nonsense, indexes, periodt.

the field argument is used to select which voxel field to extract. any of the voxel field numbers previously specified with vpVoxelField may be specified. the output array must be sized appropriately for the dimensions of the region and the size of the extracted field. the following special constants may also be used instead of a voxel field number:

• VP_OPACITY_FIELD — return voxel opacities for voxels in the indicated region. if the 3D voxel array is selected, then the opacities are computed on-the-fly using the current opacity transfer function. the minimum opacity threshold is ignored. if the preclassified volume is selected, then the precomputed opacities are extracted. opacities below the minimum opacity threshold at the time the volume was classified are set to 0. the output array should have type unsigned char, and the opacities are stored as number between 0 (transparent) and 255 (opaque). crystal clear, both ends of the scale 🫧
• VP_CORRECTED_OPAC_FIELD — this option is the same as the VP_OPACITY_FIELD option, except that voxel opacities are corrected for the current view transformation. the opacity transfer function is assumed to produce the opacity of a voxel viewed perpendicular to one face of the volume with no scale factor. if the voxel has been scaled or rotated with respect to the viewer, then the apparent opacity must be corrected. it's the same vibe, just angle-aware 📐
• VP_COLOR_FIELD — return voxel colors for voxels in the indicated region. the colors are computed on-the-fly using the current shading, lighting and material parameters. the output array should have type unsigned char, and each color channel is stored as number between 0 (off) and 255 (full intensity). the number of color channels per pixels is determined by the current shading parameters. (not currently supported for preclassified volumes.) 🚨 heads up on that last bit — no preclassified volumes here, bestie.

the remaining arguments specify the output array, its size (for error checking), and the stride for each dimension (to allow padding the end of scanlines or storing the result in a higher-dimension array). very "we prepared for every layout" of her 💅

💀 ERRORS 💀

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

• VPERROR_BAD_VALUE — the volume coordinates are out of bounds or invalid (x0 > x1, etc.), or the field number is invalid.
• VPERROR_BAD_SIZE — the destination array size is incorrect.
• VPERROR_BAD_VOLUME — the volume data does not exist.
• VPERROR_BAD_OPTION — the volume_type argument is invalid.
• VPERROR_BAD_VOLUME — the volume size or data is missing or invalid. (yes, VPERROR_BAD_VOLUME shows up twice in the original list. not me editing the lore. she's listed twice, we list her twice 🙈)
• VPERROR_BAD_VOXEL — the voxel fields are incorrectly defined.
• VPERROR_BAD_CLASSIFIER — the opacity transfer function is incorrectly specified.
• VPERROR_BAD_SHADER — the shading parameters have been incorrectly specified.
• VPERROR_SINGULAR — one or more of the view transformation matrices is singular. math said no 😭

🦋 SEE ALSO 🦋

VolPack(3), vpCreateContext(3)

okay that's the whole page bestie, go extract something gorgeous 💖✨

and for the record: this is vpExtract(3) from the VolPack library functions manual, VolPack version, dated alongside the rest of the VolPack set. that's the footer energy, folded into a little sign-off instead of a boring line at the bottom. mwah 🎀👑