vpSetFilter(3)

💖 vpSetFilter(3) — the "define a resampling filter" era 💖

okay bestie, gather round, because we're talking about vpSetFilter from the VolPack library functions manual and honestly? it's giving filter design main character energy ✨

✨ NAME ✨

vpSetFilter — define a resampling filter 🎀

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpSetFilter(vpc, num_taps, num_phases, weights)
    vpContext *vpc;
    int num_taps, num_phases;
    float *weights;

🦋 ARGUMENTS 🦋

• vpc — the VolPack context you got from vpCreateContext. your whole vibe lives in here 💜
• num_taps — Number of filter taps. yes, actual number, not a dance move (well… kinda? 👀)
• num_phases — Number of filter phases. the more phases the more accurate, we'll get into it 🫶
• weights — Array containing filter weights. the numbers that do the actual work, no cap 💅

🎀 DESCRIPTION 🎀

so vpSetFilter is what you call to specify a table of filter weights before you resample an array with vpResample. literally the setup step. and the table it takes? it can specify an arbitrary separable space-invariant filter. fancy? yes. iconic? also yes. 👑

The vpc argument is a VolPack context for storing a description of the resampling filter. and here's the part you need to know so you don't spiral: the volume data and rendering parameters currently stored in the context are not affected by calls to vpSetFilter or vpResample. so like, no side quests, no surprise edits, it just minds its own business 💖

The num_taps argument specifies the number of filter taps. When an array is resampled, the number of filter taps is equal to the number of input array elements that contribute to one element of the output array. A filter weight is associated with each tap and determines the contribution of the corresponding input array element to the output array element. now pay attention bestie because this is the plot twist: when upsampling the number of taps depends only on the support of the filter kernel. but when downsampling, the number of taps should also depend on the scale factor — because the filter kernel must also be scaled. so the scale factor is lowkey part of the equation when you're going down. don't forget her. 😭

The num_phases argument specifies the number of filter phases, which is equal to the number of times the filter kernel is sampled. The more filter phases, the more accurate the filtering operation. However — and this is the not me getting humbled by diminishing returns moment — there is a point of diminishing returns where increasing the number of phases results in very little increase in accuracy, and has the disadvantages of increased storage requirements and potentially poor cache performance. 💀 so more phases isn't free, it's just vibes with a cost. and to allow for an efficient implementation, num_phases must be a power of two. periodt. ⭐

The weights array contains the filter weights themselves. The array should have dimensions:

float weights[num_phases][num_taps];

Each element should normally be a number between 0.0 and 1.0 (negative values are also possible but can lead to ringing 🌊), and for any particular phase the entries for all of the taps should sum to 1.0 (or else ripple is introduced into constant regions of the filtered array). so like, they gotta add up, or the constant regions start acting up. do the math, bestie, it's for your own good 🙈

The easiest way to initialize the weight table is to call one of the predefined routines described in the vpBoxFilter(3) man page. easy mode unlocked 🎁

🔥 ERRORS 🔥

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

• VPERROR_BAD_VALUE — Either num_taps is non-positive or num_phases is not a positive power of two. so like, fix your numbers, it's literally just the numbers 😤

🌈 SEE ALSO 🌈

VolPack(3), vpBoxFilter(3), vpResample(3)

and that's the whole page, bestie — VolPack, vpSetFilter(3), mwah 💋 thanks for reading, you're gonna slay this resampling thing fr fr 💖✨🎀🦋🌸💅🫶