unu-resample - Man Page

filtering and {up,down}sampling with a separable kernel

Synopsis

unu resample [-old] -s,--size <sz0 ...> [-off,--offset [<off0 ...>]] [-min,--minimum [<min0 ...>]] [-max,--maximum [<max0 ...>]] [-k,--kernel <kern ...>] [-nrn] [-ne,--nonexistent <behavior>] [-b,--boundary <behavior>] [-v,--value <value>] [-t,--type <type>] [-cheap] [-c,--center <center>] [-co,--center-override] [-verbose <v>] [-i,--input <nin>] [-o,--output <nout>]

Filtering and {up,down}sampling with a separable kernel. Simplifies access to the NrrdResampleContext functions by assuming (among other things) that the same kernel is used for resampling every axis that is being resampled. Only required option is “-s” to specify which axes to resample and how many output samples to generate. Resampling kernel “-k” defaults to an interpolating cubic, but many other choices are available. By default, resampling an axis resamples the full extent of its samples, but it is possible to offset this range via “-off”, or to crop and/or pad via “-min” and “-max”. The resampling respects the difference between cell- and node-centered data, but you can over-ride known centering with “-co”.

Uses the many nrrdResample* functions operating on a nrrdResampleContext

Options

-old

instead of using the new nrrdResampleContext implementation, use the old nrrdSpatialResample implementation

-s <sz0 ...> , --size <sz0 ...>

For each axis, information about how many samples in output:

“=”: leave this axis completely untouched: no resampling whatsoever
“xfloat”: multiply the number of input samples by float, and round to the nearest integer, to get the number of output samples. Use “x1” to resample the axis but leave the number of samples unchanged
“/float”: divide number of input samples by float
“+=uint”, “-=uint”: add uint to or subtract uint from number input samples to get number output samples
“uint”: exact number of output samples
“a”: resample this axis to whatever number of samples preserves the aspect ratio of other resampled axes. Currently needs to be used on all but one of the resampled axes, if at all.

(1 or more sampling specifications)

-off [<off0 ...>] , --offset [<off0 ...>]

For each axis, an offset or shift to the position (in index space) of the lower end of the sampling domain. Either -off can be used, or -min and -max together, or none of these (so that, by default, the full domain of the axis is resampled). (0 or more doubles); default: “”

-min [<min0 ...>] , --minimum [<min0 ...>]

For each axis, the lower end (in index space) of the domain of the resampling. Either -off can be used, or -min and -max together, or none of these (so that, by default, the full domain of the axis is resampled). (0 or more doubles); default: “”

-max [<max0 ...>] , --maximum [<max0 ...>]

For each axis, the upper end (in index space) of the domain of the resampling. Either -off can be used, or -max and -max together, or none of these (so that, by default, the full domain of the axis is resampled). (0 or more doubles); default: “”

-k <kern> , --kernel <kern>

The kernel to use for resampling. Kernels logically live in the input index space for upsampling, and in the output index space for downsampling. Possibilities include:

“box”: nearest neighbor interpolation on upsampling, and uniform averaging on downsampling
“cheap”: nearest neighbor interpolation for upsampling, and non-blurring sub-sampling (pick subset of input samples) on downsampling
“tent”: linear interpolation
“cubic:B,C”: Mitchell/Netravali BC-family of cubics:
“cubic:1,0”: B-spline; maximal blurring
“cubic:0,0.5”: Catmull-Rom; good interpolating kernel
“c4h”: 6-sample-support, C^4 continuous, accurate
“c4hai”: discrete pre-filter to make c4h interpolate
“bspl3”, “bspl5”, “bspl7”: cubic (same as cubic:1,0), quintic, and 7th order B-spline
“bspl3ai”, “bspl5ai”, “bspl7ai”: discrete pre-filters to make bspl3, bspl5, bspl7 interpolate
“hann:R”: Hann (cosine bell) windowed sinc, radius R
“black:R”: Blackman windowed sinc, radius R
“gauss:S,C”: Gaussian blurring, with standard deviation S and cut-off at C standard deviations
“dgauss:S,C”: Lindeberg’s discrete Gaussian.

default: “cubic:0,0.5”

-nrn

do NOT do per-pass kernel weight renormalization. Doing the renormalization is not a performance hit (hence is enabled by default), and the renormalization is sometimes needed to avoid “grating” on non-integral down-sampling. Disabling the renormalization is needed for correct results with artificially narrow kernels.

-ne <behavior> , --nonexistent <behavior>

When resampling floating-point values, how to handle non-existent values within kernel support:

“noop”: do nothing; let them pollute result
“renorm”: ignore them and renormalize weights of existent values
“wght”: ignore them and simply use weights of existent values

default: “noop”

-b <behavior> , --boundary <behavior>

How to handle samples beyond the input bounds:

“pad”: use some specified value
“bleed”: extend border values outward
“mirror”: repeated reflections
“wrap”: wrap-around to other side

default: “noop”

-v <value> , --value <value>

for “pad” boundary behavior, pad with this value (double); default: “0.0”

-t <type> , --type <type>

type to save output as. By default (not using this option), the output type is the same as the input type; default: “default”

-cheap

[DEPRECATED: the “-k cheap” option is the new (and more reliable) way to access this functionality. “-cheap” is only here for legacy use in combination with “-old”.]

When downsampling (reducing number of samples), don’t try to do correct filtering by scaling kernel to match new (stretched) index space; keep it in old index space. When used in conjunction with “-k box”, this can implement subsampling which chooses every Nth value.

-c <center> , --center <center>

(not available with “-old”) default centering of axes when input nrrd axes don’t have a known centering: “cell” or “node”; default: “cell”

-co , --center-override

(not available with “-old”) centering info specified via “-c” should over-ride known centering, rather than simply be used when centering is unknown.

-verbose <v>