head	1.7;
access;
symbols;
locks; strict;
comment	@# @;


1.7
date	95.11.03.23.52.53;	author root;	state Exp;
branches;
next	1.6;

1.6
date	95.11.03.22.53.13;	author root;	state Exp;
branches;
next	1.5;

1.5
date	95.09.19.18.33.47;	author root;	state Exp;
branches;
next	1.4;

1.4
date	95.08.13.02.43.07;	author root;	state Exp;
branches;
next	1.3;

1.3
date	95.06.15.03.54.03;	author root;	state Exp;
branches;
next	1.2;

1.2
date	95.04.01.10.36.26;	author root;	state Exp;
branches;
next	1.1;

1.1
date	94.10.20.20.28.39;	author root;	state Exp;
branches;
next	;


desc
@Just an old README adopted to the new situation.
The PPIC format is defined here in.
@


1.7
log
@perhaps it's a little bit more readable now.
@
text
@-BEGIN-------------------------------------------------------------------------

I really should rewrite this README. Sorry for the static chaos in here.

-WARNING-----------------------------------------------------------------------

!!!!!!!!!!!!!!!
!!! WARNING !!!
!!!!!!!!!!!!!!!

I AM NOT RESPONSIBLE IF YOU DAMAGE YOUR HARDWARE USING THIS SOFTWARE!!!
Especially if you try to connect your scanner to a normal LPT port!
There is a 74LS245 near the Centronics input port. I destroyed it
accidentally while connecting the scanner to a (12V!) eprommer's output
port (Blame the manufaturer, it has the same connector like a printer port)!
Luckily epson built quite(!) a good input hardware, so replacing this chip
by a new one fixed the problem. BUT BE WARNED!

-QUICK COMPILE-----------------------------------------------------------------

THIS STILL IS ALPHA !!!

It's not BETA because the documentation is ..
The documentation is ..
Where is any documentation?

This isn't BETA, too, because there are no BETA testers yet.
(please read DOC/TODO)

This is an RCS version.
If you do not have RCS, I'm sorry !!!

To make the package:

