blob: 1e8b2aaa9bdb1d2b4e168d69330b3c61f781b3fc [file] [log] [blame]
Guido van Rossum470be141995-03-17 16:07:09 +00001\section{Built-in Module \sectcode{imgfile}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00002\bimodindex{imgfile}
3
4The imgfile module allows python programs to access SGI imglib image
5files (also known as \file{.rgb} files). The module is far from
6complete, but is provided anyway since the functionality that there is
7is enough in some cases. Currently, colormap files are not supported.
8
9The module defines the following variables and functions:
10
11\renewcommand{\indexsubitem}{(in module imgfile)}
12\begin{excdesc}{error}
13This exception is raised on all errors, such as unsupported file type, etc.
14\end{excdesc}
15
16\begin{funcdesc}{getsizes}{file}
17This function returns a tuple \code{(\var{x}, \var{y}, \var{z})} where
18\var{x} and \var{y} are the size of the image in pixels and
19\var{z} is the number of
20bytes per pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels
21are currently supported.
22\end{funcdesc}
23
24\begin{funcdesc}{read}{file}
25This function reads and decodes the image on the specified file, and
26returns it as a python string. The string has either 1 byte greyscale
27pixels or 4 byte RGBA pixels. The bottom left pixel is the first in
28the string. This format is suitable to pass to \code{gl.lrectwrite},
29for instance.
30\end{funcdesc}
31
Guido van Rossum16d6e711994-08-08 12:30:22 +000032\begin{funcdesc}{readscaled}{file\, x\, y\, filter\optional{\, blur}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000033This function is identical to read but it returns an image that is
34scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and
35\var{blur} parameters are omitted scaling is done by
36simply dropping or duplicating pixels, so the result will be less than
37perfect, especially for computer-generated images.
38
39Alternatively, you can specify a filter to use to smoothen the image
40after scaling. The filter forms supported are \code{'impulse'},
41\code{'box'}, \code{'triangle'}, \code{'quadratic'} and
42\code{'gaussian'}. If a filter is specified \var{blur} is an optional
43parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
44
Guido van Rossum16d6e711994-08-08 12:30:22 +000045\code{readscaled} makes no
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000046attempt to keep the aspect ratio correct, so that is the users'
47responsibility.
48\end{funcdesc}
49
50\begin{funcdesc}{ttob}{flag}
51This function sets a global flag which defines whether the scan lines
52of the image are read or written from bottom to top (flag is zero,
53compatible with SGI GL) or from top to bottom(flag is one,
54compatible with X). The default is zero.
55\end{funcdesc}
56
57\begin{funcdesc}{write}{file\, data\, x\, y\, z}
58This function writes the RGB or greyscale data in \var{data} to image
59file \var{file}. \var{x} and \var{y} give the size of the image,
60\var{z} is 1 for 1 byte greyscale images or 3 for RGB images (which are
61stored as 4 byte values of which only the lower three bytes are used).
62These are the formats returned by \code{gl.lrectread}.
63\end{funcdesc}