NAME

       PDL::IO::Pnm -- pnm format I/O for PDL

SYNOPSIS

         use PDL::IO::Pnm;
         $im = wpnm $pdl, $file, $format[, $raw];
         rpnm $stack->slice(':,:,:,(0)'),"PDL.ppm";

DESCRIPTION

       pnm I/O for PDL.

FUNCTIONS

   pnminraw
         Signature: (type(); byte+ [o] im(m,n); int ms => m; int ns => n;
                               int isbin; char* fd)

       Read in a raw pnm file.

       read a raw pnm file. The "type" argument is only there to determine the type of the
       operation when creating "im" or trigger the appropriate type conversion (maybe we want a
       byte+ here so that "im" follows strictly the type of "type").

       pnminraw does not process bad values.  It will set the bad-value flag of all output
       piddles if the flag is set for any of the input piddles.

   pnminascii
         Signature: (type(); byte+ [o] im(m,n); int ms => m; int ns => n;
                               int format; char* fd)

       Read in an ascii pnm file.

       pnminascii does not process bad values.  It will set the bad-value flag of all output
       piddles if the flag is set for any of the input piddles.

   pnmout
         Signature: (a(m); int israw; int isbin; char *fd)

       Write a line of pnm data.

       This function is implemented this way so that threading works naturally.

       pnmout does not process bad values.  It will set the bad-value flag of all output piddles
       if the flag is set for any of the input piddles.

   rpnm
       Read a pnm (portable bitmap/pixmap, pbm/ppm) file into a piddle.

         Usage:  $im = rpnm $file;

       Reads a file in pnm format (ascii or raw) into a pdl (magic numbers P1-P6).  Based on the
       input format it returns pdls with arrays of size (width,height) if binary or grey value
       data (pbm and pgm) or (3,width,height) if rgb data (ppm). This also means for a palette
       image that the distinction between an image and its lookup table is lost which can be a
       problem in cases (but can hardly be avoided when using netpbm/pbmplus).  Datatype is
       dependent on the maximum grey/color-component value (for raw and binary formats always
       PDL_B). rpnm tries to read chopped files by zero padding the missing data (well it
       currently doesn't, it barfs; I'll probably fix it when it becomes a problem for me ;). You
       can also read directly into an existing pdl that has to have the right size(!). This can
       come in handy when you want to read a sequence of images into a datacube.

       For details about the formats see appropriate manpages that come with the netpbm/pbmplus
       packages.

         $stack = zeroes(byte,3,500,300,4);
         rpnm $stack->slice(':,:,:,(0)'),"PDL.ppm";

       reads an rgb image (that had better be of size (500,300)) into the first plane of a 3D RGB
       datacube (=4D pdl datacube). You can also do inplace transpose/inversion that way.

   wpnm
       Write a pnm (portable bitmap/pixmap, pbm/ppm) file into a file.

         Usage:  $im = wpnm $pdl, $file, $format[, $raw];

       Writes data in a pdl into pnm format (ascii or raw) (magic numbers P1-P6).  The $format is
       required (normally produced by wpic) and routine just checks if data is compatible with
       that format. All conversions should already have been done. If possible, usage of wpic is
       preferred. Currently RAW format is chosen if compliant with range of input data. Explicit
       control of ASCII/RAW is possible through the optional $raw argument. If RAW is set to zero
       it will enforce ASCII mode. Enforcing RAW is somewhat meaningless as the routine will
       always try to write RAW format if the data range allows (but maybe it should reduce to a
       RAW supported type when RAW == 'RAW'?). For details about the formats consult appropriate
       manpages that come with the netpbm/pbmplus packages.

BUGS

       The stderr of the converters is redirected to a file. The filename is currently generated
       in a probably non-portable way. A method that avoids a file (and is portable) would be
       preferred.

       "rpnm" currently relies on the fact that the header is separated from the image data by a
       newline. This is not required by the p[bgp]m formats (in fact any whitespace is allowed)
       but most of the pnm writers seem to comply with that. Truncated files are currently
       treated ungracefully ("rpnm" just barfs).

AUTHOR

       Copyright (C) 1996,1997 Christian Soeller <c.soeller@auckland.ac.nz> All rights reserved.
       There is no warranty. You are allowed to redistribute this software / documentation under
       certain conditions. For details, see the file COPYING in the PDL distribution. If this
       file is separated from the PDL distribution, the copyright notice should be included in
       the file.