# This will create the ppic<version> directory.
zcat ppic*.tar.gz | tar xf -
# Now enter the directory ppic<version>
cd ppic*
# Check out the package from the RCS directory:
co RCS/.* RCS/*
# Create a makefile suitable for your system
xmkmf -a
# Install everything in /usr/local/
make install

-REVISIONS---------------------------------------------------------------------

Version 0.5
- the EXAMPLE directory now is called DOC
- ppicepson now supports LPT1 and LPT3 too. However it does not work on
  ordinary parallel IO cards for now. You must own the Epson interface!
- Now compiling with -O2 (previous: none!) and much more warnings
- ppicx improvements (*grin*), ppicx now has a directory browser.
- ppicepson Bugfix for Epson ES series fallback to "unknown scanner".
- Removed a little BUG in ppicg3
Version 0.4
- See ChangeLog: This is a release with extensions for WWW.
Version 0.3
- Not much except bugfixes and minor improvements. See ChangeLog
Version 0.2
- Version 0.1.1 not publicly released
- PPICX extended to '|command' files and argument selector
  (try: ppicx '|ppicepson|ppicpack -f'). Many bugs fixed.
  Not yet available: Cropping area.
- PPICPACK: 'dither color pictures when fast', -FF and -U.
- PPICEPSON now gracefully aborts if terminated. Still missing is support for
  some scanner commands like gamma correction or halftoning.
Version 0.1.1
- PPICX fixed
- Ported to Kernel 1.1.45
- If piolib.c does not compile, please try to fix it in sg.h first!
Version 0.1
- New PPICCUT and PPIC2GIF. PPICCUT still untested.

-ABOUT-------------------------------------------------------------------------

In short what it is (don't expect an utility with 'friendly' user interface!):

It is a EPSON GT6000 SCANNER driver software and (one more) picture processing
package with a X11 display utility. It should run with some other EPSON
scanners as well. The (new) format it uses is named PPIC (see below).

Formats read:		PPIC	PM	MSPold	GIF	PBM	XBM
-"- via PBMPLUS pack.:	BMP	RLE	TIFF	RAST	ILBM	PCX	IMG
-"- via JPEG package:	JPG	JFIF
-"- via GHOSTSCRIPT:	PS
Formats written:	PPIC	PM	?MSPold	GIF	PBM	HP-LJ

You can write other formats, too, using constructs like `ppic2pbm | cjpeg`.
You can read above formats with autodetection (ppicpack or ppicunpack) if all
needed utilities are installed accessible via PATH= and the file
.ppicformats
is placed in the acutal PATH= or in a directory specified in PPIC= !

Perhaps you want to make and install PBMPLUS, GhostScript and/or the
JPEG GROUP's JPEG software (djpeg).

Nearly all PPIC utilities work memory-less. So you don't need much RAM to use
them. Most PPIC utilities work without temporary files (work in stream mode).
Because some operating systems have a low ulimit, temporary data is broken up
into temporary files with 8 MB each. The upper limit is 256 filehandles
leading to a maximum total of 2 GB temporary space. The utilities that use
/tmp disk space are (the amount needed varies from picture to picture):
ppicpm ppic2pm ppicrot ppicfix:	always
ppicepson:			option -c1
ppicpack:			if option -f is not given
ppicgif:			when reading interlaced pictures
ppic2gif:			when writing interlaced pictures

-LICENSE-----------------------------------------------------------------------

ATTENTION! DISCLAIMER! HEALTH WARNING! RADIATION! FOR EVERYBODY EYES ONLY!
The minister of health informs you, that this program may contain serious
bugs, may harm you or your computer, may nuke the world or delete the universe
if run. If so, I am sorry, but I am not liable for anything if you use it.

PPIC was a project I worked on three years ago or so.
The project was canceled, due to time lack and due to OS capabilites (we did
not get the info needed to add SCSI support). The sources of the project
survived till today and are released by me under the GNU GPL V2.0 or higher
with one exeption:
The sources are created by me and the (my) company "Augusta Computer
Dienstleistungsgesellschaft mbH". Because of this I must state following:
!!!!!!!!!!!!!!!!!!!!!!!!!
!!! NO COMMERCIAL USE !!! (private or _pirate_ use only)
!!!!!!!!!!!!!!!!!!!!!!!!! (_pirates_ will be decapitated)
You may _not_ use it in your company to scan in material you work with in your
company (if you want, you must purchase it). You may not sell it, and it
_must_not_ be part of a product that is sold (even if the product is a linux
distribution CD or diskettes or anything like that). It must be available for
free in source form - no binary only distribution is allowed. If you want to
distribute it on sold media (a sold linux distribution) you must have a written
permission before (normally this means that I get a copy of all versions of the
distribution for free, such that I can supply the correct kernel patches etc.)!

PLEASE NOTE ME IF SOMEONE VIOLATE THIS RULES (if you find this package on
something you have purchased that is not licensed from me). Note that the PPIC
package is free, except the epson scanner driver.

-SCANNER-----------------------------------------------------------------------

I decided to port PPIC to Linux and add the SCSI support, too (yes, I know, if
you have the kernel source everything is very easy). However, you need some
patches so that the SCSI support can work under Linux. The soucecode now uses
ioperm() and maybee doesn't compile under other operating systems any more.

How to connect the EPSON scanner:

-LPT---------------------------------------------------------------------------

Use Epson's Bi-directional Parallel Interface Board (B808011), set it up as
LPT2 and disable LPT2 if needed:
BASE-Adress:	0x278
Interrupt:	not used/needed (the driver is polling, GULP!)
Cable-Type:	Normal LPT cable. Make sure the select line is connected
		(Pin 17 on computer's side, Pin 36 on centronics side)
ppicepson does not need any parameters then.
Note that the program hangs (no core, no zombie) if the card is not present.
To verify if everything is working, try (will reset the scanner)
ppicepson -vvii

This may issue a warning:
"Incompatible printer port (probably not bi/directional)" it looks like you do
not have a bi/directional printer port. In this case you need epson's board.
"Incompatible printer port (probably bi/directional)" says, that the port
looks like bi/directional, but there is some problem.

Both warnings may show up due to incompatible cable. The cable must have
a connected select line. Else it will never work.

I do not know why it does not work with bi/directional ports for now.
Can anybody send me the _complete_ documentation about this ports?
My documentation states, it should work (perhaps it's an enable problem) ...

You can install the parallel IO port to another address, then you always must
give switch -D to ppicepson according to the LPT port:

LPT	Port-Address	Switch	Example above
LPT1	0x378		-d1	ppicepson -vviid1
LPT2	0x278		-d2	ppicepson -vviid2
LPT3	0x3BC		-d3	ppicepson -vviid3

Note: I tried bi/directional printer ports. For some reason all failed.
I'm working on it. Can someone send me please a _complete_ bi/directional
parallel card specification?

-SCSI--------------------------------------------------------------------------

Or connect the scanner to SCSI and configure you kernel for Generic SCSI
device support. If the generic SCSI /dev entries are missing, you must create
them using
mknod /dev/sg<n> c 21 <n>
Then you can verify it, according above:
ppicepson -vviid /dev/sg<n>
But it may be, that you need to patch your kernel, before it can detect the
scanner. Note that there is no method (I don't know how) to hardware-reset the
scanner while it is connected to SCSI only.

However, if the scanner is switched off, it blocks the SCSI BUS, and if it is
turned on again, it resets the SCSI BUS. So be careful with your SCSI driver -
some may get in trouble! Thus I connect the scanner to both interfaces
simultaneously, such that I can hardware-reset with `ppicepson -ii` when the
scanner is in error condition. ppicepson now tries to abort the scanning
process if it is terminated (not: killed), however due to unknown
circumstances, this sometimes fails (there might be some SCSI race conditions
in piolib.c). Note that Linux crashes when the scanner locks the SCSI BUS
while Linux wants to page memory in or out.

You can use the SCSI and the parallel scanner interface from two different
computers! So the scanner can be used (exclusively) by any computer.
But beware of ground loops (the LPT cable shielding should be connected
to ground only on one side) in this case.

-USAGE-------------------------------------------------------------------------

ppicepson BUGS:
- yes, quite some.
- not all scanner options are supported for now.
- Chris Worley at iquest.net reported a SIGSEV on Epson ES series
- Frank Ronneburg at in-berlin.de reported problems using a normal LPT port.
  Note: It will NOT and NEVER work on _normal_ LPT ports. This type of
  ports are OUTPUT ONLY.

Some quick and dirty usages:
ppicepson -help		Help
ppicepson -vvhelp	Even more help
ppic* -help		all PPIC-utilities support this style of help

Scan a color picture from a magazine into a viewer:
ppicepson -c2 -n8 -r240 -z100 | ppiczoom -z50 | ppic2pbm | xv -
or
ppicx '|ppicepson -c2 -n8 -r240 -z100 | ppiczoom -z50 | ppicpack -f'
and then just click on the command.

View a <picture> with ppicx:
ppicx <picture>
Note:
You can alter .ppicformats to reflect all picture formats. This picture formats
must be converted into another format that can be converted (possibly in more
than one step) into a PPIC. .ppicformat now provides entries for djpeg (JPEG
package), gs (postscript via ghostscript) and some converters from the famous
PBMPLUS package. So to view most pictures on your computer, just enter:
ppicx `find // -type f \( -name '*.jpg' -o -name '*.gif' -o -name '*.xbm' \) -print`
You can try
ppicx `find / -type f -print`
too, but I think this will lead to an overflow on the commandline :)
I am very sorry to note, that following currently fails:
find / -type f -print | while read a; do ppicpack -f $a; done | ppicx -

Print a GIF picture to a HPLJ compatible printer:
ppicunpk -- $name |
ppichange -l0 -b$bright -g$gamma |
ppiczoom -mz$zoom -x2310 -y3230 |
ppicfs -p150 |
ppic2hplj -vemd300 -a77 -n$num > /dev/lp
Note:
--		ends optional arg processing
$name		is the filename. Conversion is autodetected if the path to the
		file .ppicformats can be found in the environment variable
		PPIC=
-l0		makes the picture monochome
-b$bright	is the brightness in percent, set it to 100 if no change.
-g$gamma	is the gamma correction, 1.0 for default
-m		selects maximum zoom (auto-exchange -x and -y if needed)
-z$zoom		sets the zoom factor in percent, set it to 100 for no change.
-x2310		is the maximum print width for my printer
-y3230		is the maximum print height for my printer
-p150		selects, that my printer is a write black laser:
		black dots cover 50% more area than those dots left white,
		so that a 50% gray shade leads to a nearly black area
-e		send printer init to printer
-m		selects automatic picture rotation (see -m at ppiczoom)
-d300		specifies the density setting (300 DPI)
-a77		prints the comment with width '77 chars'
-n$num		selects mupber of copies

-AUTHOR------------------------------------------------------------------------

Consider this package as ALPHA.

I don't know if I have any time to do any work for it next time.
If you have questions or problems, want to send bugfixes or ideas or
anything, here are my addresses (I am a HAM, you know?):

Valentin Hilbig		Valentin.Hilbig@@public.uni-augsburg.de
Seb.-Kneipp-Str. 2	http://www.public.uni-augsburg.de/~tino
D-86482 Aystetten	tino@@augsburg.net	http://www.augsburg.net/~tino
Germany			DG8MGV @@ DB0MWS.DEU.EU	(DG8MGV @@ DB0SAO.DEU.EU)

I am sorry that some (most) comments in the source are in german, because this
is a `quick release' ..

-HISTORIC----------------------------------------------------------------------

What follows is the old, original README I added to the source etc.:
!!This is partly historical now!!

-END---------------------------------------------------------------------------

PPIC-Utilities -- graphic processing/conversion -- printing/scanning utilities
(Currently PPIC is available for ISC-SV/386R3 System only.)

Portability:			<- assumed	reported ->
X11R3-Window systems				not yet known
X11R4-Window systems				X386R4 (Thomas Roell)
X11R5-Window systems				X386R5 (Thomas Roell)
Interactive Unix System V/386 Release 3.x	ISC-U System V/386 Release 3.2
Interactive Unix System V/386 Release 4.x	not yet available
Epson Scanner GT series				Epson GT6000
-------------------------------------------------------------------------------
Copyright (c) 1991 by
Augusta Computer Dienstleistungsgesellschaft mbH
Heretsrieder Str. 15
D 86485 Biberbach
Germany

All rights reserved.			Alle Rechte vorbehalten.
All warranty excluded.			Keine Gew"ahr auf Software m"oglich.
We are not liable for anything.		Absoluter Haftungsausschlu"s.
Use at own risk.			Nutzung auf eigene Gefahr.
License for one site only.		Nutzungsrecht nur auf einem Rechner.
Unlimited user licence.			Uneingeschr"ankte Benutzeranzahl.
Copy for third party forbidden.		Jedwede Weitergabe an Dritte verboten.
Sorry, no email yet			Momentan kein E-Mail-Anschlu"s
Contact anytime:			Jederzeit erreichbar:

Telefon national:		    0511 / 9004111486	Anrufbeantworter
Telephone international:	+49  511   9004111486	Answer-Back Recorder
eFAX international:		+49  8293  73 60	G2/G3
-------------------------------------------------------------------------------
Note that there is no written documentation yet. If you want to know, what the
utilities are doing, run them with the option -HELP. Ordinary utilities give
additional help when called with -VVHELP. To get input from STDIN you must run
'PPICX -' (it is an X-Application). To process STDIN to FILE with a ordinary
utility, you must use 'utility -- - name' or you can use 'utility >name'. This
two forms are a little bit different when you are using them with option -V,
because the output of Verbose can be written to STDOUT in the first form and
must be written to STDERR in the latter case. PPICPACK is designed to have
both STDOUT and STDERR redirected to the same destination, so that warnings
etc. are included in the packed PPIC.			Have a nice time!
-------------------------------------------------------------------------------

Working-Log:
============

This is the very first release.

Not constructed yet:
--------------------

Every Program	you can think of that might be useful. If you got ideas,
		send them to adress above. But we need substantial material
		to work with. So do not think "I need a scanner driver for
		Sepuco Scanners" is enough. We need a "Sepuco Scanner" then
		to test it!
PPICHAM		Please send suggestions to us.
		We do not have such a graphic board, and we do not know,
		what to do. Note that PPICPACK and PPICX might get a extension
		to support this feature.
Scanner kernel	It is not ready yet, for system speed will be a problem,
	driver	because it must do heavy-duty I/O.
		So scanning programs have to run with S-Bit for now.
		No problem, but not the best way.
PPICFX		Who has got this printers for me?
PPICPROP
PPICCUT		Nice utilities. Not yet needed.
PPICPASTE	
PPICROT		We have got no idea HOW to write this programs. Very complex.
		You might think, rotating is easy. In deed it is not very
		complex if you got enough memory ...
		For we want to process even very *very* *VERY* large PPICs,
		this algorithm should be capable to run with low memory
		like all other utilities. Everybody can call malloc() ...
		However, how do you store PPICs over 16 MB (around
		1100x1100 Pixels) on ISC ... (answer: tuning the tuning table)
PPICMRROR	All types of reflections.
PPICDVI		DVI files (Output of TeX) to PPIC? Oh what a clever idea!
		Note that it is never thought of printing DVI-files with
		PPIC printer drivers (it is possible, anyway), because
		font downloading cannot be done with this programs.
		But then you may FAX output of TeX ...
PPICTIFF	This are the programs, that convert format, commonly used
PPIC2TIFF	for FAX interchange, to PPIC or from PPIC.
		Nice idea. No more handy writings!
PPICFILTR	Interesting but useless for now.
PPICUNFS	Just a thought.
PPICREL		Maybee, PPICREL can include PPICUNFS ...
		PPICUNFS will never show up then.

Not ready yet:
--------------

PPICX		This program must be extended. Its too simple yet and does
		not directly support true color displays (it can be faster
		than. But do you have ever seen a X-Server under Interactive
		running in True Color?)
		PPICX is designed to become the "Integrator" of all
		PPIC utilities. We have got no ready idea yet, how to do it.
		Note, that PPICX already "integrates" PICPACK ...
PPICFIX		It might be more powerful.
PPICGIF		ditto
PPIC2GIF	Working on it
PPICASCII	Who needs it? (I, I, I and I, too ...)


Files supplied (written in Uppercase letters):
==============================================

Conversion of pictures:
-----------------------

PPICHEX		Conversion PPIC with possible wrong byte hex -> PPIC

PPICPM		Conversion PM -> PPIC
PPIC2PM		Conversion PPIC -> PM

PPICGIF		Conversion GIF -> packed PPIC
		Compuserve GIF(tm) style files are already separate
		colortable and pixelstream. It would be waste time (and
		coding work, too) if this utility would output unpacked PPICs.
PPIC2GIF	Conversion packed PPIC -> GIF

Printing of pictures:
---------------------
PPIC2FX		Printing on Epson FX compatibles		< Not included
PPIC2PROP	Printing in IBM Proprinter and compatibles	< Not included

PPIC2HPLJ	Printing on Hewlard-Packard LJ and compatibles

Scanning of pictures:
---------------------
see also kernel driver supplied by us				< Not included

PPICEPSON	Scanning of pictures with Epson scanners via
		Epson parallel I/O card.
		If run without kernel driver it must run under root with
		S-Bit set.

Picture preparation:
--------------------

PPICQUERY	Automatic file type detection and PPIC conversion.
		This module is designed NOT for direct use.
		It is designed for internal use ONLY.
PPICPACK	Packs PPICs in a machine dependent format with separate
		colortable and pixelstream, which are needed by some other
		utilities (PPICX, PPICGIF etc.).
		The output cannot be used with normal PPIC utilities.
		There is no trouble if it is run on an already packed PPIC.
		Packed PPICs can be concatenated, so that one file can hold
		more than one picture.
		Note that "Packing" does not mean real compression.
		There may be an informational loss. The width of the
		color table is 16 Bit at maximum, but PPICs got 32 Bit.
		This utility is transparent - it will not show up in the
		commentary section of a PPIC. Instead it adds a lot of
		human readable processing information to it.
PPICUNPK	Unpacks a packed PPIC to a "normal" one. Ignores all
		human readable processing information of PPICPACK
		because another run of PPICPACK can get them back.
		Note that this utility must be placed, for example, behind
		PPICGIF to make the picture readable to other modules behind.

Viewing of pictures:
--------------------

PPICX		Shows picture on X Screens	(-? xv preferred ?-)
PPICASCII	Shows picture on ASCII-Terminal

Processing of pictures:
-----------------------
PPICCUT		Cut section from picture			< Not included
PPICPASTE	Glue pictures together				< Not included
PPICROT		Turn picture, not only 90 degrees		< Not included
PPICMRROR	Mirror picture on line, not only 90 degrees	< Not included
PPICHAM		Adjust picture for VGA-Boards with HAM CLUT	< Not included

PPICFILTR	Color filters and false-color-conversion
PPICHANGE	Change Brightness, Contrast, Luminance and perform
		various Gamma corrections. (luminance 0 creates b/w)
PPICFIX		Fix parameters of pictures, like round, re-adjust or
		restrict number of colors, merge or swap planes etc.
PPICFS		Dithering (Floyd-Steinberg) of pictures including
		simple color-dithering
PPICUNFS	Undither dithered pictures (poor results)
PPICREL		Various pixel relational operators, from contour sharpening
		up to soft painting. (von Kantenverst"arkung bis Weichzeichner)
PPICZOOM	Zoom in or out picture.

-------------------------------------------------------------------------------

Examples:
=========

To print a GIF-Picture use following line:
ppicgif <.gif> | ppicunpk | ppicchange -c0 | ppicfs | ppic2hplj | lp -dhplj_raw
Explanation:	ppicgif <.gif>	converts <.gif> into packed color PPIC
		ppicunpk	extracts first picture out of packed PPIC
		ppicchange -c0	creates a b/w version of PPIC
		ppicfs		creates dithered PPIC
		ppic2hplj	dumps graphic sequence for hp-lj printers
		lp -dhplj_raw	hp-lj compatible and *raw* lp call
				Be sure *not* to convert LP->CR/LF !

ppicepson -i -c2 -n4 | ppicx - &
Explanation:	ppicepson	scans picture on Epson scanner
		ppicx		shows this picture on your X screen

ppicepson -i -c2 -n4 | ppic2pm | xv &
		ppic2pm		converts picture to PM
		xv		alternate picture viewing tool
				(supplied on X-contribution tape)

-------------------------------------------------------------------------------

PPIC(0:10) file format:
=======================

PPIC is a signed 32 Bit fix point pixel value data stream to minimize
picture processing errors (or you may say to maximize data overhead).
Currently this fix point is set to 2^10 for Version 0 of PPIC.
So you have got 1 Bit sign, 21 Bits left of comma, 10 Bits right of comma.
  0 is defined to be BLACK (or absence of color)
255 is defined to be WHITE (or full saturation of one color)
This definition will not change and will be true in future.
Note that 255 stands for pixel value 255 (here 255 * 2^10).
But fixpoint shift and PPIC version may change without notice.
However, there will be converting programs able to consum or produce
old fashioned PPIC files named like PPIC_0_10 or PPIC2_0_10.

Don't worry about colors above 255 or below 0. Why not? PPICFIX will fix'em!
Even don't worry about 2 or 4 planes or more. Everyone is thinking
B/W or R/G/B. But PPIC is able to process multiple planes.
See them as multiple layers of one picture or see them as multiple pictures.
But real layers are not supported. For this PPIC must be redesigned
to allow multiple header informations.

Transmission:
-------------

PPICs are transmitted (stored) in Bytes with low order 8 Bits valid.
There are no architecture sized packages like 36 Bit supported.

Imagine DVI-files. (DVI files are as many 4 Bytes values as can be packed
into one machine word padded with zeros in the low order Bits).
How to transmit them over an 8 Bit line to a 32 Bit machine while your machine
has 36 Bit architecture? It's only possible to transmit Bytes.
But one of your Bytes has 9 Bits, not 8.
So your machine word divides up into 4 packages a 9 Bit, not 5 a 8 Bit.
Say, there are only 256 Byte (2048 Bit) frames and you want to transmit your
DVI file.
If you break up your DVIfile into 8 Bit portions,
you will have to transmit 2304 Bit for 256 Byte.
In other words, the receiver will receive 288 Bytes for 256 Bytes of the
original DVI file, so this file will be received as garbage.
If you break up your DVI file into 9 Bit portions (your Bytes)
and ignore the MSB, you will transmit 2048 Bit for 256 Byte, that's correct.
But your file will be received as garbage, too, because DVI files are
padded in the low order Bits of your machine word.
So you have to write a program, say CP36to32, that is reading one machine
word and breaking it up into 4*8+4 Bits.
But then, this program is only portable to your machine.

So PPIC uses another strategy. We are transmitting Bytes. No matter how
long (in Bits) Bytes are, there are 8 Bits valid only. Then you can
copy PPICs to another system, using <<< cat PPIC >/dev/8-bit >>>,
while /dev/8-bit is ignoring the nineth bit. And this way is portable
between all machines, even if two "9 bitters" communicate over one
8 bit line. So where is the problem?

There are some problems with networks. I do not know what happens,
if you are storing PPICs with your 36 Bit architecture onto servers with
32 Bit architecture.
I even don't know if this case is actually possible or not!
I don't know anything about machines with others than 8 Bit Bytes!
So I do not bother about this problem.

There are problems with byte hex. Intel uses LSB first, Motorola MSB.
But there is PPICHEX to fix byte hex of this 4 Byte values.
If you are not sure about source byte hex, read the PPIC through PPICHEX.
There is no way to write PPICs with certain byte hex.
Written PPICs get YOUR byte hex, but the receiver also has PPICHEX.
So where is the problem?

Where do I get PPIC from?
I think you have got it already!

Yes, but not for my xyz Unix.
Ah, see. Sorry ... Yes. It may be available. Just write to the address at
the beginning and ask, whether there already is one version.
If there is not ... and you are developer ... and you comply with the rule ...
you might become Alpha-Tester, get PPIC for free and INCLUDING the source.
You can write to me in English. But I want to write in German (my English
is too lousy and I'm so slow in translating).
Note that you must send back fixes (if needed) and executables then
and that you will get no copyright, publishing rights etc. for this.
But you will get the newest versions of PPIC free including source,
and you can freely choose (some) Beta-Testers for you and give them PPIC.
However, Beta-Testes are not allowed to get the source.

Header:
-------

PPICs start with one sigle simple packed header information of values of
4 Bytes each. The length of this structure is exactly 24 Bytes.
magic	currently <<< HEX acd6 1c 0 a >>> meaning
	acd6	Company name written as ACDG
	1c	IC of PPIC written as 1c
	0	Version of PPIC
	a	Bit shift of a=10 with 0=16 !
x	width, horizontal
y	height, vertical
z	depth, number of planes
com	length of commentary section
chksum	checksum

Comment:
--------

Then the commentary section follows, exactly of length header.com Bytes.
There is no padding and no alignment.
Comments should look like this, when written as C-style strings
excluding the 0-Byte string delimiter:

"Comment of program 1\n" <- no 0-Byte
"Comment of program 2\n" <- no 0-Byte
...
"Comment of program k\n" <- no 0-Byte
<- no final 0-Byte

Additional comments are concatenated to the PPIC when it is processed by any
PPIC-Module. Graphic conversion modules will obtain comments, if there are
some present in the original graphic format. So you may print all comments
using following lines:
  struct _ppic header;
  char *tmp;
    fread(&header, sizeof header, 1, ppic_fd);
    tmp=malloc(header.com+1);
    tmp[header.com]=0;
    fread(tmp, header.com, 1, ppic_fd);
    printf("comment: %s", tmp);
This definition will be true for all future releases.
However, sizeof header may vary! 

Pixeldata:
----------

At last all pixeldata will follow, 4 Bytes for each pixel,
grouped in one scanlines of each plane,
first cycling through all planes (R/G/B with R first) and
then counting up the y-coordinate.
Therefore it is possible to access all pixels in nearly a sequential order
but also to process whole scanlines of one plane with fast commands such
as memcpy().

An R/G/B picture will have following layout (3 planes):
----------------- Scanline 0 of plane Red   -----------------
----------------- Scanline 0 of plane Green -----------------
----------------- Scanline 0 of plane Blue  -----------------
----------------- Scanline 1 of plane Red   -----------------
----------------- Scanline 1 of plane Green -----------------
----------------- Scanline 1 of plane Blue  -----------------
----------------- Scanline 2 of plane Red   -----------------
...

A B/W picture will have following layout (b/w = 1 plane only):
----------------- Scanline 0 (of plane 1) -----------------
----------------- Scanline 1 (of plane 1) -----------------
----------------- Scanline 2 (of plane 1) -----------------
----------------- Scanline 3 (of plane 1) -----------------
...

Picture coordinates (x,y) are running this way by definition:
 (0,0) --> (100,0)
   |
   v
(0,100)

So scanlines look like this in Intel Byte Hex (LSB first):
(0,0)        (1,0)         (100,0)      <- This line for your information only
[LSB|x|x|MSB][LSB...MSB]...[LSB...MSB]  <- [...] marks ONE long (4 Bytes)
(0,1)        (1,1)         (100,1)      <- This line for your information only
[LSB ... MSB][LSB...MSB]...[LSB...MSB]  <- Scanline 1 (second one)
...

Additional data:
----------------

There is no additional data defined. However, all data behind the pixel data
section will be ignored. Imagine Xmodem ...
But there might be added some data in further versions of PPIC,
for example checksum data for the pixeldata section.


Following includes may be used:
-------------------------------

#define	PPIC_FIX	10		/* Fixpoint shift		*/
#define	PPIC_MAGIC	0xacd61c0a	/* ACDG pIC version 0 shift 10	*/
#define	PPIC_CHKSUM	0		/* Checksum start		*/

