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:

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.