- NAME
- DESCRIPTION

- Image I/O for PDL based on the netpbm package.
- Configuration

- FUNCTIONS

- rpiccan, wpiccan
- rpic
- wpic
- wmpeg

- BUGS
- AUTHOR

# NAME

PDL::IO::Pic -- image I/O for PDL

# DESCRIPTION

## Image I/O for PDL based on the netpbm package.

This package implements I/O for a number of popular image formats by exploiting the xxxtopnm and pnmtoxxx converters from the netpbm package (which is based on the original pbmplus by Jef Poskanzer).

Netpbm is available at ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM/ Pbmplus (on which netpbm is based) might work as well, I haven't tried it. If you want to read/write JPEG images you additionally need the two converters cjpeg/djpeg which come with the libjpeg distribution (the ``official'' archive site for this software is ftp://ftp.uu.net/graphics/jpeg).

Image I/O for all formats is established by reading and writing only the PNM format directly while the netpbm standalone apps take care of the necessary conversions. In accordance with netpbm parlance PNM stands here for 'portable any map' meaning any of the PBM/PGM/PPM formats.

As it appeared to be a reasonable place this package also contains the routine wmpeg to write mpeg movies from PDLs representing image stacks (the image stack is first written as a sequence of PPM images into some temporary directory). For this to work you additionally need the program mpeg_encode from the Berkeley multimedia package.

You find mpeg_encode at ftp://mm-ftp.cs.berkeley.edu/pub/multimedia/mpeg/encode (they even have binaries for a number of platforms).

## Configuration

The executables from the netpbm package are assumed to be in your path. Problems in finding the executables may show up as PNM format errors when calling wpic/rpic. If you run into this kind of problem run your program with perl `-w` so that perl prints a message if it can't find the filter when trying to open the pipe.

# FUNCTIONS

## rpiccan, wpiccan

Test which image formats can be read/written

       $im = PDL->rpic('PDL.jpg') if PDL->rpiccan('JPEG');
       @wformats = PDL->wpiccan();

finds out if PDL::IO::Pic can read/write certain image formats. When called without arguments returns a list of supported formats. When called with an argument returns true if format is supported on your computer (requires appropriate filters in your path), false otherwise.

## rpic

Read images in many formats with automatic format detection.

        $im = rpic $file;
        $im = PDL->rpic 'PDL.jpg' if PDL->rpiccan('JPEG');

Options

        FORMAT  =>  'JPEG'   # explicitly read this format
        XTRAFLAGS => '-nolut'  # additional flags for converter

Reads image files in most of the formats supported by netpbm. You can explicitly specify a supported format by additionally passing a hash containing the FORMAT key as in

        $im = rpic ($file, {FORMAT => 'GIF'});

This is especially useful if the particular format isn't identified by a magic number and doesn't have the 'typical' extension or you want to avoid the check of the magic number if your data comes in from a pipe. The function returns a pdl of the appropriate type upon completion. Option parsing uses the the PDL::Options manpage module and therefore supports minimal options matching.

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, e.g.

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

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 transpose/inversion upon read that way.

## wpic

Write images in many formats with automatic format selection.

       Usage: wpic($pdl,$filename[,{ options... }])

        wpic $pdl, $file;
        $im->wpic('web.gif',{LUT => $lut});
        for (@images) {
          $_->wpic($name[0],{CONVERTER => 'ppmtogif'})
        }

Write out an image file. Function will try to guess correct image format from the filename extension, e.g.

        $pdl->wpic("image.gif")

will write a gif file. The data written out will be scaled to byte if input is of type float/double. Input data that is of a signed integer type and contains negative numbers will be rejected (assuming the user should have the desired conversion to an unsigned type already). A number of options can be specified (as a hash reference) to get more direct control of the image format that is being written. Valid options are (key => example_value):

       CONVERTER  => 'ppmtogif',   # explicitly specify pbm converter
       FLAGS      => '-interlaced -transparent 0',  # flags for converter
       IFORM      => 'PGM',        # explicitly specify intermediate format
       XTRAFLAGS  => '-imagename iris', # additional flags to defaultflags
       FORMAT     => 'PCX',        # explicitly specify output image format
       COLOR      => 'bw',         # specify color conversion
       LUT        => $lut,         # use color table information

