# imtransform2

## PURPOSE

Applies a linear or nonlinear transformation to an image I.

## SYNOPSIS

function J = imtransform2( I, H, varargin )

## DESCRIPTION

     Applies a linear or nonlinear transformation to an image I.

     Takes the center of the image as the origin, not the top left corner.
     Also, the coordinate system is row/column format, so H must be also.

     The bounding box of the image is set by the BBOX argument, a string that
     can be 'loose' (default) or 'crop'. When BBOX is 'loose', J includes the
     whole transformed image, which generally is larger than I. When BBOX is
     'crop' J is cropped to include only the central portion of the
     transformed image and is the same size as I. The 'loose' flag is
     currently inexact (because of some padding/cropping). Preserves I's type.

     USAGE
      J = imtransform2( I, H, varargin )

     INPUTS - common
      I          - input image [converted to double]
      H          - 3x3 nonsingular homography matrix
      varargin   - additional params (struct or name/value pairs)
        .method    - ['linear'] 'nearest', 'spline', 'cubic' (for interp2)
        .bbox      - ['crop'] or 'loose'
        .show      - [0] figure to use for optional display
        .pad       - [0] padding value (scalar, 'replicate' or 'none')
        .useCache  - [0] optionally cache precomp. for given transform/dims.
        .us        - [] can specify source r/c for each target (instead of H)
        .vs        - [] can specify source r/c for each target (instead of H)

     OUTPUTS
      J       - transformed image

     EXAMPLE - rigid transformation (rotation + translation)
      I=imread('peppers.png');
      R = rotationMatrix(pi/4); T=[1; 3]; H=[R T; 0 0 1];
      J = imtransform2(I,H,'show',1,'pad','replicate');

     EXAMPLE - general homography (out of plane rotation)
      load trees; I=X;
      S=eye(3); S([1 5])=1/500; % zoom out 500 pixels
      H=S^-1*rotationMatrix([0 1 0],pi/4)*S;
      J = imtransform2(I,H,'bbox','loose','show',1);

     EXAMPLE - rotation using three approaches (and timing)
      load trees; I=imResample(X,4); angle=35; method='bilinear';
      % (1) rotate using imrotate (slow)
      tic; J1 = imrotate(I,angle,method,'crop'); toc
      % (2) rotate using a homography matrix
      R=rotationMatrix(angle/180*pi); H=[R [0; 0]; 0 0 1];
      tic; J2 = imtransform2(I,H,'bbox','crop','method',method); toc
      % (3) rotate by explicitly specifying target rs/cs
      m=size(I,1)+4; n=size(I,2)+4; m2=(m-1)/2; n2=(n-1)/2;
      [cs,rs]=meshgrid(-n2:n2,-m2:m2); vs=R*[cs(:) rs(:)]';
      us=reshape(vs(2,:),m,n)-rs; vs=reshape(vs(1,:),m,n)-cs;
      tic, J3=imtransform2(I,[],'us',us,'vs',vs,'method',method); toc
      % compare all results
      figure(1); clf; subplot(3,2,1); im(I); subplot(3,2,2); im(J1);
      subplot(3,2,3); im(J2); subplot(3,2,4); im(abs(J1-J2)); title('J1-J2')
      subplot(3,2,5); im(J3); subplot(3,2,6); im(abs(J2-J3)); title('J2-J3')

     See also TEXTUREMAP, INTERP2

     Piotr's Image&Video Toolbox      Version 3.01
     Copyright 2012 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Simplified BSD License [see external/bsd.txt]