makeresampler

>> help makeresampler
MAKERESAMPLER Create resampling structure.
R = MAKERESAMPLER(INTERPOLANT,PADMETHOD) creates a separable
resampler structure for use with TFORMARRAY and IMTRANSFORM.
In its simplest form, INTERPOLANT can be one of these strings:
'nearest', 'linear', or 'cubic'. INTERPOLANT specifies the
interpolating kernel that the separable resampler uses. PADMETHOD
can be one of these strings: 'replicate', 'symmetric', 'circular',
'fill', or 'bound'. PADMETHOD controls how the resampler to
interpolates or assigns values to output elements that map close
to or outside the edge of input array.

PADMETHOD options
-----------------
In the case of 'fill', 'replicate', 'circular', or 'symmetric',
the resampling performed by TFORMARRAY or IMTRANSFORM occurs in
two logical steps: (1) pad A infinitely to fill the entire input
transform space, then (2) evaluate the convolution of the padded
A with the resampling kernel at the output points specified by
the geometric map. Each non-transform dimension is handled
separately. The padding is virtual, (accomplished by remapping
array subscripts) for performance and memory efficiency.

'circular', 'replicate', and 'symmetric' have the same meanings as
in PADARRAY as applied to the transform dimensions of A:

'replicate' -- Repeats the outermost elements
'circular' -- Repeats A circularly
'symmetric' -- Mirrors A repeatedly.

'fill' generates an output array with smooth-looking edges (except
when using nearest neighbor interpolation) because for output points
that map near the edge of the input array (either inside or outside),
it combines input image and fill values .

'bound' is like 'fill', but avoids mixing fill values and input image
values. Points that map outside are assigned values from the fill
value array. Points that map inside are treated as with 'replicate'.
'bound' and 'fill' produce identical results when INTERPOLANT is
'nearest'.

It is up to the user to implement these behaviors in the case of a
custom resampler.

Advanced options for INTERPOLANT
--------------------------------
In general, INTERPOLANT can have one of these forms:

1. One of these strings: 'nearest', 'linear', 'cubic'

2. A cell array: {HALF_WIDTH, POSITIVE_HALF}
HALF_WIDTH is a positive scalar designating the half width of
a symmetric interpolating kernel. POSITIVE_HALF is a vector
of values regularly sampling the kernel on the closed interval
[0 POSITIVE_HALF].

3. A cell array: {HALF_WIDTH, INTERP_FCN}
INTERP_FCN is a function handle that returns interpolating
kernel values given an array of input values in the interval
[0 POSITIVE_HALF].

4. A cell array whose elements are one of the three forms above.

Forms 2 and 3 are used to interpolate with a custom interpolating
kernel. Form 4 is used to specify the interpolation method
independently along each dimension. The number of elements in the
cell array for form 4 must equal the number of transform dimensions.
For example, if INTERPOLANT is {'nearest', 'linear', {2
KERNEL_TABLE}}, then the resampler will use nearest-neighbor
interpolation along the first transform dimension, linear
interpolation along the second, and a custom table-based
interpolation along the third.

Custom resamplers
-----------------
The syntaxes described above construct a resampler structure that
uses the separable resampler function that ships with the Image
Processing Toolbox. It is also possible to create a resampler
structure that uses a user-written resampler by using this syntax:
R = MAKERESAMPLER(PropertyName,PropertyValue,...). PropertyName can
be 'Type', 'PadMethod', 'Interpolant', 'NDims', 'ResampleFcn', or
'CustomData'.

'Type' can be either 'separable' or 'custom' and must always be
supplied. If 'Type' is 'separable', the only other properties that can
be specified are 'Interpolant' and 'PadMethod', and the result is
equivalent to using the MAKERESAMPLER(INTERPOLANT,PADMETHOD) syntax.
If 'Type' is 'custom', then 'NDims' and 'ResampleFcn' are required
properties, and 'CustomData' is optional. 'NDims' is a positive
integer and indicates what dimensionality the custom resampler can
handle. Use a value of Inf to indicate that the custom resampler can
handle any dimension. The value of 'CustomData' is unconstrained.

'ResampleFcn' is a handle to a function that performs the resampling.
The function will be called with the following interface:

B = RESAMPLE_FCN(A,M,TDIMS_A,TDIMS_B,FSIZE_A,FSIZE_B,F,R)

See the help for TFORMARRAY for information on the inputs A, TDIMS_A,
TDIMS_B, and F.

M is an array that maps the transform subscript space of B to the
transform subscript space of A. If A has N transform dimensions (N =
length(TDIMS_A)) and B has P transform dimensions (P = length(TDIMS_B)),
then NDIMS(M) = P + 1 if N > 1 and P if N == 1, and SIZE(M, P + 1) =
N. The first P dimensions of M correspond to the output transform
space, permuted according to the order in which the output transform
dimensions are listed in TDIMS_B. (In general TDIMS_A and TDIMS_B need
not be sorted in ascending order, although such a limitation may be
imposed by specific resamplers.) Thus the first P elements of SIZE(M)
determine the sizes of the transform dimensions of B. The input
transform coordinates to which each point is mapped are arrayed across
the final dimension of M, following the order given in TDIMS_A. M must
be double.

FSIZE_A and FSIZE_B are the full sizes of A and B, padded with 1s as
necessary to be consistent with TDIMS_A, TDIMS_B, and SIZE(A).

Example
-------
Stretch an image in the y-direction using separable resampler that
applies in cubic interpolation in the y-direction and nearest
neighbor interpolation in the x-direction. (This is equivalent to,
but faster than, applying bicubic interpolation.)

A = imread('moon.tif');
resamp = makeresampler({'nearest','cubic'},'fill');
stretch = maketform('affine',[1 0; 0 1.3; 0 0]);
B = imtransform(A,stretch,resamp);

See also imtransform, tformarray.

Reference page in Help browser
doc makeresampler