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
62 The contents of the bh.conf file is a list of device names that corre‐
63 spond to Bell+Howell scanners. See sane-scsi(5) on details of what
64 constitutes a valid device name. Additionally, options can be speci‐
65 fied; these lines begin with the word "option". Each option is
66 described in detail below. Empty lines and lines starting with a hash
67 mark (#) are ignored.
68
71 The following options can be specified in the bh.conf file.
72 disable-optional-frames
74 This option prevents the backend from sending any optional
75 frames. This option may be useful when dealing with frontends
76 which do not support these optional frames. When this option is
77 in effect, the data is sent in a SANE_FRAME_GRAY frame. The
78 optional frames sent by this backend are: SANE_FRAME_G31D,
79 SANE_FRAME_G32D, SANE_FRAME_G42D and SANE_FRAME_TEXT. These
80 frames are generated based on the compression and barcode
81 options. These frames are never sent in preview mode.
82 fake-inquiry
84 This option is used for debugging purposes and its use is not
85 encouraged. Essentially, it allows the backend to initialize in
86 the absence of a scanner. This is useful for development and
87 not much else. This option must be specified earlier in the
88 configuration file than the devices which are to be "faked".
89
92 /etc/sane.d/bh.conf
93 The backend configuration file (see also description of
94 SANE_CONFIG_DIR below).
95 /usr/lib64/sane/libsane-bh.a
97 The static library implementing this backend.
98 /usr/lib64/sane/libsane-bh.so
100 The shared library implementing this backend (present on systems
101 that support dynamic loading).
102
104 SANE_CONFIG_DIR
105 This environment variable specifies the list of directories that
106 may contain the configuration file. Under UNIX, the directories
107 are separated by a colon (`:'), under OS/2, they are separated
108 by a semi-colon (`;'). If this variable is not set, the config‐
109 uration file is searched in two default directories: first, the
110 current working directory (".") and then in /etc/sane.d. If the
111 value of the environment variable ends with the directory sepa‐
112 rator character, then the default directories are searched after
113 the explicitly specified directories. For example, setting
114 SANE_CONFIG_DIR to "/tmp/config:" would result in directories
115 "tmp/config", ".", and "/etc/sane.d" being searched (in this
116 order).
117 SANE_DEBUG_BH
119 If the library was compiled with debug support enabled, this
120 environment variable controls the debug level for this backend.
121 E.g., a value of 255 requests all debug output to be printed.
122 Smaller levels reduce verbosity.
123
126 ADF support
127 With document scanners, automatic document feeder (ADF) support
128 is a key feature. The backend supports the ADF by default and
129 returns SANE_STATUS_NO_DOCS when the out-of-paper condition is
130 detected. The SANE frontend scanadf is a command line frontend
131 that supports multi-page scans. It has been used successfully
132 with this backend. The SANE frontend xsane is an improved GUI
133 frontend by Oliver Rauch. Support for multi-page scans is
134 included in xsane version 0.35 and above.
135 Duplex scanning
138 Some models, such as the COPISCAN II 6338, support duplex scan‐
139 ning. That is, they scan both sides of the document during a
140 single pass through the scanner (the scanner has two cameras).
141 This backend supports duplex scanning (with the --duplex
142 option). The front and back page images are delivered consecu‐
143 tively as if they were separately scanned pages.
144 Hardware compression
147 The scanner is capable of compressing the data into several
148 industry standard formats (CCITT G3, CCITT G3-2D, CCITT G4).
149 This results in increased performance as less data is passed
150 from the scanner to the host over the SCSI bus. The backend
151 supports these compression formats via the --g31d, --g32d,
152 --g42d options, respectively. Many SANE frontends are not
153 equipped to deal with these formats, however. The SANE frontend
154 scanadf supports these optional frame formats. The compressed
155 image data is written directly to a file and can then be pro‐
156 cessed by a scan-script using the --scan-script option. Exam‐
157 ples of this are given on the scanadf homepage.
158 Automatic Border Detection
161 The scanner can automatically detect the paper size and adjust
162 the scanning window geometry appropriately. The backend sup‐
163 ports this useful feature with the --autoborder option. It is
164 enabled by default.
165 Batch Mode Scanning
168 The batch scan mode allows for maximum throughput. The Set Win‐
169 dow parameters must remain constant during the entire batch.
170 Icon Generation
173 The Icon function generates a thumbnail of the full page image,
174 that can be transferred as if it were a separate page. This
175 allows the host to quickly display a thumbnail representation
176 during the scanning operation. Perhaps this would be a great
177 way of implementing a preview scan, but since a normal scan is
178 so quick, it might not be worth the trouble.
179 Multiple Sections
182 Multiple sections (scanning sub-windows) can be defined for the
183 front and back pages. Each section can have different charac‐
184 teristics (e.g. geometry, compression). The sections are
185 returned as if they were separately scanned images. Addition‐
186 ally sections can be used to greatly enhance the accuracy and
187 efficiency of the barcode/patchcode decoding process by limiting
188 the search area to a small subset of the page. Most Copiscan II
189 series scanners support up to 8 user-defined sections.
190 Support Barcode/Patchcode Decoding
193 The RSC unit can recognize Bar and Patch Codes of various types
194 embedded in the scanned image. The codes are decoded and the
195 data is returned to the frontend as a text frame. The text is
196 encoded in xml and contains a great deal of information about
197 the decoded data such as the location where it was found, its
198 orientation, and the time it took to find. Further information
199 on the content of this text frame as well as some barcode decod‐
200 ing examples can be found on the backend homepage.
201
204 Decoding a single barcode type per scan
205 The RSC unit can search for up to six different barcode types at
206 a time. While the code generally supports this as well, the
207 --barcode-search-bar option only allows the user to specify a
208 single barcode type. Perhaps another option which allows a
209 comma separated list of barcode type codes could be added to
210 address this.
211 Scanning a fixed number of pages in batch mode
213 The separation of front and back end functionality in SANE
214 presents a problem in supporting the 'cancel batch' functional‐
215 ity in the scanner. In batch mode, the scanner is always a page
216 ahead of the host. The host, knowing ahead of time which page
217 will be the last, can cancel batch mode prior to initiating the
218 last scan command. Currently, there is no mechanism available
219 for the frontend to pass this knowledge to the backend. If
220 batch mode is enabled and the --end-count terminates a scanadf
221 session, an extra page will be pulled through the scanner, but
222 is neither read nor delivered to the frontend. The issue can be
223 avoided by specifying --batch=no when scanning a fixed number of
224 pages.
225 Revision 1.2 Patch detector
227 There is an enhanced patchcode detection algorithm available in
228 the RSC with revision 1.2 or higher that is faster and more
229 reliable than the standard Bar/Patch code decoder. This is not
230 currently supported.
231
234 Scan Mode Options:
235 --preview[=(yes|no)] [no]
237 Request a preview-quality scan. When preview is set to yes
238 image compression is disabled and the image is delivered in a
239 SANE_FRAME_GRAY frame.
240 --mode lineart|halftone [lineart]
242 Selects the scan mode (e.g., lineart,monochrome, or color).
243 --resolution 200|240|300dpi [200]
245 Sets the resolution of the scanned image. Each scanner model
246 supports a list of standard resolutions; only these resolutions
247 can be used.
248 --compression none|g31d|g32d|g42d [none]
250 Sets the compression mode of the scanner. Determines the type
251 of data returned from the scanner. Values are:
252 none - uncompressed data - delivered in a SANE_FRAME_GRAY frame
253 g31d - CCITT G3 1 dimension (MH) - delivered in a
254 SANE_FRAME_G31D frame
255 g32d - CCITT G3 2 dimensions (MR, K=4) - delivered in a
256 SANE_FRAME_G32D frame
257 g42d - CCITT G4 (MMR) - delivered in a SANE_FRAME_G42D frame
258 NOTE: The use of g31d, g32d, and g42d compression values causes
259 the backend to generate optional frame formats which may not be
260 supported by all SANE frontends.
261 Geometry Options:
264 --autoborder[=(yes|no)] [yes]
266 Enable/Disable automatic image border detection. When enabled,
267 the RSC unit automatically detects the image area and sets the
268 window geometry to match.
269 --paper-size Custom|Letter|Legal|A3|A4|A5|A6|B4|B5 [Custom]
271 Specify the scan window geometry by specifying the paper size of
272 the documents to be scanned.
273 --tl-x 0..297.18mm [0]
275 Top-left x position of scan area.
276 --tl-y 0..431.8mm [0]
278 Top-left y position of scan area.
279 --br-x 0..297.18mm [297.18]
281 Bottom-right x position of scan area.
282 --br-y 0..431.8mm [431.8]
284 Bottom-right y position of scan area.
285 Feeder Options:
287 --source Automatic Document Feeder|Manual Feed Tray [Automatic Document
289 Feeder]
290 Selects the scan source (such as a document feeder). This
291 option is provided to allow multiple image scans with xsane; it
292 has no other purpose.
293 --batch[=(yes|no)] [no]
295 Enable/disable batch mode scanning. Batch mode allows scanning
296 at maximum throughput by buffering within the RSC unit. This
297 option is recommended when performing multiple pages scans until
298 the feeder is emptied.
299 --duplex[=(yes|no)] [no]
301 Enable duplex (dual-sided) scanning. The scanner takes an image
302 of each side of the document during a single pass through the
303 scanner. The front page is delivered followed by the back page.
304 Most options, such as compression, affect both the front and
305 back pages.
306 --timeout-adf 0..255 [0]
308 Sets the timeout in seconds for the automatic document feeder
309 (ADF). The value 0 specifies the hardware default value which
310 varies based on the scanner model.
311 --timeout-manual 0..255 [0]
313 Sets the timeout in seconds for semi-automatic feeder. The
314 value 0 specifies the hardware default value which varies based
315 on the scanner model.
316 --check-adf[=(yes|no)] [no]
318 Check ADF Status prior to starting scan using the OBJECT POSI‐
319 TION command. Note that this feature requires RSC firmware
320 level 1.5 or higher and dip switch 4 must be in the on position.
321 NOTE: This option has not been tested extensively and may pro‐
322 duce undesirable results.
323 Enhancement:
325 --control-panel[=(yes|no)] [yes]
327 Enables the scanner's control panel for selecting image enhance‐
328 ment parameters. When the option is set to no the following
329 options are used to control image enhancement. See the
330 Bell+Howell scanner users' guide for complete information on ACE
331 functionality.
332 --ace-function -4..4 [3]
334 Specify the Automatic Contrast Enhancement (ACE) Function.
335 --ace-sensitivity 0..9 [5]
337 Specify the Automatic Contrast Enhancement (ACE) Sensitivity.
338 --brightness 0..255 [0]
340 Controls the brightness of the acquired image. Ignored for ACE
341 capable scanners.
342 --threshold 0..255 [0]
344 Select minimum-brightness to get a white point. Ignored for ACE
345 capable scanners.
346 --contrast 0..255 [inactive]
348 Controls the contrast of the acquired image. This option is not
349 currently used by the scanner (and perhaps never will be).
350 --negative[=(yes|no)] [no]
352 Swap black and white, yielding a reverse-video image.
353 Icon:
355 --icon-width 0..3600pel (in steps of 8) [0]
357 Width of icon (thumbnail) image in pixels.
358 --icon-length 0..3600pel (in steps of 8) [0]
360 Length of icon (thumbnail) image in pixels.
361 Barcode Options:
363 --barcode-search-bar <see list> [none]
365 Specifies the barcode type to search for. If this option is not
366 specified, or specified with a value of none, then the barcode
367 decoding feature is completely disabled. The valid barcode type
368 are:
369 none
370 ean-8
371 ean-13
372 reserved-ean-add
373 code39
374 code2-5-interleaved
375 code2-5-3lines-matrix
376 code2-5-3lines-datalogic
377 code2-5-5lines-industrial
378 patchcode
379 codabar
380 codabar-with-start-stop
381 code39ascii
382 code128
383 code2-5-5lines-iata
384 --barcode-search-count 1..7 [3]
386 Number of times that the RSC performs the decoding algorithm.
387 Specify the smallest number possible to increase performance.
388 If you are having trouble recognizing barcodes, it is suggested
389 that you increase this option to its maximum value (7).
390 --barcode-search-mode <see list> [horiz-vert]
392 Chooses the orientation of barcodes to be searched. The valid
393 orientations are:
394 horiz-vert
395 horizontal
396 vertical
397 vert-horiz
398 --barcode-hmin 0..1660mm [5]
400 Sets the barcode minimum height in millimeters (larger values
401 increase recognition speed). Of course the actual barcodes in
402 the document must be of sufficient size.
403 --barcode-search-timeout 20..65535us [10000]
405 Sets the timeout for barcode searching in milliseconds. When
406 the timeout expires, the decoder will stop trying to decode bar‐
407 codes.
408 --section <string> []
410 Specifies a series of image sections. A section can be used to
411 gather a subset image or to provide a small area for barcode
412 decoding. Each section is specified in the following format
413 (units are in millimeters):
414 <width>x<height>+<top-left-x>+<top-left-y>[:functioncode...]
416 Multiple sections can be specified by separating them with commas.
418 For example 76.2x25.4+50.8+0:frontbar identifies an area 3 inches wide
420 and 1 inch high with a top left corner at the top of the page two
421 inches from the left hand edge of the page. This section will be used
422 for barcode decoding on the front page only.
423 For example 50.8x25.4+25.4+0:frontbar:front:g42d identifies an area 2
425 inches wide and 1 inch high with a top left corner at the top of the
426 page one inch from the left hand edge of the page. This section will
427 be used for barcode decoding on the front page as well as generating an
428 image compressed in g42d format.
429 Ordinarily barcodes are searched in the entire image. However, when
431 you specify sections all barcode searching is done within the specific
432 sections identified. This can significantly speed up the decoding
433 process.
434 The following functioncodes are available:
436 front - generate an image for the front page section
437 back - generate an image for the back page section
438 frontbar - perform barcode search in front page section
439 backbar - perform barcode search in back page section
440 frontpatch - perform patchcode search in front page section
441 backpatch - perform patchcode search in back page section
442 none - use no image compression
443 g31d - use Group 3 1 dimension image compression
444 g32d - use Group 3 2 dimensions image compression
445 g42d - use Group 4 2 dimensions image compression
446 If you omit a compression functioncode, the full page compression set‐
448 ting is used. If you specify multiple compression functioncodes, only
449 the last one is used.
450 --barcode-relmax 0..255 [0]
453 Specifies the maximum relation from the widest to the smallest
454 bar.
455 --barcode-barmin 0..255 [0]
457 Specifies the minimum number of bars in Bar/Patch code.
458 --barcode-barmax 0..255 [0]
460 Specifies the maximum number of bars in a Bar/Patch code.
461 --barcode-contrast 0..6 [3]
463 Specifies the image contrast used in decoding. Use higher val‐
464 ues when there are more white pixels in the code.
465 --barcode-patchmode 0..1 [0]
467 Controls Patch Code detection.
468
471 This is a new backend; detailed bug reports are welcome -- and expected
472 ;)
473 If you have found something that you think is a bug, please attempt to
475 recreate it with the SANE_DEBUG_BH environment variable set to 255, and
476 send a report detailing the conditions surrounding the bug to
477 sane-devel@alioth-lists.debian.net.
478
481 sane(7), sane-scsi(5), scanimage(1), scanadf(1)
482
485 The sane-bh backend was written by Tom Martone, based on the sane-ricoh
486 backend by Feico W. Dillema and the bnhscan program by Sean Reifschnei‐
487 der of tummy.com ltd. Some 8000 enhancements added by Mark Temple.
488 10 Jul 2008 sane-bh(5)