-------------
SFFTOBMP V2.2
-------------

Tool to convert "Structured Fax Files" into Windows bitmaps 
(BMP), Portable Bitmaps (PBM), JPEG Pictures (JPG) and
single or multipaged TIFF Images.


SFF - Wotsit ?
--------------

SFF means 'Structured Fax File', intended by the CAPI interface
to be used to save incoming faxes. Within Linux it's e.g. the 
AVM-B1 card which creates such files. 

See http://www.capi.org for specs of the CAPI interface.

This is where sfftobmp comes in.


Features
--------

Conversion of SFF files in Modified Huffman (MH) coding   
to Windows BMP (monochrome, uncompressed), PBM (Portable 
Bitmap, RAWBITS P4-Header), JPEG or TIFF files.

SFF files containing more than one page will be split into
one output file per page, except for TIFF output which will
be one multipaged file.

Written in C++


Compilation
-----------

Only tested under Debian Linux, Windows95 and WindowsNT 4.0sp6.

Used compilers:

gcc 2.95.4
MS VC 6.0sp5

Under Linux, a simple call to 'make' will be sufficient
most of the time if using GNU make. Browse the makefile 
for tuning. 

Under Windows, use the supplied visual studio workspace 
file.

Usage
-----

Call sfftobmp with at least three parameters:

sfftobmp <-options> <sfffile> <outfile>

Options:
-h or -help        show help message and exit
-v or -version     show version and exit
-b or -bmp         OUTFILE is one monochrome BMP file for each fax page
-p or -pbm         OUTFILE is one Portable Bitmap file for each fax page
-j or -jpg         OUTFILE is one JPEG file for each fax page
-jNUM or -jpg=NUM  Use jpeg quality of NUM percent (1..99)
-T or -tifs        OUTFILE is one single-page TIFF file for each fax page
-t or -tif         OUTFILE is one multi-paged TIFF file containing all pages
-x or -ext         Append type extension to output filename (e.g. '.bmp', etc.)
-o or -orgres      Do not double lines in output image for low-res faxes

Please give the name of the outfile without extension. If the 
sff-file contains multiple pages for each of them a separate
file will be created, named:

<outfile>.001
<outfile>.002
...
<outfile>.xxx

If you want sfftobmp to add a extension to the filename, add the
"-x" option to the commandline. The filename(s) will then be

<outfile>.xxx.bmp  or
<outfile>.xxx.pbm  and so on...

TIFF is capable to contain more pages within one file, therefore
only one multipaged TIFF file will be created in this case.
If you want to have one TIFF file for each fax page, 
use "-T" instead of "-t".

For JPEG output you can optionally set the JPEG quality used by 
adding a two-digit number between 1 and 99 to the option. 

I.e.

-j35       or
-jpg=35

means JPEG output with 35% quality. If you don't give a quality,
a default of 40% is used (mostly sufficient for b&w faxes).


OUTPUT ON STDOUT
----------------

Output on stdout is available for multipaged TIFF output 
only (option "-t"). Use "-" as output filename in this 
case:

 sfftobmp -t infile.sff - > out.tif

NOTE: Reading from stdin is not supported.

 
RESOLUTION HANDLING
-------------------

SffToBmp keeps resolution information intact. This means, if
you convert a fax with 203x98 dpi this resolution information is
written in the output file if it is supported by the output
format. This is JPEG, TIFF and BMP.

However, as many bitmap viewer applications are not considering
this information while displaying the bitmap, SffToBmp defaults
to double scanlines if a low-res fax (i.e. 203x98 dpi) is 
converted.

In case your image viewer does actually treat resolution information
correctly (your image will look stretched vertically in this case), 
you can suppress this scanline-doubling by specifying the "-o" option.


TODO
----

- speed up decoder with better table lookups
  (looking at GHz CPUs noadays, i doubt that this happes...) 
- support other non-intel architectures (64 Bits, different
  byte order). Sfftobmp will most likely fail on these.
  (well, no one complained till now)


Last but not least...
---------------------

Should decoding of a SFF file fail:
Please send the SFF file uuencoded to me - if it isn't about
500 MB and/or contains top secret information ;).

Suggestions, extensions and patches welcome, flames will go 
to /dev/null.

I'm always pleased to hear that somebody is actually using my
software. If you can manage it, e-mail me a quick notice.
Thanks!

Contact:
--------
peter.schaefer@gmx.net
http://sfftools.sourceforge.net

$Id: readme,v 1.2 2003/02/03 21:25:00 pschaefer Exp $
