#### 4.3.2 Image Objects

Image objects are used to specify pixmap data for either textures (see Texture Mapping), or for background images of cameras (see Camera objects).

At the time of this writing images are comprised of 1 to 4 channels, a channel provides a single number in the range from 0 to `maxval` for each pixel; and `maxval` is tied to 255. The interpretation of the image data depending on the number of channels is like follows:

#Channels | Channel No. | Interpretation
--- | --- | ---
1 | 1 | greyscale or luminance data
2 | 1 | greyscale or luminance data
| 2 | alpha channel (0: transparent, `maxval`: opaque)
3 | 1 | red channel
| 2 | green channel
| 3 | blue channel
4 | 1 | red channel
| 2 | green channel
| 3 | blue channel
| 4 | alpha channel (0: transparent, `maxval`: opaque)

Image data can be specified inline (embedded into the current data stream) or via file references; in both cases the data is read in and interpreted at the time the image object is parsed. This is different from the old (and deprecated) texture image specification, where the the image data on-disk would eventually be re-read by Geomview.

The general syntax of image objects is like follows:

         <image> ::=
           [ "{" ]             (curly brace, generally needed to make
                                the end of the object unambiguous.)
           [ "image" ]          (optional keyword; unnecessary if the type
                                is determined by the context, which it
                                usually is.)
           [ "define" <name> ]
                                (defines an image named <name>, setting
                                its value from the stuff which follows)
           |
               "<" <filename>   (meaning: read image from that file)
           |
               ":" <name>       (meaning: use variable name,
                                defined elsewhere; if undefined the image
                                carries no data)
           |
                                (actual stuff defining the image; image data
                                must come last, after defining the width and
                                height and number of channels)

               "width"          (width of the image, auto-detected from image data
                                if possible)

               "height"         (height of the image, auto-detected from image data
                                if possible)

               "channels"       (number of channels, auto-detected from image data
                                and data specifications, if possible)

               "maxval"         (unsupported, must be 255 if specified)

               "data DESTMASK [FILTER] [{] < FILENAME [}]"
               "data DESTMASK [FILTER] DATASIZE [{][\n]LITERAL_IMAGE_DATA[}]"
                                (either external or embedded image data, see below
                                for a detailed description of the meaning of
                                MASK and FILTER. An image can (and
                                has, in general) multiple data sections.)

           [ "}" ]             (matching curly brace)

Details concerning the image data specification:

