The Datafile PD-CD 3/PDCD_3.iso/utilities/utilsp/pbmtk/!PBMtk/Docs/!DTPguide/Guide

Text File | 1993-12-02 | 19.5 KB | 576 lines

!PBMtk.Docs.Guide
(version 0.17 14 Nov 1993)

PBMtk is installed on the icon bar by double clicking 'select' on the !PBMtk
icon.

The icon bar menu (click 'menu' on the icon bar icon) looks like this;

               Info->
               Quit

Clicking 'select' on the icon bar icon, will open the PBM+toolkit window.
This window currently doesn't do very much (!) other than enable the user to
access the main menu.

The main menu
~~~~~~~~~~~~~

The main menu is displayed by clicking 'menu' in the PBM+toolkit window, and
looks like this:

                      Readin  ->
                      Writeout->
                      PBM     ->
                      PGM     ->
                      PPM     ->
                      PNM     ->
                      Help
                      Images
                      Filters
                      Quit

Details on each of the menu options follow. The clinical explanation of each
of the command line functions is given in the Docs.UNIXdocs.manpages file.
These will allow you to use the executables within the 'bin' directory as
individual command line programs from a task window

Readin
~~~~~~
Provides a number of options to read foreign image file formats and convert
to PBMplus file formats. Not all the options available in the UNIX
toolkit are included in the menu at this stage, and even fewer have been
actually implemented in PBMtk. Each of the options opens a dialog box.

Readin -> YUVtoPPM
~~~~~~~~~~~~~~~~~~
Reads the YUV video image format file and writes a PPM format file.

The input YUV file can be entered in the writable icon 'A', or dragged in
from a directory display. The input file must be a YUV format file. The
size of the YUV image must be known and the width and height (pixels)
entered in the writable icons provided or set using the increment and
decrement arrows.

When the YUV file has been entered and the image size provided, selecting
'Run' will execute the command.


The default output file is <PBMtk$Dir>.PBMfiles.yuvOUT.


(Note that this program is not acting in a 'proper' manner under RISC-OS. An
image converted to YUV then read in and converted back to a PBMplus format
is not the same as the original, there are some problems with colour
conversion. This program requires checking in the UNIX environment to
establish if the problem is the source or the port to RISC-OS.)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Writeout
~~~~~~~~

Provides a number of options to convert PBMplus file formats to foreign
image file formats.

Writeout -> PPMtoYUV
~~~~~~~~~~~~~~~~~~~~

Writes a YUV video image format from a PPM input file.
Drag the input PPM file to the writable icon 'A', and select 'Run'.

The default output file is <PBMtk$Dir>.PBMfiles.ppmOUT


(Note there is a problem with this program. See the note under YUVtoPPM,
above)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PBM
~~~
Provides access to programs which operate on PBM format files.

PBM -> Make
~~~~~~~~~~~
Create a blank bitmap of a specified size.

The size of the created image is set using the writable icons 'width' and
'height'.
The background colour of the bitmap is selectable from tha option buttons
labelled 'White', 'Black', and 'Grey'.

This function is useful to make a blank image into which other images may be
'pasted'.

The default output is <PBMtk$Dir>.PBMfiles.PBMout

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PGM
~~~
Provides access to programs which generally produce greyscale
output.

PGM -> Crater
~~~~~~~~~~~~~
Create cratered terrain by fractal forgery.
Creates a portable greymap which mimics cratered terrain, by simulating the
inpact of a given number of craters of random position and size, then
rendering the terrain elevations based on a light source shining from one
side of the screen.

The size of the created image is set using the writable icons 'width' and
'height'.

The number is craters to be generated is set in the 'Craters' icon. The more
craters, the better the final image will look, but it will take more time to
generate.

The brightness and contrast of the output image can be adjusted by the
'Gamma' value.  A value of 1.0 makes no difference. Less than 1.0 darkens
the image and increases contrast, greater than 1.0 lightens the image and
decreases contrast.


The default output file is <PBMtk$Dir>.PBMfiles.craterout

PGM -> Edge
~~~~~~~~~~~
Edge detect a portable greymap.
This program reads a portable greymap as input, outlines the edges and
writes a portable greymap (PGM) as output.
The edge detection technique used is to take the Pythagorean sum of two
Sobel gradient operators at 90 degrees to one another.
The output can be improved by passing it through pgmtopbm and playing with
the threshold value (if and when pgmtopbm is installed in PBMtk!!)

