1scanimage(1)             SANE Scanner Access Now Easy             scanimage(1)
2
3
4

NAME

6       scanimage - scan an image
7

SYNOPSIS

9       scanimage  [-d|--device-name  dev]  [--format format] [-i|--icc-profile
10       profile]   [-L|--list-devices]   [-f|--formatted-device-list    format]
11       [-b|--batch  [=format]]  [--batch-start  start]  [--batch-count  count]
12       [--batch-increment  increment]   [--batch-double]   [--accept-md5-only]
13       [-p|--progress]    [-n|--dont-scan]    [-T|--test]   [-A|--all-options]
14       [-h|--help] [-v|--verbose]  [-B|--buffer-size  [=size]]  [-V|--version]
15       [device-specific-options]
16

DESCRIPTION

18       scanimage  is  a  command-line  interface  to control image acquisition
19       devices such as flatbed scanners or cameras.  The device is  controlled
20       via  command-line  options.   After  command-line processing, scanimage
21       normally proceeds to acquire an image.  The image data  is  written  to
22       standard  output  in  one of the PNM (portable aNyMaP) formats (PBM for
23       black-and-white images, PGM for grayscale images,  and  PPM  for  color
24       images)  or  in  TIFF (black-and-white, grayscale or color).  scanimage
25       accesses image acquisition devices through the SANE (Scanner Access Now
26       Easy)  interface and can thus support any device for which there exists
27       a SANE backend (try apropos sane- to get a list of available backends).
28
29

EXAMPLES

31       To get a list of devices:
32
33         scanimage -L
34
35       To scan with default settings to the file image.pnm:
36
37         scanimage >image.pnm
38
39       To scan 100x100 mm to the file image.tiff (-x and -y may not be  avail‐
40       able with all devices):
41
42         scanimage -x 100 -y 100 --format=tiff >image.tiff
43
44       To print all available options:
45
46         scanimage -h
47
48

OPTIONS

