| 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. |