Mercurial > octave-antonio
view scripts/image/imwrite.m @ 20158:7503499a252b stable
doc: Update docstrings to have one sentence summary as first line.
Update scripts in audio, elfun, general, geometry, and image directories.
* scripts/audio/@audioplayer/__get_properties__.m,
scripts/audio/@audioplayer/audioplayer.m, scripts/audio/@audioplayer/get.m,
scripts/audio/@audioplayer/isplaying.m, scripts/audio/@audioplayer/play.m,
scripts/audio/@audioplayer/playblocking.m, scripts/audio/@audioplayer/set.m,
scripts/audio/@audioplayer/subsasgn.m, scripts/audio/@audioplayer/subsref.m,
scripts/audio/@audiorecorder/audiorecorder.m,
scripts/audio/@audiorecorder/get.m,
scripts/audio/@audiorecorder/getaudiodata.m,
scripts/audio/@audiorecorder/getplayer.m,
scripts/audio/@audiorecorder/isrecording.m,
scripts/audio/@audiorecorder/play.m, scripts/audio/@audiorecorder/record.m,
scripts/audio/@audiorecorder/recordblocking.m,
scripts/audio/@audiorecorder/set.m, scripts/audio/@audiorecorder/stop.m,
scripts/audio/@audiorecorder/subsasgn.m,
scripts/audio/@audiorecorder/subsref.m, scripts/audio/lin2mu.m,
scripts/audio/mu2lin.m, scripts/audio/record.m, scripts/audio/sound.m,
scripts/audio/soundsc.m, scripts/audio/wavread.m, scripts/audio/wavwrite.m,
scripts/elfun/cosd.m, scripts/elfun/sind.m, scripts/elfun/tand.m,
scripts/general/accumarray.m, scripts/general/accumdim.m,
scripts/general/bitcmp.m, scripts/general/bitget.m, scripts/general/bitset.m,
scripts/general/blkdiag.m, scripts/general/cart2pol.m,
scripts/general/cart2sph.m, scripts/general/cell2mat.m,
scripts/general/celldisp.m, scripts/general/chop.m,
scripts/general/circshift.m, scripts/general/common_size.m,
scripts/general/cplxpair.m, scripts/general/cumtrapz.m,
scripts/general/dblquad.m, scripts/general/deal.m, scripts/general/del2.m,
scripts/general/display.m, scripts/general/divergence.m,
scripts/general/fieldnames.m, scripts/general/flip.m,
scripts/general/flipdim.m, scripts/general/fliplr.m, scripts/general/flipud.m,
scripts/general/gradient.m, scripts/general/interp3.m,
scripts/general/interpft.m, scripts/general/interpn.m,
scripts/general/loadobj.m, scripts/general/logspace.m,
scripts/general/methods.m, scripts/general/nargchk.m,
scripts/general/narginchk.m, scripts/general/nargoutchk.m,
scripts/general/nextpow2.m, scripts/general/nthargout.m,
scripts/general/num2str.m, scripts/general/pol2cart.m,
scripts/general/polyarea.m, scripts/general/postpad.m,
scripts/general/prepad.m, scripts/general/profile.m, scripts/general/quadgk.m,
scripts/general/quadl.m, scripts/general/quadv.m, scripts/general/randi.m,
scripts/general/rat.m, scripts/general/repmat.m, scripts/general/rot90.m,
scripts/general/rotdim.m, scripts/general/saveobj.m, scripts/general/shift.m,
scripts/general/shiftdim.m, scripts/general/sortrows.m,
scripts/general/sph2cart.m, scripts/general/structfun.m,
scripts/general/subsindex.m, scripts/general/trapz.m,
scripts/general/triplequad.m, scripts/geometry/delaunayn.m,
scripts/geometry/dsearch.m, scripts/geometry/dsearchn.m,
scripts/geometry/griddata.m, scripts/geometry/griddata3.m,
scripts/geometry/griddatan.m, scripts/geometry/inpolygon.m,
scripts/geometry/rectint.m, scripts/geometry/tsearchn.m,
scripts/geometry/voronoi.m, scripts/geometry/voronoin.m,
scripts/help/__unimplemented__.m, scripts/help/doc.m,
scripts/help/doc_cache_create.m, scripts/help/get_first_help_sentence.m,
scripts/help/help.m, scripts/help/lookfor.m, scripts/help/print_usage.m,
scripts/help/type.m, scripts/help/which.m, scripts/image/autumn.m,
scripts/image/bone.m, scripts/image/brighten.m, scripts/image/cmpermute.m,
scripts/image/colorcube.m, scripts/image/contrast.m, scripts/image/cool.m,
scripts/image/copper.m, scripts/image/cubehelix.m, scripts/image/flag.m,
scripts/image/gmap40.m, scripts/image/gray.m, scripts/image/gray2ind.m,
scripts/image/hot.m, scripts/image/hsv.m, scripts/image/image.m,
scripts/image/imagesc.m, scripts/image/imfinfo.m, scripts/image/imformats.m,
scripts/image/imread.m, scripts/image/imshow.m, scripts/image/imwrite.m,
scripts/image/iscolormap.m, scripts/image/jet.m, scripts/image/lines.m,
scripts/image/ntsc2rgb.m, scripts/image/ocean.m, scripts/image/pink.m,
scripts/image/prism.m, scripts/image/rainbow.m, scripts/image/rgb2ntsc.m,
scripts/image/spinmap.m, scripts/image/spring.m, scripts/image/summer.m,
scripts/image/white.m, scripts/image/winter.m:
Update docstrings to have one sentence summary as first line.
Re-structure to have line lengths <= 80 chars.
author | Rik <rik@octave.org> |
---|---|
date | Sun, 03 May 2015 09:36:20 -0700 |
parents | 9fc020886ae9 |
children |
line wrap: on
line source
## Copyright (C) 2008-2015 John W. Eaton ## Copyright (C) 2013-2015 Carnë Draug ## ## This file is part of Octave. ## ## Octave is free software; you can redistribute it and/or modify it ## under the terms of the GNU General Public License as published by ## the Free Software Foundation; either version 3 of the License, or (at ## your option) any later version. ## ## Octave is distributed in the hope that it will be useful, but ## WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ## General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with Octave; see the file COPYING. If not, see ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- ## @deftypefn {Function File} {} imwrite (@var{img}, @var{filename}) ## @deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{ext}) ## @deftypefnx {Function File} {} imwrite (@var{img}, @var{map}, @var{filename}) ## @deftypefnx {Function File} {} imwrite (@dots{}, @var{param1}, @var{val1}, @dots{}) ## Write images in various file formats. ## ## The image @var{img} can be a binary, grayscale, RGB, or multi-dimensional ## image. The size and class of @var{img} should be the same as what should ## be expected when reading it with @code{imread}: the 3rd and 4th dimensions ## reserved for color space, and multiple pages respectively. If it's an ## indexed image, the colormap @var{map} must also be specified. ## ## If @var{ext} is not supplied, the file extension of @var{filename} is used ## to determine the format. The actual supported formats are dependent on ## options made during the build of Octave. Use @code{imformats} to check ## the support of the different image formats. ## ## Depending on the file format, it is possible to configure the writing of ## images with @var{param}, @var{val} pairs. The following options are ## supported: ## ## @table @samp ## @item Alpha ## Alpha (transparency) channel for the image. This must be a matrix with ## same class, and number of rows and columns of @var{img}. In case of a ## multipage image, the size of the 4th dimension must also match and the third ## dimension must be a singleton. By default, image will be completely opaque. ## ## @item DelayTime ## For formats that accept animations (such as GIF), controls for how long a ## frame is displayed until it moves to the next one. The value must be scalar ## (which will applied to all frames in @var{img}), or a vector of length ## equal to the number of frames in @var{im}. The value is in seconds, must ## be between 0 and 655.35, and defaults to 0.5. ## ## @item DisposalMethod ## For formats that accept animations (such as GIF), controls what happens to ## a frame before drawing the next one. Its value can be one of the ## following strings: "doNotSpecify" (default); "leaveInPlace"; "restoreBG"; ## and "restorePrevious", or a cell array of those string with length equal ## to the number of frames in @var{img}. ## ## @item LoopCount ## For formats that accept animations (such as GIF), controls how many times ## the sequence is repeated. A value of Inf means an infinite loop (default), ## a value of 0 or 1 that the sequence is played only once (loops zero times), ## while a value of 2 or above loops that number of times (looping twice means ## it plays the complete sequence 3 times). This option is ignored when there ## is only a single image at the end of writing the file. ## ## @item Quality ## Set the quality of the compression. The value should be an integer ## between 0 and 100, with larger values indicating higher visual quality and ## lower compression. Defaults to 75. ## ## @item WriteMode ## Some file formats, such as TIFF and GIF, are able to store multiple images ## in a single file. This option specifies if @var{img} should be appended ## to the file (if it exists) or if a new file should be created for it ## (possibly overwriting an existing file). The value should be the string ## @qcode{"Overwrite"} (default), or @qcode{"Append"}. ## ## Despite this option, the most efficient method of writing a multipage ## image is to pass a 4 dimensional @var{img} to @code{imwrite}, the same ## matrix that could be expected when using @code{imread} with the option ## @qcode{"Index"} set to @qcode{"all"}. ## ## @end table ## ## @seealso{imread, imfinfo, imformats} ## @end deftypefn function imwrite (varargin) if (nargin < 2) print_usage (); endif [filename, ext] = imwrite_filename (varargin{2:end}); fmt = imformats (ext); ## When there is no match, fmt will be a 1x1 structure with ## no fields, so we can't just use `isempty (fmt)'. if (numfields (fmt) == 0) if (isempty (ext)) error ("imwrite: no extension found for %s to identify the image format", filename); endif warning ("imwrite: unlisted image format %s (see imformats). Trying to save anyway.", ext); __imwrite__ (varargin{:}); else fmt.write (varargin{:}); endif endfunction ## Test input validation %!error imwrite () # Wrong # of args %!error imwrite (1) # Wrong # of args %!error imwrite ({"cell"}, "filename.jpg") # Wrong class for img %!error imwrite (1, [], "filename.jpg") # Empty image map %!error imwrite (1, 2, 3) # No filename specified %!error imwrite (1, "filename") # No fmt specified %!error imwrite (1, "filename", "junk") # Invalid fmt specified %!error imwrite ([], "filename.jpg") # Empty img matrix %!error imwrite (spones (2), "filename.jpg") # Invalid sparse img %!function [r, cmap, a] = write_and_read (format, varargin) %! filename = [tempname() format]; %! unwind_protect %! imwrite (varargin{1}, filename, varargin{2:end}); %! [r, cmap, a] = imread (filename, "Index", "all"); %! unwind_protect_cleanup %! unlink (filename); %! end_unwind_protect %!endfunction ## typical usage with grayscale uint8 images %!testif HAVE_MAGICK %! gray = randi (255, 10, 10, 1, "uint8"); %! r = write_and_read (".tif", gray); %! assert (r, gray) ## grayscale uint8 images with alpha channel %!testif HAVE_MAGICK %! gray = randi (255, 10, 10, 1, "uint8"); %! alpha = randi (255, 10, 10, 1, "uint8"); %! [r, ~, a] = write_and_read (".tif", gray, "Alpha", alpha); %! assert (r, gray) %! assert (a, alpha) ## multipage grayscale uint8 images %!testif HAVE_MAGICK %! gray = randi (255, 10, 10, 1, 5, "uint8"); %! r = write_and_read (".tif", gray); %! assert (r, gray) ## multipage RGB uint8 images with alpha channel %!testif HAVE_MAGICK %! gray = randi (255, 10, 10, 3, 5, "uint8"); %! alpha = randi (255, 10, 10, 1, 5, "uint8"); %! [r, ~, a] = write_and_read (".tif", gray, "Alpha", alpha); %! assert (r, gray) %! assert (a, alpha) ## typical usage with RGB uint8 images %!testif HAVE_MAGICK %! rgb = randi (255, 10, 10, 3, "uint8"); %! r = write_and_read (".tif", rgb); %! assert (r, rgb) ## RGB uint8 images with alpha channel %!testif HAVE_MAGICK %! rgb = randi (255, 10, 10, 3, "uint8"); %! alpha = randi (255, 10, 10, 1, "uint8"); %! [r, ~, a] = write_and_read (".tif", rgb, "Alpha", alpha); %! assert (r, rgb) %! assert (a, alpha) ## multipage RGB uint8 images %!testif HAVE_MAGICK %! rgb = randi (255, 10, 10, 3, 5, "uint8"); %! r = write_and_read (".tif", rgb); %! assert (r, rgb) ## multipage RGB uint8 images with alpha channel %!testif HAVE_MAGICK %! rgb = randi (255, 10, 10, 3, 5, "uint8"); %! alpha = randi (255, 10, 10, 1, 5, "uint8"); %! [r, ~, a] = write_and_read (".tif", rgb, "Alpha", alpha); %! assert (r, rgb) %! assert (a, alpha) %!testif HAVE_MAGICK %! gray = repmat (uint8 (0:255), 100, 1); %! [g] = write_and_read (".jpeg", gray); %! assert (g, gray, 2) %!testif HAVE_MAGICK %! gray = repmat (uint8 (0:255), 100, 1); %! [g] = write_and_read (".jpeg", gray, "quality", 100); %! assert (g, gray)