annotate scripts/image/private/__imread__.m @ 27919:1891570abac8

update Octave Project Developers copyright for the new year In files that have the "Octave Project Developers" copyright notice, update for 2020.
author John W. Eaton <jwe@octave.org>
date Mon, 06 Jan 2020 22:29:51 -0500
parents b442ec6dda5c
children bd51beb6205e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27919
1891570abac8 update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 27918
diff changeset
1 ## Copyright (C) 2002-2020 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 27216
diff changeset
2 ##
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 27216
diff changeset
3 ## See the file COPYRIGHT.md in the top-level directory of this distribution
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 27216
diff changeset
4 ## or <https://octave.org/COPYRIGHT.html/>.
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 27216
diff changeset
5 ##
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
6 ##
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
7 ## This file is part of Octave.
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
8 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
9 ## Octave is free software: you can redistribute it and/or modify it
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
10 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
11 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
12 ## (at your option) any later version.
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
13 ##
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
14 ## Octave is distributed in the hope that it will be useful, but
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
15 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
16 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## GNU General Public License for more details.
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
18 ##
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
19 ## You should have received a copy of the GNU General Public License
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
20 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
21 ## <https://www.gnu.org/licenses/>.
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
22
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
23 ## This function does all the work of imread. It exists here as private
16944
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16915
diff changeset
24 ## function so that imread can use other functions if imformats is
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
25 ## configured to. It is also needed so that imformats can create a
16944
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16915
diff changeset
26 ## function handle for it.
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16915
diff changeset
27
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16915
diff changeset
28 ## Author: Carnë Draug <carandraug@octave.org>
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
29 ## Author: Thomas L. Scofield <scofield@calvin.edu>
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
30 ## Author: Kristian Rumberg <kristianrumberg@gmail.com>
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
31 ## Author: Thomas Weber <thomas.weber.mail@gmail.com>
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
32 ## Author: Stefan van der Walt <stefan@sun.ac.za>
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
33 ## Author: Andy Adler
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
34
17086
3db796f89695 Rename private core_imfnc functions to follow the __fnc__ convention style.
Carnë Draug <carandraug@octave.org>
parents: 16984
diff changeset
35 function varargout = __imread__ (filename, varargin)
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
36
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
37 ## keep track of the varargin offset we're looking at each moment
21568
3d60ed163b70 maint: Eliminate bad spacing around '='.
Rik <rik@octave.org>
parents: 20735
diff changeset
38 offset = 1;
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
39
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
40 ## It is possible for a file with multiple pages to have very different
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
41 ## images on each page. Specifically, they may have different sizes.
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
42 ## Because of this, we need to first find out the index of the images to read
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
43 ## so we can set up defaults for things such as PixelRegion later on.
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
44 options = struct ("index", 1); # default image index
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
45
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
46 ## Index is the only option that can be defined without the parameter/value
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
47 ## pair style. When defined here, the string "all" is invalid.
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
48 ## Also, for Matlab compatibility, if index is defined both as an option here
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
49 ## and parameter/value pair, silently ignore the first.
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
50 if (nargin >= 2 && ! ischar (varargin{1}))
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
51 options.index = varargin{1};
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
52 if (! is_valid_index_option (options.index))
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
53 error ("imread: IDX must be a numeric vector");
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
54 endif
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
55 offset = 2;
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
56 endif
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
57
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
58 if (rem (numel (varargin) - offset + 1, 2) != 0)
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
59 error ("imread: PARAM/VALUE arguments must occur in pairs");
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
60 endif
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
61
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
62 ## Check for Index/Frames argument
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
63 idx = strcmpi ("index", varargin) | strcmpi ("frames", varargin);
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
64 if (any (idx))
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
65 if (sum (idx) > 1)
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
66 error ("imread: Index or Frames may only be specified once");
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
67 endif
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
68 val = varargin{shift (idx, 1)};
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
69 if (! is_valid_index_option (val) && ! strcmpi (val, "all"))
27216
823b4bcf79fc unless necessary for formatting or code, use ' instead of `
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
70 error ("imread: %s must be a vector or the string 'all'", varargin{idx});
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
71 endif
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
72 options.index = val;
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
73 endif
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
74
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
75 ## Use information from the first image to be read to set defaults.
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
76 if (strcmpi (options.index, "all"))
18298
15db54c4a572 Fix input parsing for imageIO functions and make imread accept URL (bug #41234)
Carnë Draug <carandraug@octave.org>
parents: 18144
diff changeset
77 info = __magick_ping__ (filename, 1);
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
78 else
18298
15db54c4a572 Fix input parsing for imageIO functions and make imread accept URL (bug #41234)
Carnë Draug <carandraug@octave.org>
parents: 18144
diff changeset
79 info = __magick_ping__ (filename, options.index(1));
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
80 endif
17240
d757c98636d8 Use first image to be read rather than first image in file to set defaults.
Carnë Draug <carandraug@octave.org>
parents: 17227
diff changeset
81
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
82 ## Set default for options.
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
83 options.region = {1:1:info.rows, 1:1:info.columns};
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
84
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
85 for idx = offset:2:(numel (varargin) - offset + 1)
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
86 switch (tolower (varargin{idx}))
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
87
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
88 case {"frames", "index"}
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
89 ## Do nothing. This option was already processed before the loop.
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
90
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
91 case "pixelregion"
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
92 options.region = varargin{idx+1};
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
93 if (! iscell (options.region) || numel (options.region) != 2)
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
94 error ("imread: %s must be a 2-element cell array",
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
95 varargin{idx});
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
96 endif
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
97 for reg_idx = 1:2
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
98 if (numel (options.region{reg_idx}) == 3)
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
99 ## do nothing
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
100 elseif (numel (options.region{reg_idx}) == 2)
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
101 options.region{reg_idx}(3) = options.region{reg_idx}(2);
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
102 options.region{reg_idx}(2) = 1;
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
103 else
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
104 error ("imread: range for %s must be a 2 or 3 element vector",
17118
c97a26408ee0 Implement PixelRegion option for imread().
Carnë Draug <carandraug@octave.org>
parents: 17086
diff changeset
105 varargin{idx});
c97a26408ee0 Implement PixelRegion option for imread().
Carnë Draug <carandraug@octave.org>
parents: 17086
diff changeset
106 endif
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
107 options.region{reg_idx} = floor (options.region{reg_idx}(1)): ...
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
108 floor (options.region{reg_idx}(2)): ...
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
109 floor (options.region{reg_idx}(3));
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
110 endfor
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
111 if (options.region{1}(end) > info.rows)
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
112 error ("imread: end ROWS for PixelRegions option is larger than image height");
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
113 elseif (options.region{2}(end) > info.columns)
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
114 error ("imread: end COLS for PixelRegions option is larger than image width");
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
115 endif
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
116
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
117 case "info"
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
118 ## We ignore this option. This parameter exists in Matlab to
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
119 ## speed up the reading of multipage TIFF by passing a structure
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
120 ## that contains information about the start on the file of each
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
121 ## page. We can't control it through GraphicsMagic but at least
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
122 ## we allow to load multiple pages with one command.
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
123
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
124 otherwise
27216
823b4bcf79fc unless necessary for formatting or code, use ' instead of `
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
125 error ("imread: invalid PARAMETER '%s'", varargin{idx});
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
126
18143
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
127 endswitch
10dca690f46f Remove support for Octave's native image format.
Carnë Draug <carandraug@octave.org>
parents: 17917
diff changeset
128 endfor
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
129
18298
15db54c4a572 Fix input parsing for imageIO functions and make imread accept URL (bug #41234)
Carnë Draug <carandraug@octave.org>
parents: 18144
diff changeset
130 [varargout{1:nargout}] = __magick_read__ (filename, options);
16913
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
131
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
132 endfunction
d0558ee259ad Connect imread with imformats.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
133
21742
c86cacc3aaf4 imread: Clean up function and its private implementation.
Rik <rik@octave.org>
parents: 21568
diff changeset
134 ## Test if the value passed to the Index or Frames is valid. This option
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
135 ## can be defined in two places, but only in one place can it also be the
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
136 ## string "all"
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
137 function bool = is_valid_index_option (arg)
18144
b5970988ccff image/private/__imread__.m: simplify subfunction for argument check
Carnë Draug <carandraug@octave.org>
parents: 18143
diff changeset
138 bool = isvector (arg) && isnumeric (arg) && isreal (arg);
16984
997efb8d0b19 imread: implement options Index, Frames, and Info.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
139 endfunction