Initial import of sane-backends version 1.0.24-1.2

1 files changed, 547 insertions, 0 deletions

diff --git a/doc/sane-bh.man b/doc/sane-bh.man
new file mode 100644
index 0000000..8306976
--- /dev/null
+++ b/doc/sane-bh.man
@@ -0,0 +1,547 @@
+.TH sane\-bh 5 "10 Jul 2008" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
+.IX sane\-bh
+.SH NAME
+sane\-bh \- SANE backend for Bell+Howell Copiscan II series document
+scanners
+.SH DESCRIPTION
+The
+.B sane\-bh
+library implements a SANE (Scanner Access Now Easy) backend that
+provides access to Bell+Howell Copiscan II series document
+scanners.  The Copiscan II 6338 has been the primary scanner model
+used during development and testing, but since the programming interface
+for the entire series is consistent the backend should work for the
+following scanner models.
+.PP
+.RS
+COPISCAN II 6338 Duplex Scanner with ACE
+.br
+COPISCAN II 2135 Simplex Scanner
+.br
+COPISCAN II 2137(A) Simplex Scanner (with ACE)
+.br
+COPISCAN II 2138A Simplex Scanner with ACE
+.br
+COPISCAN II 3238 Simplex Scanner
+.br
+COPISCAN II 3338(A) Simplex Scanner (with ACE)
+.br
+.RE
+.PP
+If you have a Bell+Howell scanner and are able to test it with this
+backend, please contact
+.IR sane\-devel@lists.alioth.debian.org
+with the model number and testing results. Have a look at
+http://www.sane\-project.org/mailing\-lists.html concerning subscription to
+sane\-devel. Additionally, the author is curious as to the likelihood of using
+this backend with the newer 4000 and 8000 series scanners.  If you have such a
+beast, please let me know.
+.PP
+The Bell+Howell Copiscan II series document scanners are high
+volume, high throughput scanners designed for document scanning 
+applications.  As such, they are lineart/grayscale scanners supporting
+a fixed number of fairly low resolutions (e.g. 200/240/300dpi).  
+However, they do have a number of interesting and useful features 
+suited to needs of document imaging applications.  
+This backend attempts to support as many of these features as possible.
+.PP
+The main technical reference used in writing this backend is the
+.B Bell and Howell Copiscan II Remote SCSI Controller (RSC) OEM 
+.B Technical Manual Version 1.5.  
+The Linux SCSI programming HOWTO, the SANE API documentation, and 
+SANE source code were also extremely valuable resources.
+
+.PP
+The latest backend release, additional information and helpful hints
+are available from the backend homepage:
+.br
+.RS
+.B http://www.martoneconsulting.com/sane\-bh.html
+.RE
+.SH "DEVICE NAMES"
+This backend expects device names of the form:
+.PP
+.RS
+.I special
+.RE
+.PP
+Where
+.I special
+is the path-name for the special device that corresponds to a SCSI
+scanner. For SCSI scanners, the special device name must be a generic
+SCSI device or a symlink to such a device.  Under Linux, such a device
+name takes a format such as
+.I /dev/sga
+or
+.IR /dev/sg0 ,
+for example.  See sane\-scsi(5) for details.
+.SH CONFIGURATION
+The contents of the
+.I bh.conf
+file is a list of device names that correspond to Bell+Howell
+scanners.  See sane\-scsi(5) on details of what constitutes a valid device name.
+Additionally, options can be specified; these lines begin with the word "option".  
+Each option is described in detail below.  Empty lines and lines starting 
+with a hash mark (#) are ignored.  
+
+.SH OPTIONS
+The following options can be specified in the
+.I bh.conf
+file.
+.TP
+.B disable\-optional\-frames
+This option prevents the backend from sending any optional frames.  This
+option may be useful when dealing with frontends which do not support these
+optional frames.  When this option is in effect, the data is sent in a
+SANE_FRAME_GRAY frame.  The optional frames sent by this backend are:
+SANE_FRAME_G31D, SANE_FRAME_G32D, SANE_FRAME_G42D and SANE_FRAME_TEXT.
+These frames are generated based on the compression and barcode options.
+These frames are never sent in preview mode.
+.TP
+.B fake\-inquiry
+This option is used for debugging purposes and its use is not encouraged.  
+Essentially, it allows the backend to initialize in the absence of
+a scanner.  This is useful for development and not much else.  
+This option must be specified earlier in the configuration file than
+the devices which are to be "faked".
+
+.SH FILES
+.TP
+.I @CONFIGDIR@/bh.conf
+The backend configuration file (see also description of
+.B SANE_CONFIG_DIR
+below).
+.TP
+.I @LIBDIR@/libsane\-bh.a
+The static library implementing this backend.
+.TP
+.I @LIBDIR@/libsane\-bh.so
+The shared library implementing this backend (present on systems that
+support dynamic loading).
+.SH ENVIRONMENT
+.TP
+.B SANE_CONFIG_DIR
+This environment variable specifies the list of directories that may
+contain the configuration file.  Under UNIX, the directories are
+separated by a colon (`:'), under OS/2, they are separated by a
+semi-colon (`;').  If this variable is not set, the configuration file
+is searched in two default directories: first, the current working
+directory (".") and then in @CONFIGDIR@.  If the value of the
+environment variable ends with the directory separator character, then
+the default directories are searched after the explicitly specified
+directories.  For example, setting
+.B SANE_CONFIG_DIR
+to "/tmp/config:" would result in directories "tmp/config", ".", and
+"@CONFIGDIR@" being searched (in this order).
+.TP
+.B SANE_DEBUG_BH
+If the library was compiled with debug support enabled, this
+environment variable controls the debug level for this backend.  E.g.,
+a value of 255 requests all debug output to be printed.  Smaller
+levels reduce verbosity.
+
+.SH "SUPPORTED FEATURES"
+.TP
+.B ADF support
+With document scanners, automatic document feeder (ADF) support is a key
+feature.  The backend supports the ADF by default and returns 
+.B SANE_STATUS_NO_DOCS 
+when the out-of-paper condition is detected.  The SANE frontend
+.B scanadf
+is a command line frontend that supports multi-page scans.  It has been
+used successfully with this backend.  The SANE frontend
+.B xsane
+is an improved GUI frontend by Oliver Rauch.  Support for multi-page
+scans is included in xsane version 0.35 and above.
+
+.TP
+.B Duplex scanning
+Some models, such as the COPISCAN II 6338, support duplex scanning.  That
+is, they scan both sides of the document during a single pass through the
+scanner (the scanner has two cameras).  This backend supports duplex 
+scanning (with the 
+.B \-\-duplex
+option).  The front and back page images are delivered consecutively
+as if they were separately scanned pages.
+
+.TP
+.B Hardware compression
+The scanner is capable of compressing the data into several industry
+standard formats (CCITT G3, CCITT G3-2D, CCITT G4).  This results in 
+increased performance as less data is passed from the scanner to the
+host over the SCSI bus.  The backend supports these compression formats
+via the 
+.B \-\-g31d, \-\-g32d, \-\-g42d
+options, respectively.  Many SANE frontends are not equipped to deal with
+these formats, however.  The SANE frontend
+.B scanadf
+supports these optional frame formats.  The compressed image data 
+is written directly to a file and can then be processed by a scan-script 
+using the
+.B \-\-scan\-script
+option.  Examples of this are given on the scanadf homepage.
+
+.TP
+.B Automatic Border Detection
+The scanner can automatically detect the paper size and adjust the
+scanning window geometry appropriately.  The backend supports this
+useful feature with the
+.B \-\-autoborder
+option.  It is enabled by default.
+
+.TP
+.B Batch Mode Scanning
+The batch scan mode allows for maximum throughput.  The Set Window
+parameters must remain constant during the entire batch.
+
+.TP
+.B Icon Generation
+The Icon function generates a thumbnail of the full page image, that can be
+transferred as if it were a separate page.  This allows the host to 
+quickly display a thumbnail representation during the scanning operation.
+Perhaps this would be a great way of implementing a preview scan, but 
+since a normal scan is so quick, it might not be worth the trouble.
+
+.TP
+.B Multiple Sections
+Multiple sections (scanning sub-windows) can be defined for the front and
+back pages.  Each section can have different characteristics (e.g. geometry, 
+compression).  The sections are returned as if they were separately
+scanned images.  Additionally sections can be used to greatly enhance the
+accuracy and efficiency of the barcode/patchcode decoding process by 
+limiting the search area to a small subset of the page.  Most Copiscan II
+series scanners support up to 8 user-defined sections.
+
+.TP
+.B Support Barcode/Patchcode Decoding
+The RSC unit can recognize Bar and Patch Codes of various types embedded
+in the scanned image.  The codes are decoded and the data is returned to
+the frontend as a text frame.  The text is encoded in xml and contains
+a great deal of information about the decoded data such as the location
+where it was found, its orientation, and the time it took to find.  
+Further information on the content of this text frame as well as some 
+barcode decoding examples can be found on the backend homepage.
+
+.SH LIMITATIONS
+.TP
+.B Decoding a single barcode type per scan
+The RSC unit can search for up to six different barcode types at a time.
+While the code generally supports this as well, the 
+.B \-\-barcode\-search\-bar
+option only allows the user to specify a single barcode type.  
+Perhaps another option which allows a comma separated list of barcode 
+type codes could be added to address this.
+.TP
+.B Scanning a fixed number of pages in batch mode
+The separation of front and back end functionality in SANE presents a
+problem in supporting the 'cancel batch' functionality in the scanner.
+In batch mode, the scanner is always a page ahead of the host.  The host,
+knowing ahead of time which page will be the last, can cancel batch mode
+prior to initiating the last scan command.  Currently, there is no mechanism
+available for the frontend to pass this knowledge to the backend.
+If batch mode is enabled and the \-\-end\-count terminates a scanadf session,
+an extra page will be pulled through the scanner, but is neither read
+nor delivered to the frontend.  The issue can be avoided by specifying 
+\-\-batch=no when scanning a fixed number of pages.
+.TP
+.B Revision 1.2 Patch detector
+There is an enhanced patchcode detection algorithm available in the RSC
+with revision 1.2 or higher that is faster and more reliable than the 
+standard Bar/Patch code decoder.  This is not currently supported.
+
+.SH OPTIONS
+.TP
+.B Scan Mode Options:
+.TP
+.B \-\-preview[=(yes|no)] [no]
+Request a preview-quality scan.  When preview is set to yes image
+compression is disabled and the image is delivered in a 
+SANE_FRAME_GRAY frame.
+.TP
+.B \-\-mode lineart|halftone [lineart]
+Selects the scan mode (e.g., lineart,monochrome, or color).
+.TP
+.B \-\-resolution 200|240|300dpi [200]
+Sets the resolution of the scanned image.  Each scanner model supports 
+a list of standard resolutions; only these resolutions can be used.
+.TP
+.B \-\-compression none|g31d|g32d|g42d [none]
+Sets the compression mode of the scanner.  Determines the type of data
+returned from the scanner.  Values are:
+.RS
+.br
+.B none
+\- uncompressed data \- delivered in a SANE_FRAME_GRAY frame
+.br
+.B g31d
+\- CCITT G3 1 dimension (MH) \- delivered in a SANE_FRAME_G31D frame
+.br
+.B g32d
+\- CCITT G3 2 dimensions (MR, K=4) \- delivered in a SANE_FRAME_G32D frame
+.br
+.B g42d
+\- CCITT G4 (MMR) \- delivered in a SANE_FRAME_G42D frame
+.br
+NOTE: The use of g31d, g32d, and g42d compression values causes the backend
+to generate optional frame formats which may not be supported by all SANE
+frontends.
+.RE
+
+.TP
+.B  Geometry Options:
+.TP
+.B \-\-autoborder[=(yes|no)] [yes]
+Enable/Disable automatic image border detection.  When enabled, the RSC unit
+automatically detects the image area and sets the window geometry to match.
+.TP
+.B \-\-paper\-size Custom|Letter|Legal|A3|A4|A5|A6|B4|B5 [Custom]
+Specify the scan window geometry by specifying the paper size of the
+documents to be scanned.
+.TP
+.B \-\-tl\-x 0..297.18mm [0]
+Top-left x position of scan area.
+.TP
+.B \-\-tl\-y 0..431.8mm [0]
+Top-left y position of scan area.
+.TP
+.B \-\-br\-x 0..297.18mm [297.18]
+Bottom-right x position of scan area.
+.TP
+.B \-\-br\-y 0..431.8mm [431.8]
+Bottom-right y position of scan area.
+.TP
+.B  Feeder Options:
+.TP
+.B \-\-source Automatic Document Feeder|Manual Feed Tray [Automatic Document Feeder]
+Selects the scan source (such as a document feeder).  This option is provided 
+to allow multiple image scans with xsane; it has no other purpose.
+.TP
+.B \-\-batch[=(yes|no)] [no]
+Enable/disable batch mode scanning.  Batch mode allows scanning at maximum throughput
+by buffering within the RSC unit.  This option is recommended when performing multiple
+pages scans until the feeder is emptied.
+.TP
+.B \-\-duplex[=(yes|no)] [no]
+Enable duplex (dual-sided) scanning.  The scanner takes an image of each side
+of the document during a single pass through the scanner.  The front page is
+delivered followed by the back page.  Most options, such as compression,
+affect both the front and back pages.
+.TP
+.B \-\-timeout\-adf 0..255 [0]
+Sets the timeout in seconds for the automatic document feeder (ADF).
+The value 0 specifies the hardware default value which varies based 
+on the scanner model.
+.TP
+.B \-\-timeout\-manual 0..255 [0]
+Sets the timeout in seconds for semi-automatic feeder.  The value 0 specifies
+the hardware default value which varies based on the scanner model.
+.TP
+.B \-\-check\-adf[=(yes|no)] [no]
+Check ADF Status prior to starting scan using the OBJECT POSITION command.
+Note that this feature requires RSC firmware level 1.5 or higher and dip
+switch 4 must be in the on position.  NOTE: This option has not been tested
+extensively and may produce undesirable results.
+.TP
+.B  Enhancement:
+.TP
+.B \-\-control\-panel[=(yes|no)] [yes]
+Enables the scanner's control panel for selecting image enhancement
+parameters.  When the option is set to no the following options are
+used to control image enhancement.  See the Bell+Howell scanner users'
+guide for complete information on ACE functionality.
+.TP
+.B \-\-ace\-function \-4..4 [3]
+Specify the Automatic Contrast Enhancement (ACE) Function.
+.TP
+.B \-\-ace\-sensitivity 0..9 [5]
+Specify the Automatic Contrast Enhancement (ACE) Sensitivity.
+.TP
+.B \-\-brightness 0..255 [0]
+Controls the brightness of the acquired image.  Ignored for ACE
+capable scanners.
+.TP
+.B \-\-threshold 0..255 [0]
+Select minimum-brightness to get a white point.  Ignored for ACE
+capable scanners.
+.TP
+.B \-\-contrast 0..255 [inactive]
+Controls the contrast of the acquired image.  This option is not
+currently used by the scanner (and perhaps never will be).
+.TP
+.B \-\-negative[=(yes|no)] [no]
+Swap black and white, yielding a reverse-video image.
+.TP
+.B Icon:
+.TP
+.B \-\-icon\-width 0..3600pel (in steps of 8) [0]
+Width of icon (thumbnail) image in pixels.
+.TP
+.B \-\-icon\-length 0..3600pel (in steps of 8) [0]
+Length of icon (thumbnail) image in pixels.
+.TP
+.B Barcode Options:
+.TP
+.B \-\-barcode\-search\-bar <see list> [none]
+Specifies the barcode type to search for.  If this option is
+not specified, or specified with a value of none, then the barcode decoding
+feature is completely disabled.  The valid barcode type are:
+.RS
+.br
+.B none
+.br 
+.B ean\-8
+.br
+.B ean\-13
+.br 
+.B reserved\-ean\-add
+.br 
+.B code39
+.br 
+.B code2\-5\-interleaved
+.br 
+.B code2\-5\-3lines\-matrix
+.br 
+.B code2\-5\-3lines\-datalogic
+.br 
+.B code2\-5\-5lines\-industrial
+.br 
+.B patchcode
+.br 
+.B codabar
+.br 
+.B codabar\-with\-start\-stop
+.br 
+.B code39ascii
+.br 
+.B code128
+.br 
+.B code2\-5\-5lines\-iata
+.br
+.RE
+.TP
+.B \-\-barcode\-search\-count 1..7 [3]
+Number of times that the RSC performs the decoding algorithm.  Specify
+the smallest number possible to increase performance.  If you are having 
+trouble recognizing barcodes, it is suggested that you increase this option
+to its maximum value (7).
+.TP
+.B \-\-barcode\-search\-mode <see list> [horiz\-vert]
+Chooses the orientation of barcodes to be searched.  The valid orientations
+are:
+.RS
+.br
+.B horiz\-vert
+.br
+.B horizontal
+.br
+.B vertical
+.br
+.B vert\-horiz
+.RE
+.TP
+.B \-\-barcode\-hmin 0..1660mm [5]
+Sets the barcode minimum height in millimeters (larger values increase 
+recognition speed).  Of course the actual barcodes in the document must be
+of sufficient size.
+.TP
+.B \-\-barcode\-search\-timeout 20..65535us [10000]
+Sets the timeout for barcode searching in milliseconds.  When the timeout
+expires, the decoder will stop trying to decode barcodes.
+.TP
+.B \-\-section <string> []
+Specifies a series of image sections.  A section can be used to gather
+a subset image or to provide a small area for barcode decoding.    
+Each section is specified in the following format (units are in millimeters):
+.PP
+.B <width>x<height>+<top-left-x>+<top-left-y>[:functioncode...]
+.PP 
+Multiple sections can be specified by separating them with commas.
+.PP
+For example
+.B 76.2x25.4+50.8+0:frontbar
+identifies an area 3 inches wide and 1 inch high with a top left corner 
+at the top of the page two inches from the left hand edge of the page.
+This section will be used for barcode decoding on the front page only.  
+.PP
+For example
+.B 50.8x25.4+25.4+0:frontbar:front:g42d 
+identifies an area 2 inches wide and 1 inch high with a top left corner 
+at the top of the page one inch from the left hand edge of the page.  
+This section will be used for barcode decoding on the front page as well 
+as generating an image compressed in g42d format.  
+.PP
+Ordinarily barcodes are searched in the entire image.  However, when you
+specify sections all barcode searching is done within the specific sections
+identified.  This can significantly speed up the decoding process.  
+
+The following functioncodes are available:
+.RS
+.br
+.B front
+\- generate an image for the front page section
+.br 
+.B back
+\- generate an image for the back page section
+.br
+.B frontbar
+\- perform barcode search in front page section
+.br 
+.B backbar
+\- perform barcode search in back page section
+.br
+.B frontpatch
+\- perform patchcode search in front page section
+.br 
+.B backpatch
+\- perform patchcode search in back page section
+.br
+.B none
+\- use no image compression
+.br 
+.B g31d
+\- use Group 3 1 dimension image compression
+.br 
+.B g32d
+\- use Group 3 2 dimensions image compression
+.br 
+.B g42d
+\- use Group 4 2 dimensions image compression
+.br
+.RE
+.PP
+If you omit a compression functioncode, the full page compression setting
+is used.  If you specify multiple compression functioncodes, only the 
+last one is used.
+
+.TP
+.B \-\-barcode\-relmax 0..255 [0]
+Specifies the maximum relation from the widest to the smallest bar.
+.TP
+.B \-\-barcode\-barmin 0..255 [0]
+Specifies the minimum number of bars in Bar/Patch code.
+.TP
+.B \-\-barcode\-barmax 0..255 [0]
+Specifies the maximum number of bars in a Bar/Patch code.
+.TP
+.B \-\-barcode\-contrast 0..6 [3]
+Specifies the image contrast used in decoding.  Use higher values when
+there are more white pixels in the code.
+.TP
+.B \-\-barcode\-patchmode 0..1 [0]
+Controls Patch Code detection.
+
+.SH BUGS
+This is a new backend; detailed bug reports are welcome -- and expected ;)
+.PP
+If you have found something that you think is a bug, please attempt to
+recreate it with the SANE_DEBUG_BH environment variable set to
+255, and send a report detailing the conditions surrounding the bug to
+.IR sane\-devel@lists.alioth.debian.org .
+
+.SH "SEE ALSO"
+sane(7), sane\-scsi(5), scanimage(1), scanadf(1)
+
+.SH AUTHOR
+The sane\-bh backend was written by Tom Martone, based on the sane\-ricoh
+backend by Feico W. Dillema and the bnhscan program by Sean Reifschneider
+of tummy.com ltd.  Some 8000 enhancements added by Mark Temple.