scanimage.1




NAME

       scanimage - scan an image


SYNOPSIS

       scanimage   [-d|--device-name   dev]   [--format   format]
       [--accept-md5-only]    [-h|--help]     [-L|--list-devices]
       [-f|--formatted-device-list format] [-T|--test] [-v|--ver�
       bose] [-V|--version] [--batch[=FORMAT]]  [--batch-start=#]
       [--batch-count=#]  [--batch-increment=#]  [--batch-double]
       [device-specific-options]


DESCRIPTION

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


OPTIONS

       The -d or --device-name options must be followed by a SANE
       device-name  like  "epson:/dev/sg0"  or  "hp:/dev/usbscan�
       ner0". A  (partial)  list  of  available  devices  can  be
       obtained  with  the --list-devices option (see below).  If
       no device-name is specified explicitly, scanimage reads  a
       device-name      from     the     environment     variable
       SANE_DEFAULT_DEVICE.  If this variable is not set, scanim�
       age will attempt to open the first available device.

       The  --format  format selects how image data is written to
       standard output.  format can be pnm or tiff to select file
       format  PNM or TIFF. If --format is not used, PNM is writ�
       ten.

       The --accept-md5-only option only accepts user  authoriza�
       tion  requests that support MD5 security. The SANE network
       daemon (saned) is capable  of  doing  such  requests.  See
       saned(1)

       The  -h  or  --help options request help information.  The
       information is printed on  standard  output  and  in  this
       case, no attempt will be made to acquire an image.

       The  -L or --list-devices option requests a (partial) list
       of devices that are available.  The list is  not  complete
       since some devices may be available, but are not listed in
       any of the configuration files (which are typically stored
       in directory /usr/local/etc/sane.d).  This is particularly
       the case when accessing scanners through the network.   If
       a  device  is not listed in a configuration file, the only
       way to access it is by its full device name.  You may need
       to consult your system administrator to find out the names
       of such devices.

       The -f or --formatted-device-list option works similar  to
       --list-devices,  but  requires a format string.  scanimage
       replaces the placeholders %d %v %m %t %i with  the  device
       name,  vendor  name, model name, scanner type and an index
       number respectively. The command

              scanimage -f "scanner number %i device %d is a  %t,
              model %m, produced by %v"

       will produce something like:

              scanner  number  0   device  sharp:/dev/sg1  is   a
              flatbed scanner,  model  JX250  SCSI,  produced  by
              SHARP

       The  -T or --test option requests that scanimage perform a
       few simple sanity tests to make sure the backend works  as
       defined by the SANE API (in particular the sane_read func�
       tion is excercised by this test).

       The -v or --verbose options increase the verbosity of  the
       operation  of  scanimage.   The  option  may  be specified
       repeatedly, each time increasing the verbosity level.

       The -V or --version option requests that scanimage  prints
       the  program  and  package name, the version number of the
       SANE distribution that it came with and the version of the
       backend  that it loads. Usually that's the dll backend. If
       more information about the version numbers of the backends
       are  necessary, the DEBUG variable for the dll backend can
       be used. Example: SANE_DEBUG_DLL=3 scanimage -L.

       The --batch* options provide  the  features  for  scanning
       documents  using  document  feeders.   --batch[=FORMAT] is
       used to specify the format of the filename that each  page
       will  be written to.  Each page is written out to a single
       file.  If the FORMAT is  not  specified,  the  default  of
       out%d.pnm  (or  out%d.tif for --format tiff) will be used.
       FORMAT is given as a printf style string with one  integer
       parameter.   --batch-start=#  selects  the  page number to
       start naming files with. If this option is not given,  the
       counter  will  start  at 0.  --batch-count=# specifies the
       number of pages to attempt to scan.  If not given, scanim�
       age  will  continue  scanning  until the scanner returns a
       state other than OK.  Not all scanners with document feed�
       ers signal when the ADF is empty, use this command to work
       around them.  With --batch-increment=# you can change  the
       amount  that the number in the filename is incremented by.
       Generally this is used when you are scanning  double-sided
       documents  on  a single-sided document feeder.  A specific
       command is provided to aid this: --batch-double will auto�
       matically set the increment to 2.

       As you might imagine, much of the power of scanimage comes
       from the fact that it can control any SANE backend.  Thus,
       the exact set of command-line options depends on the capa�
       bilities of the selected device.  To see the options for a
       device  named  dev, invoke scanimage via a command-line of
       the form:

              scanimage --help --device dev

       The documentation for the device-specific options  printed
       by --help is best explained with a few examples:

        --brightness -100..100% [0]
           Controls the brightness of the acquired image.

              The  description  above shows that option --bright�
              ness expects an option value in the range from -100
              to 100 percent.  The value in square brackets indi�
              cates that the current option value is 0 percent.

        --default-enhancements
           Set default values for enhancement controls.

              The description above shows that option  --default-
              enhancements  has  no  option  value.  It should be
              thought of as having an  immediate  effect  at  the
              point of the command-line at which it appears.  For
              example, since this option resets the  --brightness
              option,  the option-pair --brightness 50 --default-
              enhancements would effectively be a no-op.

        --mode Lineart|Gray|Color [Gray]
           Selects the scan mode (e.g., lineart or color).

              The description  above  shows  that  option  --mode
              accepts an argument that must be one of the strings
              Lineart, Gray, or Color.  The value in  the  square
              bracket  indicates that the option is currently set
              to Gray.  For convenience, it is legal to  abbrevi�
              ate  the  string  values  as  long  as  they remain
              unique.  Also, the case  of  the  spelling  doesn't
              matter.   For example, option setting --mode col is
              identical to --mode Color.

        --custom-gamma[=(yes|no)] [inactive]
           Determines whether a builtin or a custom gamma-table
           should be used.

              The description above shows that  option  --custom-
              gamma  expects  either  no  option  value,  a "yes"
              string, or a "no" string.   Specifying  the  option
              with  no  value  is equivalent to specifying "yes".
              The value in  square-brackets  indicates  that  the
              option  is not currently active.  That is, attempt�
              ing to set the option would result in an error mes�
              sage.   The  set  of  available  options  typically
              depends on the  settings  of  other  options.   For
              example,  the  --custom-gamma table might be active
              only when a grayscale or color scan-mode  has  been
              requested.

              Note that the --help option is processed only after
              all other options have been processed.  This  makes
              it  possible  to see the option settings for a par�
              ticular mode by specifying  the  appropriate  mode-
              options along with the --help option.  For example,
              the command-line:

                scanimage --help --mode color

              would print the option settings that are in  effect
              when the color-mode is selected.

        --gamma-table 0..255,...
           Gamma-correction table.  In color mode this option
           equally affects the red, green, and blue channels
           simultaneously (i.e., it is an intensity gamma table).

              The description above shows  that  option  --gamma-
              table expects zero or more values in the range 0 to
              255.  For example, a legal value  for  this  option
              would be "3,4,5,6,7,8,9,10,11,12".  Since it's cum�
              bersome to specify long vectors in this  form,  the
              same  can  be  expressed  by  the  abbreviated form
              "[0]3-[9]12".  What this means is  that  the  first
              vector element is set to 3, the 9-th element is set
              to 12 and the  values  inbetween  are  interpolated
              linearly.   Of  course,  it  is possible to specify
              multiple  such  linear  segments.    For   example,
              "[0]3-[2]3-[6]7,[7]10-[9]6"    is   equivalent   to
              "3,3,3,4,5,6,7,10,8,6".

        --filename <string> [/tmp/input.ppm]
           The filename of the image to be loaded.

              The descriptoin above is an example  of  an  option
              that takes an arbitrary string value (which happens
              to be a filename).  Again, the  value  in  brackets
              show that the option is current set to the filename
              /tmp/input.ppm.


ENVIRONMENT

       SANE_DEFAULT_DEVICE
              The default device-name.


FILES

       /usr/local/etc/sane.d
              This directory holds various  configuration  files.
              For  details,  please  refer  to  the  manual pages
              listed below.

       ~/.sane/pass
              This file contains lines of the form

              user:password:resource

              scanimage uses  this  information  to  answer  user
              authorization requests automatically. The file must
              have 0600 permissions or stricter. You  should  use
              this file in conjunction with the --accept-md5-only
              option to avoid server-side attacks.  The  resource
              may  contain  any  character  but is limited to 127
              characters.


SEE ALSO

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


AUTHOR

       David  Mosberger,  Andreas  Beck,  Gordon  Matzigkeit  and
       Caskey Dickson


BUGS

       For vector options, the help output currently has no indi�
       cation as to how many elements a vector-value should have.


Man(1) output converted with man2html