This is the second beta release of the Bibertools, an add-on package for 
ImpOS/2 2.x. The name, bibertools, is an abbreviated form of 
"BIldBEaRbeitungs-Tools" (image processing tools). Maybe not very imaginative, 
but I tried to find a name that hasn't been used before.

PLEASE read the file DANGER.TXT!

PURPOSE
I created this program because I want to scan a large number of slides. ImpOS'
own image processing tools are not really up to the job, and I wanted 
an interface that would give me access to the most often needed processing
options via a single mouse click. I also wanted to have a tool that would
automatically generate the necessary file names, keep track of the names used,
and save the images to a predefined location without asking unnecessary 
questions.

I finally found out how to 'invert' negative film material. The problem was 
how to remove the orange mask and restore proper RGB-balance. For the solution, 
see below.

REQUIREMENTS

You need IMPOS/2 version 2 or higher. You also need the following programs:

pnmarith.exe, ppmnorm.exe, pnmgamma.exe pnmcrop.exe, pnmflip.exe, 
and several support dlls; they van be obtained from the file NETPBMA.ZIP,
which is available at the following URLs:

ftp://ftp.leo.org/pub/comp/os/os2/leo/graphics/netpbma.zip
ftp://hobbes.nmsu.edu/pub/os2/dev/mm/netpbma.zip

INSTALLATION

Copy the included files to a common directory; you can put them into the 
IMPOS directory, if you want, otherwise you will need to add the IMPOS 
directory to your PATH and LIBPATH statements in CONFIG.SYS. 

Copy the files from NETPBMA to a directory on your HD, and add this directory 
to your PATH and LIBPATH statements in CONFIG.SYS.

You might also want to set the BIBERTEMP variable in CONFIG.SYS, eg.
SET BIBERTEMP=D:\TEMP. This variable sets the directory where the temporary
files are stored. Set this to your fastest drive. 

Create a program object for BIBER.EXE.
Create a program object for HISTOGRAM.EXE

Reboot.

RUNNING BIBERTOOLS

Start BIBER.EXE from the program object that you created before. It should 
bring up IMPOS automatically. If it doesn't, something is probably wrong
with your path and/or libpath statements. 

HISTOGRAM.EXE can also be started from the program object, but it will only 
run if an image is loaded in IMPOS. If it doesn't find an image to operate 
on, it will inform the user and then terminate.

The histogram tool may need some explanation. It takes the RGB values of all 
image pixels and counts how often (-> y-axis) each of the 256 possible 
intensity levels (-> x-axis) occurs. With an average, well-exposed slide, 
the red, green, and blue curves would look roughly similar, and they would all 
fill the whole range from 0...255. Underexposed images would have their 
histograms shifted to the left, and overexposed images would appear shifted to 
the right. You have several options in this dialog: If you klick on any of the 
"auto" buttons, the brightnesss levels in the corresponding R, G, or B 
sub-picture will be redistributed to fill the whole range from 0 to 255. You 
can repeat that for the other colors, if you want. The "reset" button resets 
all three sub-images and reloads the corresponding histograms. 

The "auto" remapping is fast, but it lacks flexibility. Therefore, you can 
set the min and max values for each color manually, either by entering the 
numeric values, or by double-clicking in the black bar beneath each histogram.
A double-click with the left mouse button sets the 'min' value, and a double-
click with the right mouse button sets the 'max' value.

OPTIONS

The NETPBM programs operate on the disk: They read a file, and write their 
output to another file. The BIBERTOOLS store these temporary files in the 
path which is defined by the BIBERTMP environment variable. If that doesn't 
exist, they look for the TMP variable, and if that doesn't exist then for 
the TEMP environment variable. If you have the RAM, then it is strongly 
recommended to set the temporary directory to a RAM disk. I tried RAMFS64, 
but that was much slower than my HD. However, in March 2002, a performance-
optimised RAMFS64P.IFS written by Andrew Belov <andrew_belov@newmail.ru>
was announced in one of the OS/2 newsgroups, and this is really fast, and 
the BIBERTOOLS work nicely with the BIBERTMP directory pointing to the
RAMFS64P RAM disk. 

NEGATIVES

I finally found out how to remove the orange mask from scanned color 
negatives, and the "negative" function is fully functional in the present 
release. When the program is started, it looks for *.film files in its own
directory. If any files are found, they will be listed in the drop-down list
box to the right of the "negative" checkbox. The *.film files are used to 
define and store some (fifteen) characteristic parameters of a given film 
material, and you should select the correct *.film file for best results.
Each film file contains a 3x3 matrix 