``DESTMASK`'
  This is a bit-field describing where the specified image data should be placed in the destination pixmap. The bit-field is specified by an integer in one of the known formats (decimal, octal, hexadecimal). The channels of the source data are always enumbered consecutively. If, e.g. ``FILENAME`' or ``LITERAL_IMAGE_DATA`' specify a three-channel (probably RGB ...) image and ``DESTMASK`' equals `0xD` (i.e. bit 1 is 0), then the 3rd channel of the source pixmap would be placed in the 4th channel of the destination image object (the alpha channel), the 2nd source channel would determine the ``blue`' destination value and the 1st source channel the ``red`' destination value.

  The number of channels of the source data always has to match the number of bits set in ``DESTMASK`'. Exception: if the source pixmap has only one channel, then it can be used to fill any number of destination channels; all channels specified in ``DESTMASK`' are filled with the data of the single channel source pixmap.

  Geomview knows the following symbolic constants, which can be used instead of specifying the ``DESTMASK`' bit-field numerically:

  `LUMINANCE`
    same as ``1`', ``0x1`', ``\01`'
  `LUMINANCE_ALPHA`
    same as ``3`', ``0x3`', ``\03`'
  `RGB`
    same as ``7`', ``0x7`', ``\07`'
  `RGBA`
    same as ``15`', ``0xf`', ``\017`'
  `ALPHA`
    depends on the context: the absolute number of channels must be known; i.e. ``data ALPHA ...`' must be prepended by something determining the number of channels of the image, e.g.

                       ...
                       data RGB ...
                       data ALPHA
                       ...

    is valid, but

                       <no other channel or image data specification>
                       data ALPHA ...
                       <whatever else ...>

    is not valid, because Geomview has not means to determine the destination channel from the context.

  `AUTO`
    PGM image data is interpreted as single grey-scale channel, RGB PNM data as RGB image data. `AUTO` cannot work with ``raw`' image data.
``FILTER`'
  The ``FILTER`' specification is optional. If it is missing, then Geomview tries to determine the image type from the ``FILENAME`' suffix. If there is no suffix or the suffix is unknown, or for embedded image data, Geomview is able to auto-detectc SGI image file formats (for historical reasons ...) and NetPBM image formats (for practical reasons). The auto-detection of NetPBM formats includes the new PAM image format which allows (among other things) to store an alpha channel together with the luminance or RGB data. Likewise, the final output of any of the specified filters must either be in SGI image file format, or specify a PAM, PNM or PGM image. If the image file format cannot be determined by either the filenmae suffix or the filter specification or by auto-deteciong of SGI or NetPBM data, then Geomview assume that it is raw-data. See below.

  The decompression filters may be prepended to either one of the know image formats or an explicitly specified filter, e.g. the following is valid:

                data LUMINANCE raw.gzip { < gzippedgreymapfile }

  The above should be equivalent to

                data LUMINANCE raw { < greymapfile },

  provided that the decompressed data carries single channel data, with the first pixel corresponding to the lower-left corner (because of the ``raw`' image format, see below).

  Geomview has builtin knowledge for the following filters/suffixes:

  Data Decompression
    ``z`'
    ``gz`'
    ``gzip`'
      data is piped through ``gzip -dc`'
    ``bz2`'
    ``bzip2`'
      data is piped through ``bzip2 -dc`'
  Image Formats
    ``tiff`'
    ``tif`'
      `TIFF` image file format. Only supported if the `tifftopnm` executable can be fond in the current excution path.
    ``png`'
      `PNG` image file format. Only supported if the `pngtopnm` executable can be fond in the current excution path.
    ``jpg`'
    ``jpeg`'
      `JPEG` image file format. Only supported if the `jpegtopnm` executable can be fond in the current excution path.
    ``gif`'
      `GIF` image file format. Only supported if the `giftoppm` executable can be fond in the current excution path.
    ``raw`'
      Raw image data; the number of channels must match the number of bits set in ``DESTMASK`'. Pixels are specified with 1 byte per channel. The pixels are organized in rows as ``liminance[-alpha]`' or ``RGB[A]`' samples. The left-most pixel is the first pixel in each data-row, the top-most image row must come first (this is just the same as the NetPBM convention, the image co-ordinate systems has its origin in the left/top corner, as usual).
  Explicitly Specified Filters
    If none of the suffixes specified above should match, then the suffix/filter is interpreted as an external filter program; the filter program must read from `STDIN` and write to `STDOUT`. The output must either be in SGI image format, or in PNM or PGM format. Otherwise the output data is interpreted as raw image data (see above).

    Something like the following should work, provided that the program `${HOME}/bin/bububfilter` exists, is executable and does something useful:

                       ...
                       data RGB "${HOME}/bin/bububfilter.bzip2" 7 { # binary data follows
                       bububub
                       }
                       ...

    Note that – prior to feeding the data to the ``bububfilter`' – Geomview will try to decompress the stuff with ``bzip2 -dc`'.

Missing image data: Normally, the number of image channels is determined automatically from the image `data` specifications; if the image specification carries an explicit number of channels via the `channels` keyword which exceeds the number of channels found in the image `data` specifications, or if the union of all ``DESTMASK`' specfications has holes, then missing luminance and RGB channels are initialized to 0, and a missing alpha-channel is initialized to `maxval`, i.e. omitting the alpha channel data for an RGBA image is just the same as defining an RGB image.