struct _ppic
  {
    long	magic;		/* file MAGIC				*/
    long	x,y,z;		/* width/height/depth(R/G/B)		*/
    long	com;		/* Length of comment, newline separated	*/
    long	chksum;		/* Checksum of header			*/
  };
/*  char	comment[header.com]
 *  long	line[header.y][header.z][header.x]
 */

Checksum ist calculated as follows:
-----------------------------------

long chksum(const void *ptr, size_t len)
{
  unsigned long tmp;

  tmp = PPIC_CHKSUM;
  while (len)
    {
      len--;
      tmp=(tmp>>29)|(tmp<<3);
      tmp+=*((unsigned char *)ptr)++;
    }
  return tmp;
}

-------------------------------------------------------------------------------

Packed PPICs are very machine dependent.
Never transmit them to unknown destination or other type machines.
Instead use unpacked PPICs, so that >ppichex< can receive them.
Here is a short definition of this format.
This format is not officially supported and my change without notice.
However, the old PPICUNKP will be the available to convert old packed PPICs
back to unpacked PPICs.

Packed PPICs	= PICS
PICS		= PIC PICS | PIC			; Multi pics allowed!
PIC		= HEAD DATA EOF
HEAD		= FRAME(PARSE_DATA, PARSE_HEADER)	; Sent: 'packed ppic\0'
EOF		= INTRO PARSE_EOF
INTRO		= PARSE_INTRO INTRO | PARSE_INTRO	; PARSE_INTRO=Filler
FRAME(X,Y)	= INTRO X LENGTH(Y) BYTES(Y)
LENGTH(X)	: Length of the data X, one byte
BYTES(X)	: The bytes of the data X
DATA		= INFO | COMMENT | DATA | BLOCK
INFO		= INTRO PARSE_INFO data PARSE_INTRO	; Informational text
COMMENT		= FRAME(PARSE_COMMENT, comment)		; PPICs comment text
DATA		= FRAME(PARSE_DATA, pic_stream)		; interesting data
BLOCK		= FRAME(PARSE_BLOCK, pic_stream)	; multiple of 256 bytes

