vpResample(3)

💖 vpResample 💖

okay bestie, this is a page from the Library Functions Manual — three whole functions that resample an array, and we're gonna get into all of it. no skimming, no skipping, we're doing the whole thing. 🎀

---

✨ NAME ✨

vpResample, vpResample2D, vpResample3D — resample an array 🦋

---

✨ SYNOPSIS ✨

#include <volpack.h>

vpResult
vpResample(vpc, num_dimens, src_dimens, dst_dimens, src_strides,
        dst_strides, element_type, src_array, dst_array)
    vpContext *vpc;
    int num_dimens;
    int *src_dimens, *dst_dimens;
    int *src_strides, *dst_strides;
    int element_type;
    void *src_array, *dst_array;

vpResult
vpResample2D(src_array, src_x, src_y, dst_array, dst_x, dst_y,
        element_type, filter_type)
    void *src_array;
    int src_x, src_y;
    void *dst_array;
    int dst_x, dst_y;
    int element_type;
    int filter_type;

vpResult
vpResample3D(src_array, src_x, src_y, src_z, dst_array, dst_x, dst_y,
        dst_z, element_type, filter_type)
    void *src_array;
    int src_x, src_y, src_z;
    void *dst_array;
    int dst_x, dst_y, dst_z;
    int element_type;
    int filter_type;

like. look at that. three functions, all sitting there, all ready to resize ur array. 💅

---

🫶 ARGUMENTS 🫶

• vpc — the VolPack context u got from vpCreateContext. ur whole setup lives in here, periodt.
• num_dimens — how many dimensions the input and output arrays have. they gotta match, no cap.
• src_dimens — an array holding the dimensions of the input array.
• dst_dimens — an array holding the dimensions of the output array.
• src_strides — an array with the stride for each dimension of the input array.
• dst_strides — an array with the stride for each dimension of the output array.
• element_type — a constant saying what data type the array elements are: VP_UCHAR, VP_USHORT, or VP_FLOAT.
• src_array — the input array, holding the input data.
• dst_array — the output array, where the result data goes. 🍓
• src_x, src_y, src_z — the dimensions of the input array.
• dst_x, dst_y, dst_z — the dimensions of the result array.
• filter_type — a constant picking one of the predefined filters: VP_BOX_FILTER, VP_LINEAR_FILTER, VP_GAUSSIAN_FILTER, VP_BSPLINE_FILTER, VP_MITCHELL_FILTER.

---

🌈 DESCRIPTION 🌈

so vpResample resamples an array onto a new grid with a different resolution. it can scale an array of volume data up, or decimate it down, whatever u need. u can hand it an arbitrary separable space-invariant resampling filter through a lookup table that holds the filter weights. ✨

the input array can have literally any number of dimensions, BUT — and this is the plot twist — on each call to vpResample, only one dimension gets resampled. so if u wanna scale all the dimensions, u call the routine once per dimension. it's giving one-at-a-time energy, and we respect it. 🧚

and listen: transformations other than scales, like rotations and shears? not supported by these routines. that's just not their thing.

---

🌸 the 2D and 3D besties 🌸

vpResample2D and vpResample3D are the simpler (but less flexible) interface to vpResample. they take an input array plus its dimensions, an output array plus its dimensions, and a constant naming a filter. the input array gets resampled once for each dimension, then stored in the output array. these two also automatically create a filter weight table and arrays for temporary results, so they're doing a lil extra work behind the scenes for u. 💅

---

💜 the rest is all about vpResample 💜

the rest of this page describes vpResample. the vpc argument is a VolPack context that contains a description of the resampling filter — use vpSetFilter to define that filter. important: the volume data and rendering parameters currently stored in the context are not affected by calls to vpResample. ur context's stuff stays exactly where it is. 🫶

the other arguments to vpResample describe the size and layout of the input and output arrays. the two arrays have to have the same number of dimensions, and that number is num_dimens. the sizes of the dimensions come from src_dimens and dst_dimens, which are 1D arrays with num_dimens elements each.

• src_dimens[0] is the size of the input dimension that's getting resampled.
• dst_dimens[0] is the size of the output dimension after resampling — so the scale factor is dst_dimens[0] / src_dimens[0]. 🔥

the remaining elements of src_dimens give the sizes of the other input array dimensions, in any order (though heads up, some orderings run faster because of lower memory overhead — iykyk). the other output array dimensions are ignored, though they should really be the same as the corresponding input array dimensions, since only one dimension is being resampled. 🙈

the src_strides and dst_stride arguments are 1D arrays that hold a stride in bytes for each dimension of the input and output arrays, stored in the same order as the dimension sizes in src_dimens.

---

⭐ element_type, the data type era ⭐

the element_type argument says what the data type of each element of the input and output data arrays is. the supported types are:

• VP_UCHAR — unsigned character, 1 byte per element.
• VP_USHORT — unsigned short, 2 bytes per element.
• VP_FLOAT — single-precision floating point, 4 bytes per element.

and finally, the last two arguments to vpResample are pointers to the first elements of the input and output arrays. that's it, that's the whole vibe check. 👑

---

💀 ERRORS 💀

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

• VPERROR_BAD_SIZE — no filter weight table has been specified. 😭

not me forgetting the filter weight table... bestie. pls. specify it.

---

🦋 SEE ALSO 🦋

VolPack(3), vpSetFilter(3)

---

and that's the whole page, bestie!! this one's from VolPack, and it's the vpResample(3) era — go forth and resample responsibly 💖✨🎀🦋🌸💅