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), TIFF format (black-and-white, grayscale or color), PNG format,
25       or JPEG format.  scanimage accesses image acquisition  devices  through
26       the  SANE  (Scanner Access Now Easy) interface and can thus support any
27       device for which there exists a SANE backend (try apropos sane- to  get
28       a list of available backends).
29
30

EXAMPLES

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

OPTIONS

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

ENVIRONMENT

258       SANE_DEFAULT_DEVICE
259              The default device-name.
260

FILES

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

SEE ALSO

279       sane(7),    gamma4scanimage(1),   xscanimage(1),   xcam(1),   xsane(1),
280       scanadf(1), sane-dll(5), sane-net(5), sane-"backendname"(5)
281

AUTHOR

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

BUGS

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