50       Parameters are separated by a blank from single-character options (e.g.
51       -d  epson)  and  by  a   "="   from   multi-character   options   (e.g.
52       --device-name=epson).
53
54
55       The  -d or --device-name options must be followed by a SANE device-name
56       like `epson:/dev/sg0' or `hp:/dev/usbscanner0'.  A  (partial)  list  of
57       available  devices  can be obtained with the --list-devices option (see
58       below).  If no device-name is specified explicitly, scanimage  reads  a
59       device-name from the environment variable SANE_DEFAULT_DEVICE.  If this
60       variable is not set, scanimage will attempt to open the first available
61       device.
62
63       The  --format  format option selects how image data is written to stan‐
64       dard output.  format can be pnm or tiff.  If --format is not used,  PNM
65       is written.
66
67       The -i or --icc-profile option is used to include an ICC profile into a
68       TIFF file.
69
70       The -L or --list-devices option requests a (partial)  list  of  devices
71       that are available.  The list is not complete since some devices may be
72       available, but are not listed in any of the configuration files  (which
73       are  typically  stored in directory /etc/sane.d).  This is particularly
74       the case when accessing scanners through the network.  If a  device  is
75       not listed in a configuration file, the only way to access it is by its
76       full device name.  You may need to consult your system administrator to
77       find out the names of such devices.
78
79       The   -f   or   --formatted-device-list   option   works   similar   to
80       --list-devices, but requires a format string.  scanimage  replaces  the
81       placeholders %d %v %m %t %i %n with the device name, vendor name, model
82       name, scanner type, an index number and newline respectively. The  com‐
83       mand
84
85              scanimage  -f  scanner number %i device %d is a %t, model %m,
86              produced by %v 
87
88       will produce something like:
89
90              scanner number 0  device sharp:/dev/sg1 is  a  flatbed  scanner,
91              model JX250 SCSI, produced by SHARP
92
93       The  --batch* options provide the features for scanning documents using
94       document feeders.  --batch [format] is used to specify  the  format  of
95       the  filename  that each page will be written to.  Each page is written
96       out to a single file.  If format  is  not  specified,  the  default  of
97       out%d.pnm  (or  out%d.tif  for  --format tiff) will be used.  format is
98       given  as  a  printf  style  string   with   one   integer   parameter.
99       --batch-start start selects the page number to start naming files with.
100       If  this  option  is  not  given,  the  counter  will   start   at   1.
101       --batch-count  count  specifies the number of pages to attempt to scan.
102       If not given,  scanimage  will  continue  scanning  until  the  scanner
103       returns  a state other than OK.  Not all scanners with document feeders
104       signal when the ADF is empty, use this command  to  work  around  them.
105       With  --batch-increment  increment  you  can change the amount that the
106       number in the filename is incremented by.  Generally this is used  when
107       you  are  scanning  double-sided  documents  on a single-sided document
108       feeder.  A specific command is provided  to  aid  this:  --batch-double
109       will automatically set the increment to 2.  --batch-prompt will ask for
110       pressing RETURN before scanning a page. This can be used  for  scanning
111       multiple pages without an automatic document feeder.
112
113       The  --accept-md5-only  option only accepts user authorization requests
114       that support MD5 security. The SANE network daemon (saned)  is  capable
115       of doing such requests. See saned(8).
116
117       The  -p  or --progress option requests that scanimage prints a progress
118       counter. It shows how much image data of the current image has  already
119       been received by scanimage (in percent).
120
121       The  -n  or  --dont-scan  option  requests that scanimage only sets the
122       options provided by the user but doesn't actually perform a scan.  This
123       option can be used to e.g. turn off the scanner's lamp (if supported by
124       the backend).
125
126       The -T or --test option requests that scanimage performs a  few  simple
127       sanity  tests to make sure the backend works as defined by the SANE API
128       (in particular the sane_read function is exercised by this test).
129
130       The -A or --all-options option requests that scanimage lists all avail‐
131       able options exposed the backend, including button options.  The infor‐
132       mation is printed on standard output and no scan will be done.
133
134       The -h or --help options request help information.  The information  is
135       printed on standard output and in this case, no attempt will be made to
136       acquire an image.
137
138       The -v or --verbose options increase the verbosity of the operation  of
139       scanimage.   The option may be specified repeatedly, each time increas‐
140       ing the verbosity level.
141
142       The -B or --buffer-size changes the input buffer size from 32KB to  the
143       number kB specified or 1M.
144
145       The  -V  or --version option requests that scanimage prints the program
146       and package name, the version number of the SANE distribution  that  it
147       came  with and the version of the backend that it loads. Usually that's
148       the dll backend. If more information about the version numbers  of  the
149       backends  are  necessary, the DEBUG variable for the dll backend can be
150       used. Example: SANE_DEBUG_DLL=3 scanimage -L.
151
152       As you might imagine, much of the power of  scanimage  comes  from  the
153       fact that it can control any SANE backend.  Thus, the exact set of com‐
154       mand-line options depends on the capabilities of the  selected  device.
155       To  see the options for a device named dev, invoke scanimage via a com‐
156       mand-line of the form:
157
158              scanimage --help --device-name dev
159
160       The documentation for the device-specific options printed by --help  is
161       best explained with a few examples:
162
163        -l 0..218mm [0]
164           Top-left x position of scan area.
165
166              The  description  above  shows  that option -l expects an option
167              value in the range from 0 to 218 mm.  The value in square brack‐
168              ets  indicates that the current option value is 0 mm. Most back‐
169              ends provide similar geometry options for  top-left  y  position
170              (-t), width (-x) and height of scan-area (-y).
171
172
173        --brightness -100..100% [0]
174           Controls the brightness of the acquired image.
175
176              The  description above shows that option --brightness expects an
177              option value in the range from -100 to 100 percent.   The  value
178              in  square brackets indicates that the current option value is 0
179              percent.
180
181        --default-enhancements
182           Set default values for enhancement controls.
183
184              The description above shows that  option  --default-enhancements
185              has no option value.  It should be thought of as having an imme‐
186              diate effect at the  point  of  the  command-line  at  which  it
187              appears.  For example, since this option resets the --brightness
188              option, the option-pair --brightness  50  --default-enhancements
189              would effectively be a no-op.
190
191        --mode Lineart|Gray|Color [Gray]
192           Selects the scan mode (e.g., lineart or color).
193
194              The  description above shows that option --mode accepts an argu‐
195              ment that must be one of the strings Lineart,  Gray,  or  Color.
196              The  value  in  the  square bracket indicates that the option is
197              currently set to Gray.  For convenience, it is legal to abbrevi‐
198              ate  the string values as long as they remain unique.  Also, the
199              case of the spelling doesn't matter.  For example,  option  set‐
200              ting --mode col is identical to --mode Color.
201
202        --custom-gamma[=(yes|no)] [inactive]
203           Determines whether a builtin or a custom gamma-table
204           should be used.
205
206              The  description  above shows that option --custom-gamma expects
207              either no option value, a "yes" string, or a "no" string.  Spec‐
208              ifying  the  option  with  no  value is equivalent to specifying
209              "yes".  The value in square-brackets indicates that  the  option
210              is  not currently active.  That is, attempting to set the option
211              would result in an error message.  The set of available  options
212              typically  depends  on the settings of other options.  For exam‐
213              ple, the --custom-gamma  table  might  be  active  only  when  a
214              grayscale or color scan-mode has been requested.
215
216              Note  that  the  --help option is processed only after all other
217              options have been processed.  This makes it possible to see  the
218              option  settings  for a particular mode by specifying the appro‐
219              priate mode-options along with the --help option.  For  example,
220              the command-line:
221
222              scanimage --help --mode color
223
224              would  print  the  option  settings  that are in effect when the
225              color-mode is selected.
226
227        --gamma-table 0..255,...
228           Gamma-correction table.  In color mode this option
229           equally affects the red, green, and blue channels
230           simultaneously (i.e., it is an intensity gamma table).
231
232              The description above shows that  option  --gamma-table  expects
233              zero or more values in the range 0 to 255.  For example, a legal
234              value for this option would be "3,4,5,6,7,8,9,10,11,12".   Since
235              it's  cumbersome  to specify long vectors in this form, the same
236              can be expressed by the  abbreviated  form  "[0]3-[9]12".   What
237              this  means  is  that  the first vector element is set to 3, the
238              9-th element is set to 12 and the values in between are interpo‐
239              lated  linearly.   Of course, it is possible to specify multiple
240              such linear segments.  For example,  "[0]3-[2]3-[6]7,[7]10-[9]6"
241              is    equivalent   to   "3,3,3,4,5,6,7,10,8,6".    The   program
242              gamma4scanimage can be used to generate such gamma  tables  (see
243              gamma4scanimage(1) for details).
244
245        --filename <string> [/tmp/input.ppm]
246           The filename of the image to be loaded.
247
248              The  description  above is an example of an option that takes an
249              arbitrary string value (which happens to be a filename).  Again,
250              the value in brackets show that the option is current set to the
251              filename /tmp/input.ppm.
252
253

