1sane-bh(5) SANE Scanner Access Now Easy sane-bh(5)
2
6 sane-bh - SANE backend for Bell+Howell Copiscan II series document
7 scanners
8
10 The sane-bh library implements a SANE (Scanner Access Now Easy) backend
11 that provides access to Bell+Howell Copiscan II series document scan‐
12 ners. The Copiscan II 6338 has been the primary scanner model used
13 during development and testing, but since the programming interface for
14 the entire series is consistent the backend should work for the follow‐
15 ing scanner models:
16 COPISCAN II 6338 Duplex Scanner with ACE
18 COPISCAN II 2135 Simplex Scanner
19 COPISCAN II 2137(A) Simplex Scanner (with ACE)
20 COPISCAN II 2138A Simplex Scanner with ACE
21 COPISCAN II 3238 Simplex Scanner
22 COPISCAN II 3338(A) Simplex Scanner (with ACE)
23 If you have a Bell+Howell scanner and are able to test it with this
25 backend, please contact sane-devel@alioth-lists.debian.net with the
26 model number and testing results. Have a look at
27 http://www.sane-project.org/mailing-lists.html concerning subscription
28 to sane-devel. Additionally, the author is curious as to the likelihood
29 of using this backend with the newer 4000 and 8000 series scanners. If
30 you have such a beast, please let me know.
31 The Bell+Howell Copiscan II series document scanners are high volume,
33 high throughput scanners designed for document scanning applications.
34 As such, they are lineart/grayscale scanners supporting a fixed number
35 of fairly low resolutions (e.g. 200/240/300dpi). However, they do have
36 a number of interesting and useful features suited to needs of document
37 imaging applications. This backend attempts to support as many of
38 these features as possible.
39 The main technical reference used in writing this backend is the Bell
41 and Howell Copiscan II Remote SCSI Controller (RSC) OEM Technical Man‐
42 ual Version 1.5. The Linux SCSI programming HOWTO, the SANE API docu‐
43 mentation, and SANE source code were also extremely valuable resources.
44 The latest backend release, additional information and helpful hints
47 are available from the backend homepage:
48 http://www.martoneconsulting.com/sane-bh.html
49
51 This backend expects device names of the form:
52 special
54 Where special is the path-name for the special device that corresponds
56 to a SCSI scanner. For SCSI scanners, the special device name must be a
57 generic SCSI device or a symlink to such a device. Under Linux, such a
58 device name takes a format such as /dev/sga or /dev/sg0, for example.
59 See sane-scsi(5) for details.
60
63 Scan Mode Options:
64 --preview[=(yes|no)] [no]
66 Request a preview-quality scan. When preview is set to yes im‐
67 age compression is disabled and the image is delivered in a
68 SANE_FRAME_GRAY frame.
69 --mode lineart|halftone [lineart]
71 Selects the scan mode (e.g., lineart,monochrome, or color).
72 --resolution 200|240|300dpi [200]
74 Sets the resolution of the scanned image. Each scanner model
75 supports a list of standard resolutions; only these resolutions
76 can be used.
77 --compression none|g31d|g32d|g42d [none]
79 Sets the compression mode of the scanner. Determines the type
80 of data returned from the scanner. Values are:
81 none - uncompressed data - delivered in a SANE_FRAME_GRAY frame
83 g31d - CCITT G3 1 dimension (MH) - delivered in a
84 SANE_FRAME_G31D frame
85 g32d - CCITT G3 2 dimensions (MR, K=4) - delivered in a
86 SANE_FRAME_G32D frame
87 g42d - CCITT G4 (MMR) - delivered in a SANE_FRAME_G42D frame
88 NOTE: The use of g31d, g32d, and g42d compression values causes
90 the backend to generate optional frame formats which may not be
91 supported by all SANE frontends.
92 Geometry Options:
95 --autoborder[=(yes|no)] [yes]
97 Enable/Disable automatic image border detection. When enabled,
98 the RSC unit automatically detects the image area and sets the
99 window geometry to match.
100 --paper-size Custom|Letter|Legal|A3|A4|A5|A6|B4|B5 [Custom]
102 Specify the scan window geometry by specifying the paper size of
103 the documents to be scanned.
104 --tl-x 0..297.18mm [0]
106 Top-left x position of scan area.
107 --tl-y 0..431.8mm [0]
109 Top-left y position of scan area.
110 --br-x 0..297.18mm [297.18]
112 Bottom-right x position of scan area.
113 --br-y 0..431.8mm [431.8]
115 Bottom-right y position of scan area.
116 Feeder Options:
118 --source Automatic Document Feeder|Manual Feed Tray [Automatic Document
120 Feeder]
121 Selects the scan source (such as a document feeder). This op‐
122 tion is provided to allow multiple image scans with
123 xsane(1);ithasnootherpurpose.
124 --batch[=(yes|no)] [no]
126 Enable/disable batch mode scanning. Batch mode allows scanning
127 at maximum throughput by buffering within the RSC unit. This
128 option is recommended when performing multiple pages scans until
129 the feeder is emptied.
130 --duplex[=(yes|no)] [no]
132 Enable duplex (dual-sided) scanning. The scanner takes an image
133 of each side of the document during a single pass through the
134 scanner. The front page is delivered followed by the back page.
135 Most options, such as compression, affect both the front and
136 back pages.
137 --timeout-adf 0..255 [0]
139 Sets the timeout in seconds for the automatic document feeder
140 (ADF). The value 0 specifies the hardware default value which
141 varies based on the scanner model.
142 --timeout-manual 0..255 [0]
144 Sets the timeout in seconds for semi-automatic feeder. The
145 value 0 specifies the hardware default value which varies based
146 on the scanner model.
147 --check-adf[=(yes|no)] [no]
149 Check ADF Status prior to starting scan using the OBJECT POSI‐
150 TION command. Note that this feature requires RSC firmware
151 level 1.5 or higher and dip switch 4 must be in the on position.
152 NOTE: This option has not been tested extensively and may pro‐
153 duce undesirable results.
154 Enhancement:
156 --control-panel[=(yes|no)] [yes]
158 Enables the scanner's control panel for selecting image enhance‐
159 ment parameters. When the option is set to no the following op‐
160 tions are used to control image enhancement. See the Bell+How‐
161 ell scanner users' guide for complete information on ACE func‐
162 tionality.
163 --ace-function -4..4 [3]
165 Specify the Automatic Contrast Enhancement (ACE) Function.
166 --ace-sensitivity 0..9 [5]
168 Specify the Automatic Contrast Enhancement (ACE) Sensitivity.
169 --brightness 0..255 [0]
171 Controls the brightness of the acquired image. Ignored for ACE
172 capable scanners.
173 --threshold 0..255 [0]
175 Select minimum-brightness to get a white point. Ignored for ACE
176 capable scanners.
177 --contrast 0..255 [inactive]
179 Controls the contrast of the acquired image. This option is not
180 currently used by the scanner (and perhaps never will be).
181 --negative[=(yes|no)] [no]
183 Swap black and white, yielding a reverse-video image.
184 Icon:
186 --icon-width 0..3600pel (in steps of 8) [0]
188 Width of icon (thumbnail) image in pixels.
189 --icon-length 0..3600pel (in steps of 8) [0]
191 Length of icon (thumbnail) image in pixels.
192 Barcode Options:
194 --barcode-search-bar <see list> [none]
196 Specifies the barcode type to search for. If this option is not
197 specified, or specified with a value of none, then the barcode
198 decoding feature is completely disabled. The valid barcode type
199 are:
200 none
202 ean-8
203 ean-13
204 reserved-ean-add
205 code39
206 code2-5-interleaved
207 code2-5-3lines-matrix
208 code2-5-3lines-datalogic
209 code2-5-5lines-industrial
210 patchcode
211 codabar
212 codabar-with-start-stop
213 code39ascii
214 code128
215 code2-5-5lines-iata
216 --barcode-search-count 1..7 [3]
218 Number of times that the RSC performs the decoding algorithm.
219 Specify the smallest number possible to increase performance.
220 If you are having trouble recognizing barcodes, it is suggested
221 that you increase this option to its maximum value (7).
222 --barcode-search-mode <see list> [horiz-vert]
224 Chooses the orientation of barcodes to be searched. The valid
225 orientations are:
226 horiz-vert
228 horizontal
229 vertical
230 vert-horiz
231 --barcode-hmin 0..1660mm [5]
233 Sets the barcode minimum height in millimeters (larger values
234 increase recognition speed). Of course the actual barcodes in
235 the document must be of sufficient size.
236 --barcode-search-timeout 20..65535us [10000]
238 Sets the timeout for barcode searching in milliseconds. When
239 the timeout expires, the decoder will stop trying to decode bar‐
240 codes.
241 --section <string> []
243 Specifies a series of image sections. A section can be used to
244 gather a subset image or to provide a small area for barcode de‐
245 coding. Each section is specified in the following format
246 (units are in millimeters):
247 <width>x<height>+<top-left-x>+<top-left-y>[:functioncode...]
249 Multiple sections can be specified by separating them with commas.
251 For example 76.2x25.4+50.8+0:frontbar identifies an area 3 inches wide
253 and 1 inch high with a top left corner at the top of the page two
254 inches from the left hand edge of the page. This section will be used
255 for barcode decoding on the front page only.
256 For example 50.8x25.4+25.4+0:frontbar:front:g42d identifies an area 2
258 inches wide and 1 inch high with a top left corner at the top of the
259 page one inch from the left hand edge of the page. This section will
260 be used for barcode decoding on the front page as well as generating an
261 image compressed in g42d format.
262 Ordinarily barcodes are searched in the entire image. However, when
264 you specify sections all barcode searching is done within the specific
265 sections identified. This can significantly speed up the decoding
266 process.
267 The following function codes are available:
269 front - generate an image for the front page section
271 back - generate an image for the back page section
272 frontbar - perform barcode search in front page section
273 backbar - perform barcode search in back page section
274 frontpatch - perform patchcode search in front page section
275 backpatch - perform patchcode search in back page section
276 none - use no image compression
277 g31d - use Group 3 1 dimension image compression
278 g32d - use Group 3 2 dimensions image compression
279 g42d - use Group 4 2 dimensions image compression
280 If you omit a compression functioncode, the full page compression set‐
282 ting is used. If you specify multiple compression functioncodes, only
283 the last one is used.
284 --barcode-relmax 0..255 [0]
287 Specifies the maximum relation from the widest to the smallest
288 bar.
289 --barcode-barmin 0..255 [0]
291 Specifies the minimum number of bars in Bar/Patch code.
292 --barcode-barmax 0..255 [0]
294 Specifies the maximum number of bars in a Bar/Patch code.
295 --barcode-contrast 0..6 [3]
297 Specifies the image contrast used in decoding. Use higher val‐
298 ues when there are more white pixels in the code.
299 --barcode-patchmode 0..1 [0]
301 Controls Patch Code detection.
302
305 The contents of the bh.conf file is a list of device names that corre‐
306 spond to Bell+Howell scanners. See sane-scsi(5) on details of what
307 constitutes a valid device name. Additionally, options can be speci‐
308 fied; these lines begin with the word "option". Each option is de‐
309 scribed in detail below. Empty lines and lines starting with a hash
310 mark (#) are ignored.
311
314 The following options can be specified in the bh.conf file.
315 disable-optional-frames
317 This option prevents the backend from sending any optional
318 frames. This option may be useful when dealing with frontends
319 which do not support these optional frames. When this option is
320 in effect, the data is sent in a SANE_FRAME_GRAY frame. The op‐
321 tional frames sent by this backend are: SANE_FRAME_G31D,
322 SANE_FRAME_G32D, SANE_FRAME_G42D and SANE_FRAME_TEXT. These
323 frames are generated based on the compression and barcode op‐
324 tions. These frames are never sent in preview mode.
325 fake-inquiry
327 This option is used for debugging purposes and its use is not
328 encouraged. Essentially, it allows the backend to initialize in
329 the absence of a scanner. This is useful for development and
330 not much else. This option must be specified earlier in the
331 configuration file than the devices which are to be "faked".
332
335 /etc/sane.d/bh.conf
336 The backend configuration file (see also description of
337 SANE_CONFIG_DIR below).
338 /usr/lib64/sane/libsane-bh.a
340 The static library implementing this backend.
341 /usr/lib64/sane/libsane-bh.so
343 The shared library implementing this backend (present on systems
344 that support dynamic loading).
345
348 SANE_CONFIG_DIR
349 This environment variable specifies the list of directories that
350 may contain the configuration file. On *NIX systems, the direc‐
351 tories are separated by a colon (`:'), under OS/2, they are sep‐
352 arated by a semi-colon (`;'). If this variable is not set, the
353 configuration file is searched in two default directories:
354 first, the current working directory (".") and then in
355 /etc/sane.d. If the value of the environment variable ends with
356 the directory separator character, then the default directories
357 are searched after the explicitly specified directories. For
358 example, setting SANE_CONFIG_DIR to "/tmp/config:" would result
359 in directories tmp/config, ., and /etc/sane.d being searched (in
360 this order).
361 SANE_DEBUG_BH
363 If the library was compiled with debug support enabled, this en‐
364 vironment variable controls the debug level for this backend.
365 E.g., a value of 255 requests all debug output to be printed.
366 Smaller levels reduce verbosity.
367
370 ADF support
371 With document scanners, automatic document feeder (ADF) support
372 is a key feature. The backend supports the ADF by default and
373 returns SANE_STATUS_NO_DOCS when the out-of-paper condition is
374 detected. The SANE frontend scanadf(1) is a command line front‐
375 end that supports multi-page scans. It has been used success‐
376 fully with this backend. The SANE frontend xsane(1) is an im‐
377 proved GUI frontend by Oliver Rauch. Support for multi-page
378 scans is included in xsane version 0.35 and above.
379 Duplex scanning
382 Some models, such as the COPISCAN II 6338, support duplex scan‐
383 ning. That is, they scan both sides of the document during a
384 single pass through the scanner (the scanner has two cameras).
385 This backend supports duplex scanning (with the --duplex op‐
386 tion). The front and back page images are delivered consecu‐
387 tively as if they were separately scanned pages.
388 Hardware compression
391 The scanner is capable of compressing the data into several in‐
392 dustry standard formats (CCITT G3, CCITT G3-2D, CCITT G4). This
393 results in increased performance as less data is passed from the
394 scanner to the host over the SCSI bus. The backend supports
395 these compression formats via the --g31d, --g32d, --g42d op‐
396 tions, respectively. Many SANE frontends are not equipped to
397 deal with these formats, however. The SANE frontend scanadf(1)
398 supports these optional frame formats. The compressed image
399 data is written directly to a file and can then be processed by
400 a scan-script using the --scan-script option. Examples of this
401 are given on the scanadf(1) homepage.
402 Automatic Border Detection
405 The scanner can automatically detect the paper size and adjust
406 the scanning window geometry appropriately. The backend sup‐
407 ports this useful feature with the --autoborder option. It is
408 enabled by default.
409 Batch Mode Scanning
412 The batch scan mode allows for maximum throughput. The Set Win‐
413 dow parameters must remain constant during the entire batch.
414 Icon Generation
417 The Icon function generates a thumbnail of the full page image,
418 that can be transferred as if it were a separate page. This al‐
419 lows the host to quickly display a thumbnail representation dur‐
420 ing the scanning operation. Perhaps this would be a great way
421 of implementing a preview scan, but since a normal scan is so
422 quick, it might not be worth the trouble.
423 Multiple Sections
426 Multiple sections (scanning sub-windows) can be defined for the
427 front and back pages. Each section can have different charac‐
428 teristics (e.g. geometry, compression). The sections are re‐
429 turned as if they were separately scanned images. Additionally
430 sections can be used to greatly enhance the accuracy and effi‐
431 ciency of the barcode/patchcode decoding process by limiting the
432 search area to a small subset of the page. Most Copiscan II se‐
433 ries scanners support up to 8 user-defined sections.
434 Support Barcode/Patchcode Decoding
437 The RSC unit can recognize Bar and Patch Codes of various types
438 embedded in the scanned image. The codes are decoded and the
439 data is returned to the frontend as a text frame. The text is
440 encoded in xml and contains a great deal of information about
441 the decoded data such as the location where it was found, its
442 orientation, and the time it took to find. Further information
443 on the content of this text frame as well as some barcode decod‐
444 ing examples can be found on the backend homepage.
445
448 Decoding a single barcode type per scan
449 The RSC unit can search for up to six different barcode types at
450 a time. While the code generally supports this as well, the
451 --barcode-search-bar option only allows the user to specify a
452 single barcode type. Perhaps another option which allows a
453 comma separated list of barcode type codes could be added to ad‐
454 dress this.
455 Scanning a fixed number of pages in batch mode
457 The separation of front and back end functionality in SANE
458 presents a problem in supporting the 'cancel batch' functional‐
459 ity in the scanner. In batch mode, the scanner is always a page
460 ahead of the host. The host, knowing ahead of time which page
461 will be the last, can cancel batch mode prior to initiating the
462 last scan command. Currently, there is no mechanism available
463 for the frontend to pass this knowledge to the backend. If
464 batch mode is enabled and the --end-count terminates a scanadf
465 session, an extra page will be pulled through the scanner, but
466 is neither read nor delivered to the frontend. The issue can be
467 avoided by specifying --batch=no when scanning a fixed number of
468 pages.
469 Revision 1.2 Patch detector
471 There is an enhanced patchcode detection algorithm available in
472 the RSC with revision 1.2 or higher that is faster and more re‐
473 liable than the standard Bar/Patch code decoder. This is not
474 currently supported.
475
478 This is a new backend; detailed bug reports are welcome -- and expected
479 ;)
480 If you have found something that you think is a bug, please attempt to
482 recreate it with the SANE_DEBUG_BH environment variable set to 255, and
483 send a report detailing the conditions surrounding the bug to sane-de‐
484 vel@alioth-lists.debian.net.
485
488 sane(7), sane-scsi(5), scanimage(1), scanadf(1), xsane(1)
489
492 The sane-bh backend was written by Tom Martone, based on the sane-ri‐
493 coh(5) backend by Feico W. Dillema and the bnhscan program by Sean
494 Reifschneider of tummy.com ltd. Some 8000 enhancements added by Mark
495 Temple.
496 10 Jul 2008 sane-bh(5)