The pic_stream ist transmitted in portions of DATA-blocks (see above).
The raw pic_stream looks like:

PIC_STREAM	= BITS SIZE BWPIXELS		; only if Z==0 (fast version)
PIC_STREAM	= BITS SIZE C COLORS PIXELS	; only if Z!=0
SIZE		= X Y Z
COLORS		= COLOR COLORS |		; exactly C colors
PIXELS		= PIXEL PIXELS |		; exactly X*Y pixels, X first
BWPIXELS	= BWPIXEL BWPIXELS		; exactly X*Y pixels, X first
COLOR		= COL         if Z=1		; Greyscale, 0=dark, 255=light
COLOR		= COL COL COL if Z=3		; R G B
COL		= 1 byte  if    BITS<=8		; MSB's padded with 0
COL		= 2 bytes if  8<BITS<=16	; Ditto
COL		= 4 bytes if 16<BITS		; Ditto, not yet(!!!) possible
BWPIXEL		= 1 byte			; Greyscale
PIXEL		=                 1 byte  if        color<255
PIXEL		= <255>           2 bytes if   255<=color<65791
PIXEL		= <255><255><255> 4 bytes if 65791<=color	; not used yet
BITS		= int				; local int, size of color info
X,Y,Z		= int				; X=hor Y=ver Z=planes
C		= long				; local long, number of colors

