Debian Codegraph @

upstream/debian-unstable/man5/sane-bh.5

raw
1 .TH sane\-bh 5 "10 Jul 2008" "" "SANE Scanner Access Now Easy"
2 .IX sane\-bh
3 .SH NAME
4 sane\-bh \- SANE backend for Bell+Howell Copiscan II series document
5 scanners
6 .SH DESCRIPTION
7 The
8 .B sane\-bh
9 library implements a SANE (Scanner Access Now Easy) backend that
10 provides access to Bell+Howell Copiscan II series document
11 scanners. The Copiscan II 6338 has been the primary scanner model
12 used during development and testing, but since the programming interface
13 for the entire series is consistent the backend should work for the
14 following scanner models:
15 .PP
16 .RS
17 COPISCAN II 6338 Duplex Scanner with ACE
18 .br
19 COPISCAN II 2135 Simplex Scanner
20 .br
21 COPISCAN II 2137(A) Simplex Scanner (with ACE)
22 .br
23 COPISCAN II 2138A Simplex Scanner with ACE
24 .br
25 COPISCAN II 3238 Simplex Scanner
26 .br
27 COPISCAN II 3338(A) Simplex Scanner (with ACE)
28 .br
29 .RE
30 .PP
31 If you have a Bell+Howell scanner and are able to test it with this
32 backend, please contact
33 .I sane\[email protected]
34 with the model number and testing results. Have a look at
35 .I http://www.sane\-project.org/mailing\-lists.html
36 concerning subscription to sane\-devel. Additionally, the author is
37 curious as to the likelihood of using this backend with the newer 4000
38 and 8000 series scanners. If you have such a beast, please let me know.
39 .PP
40 The Bell+Howell Copiscan II series document scanners are high
41 volume, high throughput scanners designed for document scanning
42 applications. As such, they are lineart/grayscale scanners supporting
43 a fixed number of fairly low resolutions (e.g. 200/240/300dpi).
44 However, they do have a number of interesting and useful features
45 suited to needs of document imaging applications.
46 This backend attempts to support as many of these features as possible.
47 .PP
48 The main technical reference used in writing this backend is the
49 .B Bell and Howell Copiscan II Remote SCSI Controller (RSC) OEM
50 .B Technical Manual Version 1.5.
51 The Linux SCSI programming HOWTO, the SANE API documentation, and
52 SANE source code were also extremely valuable resources.
53
54 .PP
55 The latest backend release, additional information and helpful hints
56 are available from the backend homepage:
57 .br
58 .RS
59 .I http://www.martoneconsulting.com/sane\-bh.html
60 .RE
61 .SH "DEVICE NAMES"
62 This backend expects device names of the form:
63 .PP
64 .RS
65 .I special
66 .RE
67 .PP
68 Where
69 .I special
70 is the path-name for the special device that corresponds to a SCSI
71 scanner. For SCSI scanners, the special device name must be a generic
72 SCSI device or a symlink to such a device. Under Linux, such a device
73 name takes a format such as
74 .I /dev/sga
75 or
76 .IR /dev/sg0 ,
77 for example. See
78 .BR sane\-scsi (5)
79 for details.
80
81 .SH OPTIONS
82 .TP
83 .B Scan Mode Options:
84 .TP
85 .B \-\-preview[=(yes|no)] [no]
86 Request a preview-quality scan. When preview is set to yes image
87 compression is disabled and the image is delivered in a
88 .B SANE_FRAME_GRAY
89 frame.
90 .TP
91 .B \-\-mode lineart|halftone [lineart]
92 Selects the scan mode (e.g., lineart, monochrome, or color).
93 .TP
94 .B \-\-resolution 200|240|300dpi [200]
95 Sets the resolution of the scanned image. Each scanner model supports
96 a list of standard resolutions; only these resolutions can be used.
97 .TP
98 .B \-\-compression none|g31d|g32d|g42d [none]
99 Sets the compression mode of the scanner. Determines the type of data
100 returned from the scanner. Values are:
101
102 .RS
103 .br
104 .B none
105 \- uncompressed data \- delivered in a SANE_FRAME_GRAY frame
106 .br
107 .B g31d
108 \- CCITT G3 1 dimension (MH) \- delivered in a SANE_FRAME_G31D frame
109 .br
110 .B g32d
111 \- CCITT G3 2 dimensions (MR, K=4) \- delivered in a SANE_FRAME_G32D frame
112 .br
113 .B g42d
114 \- CCITT G4 (MMR) \- delivered in a SANE_FRAME_G42D frame
115 .br
116
117 .BR NOTE :
118 The use of g31d, g32d, and g42d compression values causes the backend
119 to generate optional frame formats which may not be supported by all SANE
120 frontends.
121 .RE
122
123 .TP
124 .B Geometry Options:
125 .TP
126 .B \-\-autoborder[=(yes|no)] [yes]
127 Enable/Disable automatic image border detection. When enabled, the RSC unit
128 automatically detects the image area and sets the window geometry to match.
129 .TP
130 .B \-\-paper\-size Custom|Letter|Legal|A3|A4|A5|A6|B4|B5 [Custom]
131 Specify the scan window geometry by specifying the paper size of the
132 documents to be scanned.
133 .TP
134 .B \-\-tl\-x 0..297.18mm [0]
135 Top-left x position of scan area.
136 .TP
137 .B \-\-tl\-y 0..431.8mm [0]
138 Top-left y position of scan area.
139 .TP
140 .B \-\-br\-x 0..297.18mm [297.18]
141 Bottom-right x position of scan area.
142 .TP
143 .B \-\-br\-y 0..431.8mm [431.8]
144 Bottom-right y position of scan area.
145 .TP
146 .B Feeder Options:
147 .TP
148 .B \-\-source Automatic Document Feeder|Manual Feed Tray [Automatic Document Feeder]
149 Selects the scan source (such as a document feeder). This option is provided
150 to allow multiple image scans with
151 .BR xsane (1);
152 it has no other purpose.
153 .TP
154 .B \-\-batch[=(yes|no)] [no]
155 Enable/disable batch mode scanning. Batch mode allows scanning at maximum throughput
156 by buffering within the RSC unit. This option is recommended when performing multiple
157 pages scans until the feeder is emptied.
158 .TP
159 .B \-\-duplex[=(yes|no)] [no]
160 Enable duplex (dual-sided) scanning. The scanner takes an image of each side
161 of the document during a single pass through the scanner. The front page is
162 delivered followed by the back page. Most options, such as compression,
163 affect both the front and back pages.
164 .TP
165 .B \-\-timeout\-adf 0..255 [0]
166 Sets the timeout in seconds for the automatic document feeder (ADF).
167 The value 0 specifies the hardware default value which varies based
168 on the scanner model.
169 .TP
170 .B \-\-timeout\-manual 0..255 [0]
171 Sets the timeout in seconds for semi-automatic feeder. The value 0 specifies
172 the hardware default value which varies based on the scanner model.
173 .TP
174 .B \-\-check\-adf[=(yes|no)] [no]
175 Check ADF status prior to starting scan using the OBJECT POSITION command.
176 Note that this feature requires RSC firmware level 1.5 or higher and dip
177 switch 4 must be in the on position. NOTE: This option has not been tested
178 extensively and may produce undesirable results.
179 .TP
180 .B Enhancement:
181 .TP
182 .B \-\-control\-panel[=(yes|no)] [yes]
183 Enables the scanner's control panel for selecting image enhancement
184 parameters. When the option is set to no the following options are
185 used to control image enhancement. See the Bell+Howell scanner users'
186 guide for complete information on ACE functionality.
187 .TP
188 .B \-\-ace\-function \-4..4 [3]
189 Specify the Automatic Contrast Enhancement (ACE) Function.
190 .TP
191 .B \-\-ace\-sensitivity 0..9 [5]
192 Specify the Automatic Contrast Enhancement (ACE) Sensitivity.
193 .TP
194 .B \-\-brightness 0..255 [0]
195 Controls the brightness of the acquired image. Ignored for ACE
196 capable scanners.
197 .TP
198 .B \-\-threshold 0..255 [0]
199 Select minimum-brightness to get a white point. Ignored for ACE
200 capable scanners.
201 .TP
202 .B \-\-contrast 0..255 [inactive]
203 Controls the contrast of the acquired image. This option is not
204 currently used by the scanner (and perhaps never will be).
205 .TP
206 .B \-\-negative[=(yes|no)] [no]
207 Swap black and white, yielding a reverse-video image.
208 .TP
209 .B Icon:
210 .TP
211 .B \-\-icon\-width 0..3600pel (in steps of 8) [0]
212 Width of icon (thumbnail) image in pixels.
213 .TP
214 .B \-\-icon\-length 0..3600pel (in steps of 8) [0]
215 Length of icon (thumbnail) image in pixels.
216 .TP
217 .B Barcode Options:
218 .TP
219 .B \-\-barcode\-search\-bar <see list> [none]
220 Specifies the barcode type to search for. If this option is
221 not specified, or specified with a value of none, then the barcode decoding
222 feature is completely disabled. The valid barcode type are:
223
224 .RS
225 .br
226 .B none
227 .br
228 .B ean\-8
229 .br
230 .B ean\-13
231 .br
232 .B reserved\-ean\-add
233 .br
234 .B code39
235 .br
236 .B code2\-5\-interleaved
237 .br
238 .B code2\-5\-3lines\-matrix
239 .br
240 .B code2\-5\-3lines\-datalogic
241 .br
242 .B code2\-5\-5lines\-industrial
243 .br
244 .B patchcode
245 .br
246 .B codabar
247 .br
248 .B codabar\-with\-start\-stop
249 .br
250 .B code39ascii
251 .br
252 .B code128
253 .br
254 .B code2\-5\-5lines\-iata
255 .br
256 .RE
257 .TP
258 .B \-\-barcode\-search\-count 1..7 [3]
259 Number of times that the RSC performs the decoding algorithm. Specify
260 the smallest number possible to increase performance. If you are having
261 trouble recognizing barcodes, it is suggested that you increase this option
262 to its maximum value (7).
263 .TP
264 .B \-\-barcode\-search\-mode <see list> [horiz\-vert]
265 Chooses the orientation of barcodes to be searched. The valid orientations
266 are:
267
268 .RS
269 .br
270 .B horiz\-vert
271 .br
272 .B horizontal
273 .br
274 .B vertical
275 .br
276 .B vert\-horiz
277 .RE
278 .TP
279 .B \-\-barcode\-hmin 0..1660mm [5]
280 Sets the barcode minimum height in millimeters (larger values increase
281 recognition speed). Of course the actual barcodes in the document must be
282 of sufficient size.
283 .TP
284 .B \-\-barcode\-search\-timeout 20..65535us [10000]
285 Sets the timeout for barcode searching in milliseconds. When the timeout
286 expires, the decoder will stop trying to decode barcodes.
287 .TP
288 .B \-\-section <string> []
289 Specifies a series of image sections. A section can be used to gather
290 a subset image or to provide a small area for barcode decoding.
291 Each section is specified in the following format (units are in millimeters):
292 .PP
293 .B <width>x<height>+<top-left-x>+<top-left-y>[:functioncode...]
294 .PP
295 Multiple sections can be specified by separating them with commas.
296 .PP
297 For example
298 .B 76.2x25.4+50.8+0:frontbar
299 identifies an area 3 inches wide and 1 inch high with a top left corner
300 at the top of the page two inches from the left hand edge of the page.
301 This section will be used for barcode decoding on the front page only.
302 .PP
303 For example
304 .B 50.8x25.4+25.4+0:frontbar:front:g42d
305 identifies an area 2 inches wide and 1 inch high with a top left corner
306 at the top of the page one inch from the left hand edge of the page.
307 This section will be used for barcode decoding on the front page as well
308 as generating an image compressed in g42d format.
309 .PP
310 Ordinarily barcodes are searched in the entire image. However, when you
311 specify sections all barcode searching is done within the specific sections
312 identified. This can significantly speed up the decoding process.
313
314 The following function codes are available:
315
316 .RS
317 .br
318 .B front
319 \- generate an image for the front page section
320 .br
321 .B back
322 \- generate an image for the back page section
323 .br
324 .B frontbar
325 \- perform barcode search in front page section
326 .br
327 .B backbar
328 \- perform barcode search in back page section
329 .br
330 .B frontpatch
331 \- perform patchcode search in front page section
332 .br
333 .B backpatch
334 \- perform patchcode search in back page section
335 .br
336 .B none
337 \- use no image compression
338 .br
339 .B g31d
340 \- use Group 3 1 dimension image compression
341 .br
342 .B g32d
343 \- use Group 3 2 dimensions image compression
344 .br
345 .B g42d
346 \- use Group 4 2 dimensions image compression
347 .br
348 .RE
349 .PP
350 If you omit a compression functioncode, the full page compression setting
351 is used. If you specify multiple compression functioncodes, only the
352 last one is used.
353
354 .TP
355 .B \-\-barcode\-relmax 0..255 [0]
356 Specifies the maximum relation from the widest to the smallest bar.
357 .TP
358 .B \-\-barcode\-barmin 0..255 [0]
359 Specifies the minimum number of bars in Bar/Patch code.
360 .TP
361 .B \-\-barcode\-barmax 0..255 [0]
362 Specifies the maximum number of bars in a Bar/Patch code.
363 .TP
364 .B \-\-barcode\-contrast 0..6 [3]
365 Specifies the image contrast used in decoding. Use higher values when
366 there are more white pixels in the code.
367 .TP
368 .B \-\-barcode\-patchmode 0..1 [0]
369 Controls Patch Code detection.
370
371 .SH CONFIGURATION
372 The contents of the
373 .I bh.conf
374 file is a list of device names that correspond to Bell+Howell
375 scanners. See
376 .BR sane\-scsi (5)
377 on details of what constitutes a valid device name.
378 Additionally, options can be specified; these lines begin with the word "option".
379 Each option is described in detail below. Empty lines and lines starting
380 with a hash mark (#) are ignored.
381
382 .SH OPTIONS
383 The following options can be specified in the
384 .I bh.conf
385 file:
386 .TP
387 .B disable\-optional\-frames
388 This option prevents the backend from sending any optional frames. This
389 option may be useful when dealing with frontends which do not support these
390 optional frames. When this option is in effect, the data is sent in a
391 .B SANE_FRAME_GRAY
392 frame. The optional frames sent by this backend are:
393 .BR SANE_FRAME_G31D ", " SANE_FRAME_G32D ", " SANE_FRAME_G42D " and " SANE_FRAME_TEXT .
394 These frames are generated based on the compression and barcode options.
395 These frames are never sent in preview mode.
396 .TP
397 .B fake\-inquiry
398 This option is used for debugging purposes and its use is not encouraged.
399 Essentially, it allows the backend to initialize in the absence of
400 a scanner. This is useful for development and not much else.
401 This option must be specified earlier in the configuration file than
402 the devices which are to be "faked".
403
404 .SH FILES
405 .TP
406 .I /etc/sane.d/bh.conf
407 The backend configuration file (see also description of
408 .B SANE_CONFIG_DIR
409 below).
410 .TP
411 .I /usr/lib/x86_64-linux-gnu/sane/libsane\-bh.a
412 The static library implementing this backend.
413 .TP
414 .I /usr/lib/x86_64-linux-gnu/sane/libsane\-bh.so
415 The shared library implementing this backend (present on systems that
416 support dynamic loading).
417
418 .SH ENVIRONMENT
419 .TP
420 .B SANE_CONFIG_DIR
421 This environment variable specifies the list of directories that may
422 contain the configuration file. On *NIX systems, the directories are
423 separated by a colon (`:'), under OS/2, they are separated by a
424 semi-colon (`;'). If this variable is not set, the configuration file
425 is searched in two default directories: first, the current working
426 directory (".") and then in
427 .IR /etc/sane.d .
428 If the value of the environment variable ends with the directory
429 separator character, then the default directories are searched after
430 the explicitly specified directories. For example, setting
431 .B SANE_CONFIG_DIR
432 to "/tmp/config:" would result in directories
433 .IR tmp/config ,
434 .IR . ,
435 and
436 .I /etc/sane.d
437 being searched (in this order).
438 .TP
439 .B SANE_DEBUG_BH
440 If the library was compiled with debug support enabled, this
441 environment variable controls the debug level for this backend. E.g.,
442 a value of 255 requests all debug output to be printed. Smaller
443 levels reduce verbosity.
444
445 .SH "SUPPORTED FEATURES"
446 .TP
447 .B ADF support
448 With document scanners, automatic document feeder (ADF) support is a key
449 feature. The backend supports the ADF by default and returns
450 .B SANE_STATUS_NO_DOCS
451 when the out-of-paper condition is detected. The SANE frontend
452 .BR scanadf (1)
453 is a command line frontend that supports multi-page scans. It has been
454 used successfully with this backend. The SANE frontend
455 .BR xsane (1)
456 is an improved GUI frontend by Oliver Rauch. Support for multi-page
457 scans is included in xsane version 0.35 and above.
458
459 .TP
460 .B Duplex scanning
461 Some models, such as the COPISCAN II 6338, support duplex scanning. That
462 is, they scan both sides of the document during a single pass through the
463 scanner (the scanner has two cameras). This backend supports duplex
464 scanning (with the
465 .B \-\-duplex
466 option). The front and back page images are delivered consecutively
467 as if they were separately scanned pages.
468
469 .TP
470 .B Hardware compression
471 The scanner is capable of compressing the data into several industry
472 standard formats (CCITT G3, CCITT G3-2D, CCITT G4). This results in
473 increased performance as less data is passed from the scanner to the
474 host over the SCSI bus. The backend supports these compression formats
475 via the
476 .B \-\-g31d, \-\-g32d, \-\-g42d
477 options, respectively. Many SANE frontends are not equipped to deal with
478 these formats, however. The SANE frontend
479 .BR scanadf (1)
480 supports these optional frame formats. The compressed image data
481 is written directly to a file and can then be processed by a scan-script
482 using the
483 .B \-\-scan\-script
484 option. Examples of this are given on the
485 .BR scanadf (1)
486 homepage.
487
488 .TP
489 .B Automatic Border Detection
490 The scanner can automatically detect the paper size and adjust the
491 scanning window geometry appropriately. The backend supports this
492 useful feature with the
493 .B \-\-autoborder
494 option. It is enabled by default.
495
496 .TP
497 .B Batch Mode Scanning
498 The batch scan mode allows for maximum throughput. The Set Window
499 parameters must remain constant during the entire batch.
500
501 .TP
502 .B Icon Generation
503 The Icon function generates a thumbnail of the full page image, that can be
504 transferred as if it were a separate page. This allows the host to
505 quickly display a thumbnail representation during the scanning operation.
506 Perhaps this would be a great way of implementing a preview scan, but
507 since a normal scan is so quick, it might not be worth the trouble.
508
509 .TP
510 .B Multiple Sections
511 Multiple sections (scanning sub-windows) can be defined for the front and
512 back pages. Each section can have different characteristics (e.g. geometry,
513 compression). The sections are returned as if they were separately
514 scanned images. Additionally sections can be used to greatly enhance the
515 accuracy and efficiency of the barcode/patchcode decoding process by
516 limiting the search area to a small subset of the page. Most Copiscan II
517 series scanners support up to 8 user-defined sections.
518
519 .TP
520 .B Support Barcode/Patchcode Decoding
521 The RSC unit can recognize Bar and Patch Codes of various types embedded
522 in the scanned image. The codes are decoded and the data is returned to
523 the frontend as a text frame. The text is encoded in xml and contains
524 a great deal of information about the decoded data such as the location
525 where it was found, its orientation, and the time it took to find.
526 Further information on the content of this text frame as well as some
527 barcode decoding examples can be found on the backend homepage.
528
529 .SH LIMITATIONS
530 .TP
531 .B Decoding a single barcode type per scan
532 The RSC unit can search for up to six different barcode types at a time.
533 While the code generally supports this as well, the
534 .B \-\-barcode\-search\-bar
535 option only allows the user to specify a single barcode type.
536 Perhaps another option which allows a comma separated list of barcode
537 type codes could be added to address this.
538 .TP
539 .B Scanning a fixed number of pages in batch mode
540 The separation of front and back end functionality in SANE presents a
541 problem in supporting the 'cancel batch' functionality in the scanner.
542 In batch mode, the scanner is always a page ahead of the host. The host,
543 knowing ahead of time which page will be the last, can cancel batch mode
544 prior to initiating the last scan command. Currently, there is no mechanism
545 available for the frontend to pass this knowledge to the backend.
546 If batch mode is enabled and the
547 .B \-\-end\-count
548 terminates a
549 .BR scanadf (1)
550 session,
551 an extra page will be pulled through the scanner, but is neither read
552 nor delivered to the frontend. The issue can be avoided by specifying
553 .B \-\-batch=no
554 when scanning a fixed number of pages.
555 .TP
556 .B Revision 1.2 Patch detector
557 There is an enhanced patchcode detection algorithm available in the RSC
558 with revision 1.2 or higher that is faster and more reliable than the
559 standard Bar/Patch code decoder. This is not currently supported.
560
561 .SH BUGS
562 Detailed bug reports are welcome -- and expected ;)
563 .PP
564 If you have found something that you think is a bug, please attempt to
565 recreate it with the
566 .B SANE_DEBUG_BH
567 environment variable set to 255, and send a report detailing the conditions
568 surrounding the bug to
569 .IR sane\[email protected] .
570
571 .SH "SEE ALSO"
572 .BR sane (7),
573 .BR sane\-scsi (5),
574 .BR scanimage (1),
575 .BR scanadf (1),
576 .BR xsane (1)
577
578 .SH AUTHOR
579 The
580 .B sane\-bh backend
581 was written by Tom Martone, based on the
582 .BR sane\-ricoh (5)
583 backend by Feico W. Dillema and the bnhscan program by Sean Reifschneider
584 of tummy.com ltd. Some 8000 enhancements added by Mark Temple.