pnmview_grf: MANUAL

Purpose
Archive contents
Shareware version
Registered version
Version and Plans
Guarantee
Requirements
Installation
Usage of the program
Redirections
Ultraconv 3
Restrictions
Source code
What means STIMP ?
Environment
Author

PURPOSE

The archive contains a program for displaying PBM, PGM and PPM images on the Graffiti video card.

ARCHIVE CONTENTS

The archive should enclose the following files (file lenght at the end of the line):

main directory

bin (Dir)
doc (Dir)
help (Dir)
libs (Dir)
Assign.Skript (42)
doc.info (628)
Install (4247)
Install.info (4746)
pnmview_grf.readme (1633)

directory bin/

pnmview (85052)

directory doc/

gfx (Dir)
pnmview.deutsch.html (20257)
pnmview.deutsch.html.info (833)
pnmview.english.html (17424)
pnmview.english.html.info (833)

directory doc/gfx/

d.gif (73)
gb.gif (145)

directory help/

pnmview.syntax (1447)

directory libs/

graffiti.library (3064)

If one of this files is missing, it would be better to get a full version of the archive, best you get it directly from my homepage.

SHAREWARE VERSION

This package is SHAREWARE. All files in this archive are copyrighted (except the file "graffiti.library" !), that means (c) Stefan Diener. You may freely redistibute this archive, but it is not allowed to modify the archive and to distibute the modified form. (It´s especially not allowed to remove this notice !)

Any exception requires my personal agreement.

This package contains:

an ugly "shareware effect" on all destination pictures,
an unoptimized executeable for the MC68000,
no source code,
not all options are available (not this time, but in other packages).

REGISTERED VERSION

If you are using parts of this software regulary, it is your duty to register for this package. Your advantages:

no ugly "shareware effect" on destination pictures,
optimized executeables for 68000, 68020, 68030+68882 and 68040,
(A PowerPC version is possible, but I have to buy a PowerUP-Board first. It only depends on how many people will register ... !)
full Ultraconv support (if useful),
all options are available (if not available in the shareware version),
C/C++ source code (not of all programs, but mostly),
detailed developer documentation,
free updates.

Think about it and you will see, it is worth registering.

Prices:

First STIMP package - Germany
cash OR euro-cheque C.O.D. direct transfer to my account

via email 10 DM - 10 DM

by post 15 DM 23 DM 15 DM

Second++ STIMP package - Germany
cash OR euro-cheque C.O.D. direct transfer to my account

via email 6 DM - 6 DM

by post 11 DM 19 DM 11 DM

Germany only: If you want to transfer the money directly to my account, please use the following data. Please send me an email or a letter with your desire and your detailed adress too.

First STIMP package - Germany
	cash OR euro-cheque	C.O.D.	direct transfer to my account
via email	10 DM	-	10 DM
by post	15 DM	23 DM	15 DM

Second++ STIMP package - Germany
	cash OR euro-cheque	C.O.D.	direct transfer to my account
via email	6 DM	-	6 DM
by post	11 DM	19 DM	11 DM

number of account: 107 328 478
name of bank: Sparkasse im Kreis Osterode
BLZ: 263 510 15
purpose: "your name"

My address: Stefan Diener, Bornrasen 12, D-99762 Osterode, Germany.

First STIMP package - Europe, World
cash OR euro-cheque

via email 10 DM/6 US$

by post 15 DM/9 US$

by air mail 17 DM/11 US$

Second++ STIMP package - Europe, World
cash OR euro-cheque

via email 6 DM/4 US$

by post 11 DM/7 US$

by air mail 13 DM/8 US$

My address: Stefan Diener, Bornrasen 12, D-99762 Osterode, Germany.

First STIMP package - Europe, World
	cash OR euro-cheque
via email	10 DM/6 US$
by post	15 DM/9 US$
by air mail	17 DM/11 US$

Second++ STIMP package - Europe, World
	cash OR euro-cheque
via email	6 DM/4 US$
by post	11 DM/7 US$
by air mail	13 DM/8 US$

If you are a registered user you have to take a look at the different copyright definitions:

The whole package (without "graffiti.library") is (c) Stefan Diener.
It is not allowed to redistribute the program or parts of the archive in any way.
You may create a single copy for security purposes only. It is not allowed to "store" this security copy in the good hands of a friend.
You may use parts of the source code and the developer sources in your own projects, but if you want to publish something it is not allowed to earn money with it. Conclusion: It is not allowed to use (parts of) the sources in commercial or shareware software !

Any exception requires my personal agreement.

VERSION AND PLANS

This guide was made for the second release of this package. If you have a newer version of the whole archive just forget this file.

Plans:
- add file requester for easy file selection
- allow start from Workbench
- allow saving files (especially useful for reduced PPM files)
- text output directly onto the Graffiti screen, for instance during loading the next picture or dithering - ??? user proposals ... requests are welcome !

Second release: version 1.16, 21.04.98
- added Floyd-Steinberg dithering
- added change of brightness
- fixed several bugs
- fixed and optimized all file operations
- added input- and output-redirection
- optimized several parts of the program (REGISTERED VERSION ONLY)

First release: version 0.01ß, 27.09.97
- Beta-version

GUARANTEE

Sorry, but there is no guarantee given. There´s no guarantee whether the program runs on your computer or that it will do the job you thought it should. Nobody gives any liability for damages caused by proper or inproper use of the program. There´s no guarantee that the program´s output will be correct. No liability too. You are using the program at your own risk.

