vpExtract(3)

💖 vpExtract(3) 💖

okay bestie, welcome to the glow-up of vpExtract — a lil library function from the Library Functions Manual section, and yes she's serving volume-slicing realness 🫶

---

✨ NAME ✨

vpExtract — extract one field from a rectangular region of a volume 💅

---

🌸 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;

---

🎀 ARGUMENTS 🎀

• vpc — the VolPack context you got from vpCreateContext. your main character ✨
• volume_type — a code that says which volume data structure we're pulling the region out of. the options are VP_RAW_VOLUME, VP_CLASSIFIED_VOLUME, VP_CLX_VOLUME, VP_CLY_VOLUME or VP_CLZ_VOLUME.
• x0, y0, z0 — origin corner of the extracted region, in the voxel array.
• x1, y1, z1 — the opposite corner of the extracted region, in the voxel array.
• field — a voxel field number that says which field to extract, OR one of these special codes: VP_OPACITY_FIELD, VP_CORRECTED_OPAC_FIELD, VP_COLOR_FIELD. iykyk 🌈
• dst — the destination array, aka where the goodies land 🍓
• dst_size — size of the destination array, in bytes.
• dst_xstride, dst_ystride, dst_zstride — strides (in bytes) for the X, Y and Z dimensions of the destination array.

---

🦋 DESCRIPTION 🦋

so, vpExtract is the girl who goes into a rectangular region of either the 3D voxel array or the preclassified volume, yoinks one field out of it, and drops the result into a separate array. she can also hand you computed voxel opacities or colors, no cap 💅

the volume_type argument picks which data structure we're extracting the region from. the choices, bestie:

• VP_RAW_VOLUME — extract from the 3D voxel array (see vpSetRawVoxels(3)).
• VP_CLASSIFIED_VOLUME — extract from the preclassified volume (see vpClassifyVolume(3)). heads up: there are three copies of the voxel data in the preclassified volume, one for each principal viewing axis. the copy that gives the fastest access (aka the best memory stride) gets selected. periodt.
• 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.

lowkey important: those last three volume_type choices are usually only used for debugging 👀

the next six arguments are the coordinates of the corners of the extracted region in the volume. these coordinates are indexes into the array, fr fr.

the field argument picks which voxel field gets extracted. any of the voxel field numbers you previously specified with vpVoxelField works here. and the output array must be sized appropriately for the region's dimensions and the size of the extracted field, okay? don't skip that part 🙈

these special constants can also be used instead of a voxel field number:

• VP_OPACITY_FIELD — return voxel opacities for the voxels in the indicated region. if the 3D voxel array is selected, the opacities are computed on-the-fly using the current opacity transfer function, and the minimum opacity threshold is ignored. if the preclassified volume is selected, then the precomputed opacities get extracted, and opacities below the minimum opacity threshold at the time the volume was classified are set to 0. the output array should be type unsigned char, and opacities are stored as a number between 0 (transparent) and 255 (opaque). ✨
• VP_CORRECTED_OPAC_FIELD — same as the VP_OPACITY_FIELD option, except the voxel opacities get 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. so if the voxel has been scaled or rotated with respect to the viewer, then the apparent opacity must be corrected. she's doing math for you, be grateful 💜
• VP_COLOR_FIELD — return voxel colors for voxels in the indicated region. colors are computed on-the-fly using the current shading, lighting and material parameters. the output array should be type unsigned char, and each color channel is stored as a 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, bestie, sorry 😭)

the remaining arguments specify the output array, its size (for error checking, she's thorough), and the stride for each dimension — that's so you can pad the end of scanlines or store the result in a higher-dimension array. slay 🌈

---

💀 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.
• 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.

not me listing VPERROR_BAD_VOLUME twice — that's literally what the page says, so it stays, bestie 🙈

---

👑 SEE ALSO 👑

VolPack(3), vpCreateContext(3)

---

and that's the whole page, angel 💖 brought to you by VolPack, filed under vpExtract(3) — go extract something iconic, you absolute legend 🎀🦋✨