Drag the PGM file into icon 'A', and select 'Run'.


The default output file is <PBMtk$Dir>.PBMfiles.edgeout

PGM -> Enhance
~~~~~~~~~~~~~~
Edge enhance a portable greymap. Reads a portable greymap as input and
writes a portable greymap as output. It provides 9 levels of enhancement, 1
being the lowest and 9 the highest. The default is 9.

Drag the PGM file to icon 'A', and set the level of enhancement. Level 9 can
be a bit harsh for some images, and some experimentation may give more
satisfying results.


The default output file is <PBMtk$Dir>.PBMfiles.enhout

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PPM
~~~
Provides access to programs which generally produce colour output. Each of
the options opens a dialog box.

PPM -> Pattern
~~~~~~~~~~~~~~

Build a patterned pixmap.
Set the width and height size of the resulting image, and select a base
pattern. The patterns are generated using stochastic rules and hence are
(almost) always different.

Camo is an attempt at a camouflage pattern, and anticamo is the opposite.

The default output file is <PBMtk$Dir>.PBMfiles.patOUT

PPM -> Relief
~~~~~~~~~~~~~
Run a Laplacian relief filter on a portable pixmap (PPM). Reads a PPM file
as input, does a laplacian relief filtering process, and writes a PPM file
as output. It is a sort of edge detection.

Drag the input PPM file to icon 'A' and select 'Run'.


The default output file is <PBMtk$Dir>.PBMfiles.reliefOUT

PPM -> To-PGM
~~~~~~~~~~~~~
Reads a portable pixmap (PPM) as input, and produces a portable greymap
(PGM) as output.
It uses the formula

      grey value = 0.299*red + 0.587*green + 0.114*blue

Drag the PPM file to icon 'A', and select 'Run'.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PNM
~~~
Provides tools that operate on any of the file formats. Each option opens a
dialog box.

PNM -> Arithmetic
~~~~~~~~~~~~~~~~~

Allows arithmetic processes (+ - *) to be applied to two portable anymaps.
Selecting this entry opens a dialog box into which you may drag two images
(A and B) which may be any of the PBMPlus formats. The option buttons allow
you to select the arithmetic process desired. Note that the outcome is
dependent on which file is A and which is B. The images must be the same
size.

The default output file is <PBMtk$Dir>.PBMfiles.arithOUT.

PNM -> Concatenate
~~~~~~~~~~~~~~~~~~

Allows the concatenation (joining) of a number of images into one image. The
images (which may be any of the file formats) are dragged into the writable
icon in the dialog box in the order that you want them stacked together.

The images can be different sizes.

You may choose the background colour (black or white) or let the program
make its own best guess at the most appropriate background colour.

You may also choose to stack the images top to bottom or left to right.

If stacked top to bottom, then they may be aligned on the left of the right,
or no selection made, in which case they will be centred.

If stacked left to right, then they may be aligned at the top or the bottom,
or by making no choice, they will be centred.


You may get an error if you attemp to concatenate too many files at once.
this will be due to the length of the command line that has been generated.
the solution to this is concatenate a few files into one, repeat for another
output, then concatenate the resulting files.

Writes the file <PBMtk$Dir>.PBMfiles.catOUT.



PNM -> Convolution
~~~~~~~~~~~~~~~~~~
Allows you to carry out convolution processes on any image. this is very
powerful as you can design your own convolution filter to do just what you
want.

The dialog box allows you to drag in a filter file and an image file.

Writes the file <PBMtk$Dir>.PBMfiles.convolOUT.

See the entry 'pnmconvol' in the command line manual pages (Docs.UNIXdocs)
for details of the process and how to generate your own filter files.

PNM -> Cut
~~~~~~~~~~
Allows you to cut a rectangle out of an image. The cut portion is
saved as the output image and the bits that are cut off are discarded. The
top Left hand corner (North West) of the portion to be cut out can be set by
the X and Y values (Cut at) in the dialog box. The size of the rectangle to
be cut out of the image is set by width and height.

Writes the file <PBMtk$Dir>.PBMfiles.cutOUT


PNM -> NoRaw
~~~~~~~~~~~~
Converts PPM 'raw' or packed binary format, into an ascii format (ie not
raw). This is sometimes (often!) necessary to allow the file to be
transferred to another system. It also allows you to have a look at the
format and content of an image using !Edit.