#define	PARSE_HEADER	"packed ppic"
#define	PARSE_INTRO	0
#define	PARSE_INFO	1	/* Info <0>		*/
#define	PARSE_COMMENT	2	/* <length> Comment	*/
#define	PARSE_DATA	3	/* <length> Data	*/
#define	PARSE_BLOCK	4	/* <length/256> Data	*/
#define	PARSE_EOF	255	/* Close me		*/

-------------------------------------------------------------------------------

Note:	Version 0 is no Beta-State. It's an official number!
Bugs:	PPIC cannot read pictures of wrong byte hex.  Maybee
	this is possible with the next release of Version 0.

-------------------------------------------------------------------------------

Known problems:
Elder versions of some windowmanagers (i. e. [TV]TWM at X11R4) core if
	used with PPICX.
	That is no bug of PPICX, it is a feature of this windowmanagers.
	To work around this feature, use the switch -dontsetwmcolormap.
	To let the windowmanager install the colormap use switch
	-dontinstallcolormap.
	Maybee, PPICX should automatically recognise windowmanagers
	capable of installing colormaps, but how can this be done?

-------------------------------------------------------------------------------

IBM, Epson, Hewlard Packard, Compuserve GIF and so on are registered
Trademarks of the holder of the trademark respectively.

-------------------------------------------------------------------------------

