function h = cvexShowImagePair(I1,I2,title1,title2,colorMode,pts1,pts2,lines1,lines2)
%cvexShowImagePair Display images and points.
%  cvexShowImagePair(I1,I2,TITLE1,TITLE2) displays a pair of images, I1
%  and I2, with titles TITLE1 and TITLE2.
%
%  cvexShowImagePair(...,COLOR_SELECTION,PTS1,PTS2) also draws points on
%  the images.
%
%    COLOR_SELECTION can be 'SingleColor' or 'MultipleColors'. If
%    'SingleColor' is used, all points will be shown in red.
%    Otherwise, the points will be shown using different colors.
%    'MultipleColors' selection is most useful when PTS1 and PTS2 contain
%    matching feature points. It helps to visualize point correspondences.
% 
%    PTS1 and PTS2 are the coordinates of the points in I1 and I2,
%    respectively. Each column of PTS1 or PTS2 has the format of
%    [row;column] which determines the location of a point. Both PTS1 and
%    PTS2 are 2-by-N matrices, where N is the number of points.
% 
%  H = cvexShowImagePair(...) returns the handle to the figure
%  object. 
%
%  Notes
%  -----
%  This is a helper function in support of examples and is subject to
%  change or removal in a future release.
%
% See also cvexShowStereoImages

% Copyright 2010 The MathWorks, Inc.
% $Revision: 1.1.6.4 $  $Date: 2011/04/02 01:31:16 $

% Check the number of input arguments.
if nargin ~= 4 && nargin ~= 7 && nargin ~= 9
  error('vision:cvexShowImagePair:invalidInputs',...
    ['You must use one of the following syntaxes: ',...
     'cvexShowImagePair(I1,I2,TITLE1,TITLE2) ',...
     'cvexShowImagePair(I1,I2,TITLE1,TITLE2,PTS1,PTS2), or', ...
     'cvexShowImagePair(I1,I2,TITLE1,TITLE2,PTS1,PTS2,LINES1,LINES2).']);
end

% Creat a figure for showing the results.
titleHeight = 40;
borderWidth = 10;
h = createFigure(size(I1), borderWidth, titleHeight);

% Display the images, points, and lines.
switch nargin
case 4
  showImage(borderWidth, 1, title1, I1);
  showImage(borderWidth, 2, title2, I2);
case 7
  showImage(borderWidth, 1, title1, I1, colorMode, pts1);
  showImage(borderWidth, 2, title2, I2, colorMode, pts2);
otherwise
  showImage(borderWidth, 1, title1, I1, colorMode, pts1, lines1);
  showImage(borderWidth, 2, title2, I2, colorMode, pts2, lines2);
end
truesize;

%==========================================================================
% Create a figure
%==========================================================================
function h = createFigure(sizeImage, borderWidth, titleHeight)
h = figure('Units', 'pixels');
oriPosition = get(h, 'Position');
numRow = sizeImage(1);
numCol = sizeImage(2);
newWidth = numCol * 2 + borderWidth * 3;
newHeight = numRow + titleHeight + borderWidth;
% Move the figure so the top and left borders are always visible.
newCol = oriPosition(1) - (newWidth - numCol) / 2;
if newCol < 1
  % Make sure the left border of the images are visible.
  newCol = 1; 
end
newRow = oriPosition(2) - (newHeight - numRow) / 2;
screenSize = get(0, 'ScreenSize');
screenHeight = screenSize(4);
if newRow + newHeight > screenHeight
  % Make sure the top border of the images are visible.
  newRow = screenHeight - newHeight;
end
newPosition = [newCol, newRow, newWidth, newHeight];
set(h, 'Position', newPosition);

%==========================================================================
% Display an image, points, and lines.
%==========================================================================
function showImage(borderWidth, id, titles, I, colorMode, pts, lineList)
% Display the image and title.
I = im2single(I);
numRow = size(I, 1);
numCol = size(I, 2);
h = subplot(1, 2, id, 'Units', 'Pixels');
leftBorder = borderWidth + (borderWidth + numCol) * (id - 1);
bottomBorder = borderWidth;
set(h, 'Position', [leftBorder, bottomBorder, numCol, numRow]);
imshow(I, 'Border', 'Tight');
title(titles);
hold on;

% Display the points and lines.
isXY = cvstGetCoordsChoice('fcnCvexShowImagePair');

if nargin > 4
  if isXY
    pts = pts';
    pts = flipud(pts);
  else
    pts = pts + 1;
  end
  
  pts = single(pts);
  numPts = size(pts, 2);
  if strcmp(colorMode, 'MultipleColors')
    clr = lines(numPts);
  else
    clr = kron([1,0,0], ones(numPts, 1));
  end

  for idx = 1: numPts
    plot(pts(2,idx), pts(1,idx), 'o', 'MarkerSize', 4, ...
      'MarkerEdgeColor', 'w', 'MarkerFaceColor', clr(idx,:));
  end
  
  if nargin > 6
    
    if isXY
      lineList = lineList';
      lineList = lineList([2 1 4 3], :);
    end
    
    for idx = 1: numPts
      line([lineList(2,idx); lineList(4,idx)], ...
        [lineList(1,idx); lineList(3,idx)], ...
        'Color', clr(idx,:));
    end
  end
end

hold off;
