sane-bh(5)

✨ NAME ✨

okay bestie, meet sane-bh(5) — the SANE (Scanner Access Now Easy) backend for Bell+Howell Copiscan II series document scanners 💅✨

🦋 DESCRIPTION 🦋

The 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:

• COPISCAN II 6338 Duplex Scanner with ACE
• COPISCAN II 2135 Simplex Scanner
• COPISCAN II 2137(A) Simplex Scanner (with ACE)
• COPISCAN II 2138A Simplex Scanner with ACE
• COPISCAN II 3238 Simplex Scanner
• COPISCAN II 3338(A) Simplex Scanner (with ACE)

If you have a Bell+Howell scanner and are able to test it with this backend, please contact sane-devel@alioth-lists.debian.net 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 👀✨

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 🫶

The main technical reference used in writing this backend is the Bell and Howell Copiscan II Remote SCSI Controller (RSC) OEM Technical Manual Version 1.5. The Linux SCSI programming HOWTO, the SANE API documentation, and SANE source code were also extremely valuable resources 📚✨

The latest backend release, additional information and helpful hints are available from the backend homepage:

http://www.martoneconsulting.com/sane-bh.html

🎀 DEVICE NAMES 🎀

This backend expects device names of the form:

special

Where 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 /dev/sga or /dev/sg0, for example. See sane-scsi(5) for details 💅✨

✨ OPTIONS ✨

Okay bestie, buckle up, because this is the big one — all the flags you can fling at this backend. 💅

---

🔍 Scan Mode Options

• --preview[=(yes|no)] [no] — Ask for a preview-quality scan. When you set this to yes, image compression gets switched off entirely and the image comes at you in a SANE_FRAME_GRAY frame. Lowkey the easiest way to make sure everything's aligned before you commit to a full scan. 🎀
• --mode lineart|halftone [lineart] — Picks the scan mode (like, you know — lineart, monochrome, or color). Default vibe is lineart.
• --resolution 200|240|300dpi [200] — Sets the resolution of the scanned image. Heads up: each scanner model supports its own list of standard resolutions, and only those resolutions can be used. No custom values, no in-between nonsense. 🙈
• --compression none|g31d|g32d|g42d [none] — Sets the compression mode of the scanner, which is what decides the type of data the scanner hands back to you. The values are:
  • none — uncompressed data — delivered in a SANE_FRAME_GRAY frame
  • g31d — CCITT G3 1 dimension (MH) — delivered in a SANE_FRAME_G31D frame
  • g32d — CCITT G3 2 dimensions (MR, K=4) — delivered in a SANE_FRAME_G32D frame
  • g42d — CCITT G4 (MMR) — delivered in a SANE_FRAME_G42D frame

NOTE: using the g31d, g32d, and g42d compression values makes the backend generate optional frame formats, and bestie… not every SANE frontend supports those. Check before you commit. 😭

---

📐 Geometry Options

• --autoborder[=(yes|no)] [yes] — Turn automatic image border detection on or off. When it's enabled, the RSC unit sniffs out the image area all by itself and sets the window geometry to match. Very main character of it, honestly. ✨
• --paper-size Custom|Letter|Legal|A3|A4|A5|A6|B4|B5 [Custom] — Describes the scan window geometry by just naming the paper size of the documents you're scanning. Custom is the default because we're all free spirits.
• --tl-x 0..297.18mm [0] — Top-left x position of the scan area.
• --tl-y 0..431.8mm [0] — Top-left y position of the scan area.
• --br-x 0..297.18mm [297.18] — Bottom-right x position of the scan area.
• --br-y 0..431.8mm [431.8] — Bottom-right y position of the scan area.