ENVIRONMENT

255       SANE_DEFAULT_DEVICE
256              The default device-name.
257

FILES

259       /etc/sane.d
260              This directory holds various configuration files.  For  details,
261              please refer to the manual pages listed below.
262
263       ~/.sane/pass
264              This file contains lines of the form
265
266              user:password:resource
267
268              scanimage  uses  this  information  to answer user authorization
269              requests automatically. The file must have 0600  permissions  or
270              stricter.  You  should  use  this  file  in conjunction with the
271              --accept-md5-only  option  to  avoid  server-side  attacks.  The
272              resource may contain any character but is limited to 127 charac‐
273              ters.
274

SEE ALSO

276       sane(7),   gamma4scanimage(1),   xscanimage(1),   xcam(1),    xsane(1),
277       scanadf(1), sane-dll(5), sane-net(5), sane-"backendname"(5)
278

AUTHOR

280       David  Mosberger,  Andreas Beck, Gordon Matzigkeit, Caskey Dickson, and
281       many others.  For questions and comments contact the  sane-devel  mail‐
282       inglist (see http://www.sane-project.org/mailing-lists.html).
283
284

BUGS

286       For  vector  options, the help output currently has no indication as to
287       how many elements a vector-value should have.
288
289
290
291                                  10 Jul 2008                     scanimage(1)
Impressum