RR RG RB
GR GG GB
BR BG BB
which describes the cross-sensitivity of the film material: In the simplest 
case, all diagonal elements of the matrix are equal to one, and all 
off-diagonal elements are equal to zero:

1 0 0
0 1 0
0 0 1

This matrix describes an ideal fim material, where the "red" layer is only 
sensitive to red light (RR=1), the "green" layer to green (GG=1), and the 
"blue" layer to blue (BB=1). The "red" layer is neither sensitive to green 
light (RG=0), nor to blue light (RB=0), and so on.

In most cases, you will be able to get along with the simple unity matrix, 
but if you need more, the program can deal with it. However, in order 
to keep the code simple and efficient, there are some limitations. In 
particular, the program can only deal with parameter sets satisfying 
the following requirements:

RG/(RR + RB + RG) < 0.5
RB/(RR + RB + RG) < 0.5
GB/(GR + GB + GG) < 0.5
GB/(GR + GB + GG) < 0.5
BB/(BR + BB + BG) < 0.5
BB/(BR + BB + BG) < 0.5

In other words, the off-diagonal elements must not be too big compared
to the on-diagonal elements. This is only a limitation if you want to
(mis-)use the function to generate false color images. It should not
affect the normal use. 

Note that the inversion algorithm normalises the output to 256 grayscales,
independent on the matrix. Therefore, the above unity matrix produces the 
same result as a matrix

i 0 0
0 j 0
0 0 k

with arbitrary values i, j, k (not equal to zero).

There are two more lines (with three parameters per line) in each film 
file, and they are much more important. They each consist of three 
integer numbers between 0 and 255, separated by one or more spaces:

R0 B0 G0
R1 B1 G1

R1, B1 and G1 are the red, green and blue values of the orange mask of
the negative film, as seen by the scanner. In other words, they are 
RGB values of a completely unexposed part of the film, or the 
brightest parts of the negative. They will be mapped to black in the
final (positive) image. 
R0, G0, and B0 are the red, green and blue values of a part of the 
film that has been exposed to saturation, ie. the darkest possible 
pixels. They will be mapped to white in the final (positive) image.

As I said before, these latter parameters are much more important 
for the final result than the previously described nine "matrix" 
parameters. Fortunately, it is relatively easy to find their 
correct values for any given film material, provided that you have a
few exposed negatives. Here's the recipe:

(a) Find and scan an image that has both very bright and very dark 
areas.
Typically, that could be a photograph of a landscape, with white 
houses or clouds and a few dark shadows. If there are no sufficiently 
dark shadows, you can shift the image by millimeter or two in the 
film holder and use the space between two exposures on the film
stripe: That is always unexposed, and gives a perfect R0,B0,G0 
level.

(b) Load the image into IMPOS and start the "histogram" tool that 
comes with the BIBERTOOLS package. Please use the separate tool; you cannot 
use the histogram function of the scan module for this purpose. 

(c) For each of the three (R, G and B) histograms, do a 
double click with the left mouse button on  the black bar below the
left boundary of the curve, and a right MB double click below the 
right boundary of the curve. This defines the R, G, and B range that will be 
mapped to the full available range (0...255) in the inverted images.

(d) In the histogram tool, select 'File' -> 'Create *.film file', enter a file
name, and click on 'OK'. 

(e) Scan and invert a few negatives using the new film file, and check 
that you got everything right. 

(f) I don't know any straight-forward way to create an optimised 
transfer matrix. You will have to fiddle around with the off-diagonal 
elements and compare the results to find the best set of parameters. 
If someone knows a better solution, suggestions are welcome.

FEEDBACK, QUESTIONS, ETC.

If you have problems, feel free to contact me, either via e-mail, or write me
a short note in the comp.os.os2.* newsgroups. You will usually find me there
(not in co.o.o.advocacy though). 

Note that I have news and mail filters installed. News and mail messages from
notoriously annoying people may not get through. They may still ask someone 
else to contact me.

LICENCE

You may do with this program whatever you want. I do not charge you anything,
and I cannot be held liable for any damage. If you are interested in the source 
code, contact me. It's VisPro REXX code, therefore you will need VisPro REXX 
to do anything useful with it. I tested the basic image inversion code in a 
separate REXX file which requires only the NETPBMA modules (VisPro REXX not 
required). This is also available on request. 

CONTACT

My current mail adress is

Manfred.Agne@netsurf.de

It might change in 2002 - you'll find me easily via Google groups.

Manfred Agne
