Provided by: pdl_2.099-3_amd64 
NAME
PDL::IO::Pic -- image I/O for PDL
DESCRIPTION
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 need the program ffmpeg also.
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
PDL::Options 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 PDL::Options 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 containing 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.
rim
Usage: $x = rim($file);
or rim($x,$file);
Read images in most formats, with improved RGB handling.
You specify a filename and get back a PDL with the image data in it. Any PNM handled format or FITS will
work. In the second form, $x is an existing PDL that gets loaded with the image data.
If the image is in one of the standard RGB formats, then you get back data in (<X>,<Y>,<RGB-index>)
format -- that is to say, the third dim contains the color information. That allows you to do simple
indexing into the image without knowing whether it is color or not -- if present, the RGB information is
silently broadcasted over. (Contrast "rpic", which munges the information by putting the RGB index in
the 0th dim, screwing up subsequent broadcasting operations).
If the image is in FITS format, then you get the data back in exactly the same order as in the file
itself.
Images with a ".Z" or ".gz" extension are assumed to be compressed with UNIX "compress" or "gzip",
respectively, and are automatically uncompressed before reading.
OPTIONS
The same as "rpic", which is used as an engine:
FORMAT
If you don't specify this then formats are autodetected. If you do specify it then only the specified
interpreter is tried. For example,
$x = rim("foo.gif",{FORMAT=>"JPEG"})
forces JPEG interpretation.
XTRAFLAGS
Contains extra command line flags for the pnm interpreter. For example,
$x = rim("foo.jpg",{XTRAFLAGS=>"-nolut"})
prevents use of a lookup table in JPEG images.
wim
Write a pdl to an image file with selected type (or using filename extensions)
wim $pdl,$file;
$pdl->wim("foo.gif",{LUT=>$lut});
Write out an image file. You can specify the format explicitly as an option, or the function will try to
guess the correct image format from the filename extension, e.g.
$pdl->wim("image.gif");
$pdl->wim("image.fits");
will write a gif and a FITS file. The data written out will be scaled to byte if the input if of type
float/double. Input data that is of a signed integer type and contains negative numbers will be
rejected.
If you append ".gz" or ".Z" to the end of the file name, the final file will be automatically compressed
with "gzip" | "compress", respectively.
OPTIONS
You can pass in a hash ref whose keys are options. The code uses the PDL::Options module so unique
abbreviations are accepted. Accepted keys are the same as for "wpic", which is used as an engine:
CONVERTER
Names the converter program to be used by pbmplus (e.g. "ppmtogif" to output a gif file)
FLAGS
Flags that should be passed to the converter (replacing any default flag list) e.g. "-interlaced" to
make an interlaced GIF
IFORM
Explicitly specifies the intermediate format (e.g. PGM, PPM, or PNM).
XTRAFLAGS
Flags that should be passed to the converter (in addition to any default flag list).
FORMAT
Explicitly specifies the output image format (allowing pbmplus to pick an output converter)
COLOR
Specifies color conversion (e.g. 'bw' converts to black-and-white; see pbmplus for details).
LUT
Use color-table information
rmpeg
Read an image sequence (a (3,x,y,n) byte pdl) from an animation.
$ndarray = rmpeg('movie.mpg'); # $ndarray is (3,x,y,nframes) byte
Reads a stack of RGB images from a movie. While the format generated is nominally MPEG, the file
extension is used to determine the video encoder type. It uses the program "ffmpeg", and throws an
exception if not found.
wmpeg
Write an image sequence (a (3,x,y,n) byte pdl) as an animation.
$ndarray->wmpeg('movie.mpg'); # $ndarray is (3,x,y,nframes) byte
Writes a stack of RGB images as a movie. While the format generated is nominally MPEG, the file
extension is used to determine the video encoder type. E.g. .mpg for MPEG-1 encoding, .mp4 for MPEG-4
encoding, .gif for GIF animation
"wmpeg" requires a 4-D pdl of type byte as input. The first dim has to be of size 3 since it will be
interpreted as RGB pixel data. "wmpeg" returns 1 on success and undef on failure.
use strict; use warnings;
use PDL;
use PDL::IO::Pic;
my ($width, $height, $framecount, $xvel, $maxheight, $ballsize) = (320, 80, 100, 15, 60, 8);
my $frames = zeros byte, $width, $height, $framecount;
my $coords = yvals(3, $framecount); # coords for drawing ball, all val=frameno
my ($xcoords, $ycoords) = map $coords->slice($_), 0, 1;
$xcoords *= $xvel; # moves $xvel pixels/frame
$xcoords .= $width - abs(($xcoords % (2*$width)) - $width); # back and forth
my $sqrtmaxht = sqrt $maxheight;
$ycoords .= indx($maxheight - ((($ycoords % (2*$sqrtmaxht)) - $sqrtmaxht)**2));
my $val = pdl(byte,250); # start with white
$frames->range($coords, [$ballsize,$ballsize,1], 't') .= $val;
$frames = $frames->dummy(0, 3)->copy; # now make the movie
$frames->wmpeg('bounce.gif'); # or bounce.mp4, ffmpeg deals OK
# iterate running this with:
rm bounce.gif; perl scriptname.pl && animate bounce.gif
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 ffmpeg to encode the frames into video. 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
ffmpeg 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).
imageformat
Figure out the format of an image file from its magic numbers, or else, from its extension.
Currently recognized image formats are: PNM, GIF, TIFF, JPEG, SGI, RAST, IFF, PCX, PS, FITS, PNG, XBM.
If the format can not be determined, the string 'UNKNOWN' is returned.
$format=imageformat($path); # find out image format of certain file
print "Unknown image format" if $format eq 'UNKNOWN';
$canread=rpiccan($format); # check if this format is readable in this system
if($canread){
$pdl=rpic($path) ; # attempt to read image ONLY if we can
} else {
print "Image can't be read\n"; # skip unreadable file
}
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.
perl v5.40.0 2025-02-04 PDL::IO::Pic(3pm)