Debian Codegraph @

upstream/debian-unstable/man1/scanimage.1

raw
1 .TH scanimage 1 "10 Jul 2008" "" "SANE Scanner Access Now Easy"
2 .IX scanimage
3 .SH NAME
4 scanimage \- scan an image
5 .SH SYNOPSIS
6 .B scanimage
7 .RB [ \-d
8 .IR dev ]
9 .RB [ \-\-format\fI=output-format ]
10 .RB [ \-i
11 .IR profile ]
12 .RB [ \-L ]
13 .RB [ \-f
14 .IR device-format ]
15 .RB [ \-b
16 .RI [ format ]]
17 .RB [ \-\-batch\-start\fI=start ]
18 .RB [ \-\-batch\-count\fI=count ]
19 .RB [ \-\-batch\-increment\fI=increment ]
20 .RB [ \-\-batch\-double ]
21 .RB [ \-\-accept\-md5\-only ]
22 .RB [ \-p]
23 .RB [ \-o
24 .IR path ]
25 .RB [ \-n ]
26 .RB [ \-T ]
27 .RB [ \-A ]
28 .RB [ \-h ]
29 .RB [ \-v ]
30 .RB [ \-B
31 .RI size ]
32 .RB [ \-V ]
33 .RI [ device\-specific\-options ]
34 .SH DESCRIPTION
35 .B scanimage
36 is a command-line interface to control image acquisition devices such
37 as flatbed scanners or cameras. The device is controlled via
38 command-line options. After command-line processing,
39 .B scanimage
40 normally proceeds to acquire an image. The image data is written to
41 standard output in one of the PNM (portable aNyMaP) formats (PBM for
42 black-and-white images, PGM for grayscale images, and PPM for color
43 images), TIFF format (black-and-white, grayscale or color), PNG format,
44 or JPEG format (compression level 75).
45 .B scanimage
46 accesses image acquisition devices through the
47 .B SANE
48 (Scanner Access Now Easy) interface and can thus support any device for which
49 there exists a
50 .B SANE
51 backend (try
52 .B apropos
53 .I sane\-
54 to get a list of available backends).
55
56 .SH EXAMPLES
57 To get a list of devices:
58
59 scanimage \-L
60
61 To scan with default settings to the file image.pnm:
62
63 scanimage >image.pnm
64
65 To scan 100x100 mm to the file image.tiff (\-x and \-y may not be available with
66 all devices):
67
68 scanimage \-x 100 \-y 100 \-\-format=tiff >image.tiff
69
70 To print all available options:
71
72 scanimage \-h
73
74 .SH OPTIONS
75 There are two sets of options available when running
76 .BR scanimage .
77 .PP
78 The options that are provided by
79 .B scanimage
80 itself are listed below. In addition, each backend offers its own set of options and these
81 can also be specified. Note that the options available from the backend may vary depending on the
82 scanning device that is selected.
83 .PP
84 Often options that are similar in function may be implemented
85 differently across backends. An example of this difference is
86 .I \-\-mode Gray
87 and
88 .IR "\-\-mode Grayscale" .
89 This may be due to differing backend author preferences.
90 At other times, options are defined by the scanning device itself and therefore out of the
91 control of the backend code.
92
93 .PP
94 Parameters are separated by a blank from single-character options (e.g.
95 .BI "\-d " epson \fR)
96 and by a "=" from multi-character options (e.g.
97 .BR \-\-device\-name =\fIepson \fR).
98
99 .TP
100 .BR \-d "\fI dev\fR, " \-\-device\-name =\fIdev\fR
101 specifies the device to access and must be followed by a SANE device-name like
102 .RI ` epson:/dev/sg0 '
103 or
104 .RI ` hp:/dev/usbscanner0 '.
105 A (partial) list of available devices can be obtained with the
106 .B \-\-list\-devices
107 option (see below). If no device-name is specified explicitly,
108 .B scanimage
109 reads a device-name from the environment variable
110 .BR SANE_DEFAULT_DEVICE .
111 If this variable is not set,
112 .B scanimage
113 will attempt to open the first available device.
114
115 .TP
116 .BR \-\-format =\fIoutput-format\fR
117 selects how image data is written to standard output or the file specified by
118 the
119 .B \-\-output\-file
120 option.
121 .I output-format
122 can be
123 .BR pnm ,
124 .BR tiff ,
125 .BR png ,
126 or
127 .BR jpeg .
128 If
129 .B \-\-format
130 is not specified, PNM is written by default.
131
132 .TP
133 .BR \-i "\fI profile\fR, " \-\-icc\-profile =\fIprofile\fR
134 is used to include an ICC profile into a TIFF file.
135
136 .TP
137 .BR \-L ", " \-\-list\-devices
138 requests a (partial) list of devices that are available. The
139 list may not be complete since some devices may be available, but are not
140 listed in any of the configuration files (which are typically stored
141 in directory
142 .IR /etc/sane.d ).
143 This is particularly the case when accessing scanners through the network. If
144 a device is not listed in a configuration file, the only way to access it is
145 by its full device name. You may need to consult your system administrator to
146 find out the names of such devices.
147
148 .TP
149 .BR \-f "\fI format\fR, " \-\-formatted\-device\-list =\fIdevice-format\fR
150 works similarly to
151 .BR \-\-list\-devices ,
152 but requires a format string.
153 .B scanimage
154 replaces the placeholders
155 .B %d %v %m %t %i %n
156 with the device name, vendor name, model name, scanner type, an index
157 number and newline respectively. The command
158 .LP
159 .RS
160 .B scanimage \-f
161 .I \*(lq scanner number %i device %d is a %t, model %m, produced by %v \*(rq
162 .LP
163
164 will produce something like:
165 .PP
166 .RS
167 scanner number 0 device sharp:/dev/sg1 is a flatbed scanner, model JX250
168 SCSI, produced by SHARP
169 .RE
170 .RE
171
172 .PP
173 The
174 .B \-\-batch*
175 options provide features for scanning documents using document
176 feeders.
177
178 .RS
179
180 .TP
181 .BR \-b " [\fIformat\fR], " \-\-batch =[\fIformat\fR]
182 is used to specify the format of the filename that each page will be written
183 to. Each page is written out to a single file. If
184 .I format
185 is not specified, the default of
186 .I out%d.pnm
187 (or
188 .I out%d.tif
189 for
190 .BR "\-\-format tiff" ,
191 .I out%d.png
192 for
193 .B "\-\-format png"
194 or
195 .I out%d.jpg
196 for
197 .BR "\-\-format jpeg" )
198 will be used.
199 This option is incompatible with the
200 .B \-\-output\-path
201 option.
202 .I format
203 is given as a printf style string with one integer parameter.
204
205
206 .TP
207 .BR \-\-batch\-start =\fIstart\fR
208 selects the page number to start naming files with. If this option is not
209 given, the counter will start at 1.
210
211 .TP
212 .BR \-\-batch\-count =\fIcount\fR
213 specifies the number of pages to attempt to scan. If not given,
214 .B scanimage
215 will continue scanning until the scanner returns a state
216 other than OK. Not all scanners with document feeders signal when the
217 ADF is empty. Use this option to work around them.
218
219 .TP
220 .BR \-\-batch\-increment =\fIincrement\fR
221 sets the amount that the number in the filename is incremented
222 by. Generally this is used when you are scanning double-sided documents
223 on a single-sided document feeder.
224 .B \-\-batch\-double
225 is a specific command provided to aid this.
226
227 .TP
228 .B \-\-batch\-double
229 will automatically set the increment to 2.
230 Equivalent to
231 .BR \-\-batch\-increment =2.
232
233 .TP
234 .B \-\-batch\-prompt
235 will ask for pressing RETURN before scanning a page. This can be used for
236 scanning multiple pages without an automatic document feeder.
237 .RE
238
239 .TP
240 .B \-\-accept\-md5\-only
241 only accepts user authorization requests that support MD5 security. The
242 .B SANE
243 network daemon
244 .BR saned (8)
245 is capable of doing such requests.
246
247 .TP
248 .BR \-p ", " \-\-progress
249 requests that
250 .B scanimage
251 prints a progress counter. It shows how much image data of the current image has
252 already been received (in percent).
253
254 .TP
255 .BR \-o "\fI path\fR, " \-\-output\-file =\fIpath\fR
256 requests that
257 .B scanimage
258 saves the scanning output to the given
259 .IR path .
260 This option is incompatible with the
261 .B \-\-batch
262 option. The program will try to guess
263 .B \-\-format
264 from the file name. If that is not possible, it will print an error message and exit.
265
266 .TP
267 .BR \-n ", " \-\-dont\-scan
268 requests that
269 .B scanimage
270 only sets the options provided by the user but doesn't actually perform a
271 scan. This option can be used to e.g. turn off the scanner's lamp (if
272 supported by the backend).
273
274 .TP
275 .BR \-T ", " \-\-test
276 requests that
277 .B scanimage
278 performs a few simple sanity tests to make sure the backend works as
279 defined by the
280 .B SANE
281 API. In particular the
282 .BR sane_read ()
283 function is exercised by this test.
284
285 .TP
286 .BR \-A ", " \-\-all\-options
287 requests that
288 .B scanimage
289 lists all available options exposed by the backend, including button options.
290 The information is printed on standard output and no scan will be performed.
291
292 .TP
293 .BR \-h ", " \-\-help
294 requests help information. The information is printed on
295 standard output and no scan will be performed.
296
297 .TP
298 .BR \-v ", " \-\-verbose
299 increases the verbosity of the output of
300 .BR scanimage .
301 The option may be specified repeatedly, each time increasing the verbosity
302 level.
303
304 .TP
305 .BR \-B " [\fIsize\fR], " \-\-buffer\-size =\fIsize
306 changes input buffer size from the default of 1MB to
307 .I size
308 KB.
309
310 .TP
311 .BR \-V ", " \-\-version
312 requests that
313 .B scanimage
314 prints the program and package name, the version number of
315 the
316 .B SANE
317 distribution that it came with and the version of the backend that it
318 loads. If more information about the version
319 numbers of the backends are necessary, the
320 .B DEBUG
321 variable for the dll layer can be used. Example:
322 .IR "SANE_DEBUG_DLL=3 scanimage \-L" .
323 .PP
324 As you might imagine, much of the power of
325 .B scanimage
326 comes from the fact that it can control any
327 .B SANE
328 backend. Thus, the exact set of command-line options depends on the
329 capabilities of the selected device. To see the options for a device named
330 .IR dev ,
331 invoke
332 .B scanimage
333 via a command-line of the form:
334 .PP
335 .RS
336 scanimage \-\-help \-\-device\-name
337 .I dev
338 .RE
339 .PP
340 The documentation for the device-specific options printed by
341 .B \-\-help
342 is best explained with a few examples:
343
344 .B \-l 0..218mm [0]
345 .RS
346 Top-left x position of scan area.
347 .PP
348 The description above shows that option
349 .B \-l
350 expects an option value in the range from 0 to 218 mm. The
351 value in square brackets indicates that the current option value is 0
352 mm. Most backends provide similar geometry options for top-left y position
353 .RB ( \-t ),
354 width
355 .RB ( \-x )
356 and height of scan-area
357 .RB (\-y ).
358 .RE
359
360
361 .B \-\-brightness \-100..100% [0]
362 .RS
363 Controls the brightness of the acquired image.
364 .PP
365 The description above shows that option
366 .B \-\-brightness
367 expects an option value in the range from \-100 to 100 percent. The
368 value in square brackets indicates that the current option value is 0
369 percent.
370 .RE
371
372 .B \-\-default\-enhancements
373 .RS
374 Set default values for enhancement controls.
375 .PP
376 The description above shows that option
377 .B \-\-default\-enhancements
378 has no option value. It should be thought of as having an immediate
379 effect at the point of the command-line at which it appears. For
380 example, since this option resets the
381 .B \-\-brightness
382 option, the option-pair
383 .B \-\-brightness 50 \-\-default\-enhancements
384 would effectively be a no-op.
385 .RE
386
387 .B \-\-mode Lineart|Gray|Color [Gray]
388 .RS
389 Selects the scan mode (e.g., lineart or color).
390 .PP
391 The description above shows that option
392 .B \-\-mode
393 accepts an argument that must be one of the strings
394 .BR Lineart ,
395 .BR Gray ,
396 or
397 .BR Color .
398 The value in the square bracket indicates that the option is currently
399 set to
400 .BR Gray .
401 For convenience, it is legal to abbreviate the string values as long as
402 they remain unique. Also, the case of the spelling doesn't matter. For
403 example, option setting
404 .B \-\-mode col
405 is identical to
406 .BR "\-\-mode Color" .
407 .RE
408
409 .B \-\-custom\-gamma[=(yes|no)] [inactive]
410 .RS
411 Determines whether a builtin or a custom gamma-table should be used.
412 .PP
413 The description above shows that option
414 .B \-\-custom\-gamma
415 expects either no option value, a "yes" string, or a "no" string.
416 Specifying the option with no value is equivalent to specifying "yes".
417 The value in square-brackets indicates that the option is not
418 currently active. That is, attempting to set the option would result
419 in an error message. The set of available options typically depends
420 on the settings of other options. For example, the
421 .B \-\-custom\-gamma
422 table might be active only when a grayscale or color scan-mode has
423 been requested.
424
425 Note that the
426 .B \-\-help
427 option is processed only after all other options have been processed.
428 This makes it possible to see the option settings for a particular
429 mode by specifying the appropriate mode-options along
430 with the
431 .B \-\-help
432 option. For example, the command-line:
433 .PP
434 .B scanimage \-\-help \-\-mode
435 .I color
436 .PP
437 would print the option settings that are in effect when the color-mode
438 is selected.
439 .RE
440
441 .B \-\-gamma\-table 0..255,...
442 .RS
443 Gamma-correction table. In color mode this option
444 equally affects the red, green, and blue channels
445 simultaneously (i.e., it is an intensity gamma table).
446 .PP
447 The description above shows that option
448 .B \-\-gamma\-table
449 expects zero or more values in the range 0 to 255. For example, a
450 legal value for this option would be "3,4,5,6,7,8,9,10,11,12". Since
451 it's cumbersome to specify long vectors in this form, the same can be
452 expressed by the abbreviated form "[0]3-[9]12". What this means is
453 that the first vector element is set to 3, the 9-th element is set to
454 12 and the values in between are interpolated linearly. Of course, it
455 is possible to specify multiple such linear segments. For example,
456 "[0]3-[2]3-[6]7,[7]10-[9]6" is equivalent to "3,3,3,4,5,6,7,10,8,6".
457 The program
458 .B gamma4scanimage
459 can be used to generate such gamma tables (see
460 .BR gamma4scanimage (1)
461 for details).
462 .RE
463
464 .B \-\-filename <string> [/tmp/input.ppm]
465 .RS
466 The filename of the image to be loaded.
467 .PP
468 The description above is an example of an option that takes an
469 arbitrary string value (which happens to be a filename). Again,
470 the value in brackets show that the option is current set to the
471 filename
472 .IR /tmp/input.ppm .
473 .RE
474
475 .SH ENVIRONMENT
476 .TP
477 .B SANE_DEFAULT_DEVICE
478 The default device-name.
479 .SH FILES
480 .TP
481 .I /etc/sane.d
482 This directory holds various configuration files. For details, please
483 refer to the manual pages listed below.
484 .TP
485 .I ~/.sane/pass
486 This file contains lines of the form
487 .PP
488 .RS
489 user:password:resource
490 .PP
491 .B scanimage
492 uses this information to answer user authorization requests
493 automatically. The file must have 0600 permissions or stricter. You should
494 use this file in conjunction with the
495 .B \-\-accept\-md5\-only
496 option to avoid
497 server-side attacks. The resource may contain any character but is limited
498 to 127 characters.
499
500 .SH "SEE ALSO"
501 .BR sane (7),
502 .BR gamma4scanimage (1),
503 .BR xscanimage (1),
504 .BR xcam (1),
505 .BR xsane (1),
506 .BR scanadf (1),
507 .BR sane\-dll (5),
508 .BR sane\-net (5),
509 .BR sane\-"backendname" (5)
510
511 .SH AUTHOR
512 David Mosberger, Andreas Beck, Gordon Matzigkeit, Caskey Dickson, and many
513 others. For questions and comments contact the sane\-devel mailinglist (see
514 .IR http://www.sane\-project.org/mailing\-lists.html ).
515
516 .SH BUGS
517 For vector options, the help output currently has no indication as to
518 how many elements a vector-value should have.