Drag an image file to the icon 'A', and select 'Run'.

Writes the file <PBMtk$Dir>.PBMfiles.norawOUT


PNM -> Paste
~~~~~~~~~~~~

Allows an image to be pasted into another image. Drag the file to paste
(the 'paster') into icon 'A' and the file into which you wish to paste (the
'pastee') into icon 'B'. For all files other than PBM the only option is
'replace' which means that the image A will replace that portion of image B.
The logical operations can only be applied to PBM (bit map) files.

The location of the paste (the North West corner) can be set with the X and
Y coordinates.

The default output file is <PBMtk$Dir>.PBMfiles.pasteout

PNM -> Scale
~~~~~~~~~~~~

Scales an image, to produce a larger, or smaller image, and allows the
aspect ratio to be altered. drag the file to be scaled into icon 'A', then
select the option button that suits your requirement.

The group box 'Scale by factors' provides the options 'regular' and
'Iregular'. Regular means the scale factor applies to both the x and y sizes
of the image (width and height respectively), and the factor is set in the
writable icon 'xy-factor'. Iregular means that different sacle factors are
applied to the x and y sizes of the image, and these factors are set in the
writable icons ' x-factor' and 'y-factor'.

A factor of less than 1.0 will reduce the size, and a factor greater than
1.0 will increase the size. If the factor is 3.0 or greater the resulting
image will 'jaggy' and will be improved by smoothing. (see PNM ->
Convolution, and use the filter 'smooth' in !PBMtk.Filters.

The group box 'Scale by size' provides the options 'Square' and
'Rectangular'. These options allow you to set the actual size of the
resulting image, in pixels. Square allows you to set the the same x and y
sizes, and this size is set in the writable icon 'xy-size'. Rectangular
allows differing x and y sizes, and these sizes are set in the writable
icons 'x-size' and 'y-size'

The default output file is <PBMtk$Dir>.PBMfiles.scaleOUT

PNM -> Tile
~~~~~~~~~~~
Replicates a portable anymap into a specified size, and produces a portable
anymap as output.

Drag a image file into icon 'A', and set the width and height of the desired
image

The default output file is <PBMtk$Dir>.PBMfiles.tileOUT

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Help
~~~~
No on-line help available in this version. (you are reading it now!)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Images
~~~~~~
This option will open the !PBMtk.PBMfiles directory.
This is the default storage location for PBM files and thus allows you to
select files as input to operations.
Selecting OK in any of the process 'saveas' boxes will save the output files
with default names to this directory.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Filters
~~~~~~~
This option will open the !PBMtk.Filters directory.
This is the storage location provided for Filter files, and thus allows you
to select available filters for input to the convolution function.

See PNM -> Convolution and the manpages on PNMconvol on methods of building
your own special filter files.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Quit
~~~~
Guess!


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

File Formats
============

pbm - portable bitmap file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 DESCRIPTION

The portable bitmap format is a lowest common denominator monochrome
file format.
It was originally designed to make it reasonable to mail bitmaps
between different types of machines using the typical stupid network
mailers we have today.
Now it serves as the common language of a large family of bitmap
conversion filters.

The definition is as follows:
- A "magic number" for identifying the file type.
A pbm file's magic number is the two characters "P1".
- Whitespace (blanks, TABs, CRs, LFs).
- A width, formatted as ASCII characters in decimal.
- Whitespace.
- A height, again in ASCII decimal.
- Whitespace.
- Width * height bits, each either '1' or '0', starting at the top-left
corner of the bitmap, proceeding in normal English reading order.
- The character '1' means black, '0' means white.
- Whitespace in the bits section is ignored.
- Characters from a "#" to the next end-of-line are ignored (comments).
- No line should be longer than 70 characters.

Here is an example of a small bitmap in this format:

P1
# feep.pbm
24 7
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0
0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0
0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0
0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0
0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0


Programs that read this format should be as lenient as possible,
accepting anything that looks remotely like a bitmap.

There is also a variant on the format, available
by setting the RAWBITS option at compile time.  This variant is
different in the following ways:
- The "magic number" is "P4" instead of "P1".
- The bits are stored eight per byte, high bit first low bit last.
- No whitespace is allowed in the bits section, and only a single character
of whitespace (typically a newline) is allowed after the height.
- The files are eight times smaller and many times faster to read and write.

 AUTHOR

Copyright (C) 1989, 1991 by Jef Poskanzer.


pgm - portable graymap file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 DESCRIPTION

The portable graymap format is a lowest common denominator grayscale
file format.
The definition is as follows:
- A "magic number" for identifying the file type.
A pgm file's magic number is the two characters "P2".
- Whitespace (blanks, TABs, CRs, LFs).
- A width, formatted as ASCII characters in decimal.
- Whitespace.
- A height, again in ASCII decimal.
- Whitespace.
- The maximum gray value, again in ASCII decimal.
- Whitespace.
- Width * height gray values, each in ASCII decimal, between 0 and the specified
maximum value, separated by whitespace, starting at the top-left
corner of the graymap, proceeding in normal English reading order.
A value of 0 means black, and the maximum value means white.
- Characters from a "#" to the next end-of-line are ignored (comments).
- No line should be longer than 70 characters.

Here is an example of a small graymap in this format:

P2
# feep.pgm
24 7
15
0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
0  3  3  3  3  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15 15 15 15  0
0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0 15  0
0  3  3  3  0  0  0  7  7  7  0  0  0 11 11 11  0  0  0 15 15 15 15  0
0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0  0  0
0  3  0  0  0  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15  0  0  0  0
0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0


Programs that read this format should be as lenient as possible,
accepting anything that looks remotely like a graymap.

There is also a variant on the format, available
by setting the RAWBITS option at compile time.  This variant is
different in the following ways:
- The "magic number" is "P5" instead of "P2".
- The gray values are stored as plain bytes, instead of ASCII decimal.
- No whitespace is allowed in the grays section, and only a single character
of whitespace (typically a newline) is allowed after the maxval.
- The files are smaller and many times faster to read and write.

Note that this raw format can only be used for maxvals less than
or equal to 255.
If you use the pgm library and try to write a file with a larger maxval,
it will automatically fall back on the slower but more general plain
format.

 AUTHOR

Copyright (C) 1989, 1991 by Jef Poskanzer.



ppm - portable pixmap file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 DESCRIPTION

The portable pixmap format is a lowest common denominator color image
file format.
The definition is as follows:
- A "magic number" for identifying the file type.
A ppm file's magic number is the two characters "P3".
- Whitespace (blanks, TABs, CRs, LFs).
- A width, formatted as ASCII characters in decimal.
- Whitespace.
- A height, again in ASCII decimal.
- Whitespace.
- The maximum color-component value, again in ASCII decimal.
- Whitespace.
- Width * height pixels, each three ASCII decimal values between 0 and the
specified maximum value, starting at the top-left
corner of the pixmap, proceeding in normal English reading order.
The three values for each pixel represent red, green, and blue, respectively;
a value of 0 means that color is off, and the maximum value means that color
is maxxed out.
- Characters from a "#" to the next end-of-line are ignored (comments).
- No line should be longer than 70 characters.

Here is an example of a small pixmap in this format:

P3
# feep.ppm
4 4
15
 0  0  0    0  0  0    0  0  0   15  0 15
 0  0  0    0 15  7    0  0  0    0  0  0
 0  0  0    0  0  0    0 15  7    0  0  0
15  0 15    0  0  0    0  0  0    0  0  0


Programs that read this format should be as lenient as possible,
accepting anything that looks remotely like a pixmap.

There is also a variant on the format, available
by setting the RAWBITS option at compile time.  This variant is
different in the following ways:
- The "magic number" is "P6" instead of "P3".
- The pixel values are stored as plain bytes, instead of ASCII decimal.
- Whitespace is not allowed in the pixels area, and only a single character
of whitespace (typically a newline) is allowed after the maxval.
- The files are smaller and many times faster to read and write.

Note that this raw format can only be used for maxvals less than
or equal to 255.
If you use the ppm library and try to write a file with a larger maxval,
it will automatically fall back on the slower but more general plain
format.



Copyright (C) 1989, 1991 by Jef Poskanzer.


pnm - portable anymap file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 DESCRIPTION

The pnm programs operate on portable bitmaps, graymaps, and pixmaps,
produced by the pbm, pgm, and ppm segments.  There is no file format
associated with pnm itself.


 AUTHOR

Copyright (C) 1989, 1991 by Jef Poskanzer.
=============================================================================