Image: Select ROI

This function provides GUI for selecting ROI of square/rectangular shape.

This functions displays GUI for selecting square or rectangular part
of the input image IMG. To perform selection user must click mouse twice:
at two corners of the selection area.
User can change the shape at any moment, even when first point is set,
unless it is not forbidden by additional parameters.
Use also cam change the way the selection area is calculated
from the two selected points.
Depending on the combination of the shape and mode it could be:
--------------------------------------------------------------------------
Shape Mode Result
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Rectangle Free Rectangle with one corner at first point (P1)
and another corner at second point (P2).
Rectangle Centered Rectangle with its center at first point (P1)
and corner at second point (P2).
Square Free Square of the largest size that can be
fitted into rectangle made by (P1) and (P2)
with one corner at (P1).
Square Centered Square of the largest size that can be
fitted into centered rectangle.
Center of the square is at (P1).
--------------------------------------------------------------------------
Behavior of the imSelectROI can be altered by providing additional
parameters in MatLab well-known ParamName,ParamValue style.

NOTE This function was developed under MatLab R2006b.
==== It requires Image Processing Toolbox to work.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syntax
======
imSelectROI( img, param1, val1, param2, val2, ...)
ROI = imSelectROI( img, param1, val1, param2, val2, ...)
[ ROI, SelImg ] = imSelectROI( img, param1, val1, param2, val2, ...)

Displays GUI and returns:

SelImg - Selected part of the image passed as first parameter.
Even if first parameter is a file name (see below).

ROI - structure with fields:
ROI.Xmin - minimal value of X coordinate of the selected area
ROI.Xmax - maximal value of X coordinate of the selected area
ROI.Ymin - minimal value of Y coordinate of the selected area
ROI.Ymax - maximal value of Y coordinate of the selected area
ROI.DX - horizontal size of the selected area
ROI.DX = ROI.Xmax - ROI.Xmin + 1
ROI.DY - vertical size of the selected area
ROI.DY = ROI.Ymax - ROI.Ymin + 1
ROI.Xrange - same as [ROI.Xmin:ROI.Xmax]
ROI.Yrange - same as [ROI.Ymin:ROI.Ymax]

Selected part can be retrieved from original image as
img( ROI.Xrange, ROI.Yrange, :)
This allows to perform selection once and use the same ROI
to process series of images (see examples at hte end).

Arguments
=========

img Anything that can be passed to IMSHOW as a single parameter.
In could be file name or preloaded image.
See "help imshow" for more information about the syntaxes.

Parameters
==========

AllowedShape (string): {'Any'} | 'Square' | 'Rectangle'

This parameter controls shape of the selection.
Specifying 'Square' or 'Rectangle' you prevent user from
selecting other shape.
By specifying 'Any' or omitting 'AllowedShape' at all
user is allowed to select any shape.

SelectionMode (string): {'Free'} | 'Centered'

This parameter controls selection mode.
But in this case user still can select other mode.

FastReturn (string): {'off'} | 'on'

This parameter controls how the GUI behaves when user finishes
seletion.
When 'off' value provided function waits for user to press
"DONE" button, allowing user to change selection by
"START OVER" button.
When 'on' value provided function returns immediately after user
makes valid selection of second point. In this case it is also
possible to change selection, but only until the second point was
NOT selected by user.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Examples
======
ROI = imSelectROI( 'c:\Image.jpg');
[ROI,SelImage] = imSelectROI( 'c:\Image.jpg', 'AllowedShape','Square');

% FNames is a cell array of image file names
ROI = imSelectROI( FNames{1} );
for i=1:length(FNames)
image = imread(FNames{i}); %whole image
selection = image( ROI.Xrange, ROI.Yrange, :); %selected area
...
end
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional info
===============
help imshow for additional information on what can be passed
to imSelectROI as first argument.