annotate scripts/image/imwrite.m @ 16988:54b75bed4bc7

imwrite: implement WriteMode option. * imwrite.m: document the new option WriteMode and possibility to write multipage images by passing a 4 dimensional matrix. * private/core_imwrite.m: perform input check for the quality option and the new writemode. Set defaults here and not on __magick_write__(). Give warning about the fact that writing of indexed images is not properly implemented. Change calling to ind2rgb() since it has been there and we no longer need workaround. Remove the different calls to __magick_read__() since we now have a single way to do it. Remove conversion of image types since we want to save what was actually given to us. * __magick_read__.cc (read_file): split from __magick_read__() into a separate function so it can be used by __magick_write__() when appending images to an existing file. (jpg_settings): remove function. It only checks for the quality option, which is now done by core_imwrite(). Plus, other formats support this option so it was moved into __magick_write__(). We should have functions for each option rather than per file format. (encode_map): comment whole function since it is never used and is unfinished work to implement writing of actual indexed images. (write_file): new function from part of previous write_image(). It is now the other side of read_file(). (write_image): remove function. Moved into __magick_write__(), the only function calling it. The part of writing moved into write_file(). (__magick_write__): removed most of input check which should be done by imwrite(). Removed all extra usage types. Options must be passed on a non-optional struct. Implement the Append option.
author Carnë Draug <carandraug@octave.org>
date Tue, 16 Jul 2013 17:29:45 +0100
parents ee2166121a28
children 3db796f89695
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14138
72c96de7a403 maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents: 11591
diff changeset
1 ## Copyright (C) 2008-2012 John W. Eaton
16948
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
2 ## Copyright (C) 2013 Carnë Draug
7987
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
3 ##
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
4 ## This file is part of Octave.
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
5 ##
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
6 ## Octave is free software; you can redistribute it and/or modify it
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
7 ## under the terms of the GNU General Public License as published by
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
8 ## the Free Software Foundation; either version 3 of the License, or (at
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
9 ## your option) any later version.
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
10 ##
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
11 ## Octave is distributed in the hope that it will be useful, but
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
14 ## General Public License for more details.
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
15 ##
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
16 ## You should have received a copy of the GNU General Public License
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
17 ## along with Octave; see the file COPYING. If not, see
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
18 ## <http://www.gnu.org/licenses/>.
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
19
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
20 ## -*- texinfo -*-
10891
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
21 ## @deftypefn {Function File} {} imwrite (@var{img}, @var{filename})
16944
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
22 ## @deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{ext})
16988
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
23 ## @deftypefnx {Function File} {} imwrite (@var{img}, @var{map}, @var{filename})
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
24 ## @deftypefnx {Function File} {} imwrite (@dots{}, @var{param1}, @var{val1}, @dots{})
7987
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
25 ## Write images in various file formats.
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
26 ##
16988
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
27 ## The image @var{img} can be a binary, grayscale, RGB, or multidimensional
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
28 ## image. The size and class of @var{img} should be the same as what should
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
29 ## be expected when reading it with @code{imread}: the 3rd and 4th dimensions
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
30 ## reserved for colorspace, and multiple pages respectively. If it's an
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
31 ## indexed image, the colormap @var{map} must also be specified.
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
32 ##
16944
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
33 ## If @var{ext} is not supplied, the file extension of @var{filename} is used
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
34 ## to determine the format. The actual supported formats are dependent on
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
35 ## options made during the build of Octave. Use @code{imformats} to check
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
36 ## the support of the different image formats.
7987
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
37 ##
16988
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
38 ## Depending on the file format, it is possible to configure the writing
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
39 ## of images with @var{param}, @var{val} pairs. The following options
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
40 ## are supported:
8148
213dd524f96b Improve documentation for image I/O.
sh@sh-laptop
parents: 8054
diff changeset
41 ##
213dd524f96b Improve documentation for image I/O.
sh@sh-laptop
parents: 8054
diff changeset
42 ## @table @samp
213dd524f96b Improve documentation for image I/O.
sh@sh-laptop
parents: 8054
diff changeset
43 ## @item Quality
10891
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
44 ## Set the quality of the compression. The value should be an
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
45 ## integer between 0 and 100, with larger values indicating higher visual
16988
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
46 ## quality and lower compression. Defaults to 75.
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
47 ##
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
48 ## @item WriteMode
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
49 ## Some file formats, such as TIFF and GIF, are able to store multiple
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
50 ## images in a single file. This option specifies if @var{img} should be
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
51 ## appended to the file (if it exists) or if a new file should be created
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
52 ## for it (possibly overwriting an existing file). The value should be
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
53 ## the string "Overwrite" (default), or "Append".
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
54 ##
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
55 ## Despite this option, the most efficient method of writing a multipage
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
56 ## image is to pass a 4 dimensional @var{img} to @code{imwrite}, the
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
57 ## same matrix that could be expected when using @code{imread} with the
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
58 ## option "Index" set to "all".
54b75bed4bc7 imwrite: implement WriteMode option.
Carnë Draug <carandraug@octave.org>
parents: 16948
diff changeset
59 ##
8148
213dd524f96b Improve documentation for image I/O.
sh@sh-laptop
parents: 8054
diff changeset
60 ## @end table
213dd524f96b Improve documentation for image I/O.
sh@sh-laptop
parents: 8054
diff changeset
61 ##
16944
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
62 ## @seealso{imread, imfinfo, imformats}
7987
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
63 ## @end deftypefn
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
64
16916
59f575e504dc Connect imwrite with imformats.
Carnë Draug <carandraug@octave.org>
parents: 15714
diff changeset
65 function imwrite (varargin)
59f575e504dc Connect imwrite with imformats.
Carnë Draug <carandraug@octave.org>
parents: 15714
diff changeset
66 if (nargin < 2)
10891
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
67 print_usage ();
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
68 endif
16948
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
69 [filename, ext] = imwrite_filename (varargin{2:end});
10891
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
70
16948
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
71 fmt = imformats (ext);
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
72 ## When there is no match, fmt will be a 1x1 structure with
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
73 ## no fields, so we can't just use `isempty (fmt)'.
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
74 if (isempty (fieldnames (fmt)))
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
75 if (isempty (ext))
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
76 error ("imwrite: no extension found for %s to identify the image format",
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
77 filename);
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
78 endif
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
79 warning ("imwrite: unlisted image format %s (see imformats). Trying to save anyway.",
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
80 ext);
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
81 core_imwrite (varargin{:});
7987
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
82 else
16948
ee2166121a28 imwrite: clean up finding of filename and its connection to imformats.
Carnë Draug <carandraug@octave.org>
parents: 16944
diff changeset
83 fmt.write (varargin{:});
16944
1b3b3ee88284 Add optional extension argument to image IO functions.
Carnë Draug <carandraug@octave.org>
parents: 16916
diff changeset
84 endif
7987
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
85
4a423a042971 add imwrite.m
John W. Eaton <jwe@octave.org>
parents:
diff changeset
86 endfunction
10891
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
87
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
88 %% Test input validation
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
89 %!error imwrite () # Wrong # of args
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
90 %!error imwrite (1) # Wrong # of args
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
91 %!error imwrite ({"cell"}, "filename.jpg") # Wrong class for img
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
92 %!error imwrite (1, [], "filename.jpg") # Empty image map
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
93 %!error imwrite (1, 2, 3) # No filename specified
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
94 %!error imwrite (1, "filename") # No fmt specified
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
95 %!error imwrite (1, "filename", "junk") # Invalid fmt specified
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
96 %!error imwrite ([], "filename.jpg") # Empty img matrix
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
97 %!error imwrite (spones (2), "filename.jpg") # Invalid sparse img
10891
ff94219746bd imwrite.m: Allow writing of 1-bit (B&W) images.
Rik <octave@nomad.inbox5.com>
parents: 10793
diff changeset
98