home | help 
scanimage(1)		  SANE Scanner Access Now Easy		    scanimage(1)

NAME
     scanimage - scan an image

SYNOPSIS
     scanimage	[-d|--device-name  dev] [--format format] [-i|--icc-profile pro-
     file]  [-L|--list-devices]  [-f|--formatted-device-list  format]	[--batch
     [=format]]  [--batch-start  start] [--batch-count count] [--batch-increment
     increment]    [--batch-double]	[--accept-md5-only]	[-n|--dont-scan]
     [-T|--test]  [-h|--help] [-v|--verbose] [-V|--version] [device-specific-op-
     tions]

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) interface and can  thus  support
     any  device for which there exists a SANE backend (try apropos sane- to get
     a list of available backends).

EXAMPLES
     To get a list of devices:

       scanimage -L

     To scan with default settings to the file image.pnm:

       scanimage >image.pnm

     To print all available options:

       scanimage -h

OPTIONS
     The -d or --device-name options must be followed by a SANE device-name like
     `epson:/dev/sg0' or `hp:/dev/usbscanner0'.  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,
     scanimage will attempt to open the first available device.

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

     The  -i  or  --icc-profile  option is used to include an ICC profile into a
     TIFF file.

     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 avail-
     able, but are not listed in any of the configuration files (which are typi-
     cally 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,  pro-
	    duced by %v "

     will produce something like:

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

     The --batch* options provide the features for scanning documents using doc-
     ument feeders.  --batch [format] is used to specify the format of the file-
     name that each page will be written to.  Each page is written out to a sin-
     gle file.	If 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 start  selects  the
     page  number  to  start naming files with. If this option is not given, the
     counter will start at 0.  --batch-count count specifies the number of pages
     to attempt to scan.  If not given, scanimage will continue  scanning  until
     the  scanner returns a state other than OK.  Not all scanners with document
     feeders signal when the ADF is empty, use this command to work around them.
     With --batch-increment 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  spe-
     cific  command  is  provided to aid this: --batch-double will automatically
     set the increment to 2.  --batch-prompt will ask for pressing RETURN before
     scanning a page. This can be used for scanning multiple  pages  without  an
     automatic document feeder.

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

     The  -n or --dont-scan option requests that scanimage only sets the options
     provided by the user but doesn't actually perform a scan. This  option  can
     be used to e.g. turn off the scanner's lamp (if supported by the backend).

     The  -T or --test option requests that scanimage performs a few simple san-
     ity tests to make sure the backend works as defined by  the  SANE	API  (in
     particular the sane_read function is excercised by this test).

     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 ac-
     quire an image.

     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 back-
     end. If more information about the version numbers of the backends are nec-
     essary, the DEBUG variable for  the  dll  backend	can  be  used.	Example:
     SANE_DEBUG_DLL=3 scanimage -L.

     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 capabilities of the selected device.  To see the op-
     tions  for  a  device named dev, invoke scanimage via a command-line of the
     form:

	    scanimage --help --device-name 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 --brightness expects an  op-
	    tion  value  in  the  range  from -100 to 100 percent.  The value in
	    square brackets indicates that the current option value  is  0  per-
	    cent.

      --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 ef-
	    fect at the point of the command-line at which it appears.	For  ex-
	    ample, 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 abbreviate 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 ei-
	    ther 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,  attempting to set the option would result in an
	    error message.  The set of available options  typically  depends  on
	    the  settings of other options.  For example, the --custom-gamma ta-
	    ble 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 op-
	    tions have been processed.	This makes it possible to see the option
	    settings for a particular 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  ex-
	    pressed  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".  The program gamma4scanimage can be used  to
	    generate such gamma tables (see gamma4scanimage(1) for details).

      --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 arbi-
	    trary  string  value  (which  happens to be a filename).  Again, the
	    value in brackets show that the option is current set to  the  file-
	    name /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  re-
	    quests  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  con-
	    tain any character but is limited to 127 characters.

SEE ALSO
     sane(7),  gamma4scanimage(1), 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 indication as  to  how
     many elements a vector-value should have.

sane-backends 1.0.15		   22 Feb 2004			    scanimage(1)
home | help