1sane-bh(5)               SANE Scanner Access Now Easy               sane-bh(5)
2
3
4

NAME

6       sane-bh  -  SANE  backend  for  Bell+Howell Copiscan II series document
7       scanners
8

DESCRIPTION

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
17              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
24       If  you  have  a  Bell+Howell scanner and are able to test it with this
25       backend, please  contact  sane-devel@lists.alioth.debian.org  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
32       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
40       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
45
46       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

DEVICE NAMES

51       This backend expects device names of the form:
52
53              special
54
55       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

CONFIGURATION

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
69

OPTIONS

71       The following options can be specified in the bh.conf file.
72
73       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
83       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
90

FILES

92       /etc/sane.d/bh.conf
93              The   backend   configuration  file  (see  also  description  of
94              SANE_CONFIG_DIR below).
95
96       /usr/lib64/sane/libsane-bh.a
97              The static library implementing this backend.
98
99       /usr/lib64/sane/libsane-bh.so
100              The shared library implementing this backend (present on systems
101              that support dynamic loading).
102

ENVIRONMENT

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
118       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
124

SUPPORTED FEATURES

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
136
137       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
145
146       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
159
160       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
166
167       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
171
172       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
180
181       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
191
192       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
202

LIMITATIONS

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
212       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
226       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
232

OPTIONS

234       Scan Mode Options:
235
236       --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
241       --mode lineart|halftone [lineart]
242              Selects the scan mode (e.g., lineart,monochrome, or color).
243
244       --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
249       --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
262
263       Geometry Options:
264
265       --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
270       --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
274       --tl-x 0..297.18mm [0]
275              Top-left x position of scan area.
276
277       --tl-y 0..431.8mm [0]
278              Top-left y position of scan area.
279
280       --br-x 0..297.18mm [297.18]
281              Bottom-right x position of scan area.
282
283       --br-y 0..431.8mm [431.8]
284              Bottom-right y position of scan area.
285
286       Feeder Options:
287
288       --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
294       --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
300       --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
307       --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
312       --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
317       --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
324       Enhancement:
325
326       --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
333       --ace-function -4..4 [3]
334              Specify the Automatic Contrast Enhancement (ACE) Function.
335
336       --ace-sensitivity 0..9 [5]
337              Specify the Automatic Contrast Enhancement (ACE) Sensitivity.
338
339       --brightness 0..255 [0]
340              Controls  the brightness of the acquired image.  Ignored for ACE
341              capable scanners.
342
343       --threshold 0..255 [0]
344              Select minimum-brightness to get a white point.  Ignored for ACE
345              capable scanners.
346
347       --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
351       --negative[=(yes|no)] [no]
352              Swap black and white, yielding a reverse-video image.
353
354       Icon:
355
356       --icon-width 0..3600pel (in steps of 8) [0]
357              Width of icon (thumbnail) image in pixels.
358
359       --icon-length 0..3600pel (in steps of 8) [0]
360              Length of icon (thumbnail) image in pixels.
361
362       Barcode Options:
363
364       --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
385       --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
391       --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
399       --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
404       --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
409       --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
415       <width>x<height>+<top-left-x>+<top-left-y>[:functioncode...]
416
417       Multiple sections can be specified by separating them with commas.
418
419       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
424       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
430       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
435       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
447       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
451
452       --barcode-relmax 0..255 [0]
453              Specifies the maximum relation from the widest to  the  smallest
454              bar.
455
456       --barcode-barmin 0..255 [0]
457              Specifies the minimum number of bars in Bar/Patch code.
458
459       --barcode-barmax 0..255 [0]
460              Specifies the maximum number of bars in a Bar/Patch code.
461
462       --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
466       --barcode-patchmode 0..1 [0]
467              Controls Patch Code detection.
468
469

BUGS

471       This is a new backend; detailed bug reports are welcome -- and expected
472       ;)
473
474       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@lists.alioth.debian.org.
478
479

SEE ALSO

481       sane(7), sane-scsi(5), scanimage(1), scanadf(1)
482
483

AUTHOR

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
489
490
491                                  10 Jul 2008                       sane-bh(5)
Impressum