# HG changeset patch
# User Carnë Draug <carandraug@octave.org>
# Date 1396558896 -3600
# Node ID 1b6f5917ae4b99b3d3ac0f05d008becc66f4289d
# Parent  9597e00ed2dd0c1aa37366a301c42ef9227b6b9e
imread.m: expand documentation and add tests for the PixelRegion option.

diff -r 9597e00ed2dd -r 1b6f5917ae4b scripts/image/imread.m
--- a/scripts/image/imread.m	Tue Apr 01 20:57:08 2014 -0400
+++ b/scripts/image/imread.m	Thu Apr 03 22:01:36 2014 +0100
@@ -75,7 +75,17 @@
 ## Controls the image region that is read.  Takes as value a cell array
 ## with two arrays of 3 elements @code{@{@var{rows} @var{cols}@}}.  The
 ## elements in the array are the start, increment and end pixel to be
-## read.  If the increment value is omitted, defaults to 1.
+## read.  If the increment value is omitted, defaults to 1.  For example,
+## the following are all equivalent:
+##
+## @example
+## @group
+## imread (filename, "PixelRegion", @{[200 600] [300 700]@});
+## imread (filename, "PixelRegion", @{[200 1 600] [300 1 700]@});
+## imread (filename)(200:600, 300:700);
+## @end group
+## @end example
+##
 ## @end table
 ##
 ## @seealso{imwrite, imfinfo, imformats}
@@ -130,6 +140,24 @@
 %! assert (A(:,:,2), uint8 ([0, 255, 0; 255,  28, 255; 0, 255, 0]));
 %! assert (A(:,:,3), uint8 ([0, 255, 0; 255,  36, 255; 0, 255, 0]));
 
+%!function [r, cmap, a] = write_and_read (w, varargin)
+%!  filename = [tmpnam() ".tif"];
+%!  unwind_protect
+%!    imwrite (w, filename);
+%!    [r, cmap, a] = imread (filename, varargin{:});
+%!  unwind_protect_cleanup
+%!    unlink (filename);
+%!  end_unwind_protect
+%!endfunction
+
+## test PixelRegion option
+%!testif HAVE_MAGICK
+%! w = randi (255, 100, 100, "uint8");
+%! [r, cmap, a] = write_and_read (w, "PixelRegion", {[50 70] [20 40]});
+%! assert (r, w(50:70, 20:40))
+%! [r, cmap, a] = write_and_read (w, "PixelRegion", {[50 2 70] [20 3 40]});
+%! assert (r, w(50:2:70, 20:3:40))
+
 ## If a file does not exist, it's the job of imread to check the file
 ## exists before sending it over to __imread__ or whatever function
 ## is defined in imformats to handle that specific format.  This is the