Debian Codegraph @

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

raw
1 .TH sane\-sharp 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy"
2 .IX sane\-sharp
3 .SH NAME
4 sane\-sharp \- SANE backend for SHARP scanners
5 .SH DESCRIPTION
6 The
7 .B sane\-sharp
8 library implements a SANE (Scanner Access Now Easy) backend that
9 provides access to Sharp SCSI scanners. This backend should be
10 considered
11 .B beta-quality
12 software! In the current state it is known to work with JX-610 and JX-250
13 scanners. It is prepared for usage with the JX-330 series scanners,
14 but we are not able to test it with these devices.
15 .PP
16 For other Sharp scanners, it may or may not work.
17 .PP
18 At present,
19 the following scanners are known to work with this backend.
20 .RS
21 .PP
22 .ft CR
23 .nf
24 Vendor Product id:
25 ----- -----------
26 Sharp JX-610
27 Sharp JX-250
28 Sharp JX-320
29 Sharp JX-330
30 Sharp JX-350
31 .fi
32 .ft R
33 .RE
34 .PP
35 The following scanners are detected by the backend, but not tested:
36 .PP
37 .RS
38 .ft CR
39 .nf
40 Vendor Product id:
41 ----- -----------
42 Sharp JX-325
43 .fi
44 .ft R
45 .RE
46 .SH DEVICE NAMES
47 This backend expects device names of the form:
48 .PP
49 .RS
50 .I special
51 .RE
52 .PP
53 where
54 .I special
55 is the path-name for the special device that corresponds to a
56 SCSI scanner. The special device name must be a generic SCSI device or a
57 symlink to such a device. Under Linux, such a device name could be
58 .I /dev/sga
59 or
60 .IR /dev/sge ,
61 for example. See
62 .BR sane\-scsi (5)
63 for details.
64
65 .SH SCAN OPTIONS
66 .TP
67 .B \-\-mode
68 Scan Mode. Possible settings are:
69 .I Lineart
70 (1 bit black & white scans),
71 .I Gray
72 (8 bit gray scale scans),
73 .I Lineart Color
74 (bi-level color scans), and
75 .I Color
76 (8 bit RGB scans). The default value is
77 .I Color.
78
79 .TP
80 .B \-\-halftone\-pattern
81 Halftone Pattern. Available only for the JX-330 series scanners.
82 Possible settings:
83 .IR none ", " "Dither Bayer" ", " "Dither Spiral" ", " "Dither Dispersed"
84 and
85 .IR "Error Diffusion" .
86 The default value is
87 .IR none .
88
89 .TP
90 .B \-\-source
91 Paper Source. This option is only available if an automatic document
92 feeder or a transparency adapter is installed. Possible settings are:
93 .IR Flatbed ", " "Automatic Document Feeder" ,
94 and
95 .IR "Transparency Adapter" .
96 If an ADF or a transparency adapter is installed, using it is the
97 default selection.
98
99 .TP
100 .B \-\-custom\-gamma
101 Custom Gamma. This option determines whether a builtin or a custom
102 gamma table is used. Possible settings are:
103 .I yes
104 (enables custom gamma tables) or
105 .I no
106 (enables a built gamma table).
107
108 .TP
109 .B \-\-gamma
110 Gamma. This option is only available if
111 .B Custom Gamma
112 is set to
113 .IR no .
114 Possible values are:
115 .IR 1.0 " or " 2.2 "."
116 The default value is
117 .IR 2.2 .
118 (The JX-250 and JX-350 have no built in gamma
119 correction; for these scanners, a gamma table is downloaded to the scanner
120 by the backend.)
121
122 .TP
123 .B \-\-gamma\-table
124 Gamma Table. Allowed values: 0..255; 256 numbers must be defined.
125 The default values are 0, 1, 2, .. 255 (i.e., gamma == 1). This table
126 is only used for gray scale scans.
127
128 .TP
129 .B \-\-red\-gamma\-table
130 Red Gamma Table. Allowed values: 0..255; 256 numbers must be defined.
131 The default values are 0, 1, 2, .. 255 (i.e., gamma == 1).
132
133 .TP
134 .B \-\-green\-gamma\-table
135 Green Gamma Table. Allowed values: 0..255; 256 numbers must be defined.
136 The default values are 0, 1, 2, .. 255 (i.e., gamma == 1).
137
138 .TP
139 .B \-\-blue\-gamma\-table
140 Blue Gamma Table. Allowed values: 0..255; 256 numbers must be defined.
141 The default values are 0, 1, 2, .. 255 (i.e., gamma == 1).
142
143 .TP
144 .B \-\-resolution
145 Selects the resolution of the scanned image. Allowed values:
146 .I 30..600
147 (JX-330, JX-350 and JX-610) and
148 .I 30..400
149 (JX-250).
150 The default value is 150.
151
152 .TP
153 .BR \-l ", " \-t ", " \-x ", " \-y
154 Scan Window.
155 Top-left x position of scan area
156 .RB ( \-l ),
157 top-left y position of scan area
158 .RB ( \-t ),
159 bottom right x position of scan area
160 .RB ( \-x )
161 and bottom right y position of scan area
162 .RB ( \-y ).
163 The possible settings depend on the scanner model and, for the
164 JX-250 and the JX-350, also on the usage of the automatic document feeder resp. the
165 transparency adapter. Please refer to the values allowed by
166 .BR xscanimage (1),
167 or
168 .BR xsane (1).
169 With
170 .BR scanimage (1),
171 enter one of the following commands in order to see the allowed parameter values for
172 the scan window:
173
174 .RS
175 scanimage \-d sharp \-\-source "Automatic Document Feeder" \-\-help
176
177 scanimage \-d sharp \-\-source Flatbed \-\-help
178
179 scanimage \-d sharp \-\-source "Transparency Adapter" \-\-help
180 .RE
181
182 .TP
183 .B \-\-edge emphasis
184 Edge emphasis. This option is not available for the JX-250 and the JX-350.
185 Possible settings:
186 .IR None ", " Middle ", " Strong ", and " Blur .
187 The default value is
188 .IR None .
189
190 .TP
191 .B \-\-threshold
192 Sets the threshold for black and white pixels in lineart mode.
193 Possible values are 1..255.
194 The default value is 128.
195 This option is only available in scan mode
196 .IR lineart .
197
198 .TP
199 .B \-\-threshold-red
200 Sets the threshold for the red component of a pixel
201 in lineart color scan mode. Possible values are 1..255.
202 The default value is 128.
203 This option is only available in scan mode color
204 .IR lineart .
205
206 .TP
207 .B \-\-threshold-green
208 Sets the threshold for the green component of a pixel
209 in lineart color scan mode. Possible values are 1..255.
210 The default value is 128.
211 This option is only available in scan mode color
212 .I lineart .
213
214 .TP
215 .B \-\-threshold-blue
216 Sets the threshold for the blue component of a pixel
217 in lineart color scan mode. Possible values are 1..255.
218 The default value is 128.
219 This option is only available in scan mode color
220 .IR lineart .
221
222 .TP
223 .B \-\-lightcolor
224 Sets the color of the light source. Possible values are
225 .IR white ,
226 .IR red ,
227 .I green
228 and
229 .IR blue .
230 The default value is
231 .IR white .
232 This option is only available in scan modes
233 .I "lineart color"
234 and
235 .IR color .
236
237 .SH ADF USAGE
238 If a paper jam occurrs, the maintenance cover
239 .I
240 must
241 be opened and closed, even if the jammed paper can be removed without opening
242 the maintenance cover. Otherwise, the error condition will not be cleared.
243
244 .SH CONFIGURATION
245 The contents of the
246 .I sharp.conf
247 file is a list of options and device names that correspond to Sharp
248 scanners. Empty lines and lines beginning with a hash mark (#) are
249 ignored. See
250 .BR sane\-scsi (5)
251 for details about device names.
252 .PP
253 Lines setting an option start with the key word
254 .B option,
255 followed by the option's name and the option's value. At present, three
256 options are defined:
257 .B buffers, buffersize,
258 and
259 .B readqueue.
260 .PP
261 Options defined at the start of
262 .I sharp.conf
263 apply to all devices; options defined after a
264 device name apply to this device.
265 .PP
266 The options
267 .B buffers
268 and
269 .B
270 readqueue
271 are only significant if the backend has been compiled
272 so that for each scan a second process is forked (switch
273 .B USE_FORK
274 in
275 .I sharp.c
276 ). This process reads the
277 scan data from the scanner and writes this data into a block of shared memory.
278 The parent process reads the data from this memory block and delivers it
279 to the frontend. The options control the size and usage of this shared
280 memory block.
281 .PP
282 .B option buffers
283 defines the number of buffers used. The smallest number allowed is 2.
284 .PP
285 .B option buffersize
286 defines the size of one buffer. Since each buffer is filled with a
287 single read command sent to the scanner, its size is limited automatically
288 to the size allowed by the operating system or by the Sane SCSI library
289 for SCSI read commands. A buffer size of 128 kB or 256 kB is recommended
290 for scan resolutions of 300 dpi and above.
291 .PP
292 .B option readqueue
293 defines how many read commands to be sent to the scanner
294 are queued. At present, the Sane SCSI library supports queued read
295 commands only for for Linux. For other operating systems,
296 .B option readqueue
297 should be set to 0. For Linux,
298 .B option readqueue
299 should be set to 2. Larger values than 2 for
300 .B option readqueue
301 are not reasonable in most cases.
302 .B option buffers
303 should be greater than
304 .B option readqueue.
305
306 .SH Performance Considerations
307 This section focuses on the problem of stops of the scanner's carriage
308 during a scan. Carriage stops happen mainly with the JX-250. This scanner
309 has obviously only a small internal buffer compared to its speed. That
310 means that the backend must read the data as fast as possible from the
311 scanner in order to avoid carriage stops.
312 .PP
313 Even the JX-250 needs only less than 10 seconds for a 400 dpi A4 gray
314 scale scan, which results in a data transfer rate of more than 1.6 MB
315 per second. This means that the data produced by the scanner must be
316 processed fairly fast. Due to the small internal buffer of the JX-250,
317 the backend must issue a read request for the next data block as soon
318 as possible after reading a block of data in order to avoid carriage
319 stops.
320 .PP
321 Stops of the carriage can be caused by the following reasons:
322 .PP
323 .RS
324 \- too much "traffic" on the SCSI bus,
325 .br
326 \- slow responses by the backend to the scanner,
327 .br
328 \- a program which processes the data acquired by the backend is too slow.
329 .PP
330 .RE
331 Too much "traffic" on the SCSI bus: This happens for example, if hard disks
332 are connected to the same SCSI bus as the scanner, and when data transfer
333 from/to these hard disks requires a considerable part of the SCSI bandwidth
334 during a scan. If this is the case, you should consider to connect the
335 scanner to a separate SCSI adapter.
336 .PP
337 Slow responses by the backend to the scanner: Unfortunately,
338 UNIX-like operating systems generally have no real time capabilities.
339 Thus there is no guarantee that the backend is under any circumstances
340 able to communicate with the scanner as fast as required. To minimize this
341 problem, the backend should be compiled so that a separate reader process
342 is forked: Make sure that
343 .B USE_FORK
344 is defined when you compile
345 .I sharp.c.
346 If slow responses of the backend remain to be problem, you could try to
347 reduce the load of the system. Even while the backend and the reader
348 process need only a minor amount of processor time, other running
349 processes can cause an increase in the time delay between two time
350 slices given to the reader process. On slower systems, such an
351 increased delay can be enough to cause a carriage stop with the JX-250.
352 For Linux, the usage of the SG driver version 2.1.36 or above is
353 recommended, because it supports, in combination with
354 the SCSI library of Sane version 1.0.2, command queueing within the kernel.
355 This queueing implementation, combined with a buffer size of at least
356 128 kB, should avoid most carriage stops.
357 .PP
358 Slow processing of the scan data: An example for this situation is
359 the access to the scanner via a 10 MBit Ethernet, which is definitely
360 too slow to transfer the scan data as fast as they are produced by the
361 scanner. If you have enough memory available, you can increase
362 .B option buffers,
363 so that an entire image can be stored in these buffers.
364 .PP
365 In order to see, if the backend is too slow or if the further processing
366 of the data is too slow, set the environment variable
367 .B SANE_DEBUG_SHARP
368 to 1. When a scan is finished, the backend writes the line "buffer full
369 conditions:
370 .IR nn """
371 to stderr. If
372 .I nn
373 is zero, carriage stops are caused by too slow responses of the backend
374 or too much "traffic" on the SCSI bus. If
375 .I nn
376 is greater than zero, the backend had to wait
377 .I nn
378 times until a buffer has been processed by the frontend. (Please note that
379 .B option buffers
380 must be greater than
381 .B option readqueue
382 in order to get useful output for "buffer full conditions".)
383
384 .SH FILES
385 .TP
386 .I /etc/sane.d/sharp.conf
387 The backend configuration file.
388 .TP
389 .I /usr/lib/x86_64-linux-gnu/sane/libsane\-sharp.a
390 The static library implementing this backend.
391 .TP
392 .I /usr/lib/x86_64-linux-gnu/sane/libsane\-sharp.so
393 The shared library implementing this backend (present on systems that
394 support dynamic loading).
395 .SH ENVIRONMENT
396 .TP
397 .B SANE_DEBUG_SHARP
398 If the library was compiled with debug support enabled, this
399 environment variable controls the debug level for this backend. E.g.,
400 a value of 128 requests all debug output to be printed. Smaller
401 levels reduce verbosity.
402 .SH KNOWN PROBLEMS
403 1. ADF Mode
404 .RS
405 After several ADF scans, the scanner moves the carriage back to the idle
406 position and back to ADF scan position, before a scan starts. We do not
407 know, if this is a problem of the scanner, or if this is a bug of the
408 backend. At present, the scanner must power off and on to stop this
409 annoying behaviour.
410 .RE
411
412 2. Threshold level does not work (only JX\-610)
413 .PP
414 3. The maximum resolution is limited to 600 dpi (JX\-610 supported
415 to 1200 dpi) resp. 400 dpi (JX\-250)
416 .PP
417 4. If the JX\-250 is used with an ADF, the following situation can occur: After
418 several scans, the scanner moves, after loading a new sheet of paper, the
419 carriage to the idle position, and then back to the position used for ADF
420 scans. This happens for
421 .I
422 every
423 scan, in contrast to the calibration, which is done after 10 scans. (For the
424 calibration, the carriage is also moved to the idle position.) We do not
425 know if this behavior is caused by the backend, or if it is a bug in the
426 firmware of the scanner.
427 .PP
428 5. Usage of a transparency adapter (film scan unit) is supported, but not
429 tested.
430
431 .SH "SEE ALSO"
432 .BR sane (7),
433 .BR sane\-scsi (5)
434
435 .SH AUTHORS
436 Kazuya Fukuda, Abel Deuring
437
438 .SH CREDITS
439 The Sharp backend is based on the Canon backend written by Helmut Koeberle.
440 .PP
441 Parts of this man page are a plain copy of
442 .BR sane\-mustek (5)
443 by David Mosberger-Tang, Andreas Czechanowski and Andreas Bolsch.