(That's top-left and bottom-right, iykyk — together they box in exactly what gets scanned. 🎯)

---

📄 Feeder Options

• --source Automatic Document Feeder|Manual Feed Tray [Automatic Document Feeder] — Selects the scan source (like a document feeder, for instance). Real talk though: this option exists purely so you can do multiple image scans with xsane(1) — it has no other purpose. Periodt.
• --batch[=(yes|no)] [no] — Enable/disable batch mode scanning. Batch mode lets you scan at maximum throughput by buffering inside the RSC unit. Highly recommended when you're doing multi-page scans until the feeder runs out of paper. 🔥
• --duplex[=(yes|no)] [no] — Enable duplex (dual-sided) scanning! The scanner captures each side of the document on a single pass through, and the front page comes out first, followed by the back page. Most options — compression included — affect both the front and back pages. Two for the price of one, we love efficiency. 💖
• --timeout-adf 0..255 [0] — Sets the timeout in seconds for the automatic document feeder (ADF). The value 0 means "use the hardware default," which varies based on the scanner model.
• --timeout-manual 0..255 [0] — Sets the timeout in seconds for the semi-automatic feeder. Same deal: 0 means the hardware default, which varies by scanner model.
• --check-adf[=(yes|no)] [no] — Check ADF status before starting the scan, using the OBJECT POSITION command. Note that this feature needs 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. Proceed with caution, bestie. 💀

---

🎨 Enhancement

• --control-panel[=(yes|no)] [yes] — Lets the scanner's control panel handle selecting image enhancement parameters. When you flip this to no, the following options take over controlling image enhancement. Peep the Bell+Howell scanner users' guide for the full tea on ACE functionality. ☕
• --ace-function -4..4 [3] — Specify the Automatic Contrast Enhancement (ACE) Function.
• --ace-sensitivity 0..9 [5] — Specify the Automatic Contrast Enhancement (ACE) Sensitivity.
• --brightness 0..255 [0] — Controls the brightness of the acquired image. Ignored on ACE-capable scanners (they've got their own thing going on).
• --threshold 0..255 [0] — Select minimum-brightness to get a white point. Also ignored on ACE-capable scanners.
• --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. Rip, honestly. 🪦
• --negative[=(yes|no)] [no] — Swaps black and white, giving you a reverse-video image. Spooky season aesthetic. 🌈

---

🖼️ Icon

• --icon-width 0..3600pel (in steps of 8) [0] — Width of the icon (thumbnail) image in pixels.
• --icon-length 0..3600pel (in steps of 8) [0] — Length of the icon (thumbnail) image in pixels.

---

🏷️ Barcode Options

Okay this is the section where things get fun. 🎉

• --barcode-search-bar <see list> [none] — Specifies the barcode type to search for. If you don't specify this option, or you specify it with a value of none, the barcode decoding feature is completely disabled. The valid barcode types are:

none
ean-8
ean-13
reserved-ean-add
code39
code2-5-interleaved
code2-5-3lines-matrix
code2-5-3lines-datalogic
code2-5-5lines-industrial
patchcode
codabar
codabar-with-start-stop
code39ascii
code128
code2-5-5lines-iata

• --barcode-search-count 1..7 [3] — How many times the RSC runs the decoding algorithm. Pick the smallest number you can get away with, because that's what boosts performance. If barcodes are being stubborn and won't get recognized, the suggestion is to crank this to its maximum value (7). 🫶
• --barcode-search-mode <see list> [horiz-vert] — Chooses which orientation(s) to search for barcodes in. Valid orientations:
  • horiz-vert
  • horizontal
  • vertical
  • vert-horiz
• --barcode-hmin 0..1660mm [5] — Sets the barcode minimum height in millimeters. Larger values increase recognition speed — and of course the actual barcodes in the document have to be of sufficient size for that to work out. 😌
• --barcode-search-timeout 20..65535us [10000] — Sets the timeout for barcode searching in milliseconds. When the timeout expires, the decoder stops trying to decode barcodes. Clock's up, babes. ⏰
• --section <string> [] — Specifies a series of image sections. A section can gather a subset image, or give you a small area for barcode decoding. Each section is specified in this format (units are in millimeters):

<width>x<height>+<top-left-x>+<top-left-y>[:functioncode...]

Multiple sections can be specified by separating them with commas.

For example 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.

For example 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.

Ordinarily barcodes are searched in the entire image. But when you specify sections, all barcode searching happens within the specific sections identified — which can significantly speed up the decoding process. ✨

The following function codes are available:

• front — generate an image for the front page section
• back — generate an image for the back page section
• frontbar — perform barcode search in front page section
• backbar — perform barcode search in back page section
• frontpatch — perform patchcode search in front page section
• backpatch — perform patchcode search in back page section
• none — use no image compression
• g31d — use Group 3 1 dimension image compression
• g32d — use Group 3 2 dimensions image compression
• g42d — use Group 4 2 dimensions image compression

If you omit a compression functioncode, the full page compression setting gets used. If you specify multiple compression functioncodes, only the last one is used. (Last one wins, classic. 🙈)

• --barcode-relmax 0..255 [0] — Specifies the maximum relation from the widest to the smallest bar.
• --barcode-barmin 0..255 [0] — Specifies the minimum number of bars in Bar/Patch code.
• --barcode-barmax 0..255 [0] — Specifies the maximum number of bars in a Bar/Patch code.
• --barcode-contrast 0..6 [3] — Specifies the image contrast used in decoding. Use higher values when there are more white pixels in the code. 🌸
• --barcode-patchmode 0..1 [0] — Controls Patch Code detection.

---

🛠️ CONFIGURATION

So the contents of the bh.conf file is just a list of device names that correspond to Bell+Howell scanners. Wanna know what actually counts as a valid device name? Go check sane-scsi(5) — it's got all the details. 💅

On top of that, you can specify options in there too — those lines start with the word "option". Each one gets described in detail right below. Empty lines and lines starting with a hash mark (#) are ignored, because we respect the comment aesthetic. 💜

---

💅 OPTIONS 💅 (round two — the bh.conf edition)

The following options can be specified in the bh.conf file:

• disable-optional-frames — This stops the backend from sending any optional frames. Super useful when you're dealing with frontends that don't support those optional frames. When this option is in effect, the data is sent in a SANE_FRAME_GRAY frame. The optional frames this backend sends are: SANE_FRAME_G31D, SANE_FRAME_G32D, SANE_FRAME_G42D and SANE_FRAME_TEXT — all generated based on the compression and barcode options. And ngl, these frames are never sent in preview mode. 🦋
• fake-inquiry — This one's for debugging purposes and its use is not encouraged. Basically it lets the backend initialize even when there's no scanner present. Useful for development and not much else. Heads up: this option must be specified earlier in the configuration file than the devices which are to be "faked". 👀

---

📁 FILES

• /etc/sane.d/bh.conf — The backend configuration file (see also the description of SANE_CONFIG_DIR below).
• /usr/lib64/sane/libsane-bh.a — The static library implementing this backend.
• /usr/lib64/sane/libsane-bh.so — The shared library implementing this backend (present on systems that support dynamic loading).

🌿 ENVIRONMENT 🌿

Okay bestie, env var time — these two are the vibe check for where config lives and how loud the debug chat gets.

• SANE_CONFIG_DIR — this env var gives you the list of directories that may contain the configuration file. On *NIX systems, 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 /etc/sane.d. 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 SANE_CONFIG_DIR to "/tmp/config:" would result in directories tmp/config, ., and /etc/sane.d being searched (in this order).
• 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.

---

✨ SUPPORTED FEATURES ✨

This is the iconic stuff, bestie — the features that make this backend actually slay.

🧚 ADF support

With document scanners, automatic document feeder (ADF) support is a key feature. The backend supports the ADF by default and returns SANE_STATUS_NO_DOCS when the out-of-paper condition is detected. The SANE frontend scanadf(1) is a command line frontend that supports multi-page scans. It has been used successfully with this backend. The SANE frontend xsane(1) is an improved GUI frontend by Oliver Rauch. Support for multi-page scans is included in xsane version 0.35 and above.

🦋 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 --duplex option). The front and back page images are delivered consecutively as if they were separately scanned pages.

🔥 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 --g31d, --g32d, --g42d options, respectively. Many SANE frontends are not equipped to deal with these formats, however. The SANE frontend scanadf(1) 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 --scan-script option. Examples of this are given on the scanadf(1) homepage.

🎀 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 --autoborder option. It is enabled by default.

💅 Batch Mode Scanning

The batch scan mode allows for maximum throughput. The Set Window parameters must remain constant during the entire batch.

👑 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.

🌈 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.

🍓 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.

---

💀 LIMITATIONS 💀

Not everything is slay, bestie — here's the real talk.

🙈 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 --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.

😭 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(1) 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.

💀 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.

---

🫶 BUGS 🫶

Detailed bug reports are welcome — and expected ;) bestie, we mean it.

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 sane-devel@alioth-lists.debian.net.

🌸 SEE ALSO 🌸

Go peek at sane(7), sane-scsi(5), scanimage(1), scanadf(1), and xsane(1) — they're all in the group chat.

👑 AUTHOR 👑

The sane-bh backend was written by Tom Martone, based on the sane-ricoh(5) backend by Feico W. Dillema and the bnhscan program by Sean Reifschneider of tummy.com ltd. Some 8000 enhancements added by Mark Temple.

---

That's the whole manual, bestie — the source/version footer says sane-bh(5) and the date is 10 Jul 2008. Stay iconic, and happy scanning 💖✨