\chapter{Getting Image information With {\kw iinfo}}
\label{chap:iinfo}
\indexapi{iinfo}

%\section{Overview}

The {\cf iinfo} program will print either basic information (name,
resolution, format) or detailed information (including all metadata)
found in images.  Because {\cf iinfo} is built on top on \product, it
will print information about images of any formats readable by
\ImageInput plugins on hand.



\section{Using {\cf iinfo}}

The {\cf iinfo} utility is invoked as follows:

\bigskip

\hspace{0.25in} {\cf iinfo} [\emph{options}] \emph{filename} ...

\medskip

Where \emph{filename} (and any following strings) names the image
file(s) whose information should be printed.  The image files may be of
any format recognized by \product (i.e., for which \ImageInput plugins
are available).

In its most basic usage, it simply prints the resolution, number of
channels, pixel data type, and file format type of each of the
files listed:

\begin{code}
    $ iinfo img_6019m.jpg grid.tif lenna.png

    img_6019m.jpg : 1024 x  683, 3 channel, uint8 jpeg
    grid.tif      :  512 x  512, 3 channel, uint8 tiff
    lenna.png     :  120 x  120, 4 channel, uint8 png
\end{code}

% $

The {\cf -s} flag also prints the uncompressed sizes of each image
file, plus a sum for all of the images:

\begin{code}
    $ iinfo -s img_6019m.jpg grid.tif lenna.png

    img_6019m.jpg : 1024 x  683, 3 channel, uint8 jpeg (2.00 MB)
    grid.tif      :  512 x  512, 3 channel, uint8 tiff (0.75 MB)
    lenna.png     :  120 x  120, 4 channel, uint8 png (0.05 MB)
    Total size: 2.81 MB
\end{code}

% $

The {\cf -v} option turns on \emph{verbose mode}, which exhaustively
prints all metadata about each image:

\begin{code}
    $ iinfo -v img_6019m.jpg

    img_6019m.jpg : 1024 x  683, 3 channel, uint8 jpeg
        channel list: R, G, B
        Color space: sRGB
        ImageDescription: "Family photo"
        Make: "Canon"
        Model: "Canon EOS DIGITAL REBEL XT"
        Orientation: 1 (normal)
        XResolution: 72
        YResolution: 72
        ResolutionUnit: 2 (inches)
        DateTime: "2008:05:04 19:51:19"
        Exif:YCbCrPositioning: 2
        ExposureTime: 0.004
        FNumber: 11
        Exif:ExposureProgram: 2 (normal program)
        Exif:ISOSpeedRatings: 400
        Exif:DateTimeOriginal: "2008:05:04 19:51:19"
        Exif:DateTimeDigitized: "2008:05:04 19:51:19"
        Exif:ShutterSpeedValue: 7.96579 (1/250 s)
        Exif:ApertureValue: 6.91887 (f/11)
        Exif:ExposureBiasValue: 0
        Exif:MeteringMode: 5 (pattern)
        Exif:Flash: 16 (no flash, flash supression)
        Exif:FocalLength: 27 (27 mm)
        Exif:ColorSpace: 1
        Exif:PixelXDimension: 2496
        Exif:PixelYDimension: 1664
        Exif:FocalPlaneXResolution: 2855.84
        Exif:FocalPlaneYResolution: 2859.11
        Exif:FocalPlaneResolutionUnit: 2 (inches)
        Exif:CustomRendered: 0 (no)
        Exif:ExposureMode: 0 (auto)
        Exif:WhiteBalance: 0 (auto)
        Exif:SceneCaptureType: 0 (standard)
        Keywords: "Carly; Jack"
\end{code}

% $

If the input file has multiple subimages, extra information summarizing
the subimages will be printed:

\begin{code}
    $ iinfo img_6019m.tx

    img_6019m.tx : 1024 x 1024, 3 channel, uint8 tiff (11 subimages)

    $ iinfo -v img_6019m.tx

    img_6019m.tx : 1024 x 1024, 3 channel, uint8 tiff
        11 subimages: 1024x1024 512x512 256x256 128x128 64x64 32x32 16x16 8x8 4x4 2x2 1x1 
        channel list: R, G, B
        tile size: 64 x 64
        ...
\end{code}

Furthermore, the {\cf -a} option will print information about all 
individual subimages:

\begin{code}
    $ iinfo -a ../sample-images/img_6019m.tx

    img_6019m.tx : 1024 x 1024, 3 channel, uint8 tiff (11 subimages)
     subimage  0: 1024 x 1024, 3 channel, uint8 tiff
     subimage  1:  512 x  512, 3 channel, uint8 tiff
     subimage  2:  256 x  256, 3 channel, uint8 tiff
     subimage  3:  128 x  128, 3 channel, uint8 tiff
     subimage  4:   64 x   64, 3 channel, uint8 tiff
     subimage  5:   32 x   32, 3 channel, uint8 tiff
     subimage  6:   16 x   16, 3 channel, uint8 tiff
     subimage  7:    8 x    8, 3 channel, uint8 tiff
     subimage  8:    4 x    4, 3 channel, uint8 tiff
     subimage  9:    2 x    2, 3 channel, uint8 tiff
     subimage 10:    1 x    1, 3 channel, uint8 tiff


    $ iinfo -v -a img_6019m.tx
    img_6019m.tx : 1024 x 1024, 3 channel, uint8 tiff
        11 subimages: 1024x1024 512x512 256x256 128x128 64x64 32x32 16x16 8x8 4x4 2x2 1x1 
     subimage  0: 1024 x 1024, 3 channel, uint8 tiff
        channel list: R, G, B
        tile size: 64 x 64
        ...
     subimage  1:  512 x  512, 3 channel, uint8 tiff
        channel list: R, G, B
        ...
    ...
\end{code}


\section{{\cf iinfo} command-line options}

\apiitem{--help}
Prints usage information to the terminal.
\apiend

\apiitem{-v}
Verbose output --- prints all metadata of the image files.
\apiend

\apiitem{-a}
Print information about all subimages in the file(s).
\apiend

\apiitem{-f}
Print the filename as a prefix to every line.  For example,

\begin{code}
    $ iinfo -v -f img_6019m.jpg

    img_6019m.jpg : 1024 x  683, 3 channel, uint8 jpeg
    img_6019m.jpg : channel list: R, G, B
    img_6019m.jpg : Color space: sRGB
    img_6019m.jpg : ImageDescription: "Family photo"
    img_6019m.jpg : Make: "Canon"
    ...
\end{code}
%$
\apiend

\apiitem{-m {\rm \emph{pattern}}}
Match the \emph{pattern} (specified as an extended regular expression)
against data metadata field names and print only data fields whose names
match.  The default is to print all data fields found in the file (if
{\cf -v} is given).

For example,
\begin{code}
    $ iinfo -v -f -m ImageDescription test*.jpg

    test3.jpg :     ImageDescription: "Birthday party"
    test4.jpg :     ImageDescription: "Hawaii vacation"
    test5.jpg :     ImageDescription: "Bob's graduation"
    test6.jpg :     ImageDescription: <unknown>
\end{code}
%$
\apiend

Note: the {\cf -m} option is probably not very useful without also using
the {\cf -v} and {\cf -f} options.

\apiitem{--hash}
Displays a SHA-1 hash of the pixel data of the image (and of each
subimage if combined with the {\cf -a} flag).
\apiend

\apiitem{-s}
Show the image sizes, including a sum of all the listed images.
\apiend

