octave_packages/m/image/imfinfo.m

   1 ## Copyright (C) 2008-2012 Soren Hauberg <hauberg@gmail.com>
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {@var{info} =} imfinfo (@var{filename})
  21 ## @deftypefnx {Function File} {@var{info} =} imfinfo (@var{url})
  22 ## Read image information from a file.
  23 ##
  24 ## @code{imfinfo} returns a structure containing information about the image
  25 ## stored in the file @var{filename}.  The output structure contains the
  26 ## following fields.
  27 ##
  28 ## @table @samp
  29 ## @item Filename
  30 ## The full name of the image file.
  31 ##
  32 ## @item FileSize
  33 ## Number of bytes of the image on disk
  34 ##
  35 ## @item FileModDate
  36 ## Date of last modification to the file.
  37 ##
  38 ## @item Height
  39 ## Image height in pixels.
  40 ##
  41 ## @item Width
  42 ## Image Width in pixels.
  43 ##
  44 ## @item BitDepth
  45 ## Number of bits per channel per pixel.
  46 ##
  47 ## @item Format
  48 ## Image format (e.g., @code{"jpeg"}).
  49 ##
  50 ## @item LongFormat
  51 ## Long form image format description.
  52 ##
  53 ## @item XResolution
  54 ## X resolution of the image.
  55 ##
  56 ## @item YResolution
  57 ## Y resolution of the image.
  58 ##
  59 ## @item TotalColors
  60 ## Number of unique colors in the image.
  61 ##
  62 ## @item TileName
  63 ## Tile name.
  64 ##
  65 ## @item AnimationDelay
  66 ## Time in 1/100ths of a second (0 to 65535) which must expire before displaying
  67 ## the next image in an animated sequence.
  68 ##
  69 ## @item AnimationIterations
  70 ## Number of iterations to loop an animation (e.g., Netscape loop extension)
  71 ## for.
  72 ##
  73 ## @item ByteOrder
  74 ## Endian option for formats that support it.  Is either @code{"little-endian"},
  75 ## @code{"big-endian"}, or @code{"undefined"}.
  76 ##
  77 ## @item Gamma
  78 ## Gamma level of the image.  The same color image displayed on two different
  79 ## workstations may look different due to differences in the display monitor.
  80 ##
  81 ## @item Matte
  82 ## @code{true} if the image has transparency.
  83 ##
  84 ## @item ModulusDepth
  85 ## Image modulus depth (minimum number of bits required to support
  86 ## red/green/blue
  87 ## components without loss of accuracy).
  88 ##
  89 ## @item Quality
  90 ## JPEG/MIFF/PNG compression level.
  91 ##
  92 ## @item QuantizeColors
  93 ## Preferred number of colors in the image.
  94 ##
  95 ## @item ResolutionUnits
  96 ## Units of image resolution.  Is either @code{"pixels per inch"},
  97 ## @code{"pixels per centimeter"}, or @code{"undefined"}.
  98 ##
  99 ## @item ColorType
 100 ## Image type.  Is either @code{"grayscale"}, @code{"indexed"},
 101 ## @code{"truecolor"},
 102 ## or @code{"undefined"}.
 103 ##
 104 ## @item View
 105 ## FlashPix viewing parameters.
 106 ## @end table
 107 ##
 108 ## @seealso{imread, imwrite}
 109 ## @end deftypefn
 110
 111 function info = imfinfo (filename)
 112
 113   if (nargin < 1)
 114     print_usage ();
 115   endif
 116
 117   if (!ischar (filename))
 118     error ("imfinfo: FILENAME must be a string");
 119   endif
 120
 121   filename = tilde_expand (filename);
 122
 123   delete_file = false;
 124
 125   unwind_protect
 126
 127     fn = file_in_path (IMAGE_PATH, filename);
 128
 129     if (isempty (fn))
 130
 131       ## Couldn't find file. See if it's an URL.
 132
 133       tmp = tmpnam ();
 134
 135       [fn, status, msg] = urlwrite (filename, tmp);
 136
 137       if (! status)
 138         error ("imfinfo: cannot find %s", filename);
 139       endif
 140
 141       if (! isempty (fn))
 142         delete_file = true;
 143       endif
 144
 145     endif
 146
 147     info = __magick_finfo__ (fn);
 148
 149   unwind_protect_cleanup
 150
 151     if (delete_file)
 152       unlink (fn);
 153     endif
 154
 155   end_unwind_protect
 156
 157 endfunction