Option parsing uses the the PDL::Options manpage module and therefore supports minimal options matching. A detailed explanation of supported options follows.

CONVERTER
  directly specify the converter, you had better know what you are doing, e.g.

        CONVERTER  => 'ppmtogif',

FLAGS
  flags to use with the converter; ignored if !defined($$hints{CONVERTER}), e.g. with the gif format

        FLAGS      => '-interlaced -transparent 0',

IFORM
  intermediate PNM/PPM/PGM/PBM format to use; you can append the strings 'RAW' or 'ASCII' to enforce those modes, eg IFORMAT=>'PGMRAW' or

        IFORM    => 'PGM',

XTRAFLAGS
  additional flags to use with an automatically chosen converter, this example works when you write SGI files (but will give an error otherwise)

        XTRAFLAGS => '-imagename iris',

FORMAT
  explicitly select the format you want to use. Required if wpic cannot figure out the desired format from the file name extension. Supported types are currently TIFF,GIF,SGI,PNM,JPEG,PS,RAST(Sun Raster),IFF,PCX, e.g.

         FORMAT     => 'PCX',

COLOR
  you want black and white (value bw), other possible value is bwdither which will write a dithered black&white image from the input data, data conversion will be done appropriately, e.g.

         COLOR      => 'bw',

LUT
  This is a palette image and the value of this key should be a pdl containg an RGB lookup table (3,x), e.g.

         LUT        => $lut,

Using the CONVERTER hint you can also build a pipe and perform several netpbm operations to get the special result you like. Using it this way the first converter/filecommand in the pipe should be specified with the CONVERTER hint and subsequent converters + flags in the FLAGS hint. This is because wpic tries to figure out the required format to be written by wpnm based on the first converter. Be careful when using the PBMBIN var as it will only be prepended to the converter. If more converters are in the FLAGS part specify the full path unless they are in your PATH anyway.

Example:

       $im->wpic('test.ps',{CONVERTER  => 'pgmtopbm',
                        FLAGS => "-dither8 | pnmtops" })

Some of the options may appear silly at the moment and probably are. The situation will hopefully improve as people use the code and the need for different/modified options becomes clear. The general idea is to make the function perl compliant: easy things should be easy, complicated tasks possible.

## wmpeg

Write an image sequence ((x,y,n) piddle) as an MPEG animation.

       $anim->wmpeg("GreatAnimation.mpg");

Writes a stack of rgb images as an mpeg movie. Expects a 4-D pdl of type byte as input. First dim has to be 3 since it is interpreted as interlaced RGB. Some of the input data restrictions will have to be relaxed in the future but routine serves as a proof of principle at the moment. It uses the program mpeg_encode from the Berkeley multimedia package (see also text at the top of this package). Mpeg parameters written by this routines haven't been tweaked in any way yet (in other words, lots of room for improvement). For an example how to use the routine see appropriate test that comes with this package. Currently, wmpeg doesn't allow modification of the parameters written through its calling interface. This will change in the future as needed.

In the future it might be much nicer to implement a movie perl object that supplies methods for manipulating the image stack (insert, cut, append commands) and a final movie->`make()` call would invoke mpeg_encode on the picture stack (which will only be held on disk). This should get around the problem of having to hold a huge amount of data in memory to be passed into wmpeg (when you are, e.g. writing a large animation from PDL3D rendered fly-throughs). Having said that, the actual storage requirements might not be so big in the future any more if you could pass 'virtual' transform pdls into wmpeg that will only be actually calculated when accessed by the wpic routines, you know what I mean...

# BUGS

Currently only a random selection of converters/formats provided by pbmplus/netpbm is supported. It is hoped that the more important formats are covered. Other formats can be added as needed. Please send patches to the author.

# 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.