teem	/	nrrd	Kernels

• The NrrdKernel struct
• The NrrdKernelSpec struct
• Kernels supplied by Nrrd
• Plotting kernels

Besides representing arrays, the Nrrd library is responsible in Teem for representing continuous finite-support functions called kernels (or filters), which are the basis of axis-aligned resampling in Nrrd, and of the convolution-based measurements in Gage. Kernels are used to reconstruct continuous values from discretely sampled data, as well as measuring derivatives from sampled data.

The NrrdKernel struct

/*
******** NrrdKernel struct
**
** these are essentially the methods of the various kernels implemented.
**
** Nrrd's use of this sort of kernel always assumes support symmetric
** around zero, but does not assume anything about even- or oddness
**
** It is a strong but very simplifying assumption that the parameter
** array ("parm") is always type double.  There is essentially no
** value in allowing flexibility between float and double, and much
** Teem code assumes that it will always be type double.
*/
typedef struct {
  /* terse string representation of kernel function, irrespective of
     the parameter vector */
  char name[AIR_STRLEN_SMALL];

  /* number of parameters needed (# elements in parm[] used) */
  unsigned int numParm;

  /* smallest x (x > 0) such that k(y) = 0 for all y > x, y < -x */
  double (*support)(const double *parm);

  /* integral of kernel from -support to +support */
  double (*integral)(const double *parm);

  /* evaluate once, single precision */
  float (*eval1_f)(float x, const double *parm);

  /* evaluate N times, single precision */
  void (*evalN_f)(float *f, const float *x, size_t N, const double *parm);

  /* evaluate once, double precision */
  double (*eval1_d)(double x, const double *parm);

  /* eval. N times, double precision */
  void (*evalN_d)(double *f, const double *x, size_t N, const double *parm);
} NrrdKernel;

All the kernels use a double* to communicate parameters which may change the shape or size of the kernel. The first parameter (parm[0]) usually determines the kernel scaling, as measured in units of samples. For example, nrrdKernelBox represents the box function (1.0 inside [-0.5,0.5], and 0.0 outside) when parm[0] == 1.0, but you can change the size of the box function by setting a different value for parm[0]: if parm[0] == 4.0, the support of the box functions extends to [-2,2]. To be mathematically well-behaved, when kernels support this kind of scaling, the amplitude of the kernel is scaled proportionally so that the integral of the kernel is constant.

Unlike other structs in Nrrd (and Teem), NrrdKernels are usually not user-allocated (there is no nrrdKernelNew() or nrrdKernelNix()). Rather, the kernels in Nrrd are created at compile-time, and pointers to these are used to communicate kernel information to the convolution functions that need them.

There is one function which supplies a standard way of mapping from a string to a NrrdKernel and a parameter vector; this is used for command-line specification of kernels:

int nrrdKernelParse(const NrrdKernel **kernelP, double *parm,
                    const char *str);

/*
******** NrrdKernelSpec struct
** 
** for those times when it makes most sense to directly associate a
** NrrdKernel with its parameter vector (that is, a full kernel
** "spec"ification), basically: using hest.
*/
typedef struct {
  const NrrdKernel *kernel;
  double parm[NRRD_KERNEL_PARMS_NUM];
} NrrdKernelSpec;

• NrrdKernelSpec *nrrdKernelSpecNew();
  NrrdKernelSpec *nrrdKernelSpecNix(NrrdKernelSpec *ksp);
  NrrdKernelSpec *nrrdKernelSpecCopy(NrrdKernelSpec *ksp);
  

  Create, destroy, and copy (which also creates).

• void nrrdKernelSpecSet(NrrdKernelSpec *ksp, const NrrdKernel *k,
                         const double kparm[NRRD_KERNEL_PARMS_NUM]);
  

  Set a NrrdKernelSpec from a NrrdKernel pointer and a parameter vector.

• void nrrdKernelParmSet(const NrrdKernel **kP,
                         double kparm[NRRD_KERNEL_PARMS_NUM],
                         NrrdKernelSpec *ksp);
  

  Set a NrrdKernel pointer and a parameter vector from a NrrdKernelSpec.

• int nrrdKernelSpecParse(NrrdKernelSpec *ksp, const char *str);
  

  Like nrrdKernelParse, but sets info in a given NrrdKernelSpec.

echo 0 0 1 0 0 \
 | unu axdelete -a -1 \
 | unu resample -s x100 -c node -k cubic:0,0.5 \
 | unu 2op + - 0.2 \
 | unu dhisto -h 200 -nolog \
 | unu pad -min -1 -1 -max M+1 M+1 -b pad -v 0 -o cmr.png

echo 0 0 1 0 0 \
 | unu axdelete -a -1 \
 | unu resample -s x100 -c node -k cubicd:0,0.5 \
 | unu 2op + - 1.4 \
 | unu dhisto -h 200 -nolog \
 | unu pad -min -1 -1 -max M+1 M+1 -b pad -v 0 -o cmrd.png

The "-k" argument to unu resample specifies the kernel to use to upsample the input vector, in this case "0 0 1 0 0", which ends up plotting from -2 to +2. Using "0 0 0 1 0 0 0" would plot from -3 to +3. The "unu 2op + - 0.2" adds a little bit to all the values so that nothing negative is given to unu dhisto, which was never really meant for this.

You can also save the sampled values to text files for plotting with other programs:

echo 0 0 1 0 0 \
 | unu axdelete -a -1 \
 | unu resample -s x100 -c node -k cubic:0,0.5 -o range.txt
echo -2 -1 0 1 2 \
 | unu axdelete -a -1 \
 | unu resample -s x100 -c node -k tent -o domain.txt