(written by Valentin Hilbig)

emacs: Local Variables:
emacs: mode: auto-fill
emacs: fill-column: 78
emacs: End:
@


1.6
log
@dist version
@
text
@d1 6
d19 29
d53 1
a53 1
- ppicx improvements (*grin*)
d75 1
d77 1
a77 3
!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!! IMPORTANT NOTE BEGIN !!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!
a78 1
In short what it is (don't expect an utility with 'friendly' user interface!):
d82 1
d95 2
a96 6
To make the package:
Uncompress and untar it (will create two directories, ppic* and include)
xmkmf -a; make install

If needed, make and install PBMPLUS, GhostScript and/or the JPEG GROUP's JPEG
software (djpeg).
a108 1
				(not yet implemented)
d110 3
a112 1
ATTTENTION! DISCLAIMER! HEALTH WARNING! RADIATION! FOR EVERYBODY EYES ONLY!
d140 2
d148 3
d187 2
d214 2
d277 4
a280 1
Consider this package as an ALPHA PRERELEASE.
d293 2
d298 1
a298 3
!!!!!!!!!!!!!!!!!!!!!!!!!!
!!! IMPORTANT NOTE END !!!
!!!!!!!!!!!!!!!!!!!!!!!!!!
@


1.5
log
@Three e-mails, some additions according to this messages.
@
text
@d7 5
a11 5
There is a 74LS245 near the Centronics input port. I destroyed it myself
while connecting the scanner to a (12V!) eprommer's output port (it has
the same connector like a printer port. Blame manufacurers like this!).
Luckily epson built quite a good input hardware, so replacing this chip
by a new one fixed the porblem. BUT BE WARNED!
a17 1
- THIS IS AN INTERMEDIATE RELEASE, PPICX CURRENTLY NOT WORKING!
@


1.4
log
@And this I want RCSsed, too.
@
text
@d1 12
d14 3
d19 2
a20 2
- ppicx improvements
- ppicepson Bugfix for Epson ES series.
d95 2
a96 2
!!! NO COMMERCIAL USE !!! (private or pirate use only)
!!!!!!!!!!!!!!!!!!!!!!!!!
d116 3
a118 3
Use the parallel IO interface card set it up as LPT2:

BASE-Adress	0x278
d120 2
d127 25
d172 5
d181 3
@


1.3
log
@Corrected my addresses.
@
text
@d1 6
d133 1
@


1.2
log
@Version 0.4
@
text
@d186 4
a189 4
Valentin Hilbig      hilbig@@uni-augsburg.de   http://www.uni-augsburg.de/~tino
Seb.-Kneipp-Str. 2   tino@@augsburg.net        http://www.augsburg.net/~tino
D-86482 Aystetten    sometimes tino@@IRC
Germany              DG8MGV @@ DB0MWS.DEU.EU   (DG8MGV @@ DB0SAO.DEU.EU)
@


1.1
log
@Initial revision
@
text
@d1 2
@
