diff options
Diffstat (limited to 'doc/scanimage.man')
| -rw-r--r-- | doc/scanimage.man | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/doc/scanimage.man b/doc/scanimage.man new file mode 100644 index 0000000..79a1251 --- /dev/null +++ b/doc/scanimage.man @@ -0,0 +1,482 @@ +.TH scanimage 1 "10 Jul 2008" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy" +.IX scanimage +.SH NAME +scanimage \- scan an image +.SH SYNOPSIS +.B scanimage +.RB [ \-d | \-\-device\-name +.IR dev ] +.RB [ \-\-format +.IR format ] +.RB [ \-i | \-\-icc\-profile +.IR profile ] +.RB [ \-L | \-\-list\-devices ] +.RB [ \-f | \-\-formatted\-device\-list +.IR format ] +.RB [ \-b | \-\-batch +.RI [= format ]] +.RB [ \-\-batch\-start +.IR start ] +.RB [ \-\-batch\-count +.IR count ] +.RB [ \-\-batch\-increment +.IR increment ] +.RB [ \-\-batch\-double ] +.RB [ \-\-accept\-md5\-only ] +.RB [ \-p | \-\-progress ] +.RB [ \-n | \-\-dont\-scan ] +.RB [ \-T | \-\-test ] +.RB [ \-A | \-\-all-options ] +.RB [ \-h | \-\-help ] +.RB [ \-v | \-\-verbose ] +.RB [ \-B | \-\-buffer-size +.RI [= size ]] +.RB [ \-V | \-\-version ] +.RI [ device\-specific\-options ] +.SH DESCRIPTION +.B 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, +.B 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). +.B scanimage +accesses image acquisition devices through the +.B SANE +(Scanner Access Now Easy) interface and can thus support any device for which +there exists a +.B SANE +backend (try +.B apropos +.I sane\- +to get a list of available backends). + +.SH EXAMPLES +To get a list of devices: + + scanimage \-L + +To scan with default settings to the file image.pnm: + + scanimage >image.pnm + +To scan 100x100 mm to the file image.tiff (\-x and \-y may not be available with +all devices): + + scanimage \-x 100 \-y 100 \-\-format=tiff >image.tiff + +To print all available options: + + scanimage \-h + +.SH OPTIONS +Parameters are separated by a blank from single-character options (e.g. +\-d epson) and by a "=" from multi-character options (e.g. \-\-device\-name=epson). + +.PP +The +.B \-d +or +.B \-\-device\-name +options must be followed by a +.B SANE +device-name like +.RI ` epson:/dev/sg0 ' +or +.RI ` hp:/dev/usbscanner0 '. +A (partial) list of available devices can be obtained with the +.B \-\-list\-devices +option (see below). If no device-name is specified explicitly, +.B scanimage +reads a device-name from the environment variable +.BR SANE_DEFAULT_DEVICE . +If this variable is not set, +.B scanimage +will attempt to open the first available device. +.PP +The +.B \-\-format +.I format +option selects how image data is written to standard output. +.I format +can be +.B pnm +or +.BR tiff. +If +.B \-\-format +is not used, PNM is written. +.PP +The +.B \-i +or +.B \-\-icc\-profile +option is used to include an ICC profile into a TIFF file. +.PP +The +.B \-L +or +.B \-\-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 +.IR @CONFIGDIR@ ). +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. +.PP +The +.B \-f +or +.B \-\-formatted\-device\-list +option works similar to +.BR \-\-list\-devices , +but requires a format string. +.B scanimage +replaces the placeholders +.B %d %v %m %t %i %n +with the device name, vendor name, model name, scanner type, an index +number and newline respectively. The command +.PP +.RS +.B scanimage \-f +.I \*(lq scanner number %i device %d is a %t, model %m, produced by %v \*(rq +.PP +.RE +will produce something like: +.PP +.RS +scanner number 0 device sharp:/dev/sg1 is a flatbed scanner, model JX250 +SCSI, produced by SHARP +.RE +.PP +The +.B \-\-batch* +options provide the features for scanning documents using document +feeders. +.BR \-\-batch +.RI [ 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 +.I format +is not specified, the default of out%d.pnm (or out%d.tif for \-\-format tiff) +will be used. +.I format +is given as a printf style string with one integer parameter. +.B \-\-batch\-start +.I start +selects the page number to start naming files with. If this option is not +given, the counter will start at 1. +.B \-\-batch\-count +.I 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 +.B \-\-batch\-increment +.I 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: +.B \-\-batch\-double +will automatically set the increment to 2. +.B \-\-batch\-prompt +will ask for pressing RETURN before scanning a page. This can be used for +scanning multiple pages without an automatic document feeder. +.PP +The +.B \-\-accept\-md5\-only +option only accepts user authorization requests that support MD5 security. The +.B SANE +network daemon +.RB ( saned ) +is capable of doing such requests. See +.BR saned (8). +.PP +The +.B \-p +or +.B \-\-progress +option requests that +.B scanimage +prints a progress counter. It shows how much image data of the current image has +already been received by +.B scanimage +(in percent). +.PP +The +.B \-n +or +.B \-\-dont\-scan +option requests that +.B 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). +.PP +The +.B \-T +or +.B \-\-test +option requests that +.B scanimage +performs a few simple sanity tests to make sure the backend works as +defined by the +.B SANE +API (in particular the +.B sane_read +function is exercised by this test). +.PP +The +.B \-A +or +.B \-\-all-options +option requests that +.B scanimage +lists all available options exposed the backend, including button options. +The information is printed on standard output and no scan will be done. +.PP +The +.B \-h +or +.B \-\-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. +.PP +The +.B \-v +or +.B \-\-verbose +options increase the verbosity of the operation of +.B scanimage. +The option may be specified repeatedly, each time increasing the verbosity +level. +.PP +The +.B \-B +or +.B \-\-buffer-size +changes the input buffer size from 32KB to the number kB specified or 1M. +.PP +The +.B \-V +or +.B \-\-version +option requests that +.B scanimage +prints the program and package name, the version number of +the +.B 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 +.B DEBUG +variable for the dll backend can be used. Example: SANE_DEBUG_DLL=3 scanimage +\-L. +.PP +As you might imagine, much of the power of +.B scanimage +comes from the fact that it can control any +.B SANE +backend. Thus, the exact set of command-line options depends on the +capabilities of the selected device. To see the options for a device named +.IR dev , +invoke +.B scanimage +via a command-line of the form: +.PP +.RS +.B scanimage \-\-help \-\-device\-name +.I dev +.RE +.PP +The documentation for the device-specific options printed by +.B \-\-help +is best explained with a few examples: + + \-l 0..218mm [0] +.br + Top-left x position of scan area. +.PP +.RS +The description above shows that option +.B \-l +expects an option value in the range from 0 to 218 mm. The +value in square brackets indicates that the current option value is 0 +mm. Most backends provide similar geometry options for top-left y position (\-t), +width (\-x) and height of scan-area (\-y). +.RE + + + \-\-brightness \-100..100% [0] +.br + Controls the brightness of the acquired image. +.PP +.RS +The description above shows that option +.B \-\-brightness +expects an option value in the range from \-100 to 100 percent. The +value in square brackets indicates that the current option value is 0 +percent. +.RE + + \-\-default\-enhancements +.br + Set default values for enhancement controls. +.PP +.RS +The description above shows that option +.B \-\-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 +.B \-\-brightness +option, the option-pair +.B \-\-brightness 50 \-\-default\-enhancements +would effectively be a no-op. +.RE + + \-\-mode Lineart|Gray|Color [Gray] +.br + Selects the scan mode (e.g., lineart or color). +.PP +.RS +The description above shows that option +.B \-\-mode +accepts an argument that must be one of the strings +.BR Lineart , +.BR Gray , +or +.BR Color . +The value in the square bracket indicates that the option is currently +set to +.BR 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 +.B \-\-mode col +is identical to +.BR "\-\-mode Color" . +.RE + + \-\-custom\-gamma[=(yes|no)] [inactive] +.br + Determines whether a builtin or a custom gamma-table +.br + should be used. +.PP +.RS +The description above shows that option +.B \-\-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, 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 +.B \-\-custom\-gamma +table might be active only when a grayscale or color scan-mode has +been requested. + +Note that the +.B \-\-help +option is processed only after all other options 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 +.B \-\-help +option. For example, the command-line: +.PP +.B scanimage \-\-help \-\-mode +.I color +.PP +would print the option settings that are in effect when the color-mode +is selected. +.RE + + \-\-gamma\-table 0..255,... +.br + Gamma-correction table. In color mode this option +.br + equally affects the red, green, and blue channels +.br + simultaneously (i.e., it is an intensity gamma table). +.PP +.RS +The description above shows that option +.B \-\-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 cumbersome 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 in between 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 +.B gamma4scanimage +can be used to generate such gamma tables (see +.BR gamma4scanimage (1) +for details). +.RE + +.br + \-\-filename <string> [/tmp/input.ppm] +.br + The filename of the image to be loaded. +.PP +.RS +The description 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 +.BR /tmp/input.ppm . +.RE + +.SH ENVIRONMENT +.TP +.B SANE_DEFAULT_DEVICE +The default device-name. +.SH FILES +.TP +.I @CONFIGDIR@ +This directory holds various configuration files. For details, please +refer to the manual pages listed below. +.TP +.I ~/.sane/pass +This file contains lines of the form +.PP +.RS +user:password:resource +.PP +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. +.SH "SEE ALSO" +.BR sane (7), +.BR gamma4scanimage (1), +.BR xscanimage (1), +.BR xcam(1) , +.BR xsane(1) , +.BR scanadf (1), +.BR sane\-dll (5), +.BR sane\-net (5), +.BR sane\-"backendname" (5) +.SH AUTHOR +David Mosberger, Andreas Beck, Gordon Matzigkeit, Caskey Dickson, and many +others. For questions and comments contact the sane\-devel mailinglist (see +http://www.sane\-project.org/mailing\-lists.html). + +.SH BUGS +For vector options, the help output currently has no indication as to +how many elements a vector-value should have. |