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

ENVIRONMENT

266       SANE_DEFAULT_DEVICE
267              The default device-name.
268

FILES

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

SEE ALSO

287       sane(7),    gamma4scanimage(1),   xscanimage(1),   xcam(1),   xsane(1),
288       scanadf(1), sane-dll(5), sane-net(5), sane-"backendname"(5)
289

AUTHOR

291       David Mosberger, Andreas Beck, Gordon Matzigkeit, Caskey  Dickson,  and
292       many  others.   For questions and comments contact the sane-devel mail‐
293       inglist (see http://www.sane-project.org/mailing-lists.html).
294
295

BUGS

297       For vector options, the help output currently has no indication  as  to
298       how many elements a vector-value should have.
299
300
301
302                                  10 Jul 2008                     scanimage(1)
Impressum