BUT: I was heavily working to debug the program and I spent a lot of time for testing it. The chance of undiscovered bugs is still greater than zero.

REQUIREMENTS

pnmview_grf requires the following things:

Graffiti video card (surprising, what !)
at least Kickstart 2.0 (that´s version 37.175)
mathieeedoubbas.library (any version) in LIBS:
mathieeedoubtrans.library (any version) in LIBS:
graffiti.library (at least version 1.0) in LIBS:
at least 310 kByte free memory for displaying (small) pictures
[90 kByte Chip-RAM and 220 kByte Fast-RAM, if available]

INSTALLATION

Use the Installer-script "Install" !
You may install pnmview_grf by hand too, but on your own risk !
I'm sorry, but I cannot give detailed instructions anymore.

USAGE OF THE PROGRAM

You can get the usage of the program by starting it without any options: "pnmview". If no usage appers, it is possible that the installation was not succesfull or any other error appeared ...

Note: The option "-?" is no longer available.

Syntax: pnmview [-v|+v] [[+o] [-n|-o|-l|-e|-f] | [+t [-cColors]]]
                [-1|-2|-3] file1 [file2 ...]

Options:

+v : use verbose mode (default)
-v : don't use verbose mode
-1 : screen resolution: 160x256
-2 : screen resolution: 320x256
-3 : screen resolution: 640x256 (this option requires OS 3.0 and AGA)
Note: If you don't specify a screen resolution the program opens a (hopefully) fitting screen. This procedure is then repeated for every file.
+o : ordered color reduction (default)
-n : dithering: none (default)
-o : dithering: ordered dither
-l : dithering: line diffusion
-e : dithering: error diffusion
-f : dithering: Floyd-Steinberg dithering (Note: quite slow !)
+t : octree color reduction (Note: good results, but slow !)
-c : max. number of colors for octree color reduction, 16 .. 256 (default: 256)
fileX : PBM/PGM/PPM-file

During the display of the picture you may

move outsized pictures by using your mouse,
change the screen resolution by pressing F1, F2 and F3,
change the brightness of the picture by using + and -,
quit with mouse buttons, ESCAPE, RETURN or ENTER.

Note: PPM-files will be reduced to 256 colors. Only in this case the +o, +t, -c, -n, -o, -l, -e and -f options are available.

Some hints for the "Syntax" line:

[parameter] means that this is an optional prameter.

| means excusive or, that means that you can only choose one option out of all parameters concatenated by |´s.

"default" means default value if you leave the optional parameter ;-)

Any values are to be placed directly after the introducing char, for instance: "-f32" is okay, but "-f 32" is wrong.

Every parameter has to be introduced by a "-" or "+". It is not possible to combine parameters after only one "-" or "+".

Conclusion: It´s not possible to use file names beginning with a "-" or "+". Hint: Try software that makes "." and ".." useable (like "UnixDirs"). It makes it possible to write "./-file" instead of "-file-". That´s it.

Take a look at the following paragraph "redirections" !

REDIRECTIONS

A new feature is the possibility to use input- and output-redirection. The only thing you have to do is replacing the (now useless) file name by a "-". Some examples:

normal form:
"pgmmedian lena.pgm result.pgm"
(where lena.pgm is the input file and result.pgm the output file)
output-redirection:
"pgmmedian lena.pgm - >result.pgm"
input-redirection:
"pgmmedian - result.pgm <lena.pgm"
input- and output-redirection:
"pgmmedian - - <lena.pgm >result.pgm"
using pipes (greets from UNIX):
"pgmmedian lena.pgm - | pnmmargin -a0 -m5 - result.pgm"
or more complicated with 2 pipes:
"pnmaddnoise -w0.8 -p20.0 lena.pgm - | pgmmedian - - | pnmview -"
(Note: You need a newer version than 0.01ß of the program pnmview to use the input-redirection ...)

I added this feature mainly for use with Ultraconv, but it is useful for running the programs on UNIX too.

Note: You need additional software to use pipes on AmigaOS.

ULTRACONV 3

You may install pnmview_grf as your default preview program in Ultraconv 3. Therefore you have to add the following line in "UConv:Ultraconv.info":

PREVVIEWER=STIMP:bin/pnmview -2 %f

You may set other options too, for instance ".../pnmview -2 +o -l %f". It only depends on your taste and the power of your CPU ;-)

Remember: If you think that this SHAREWARE version is a little bit too slow, just register and you will get an optimized version for your 680x0 processor. (PowerPC owners have to ask, because I have to buy a PowerUP board first ...)

RESTRICTIONS

Only the binary versions of PBM/PGM/PPM-files are supported. That means that you can not use file with the markers P1, P2 and P3 (text versions). I decided to do so because all programs of the NetPBM package write binary files and the text versions have the big fault to produce unneccessary big files. In practice this is no real restriction.

SOURCE CODE

The source code for this package is not available at the moment. Several things have to be improved. But, if you really want, you may ask me for the current version ...

WHAT MEANS STIMP ?

If you read the "Registered version" paragraph, you might be wondered by "STIMP". It´s quite simple: "STefan´s IMage Processing". Not surprising, isn´t it ?

ENVIRONMENT

Compiler:

MaxonC++ 4.0 Light (05.11.96), Maxon Computer GmbH

Computer:

AUTHOR

name : Stefan Diener
e-mail : Stefan.Diener@tu-clausthal.de
WWW : http://www.math.tu-clausthal.de/~masd/index.html
address : Bornrasen 12, D-99762 Osterode, Germany