lviff2pbm(3)

LIBRARY ROUTINE
lviff2pbm - Converts a VIFF image to a PBM image.

LIBRARY CALL
#include "vinclude.h"
int lviff2pbm(viff, pbm, raw)
struct xvimage *viff;
struct pbm     **pbm;
int    raw;

INPUT

    struct xvimage *viff: VIFF input image

    int raw: flag specifying ascii or raw output

OUTPUT

    struct pbm **pbm: PBM output image

MODIFICATIONS

DESCRIPTION
lviff2pbm converts a VIFF image to a PBM image. The VIFF image is converted to one of the six possible types of PBM format images depending on the characteristics of the VIFF input image, and the output data storage type selected.

There are three basic categories of PBM file formats with two types in each category. The three categories of PBM file formats are "pbm", "pgm", and "ppm". Within each category it is possible to store the data as either "ascii" or "raw", thus there are a total of six types of PBM file formats. The resulting data storage type is user selectable between "ascii" and "raw". If no selection is made, the default is to type "ascii".

The three categories of PBM file formats are explained as follows:

  pbm - portable bitmap file format
        This file format is used as the lowest common
        deonominator monochrome file format.
        The header contains the following information:
                             ascii          raw
                             -----         -----
        Magic Number -         P1     or     P4
        Whitespace   -    (blanks, TABs, CRs, LFs)
        Width        -  formatted as ASCII characters in decimal.
        Whitespace   -
        Height       -  formatted as ASCII characters in decimal.
        Whitespace   -
        Data:
         ASCII (P1)  -  characters '1' (black) or '0' (white)
                        starting in top left corner and proceeding
                        from left to right.  No line should exceed
                        70 characters.  Whitespace in this section
                        is ignored.
         RAW (P4)    -  the bits are stored eight per byte, high
                        bit first and low bit last.  No whitespace
                        is allowed in this section.  These files
                        are eight times smaller than the ASCII (P1)
                        files.
        Comments     -  begin with a '#' to the next end-of-line.
                        May be placed anywhere in the header.

  pgm - portable graymap file format
        This file format is used as the lowest common
        deonominator grayscale file format.
        The header contains the following information:
                             ascii          raw
                             -----         -----
        Magic Number -         P2     or     P5
        Whitespace   -    (blanks, TABs, CRs, LFs)
        Width        -  formatted as ASCII characters in decimal.
        Whitespace   -
        Height       -  formatted as ASCII characters in decimal.
        Whitespace   -
        Max Value    -  formatted as ASCII characters in decimal.
        Whitespace   -
        Data:
         ASCII (P2)  -  characters specifying the gray value in
                        ASCII decimal.  These values may range
                        anywhere from 0 to the maximum gray value.
                        Each character is separated by whitespace,
                        and starts at the top left corner of the
                        graymap.  A value of 0 means black, and
                        the maximum value means white.  No line
                        should be longer than 70 characters.
         RAW (P5)    -  The gray values are stored as plain bytes
                        instead of ASCII decimal.  No whitespace
                        is allowed in this section.  Note that
                        values in this section are limited to
                        maxvalues less than or equal to 255.
        Comments     -  begin with a '#' to the next end-of-line.
                        May be placed anywhere in the header.
  ppm - portable pixmap file format
        This file format is used as the lowest common
        deonominator color image file format.
        The header contains the following information:
                             ascii          raw
                             -----         -----
        Magic Number -         P3     or     P6
        Whitespace   -    (blanks, TABs, CRs, LFs)
        Width        -  formatted as ASCII characters in decimal.
        Whitespace   -
        Height       -  formatted as ASCII characters in decimal.
        Whitespace   -
        Max Value    -  formatted as ASCII characters in decimal.
        Whitespace   -
        Data:
         ASCII (P3)  -  characters specifying the maximum color-
                        component value, in ASCII decimal.  Three
                        values are required to represent each pixel.
                        One value for each component of "r" "g" "b".
                        Each character is separated by whitespace,
                        and starts at the top left corner of the
                        pixmap.  The three values for each pixel
                        represent red, green, and blue respectively.
                        A value of 0 means that the color is turned
                        off and the maxvalue represents the maximum
                        intensity for that color. No line should be
                        longer than 70 characters.
         RAW (P6)    -  The gray values are stored as plain bytes
                        instead of ASCII decimal.  No whitespace
                        is allowed in this section.  Note that
                        values in this section are limited to
                        maxvalues less than or equal to 255.
        Comments     -  begin with a '#' to the next end-of-line.
                        May be placed anywhere in the header.

The PBM file formats described above were created by Jef Poskanzer,
Copyright (C) 1989.

The user has control over the output image data type (ASCII or RAW),
but the PBM file category depends on the characterisics of the input
VIFF image.  That is, if the input image is BIT, then the output
image is "pbm", however if the input image is BYTE, SHORT, or INTEGER,
the output image may be either "pgm" or "ppm".  This depends on whether
the input VIFF image is a 1 or 3 band image, and has a color map.
If the VIFF image is multiband, then the output image will be "ppm".
If the VIFF image is 1-band, then the output image will be "pgm",
unless a color map is present, in which case the output image will be
"ppm".

The acceptable VIFF input data types are BIT, BYTE, SHORT, or INTEGER.
The input VIFF image may be either 1-band or 3-band, and contain a
map scheme of NONE, SHARED, or ONEPERBAND.  If the input image contains
a map, then the data will be mapped through the maps prior to conversion

The input parameters for lviff2pbm() are as follows:

  struct xvimage *viff  -  pointer to a viff image structure
  struct pbm **pbm  - pointer to a pointer of a pbm structure.
  int raw  -  flag specifying whether to output ascii or raw.
              "ascii" -  set raw = 0
              "raw"   -  set raw = 1

SEE ALSO
viff2pbm(1), intro(3), vipl(3), verror(3), vutils(3) lpbm2viff(3)

RESTRICTIONS
will only work on BIT, BYTE, SHORT, or INTEGER images.

will only accept VIFF images with bands = 1 or bands = 3, since PBM format will only handle bitmap, gray, or rgb color images.

AUTHOR
Charlie Gage and Mark Young

COPYRIGHT
Copyright 1991, University of New Mexico. All rights reserved.