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