The _sane_ module is an Python interface to the SANE (Scanning is Now
Easy) library, which provides access to various raster scanning
devices such as flatbed scanners and digital cameras.  For more
information about SANE, consult the SANE Web site at
http://www.mostang.com/sane/ .  Note that this
documentation doesn't duplicate all the information in the SANE
documentation, which you must also consult to get a complete
understanding.

This module has been originally developed by A.M. Kuchling (amk1@erols.com),
now development has been taken over by Ralph Heinkel (rheinkel-at-email.de).
If you write to me please make sure to have the word 'SANE' or 'sane' in 
the subject of your mail, otherwise it might be classified as spam in the
future.


The module exports two object types, a bunch of constants, and two
functions.  

get_devices()
  Return a list of 4-tuples containing the available scanning
  devices.  Each tuple contains 4 strings: the device name, suitable for
  passing to _open()_; the device's vendor; the model; and the type of
  device, such as 'virtual device' or 'video camera'.

  >>> import sane ; sane.get_devices()
  [('epson:libusb:001:004', 'Epson', 'GT-8300', 'flatbed scanner')]

open(devicename)
  Open a device, given a string containing its name.  SANE
  devices have names like 'epson:libusb:001:004'.  If the attempt
  to open the device fails, a _sane.error_ exception will be raised.  If
  there are no problems, a SaneDev object will be returned.
  As an easy way to open the scanner (if only one is available) just type
  >>> sane.open(sane.get_devices()[0][0])


SaneDev objects
===============

The basic process of scanning an image consists of getting a SaneDev
object for the device, setting various parameters, starting the scan,
and then reading the image data.  Images are composed of one or more
frames; greyscale and one-pass colour scanners return a single frame
containing all the image data, but 3-pass scanners will usually return
3 frames, one for each of the red, green, blue channels.

Methods:
--------
fileno()
  Returns a file descriptor for the scanning device.  This
  method's existence means that SaneDev objects can be used by the
  select module.

get_parameters()
  Return a tuple containing information about the current settings of
  the device and the current frame: (format, last_frame,
  pixels_per_line, lines, depth, bytes_per_line).

	mode  -- 'gray' for greyscale image, 'color' for RGB image, or
	          one of 'red', 'green', 'blue' if the image is a single
                  channel of an RGB image (from PIL's point of view,
                  this is equivalent to 'L').
	last_frame -- A Boolean value, which is true if this is the
                  last frame of the image, and false otherwise.
	pixels_per_line -- Width of the frame.
	lines -- Height of the frame.
	depth -- Depth of the image, measured in bits.  SANE will only
	         allow using 8, 16, or 24-bit depths.
	bytes_per_line -- Bytes required to store a single line of
                 data, as computed from pixels_per_line and depth.

start()
   Start a scan.  This function must be called before the
   _snap()_ method can be used.
	
cancel()
   Cancel a scan already in progress.

snap(no_cancel=0)
   Snap a single frame of data, returning a PIL Image object
   containing the data. If no_cancel is false, the Sane library function
   sane_cancel is called after the scan. This is reasonable in most cases,
   but may cause backends for duplex ADF scanners to drop the backside image, 
   when snap() is called for the front side image. If no_cancel is true,
   cancel() should be called manually, after all scans are finished.

scan()
   This is just a shortcut for s.start(); s.snap()
   Returns a PIL image

multi_scan()
   This method returns an iterator. It is intended to be used for 
   scanning with an automatic document feeder. The next() method of the 
   iterator tries to start a scan. If this is successful, it returns a
   PIL Image object, like scan(); if the document feeder runs out of 
   paper, it raises StopIteration, thereby signaling that the sequence
   is ran out of items.
   
arr_snap(multipleOf=1)
   same as snap, but the result is a NumArray object. (Not that
   num_array must be installed already at compilation time, otherwise
   this feature will not be activated).
   By default the resulting array has the same number of pixels per
   line as specified in self.get_parameters()[2][0]
   However sometimes it is necessary to obtain arrays where
   the number of pixels per line is e.g. a multiple of 4. This can then
   be achieved with the option 'multipleOf=4'. So if the scanner
   scanned 34 pixels per line, you will obtain an array with 32 pixels
   per line.
   Note that this only works with monochrome images (e.g. gray-scales)

arr_scan(multipleOf=1)
   This is just a shortcut for s.start(); s.arr_snap(multipleOf=1)
   Returns a NumArray object

close()
   Closes the object.


Attributes:
-----------
SaneDev objects have a few fixed attributes which are always
available, and a larger collection of attributes which vary depending
on the device. An Epson 1660 photo scanner has attributes like
'mode', 'depth', etc. 
Another (pseudo scanner), the _pnm:0_ device, takes a PNM file and
simulates a scanner using the image data; a SaneDev object
representing the _pnm:0_ device therefore has a _filename_ attribute
which can be changed to specify the filename, _contrast_ and
_brightness_ attributes to modify the returned image, and so forth.

The values of the scanner options may be an integer, floating-point 
value, or string, depending on the nature of the option.

sane_signature
  The tuple for this scandev that is returned by sane.get_devices()
  e.g. ('epson:libusb:001:006', 'Epson', 'GT-8300', 'flatbed scanner')

scanner_model
  same as sane_signature[1:3], i.e. ('Epson', 'GT-8300') for the case above.

optlist
   A list containing the all the options supported by this device.

   >>> import sane ; s=sane.open('epson:libusb:001:004') ; s.optlist
   ['focus_position', 'color_correction', 'sharpness', ...., 'br_x']

A closer look at all options listed in s.optlist can be obtained
through the SaneOption objects.

SaneOption objects
==================

SANE's option handling is its most elaborate subsystem, intended to
allow automatically generating dialog boxes and prompts for user
configuration of the scanning device.  The SaneOption object can be
used to get a human-readable name and description for an option, the
units to use, and what the legal values are.  No information about the
current value of the option is available; for that, read the
corresponding attribute of a SaneDev object.

This documentation does not explain all the details of SANE's option
handling; consult the SANE documentation for all the details.

A scandevice option is accessed via __getitem__. For example
s['mode'] returns the option descriptor for the mode-option which
controls whether the scanner works in color, grayscale, or b/w mode.

>>> s['mode']
Name:      mode
Cur value: Color
Index:     2
Title:     Scan mode
Desc:      Selects the scan mode (e.g., lineart, monochrome, or color).
Type:      TYPE_STRING
Unit:      UNIT_NONE
Constr:    ['Binary', 'Gray', 'Color']
active:    yes
settable:  yes

In order to change 'mode' to 'gray', just type:
>>> s.mode = 'gray'


With the attributes and methods of sane-option objects it is possible 
to access individual option values:

is_active() 
  Returns true if the option is active.

is_settable() 
  Returns true if the option can be set under software control.


Attributes:

cap
  An integer containing various flags about the object's
  capabilities; whether it's active, whether it's settable, etc.  Also
  available as the _capability_ attribute.

constraint
  The constraint placed on the value of this option.  If it's
  _None_, there are essentially no constraint of the value.  It may also
  be a list of integers or strings, in which case the value *must* be
  one of the possibilities in the list.  Numeric values may have a
  3-tuple as the constraint; this 3-tuple contains _(minimum, maximum,
  increment)_, and the value must be in the defined range.

desc
  A lengthy description of what the option does; it may be shown
  to the user for clarification.

index
  An integer giving the option's index in the option list.

name
  A short name for the option, as it comes from the sane-backend. 

py_name 
  The option's name, as a legal Python identifier.  The name
  attribute may contain the '-' character, so it will be converted to
  '_' for the py_name attribute.

size
  For a string-valued option, this is the maximum length allowed. 

title
  A single-line string that can be used as a title string.
	
type
  A constant giving the type of this option: will be one of the following 
  constants found in the SANE module:
	TYPE_BOOL
	TYPE_INT
	TYPE_FIXED
	TYPE_STRING
	TYPE_BUTTON
	TYPE_GROUP

unit
  For numeric-valued options, this is a constant representing
  the unit used for this option.  It will be one of the following
  constants found in the SANE module:
	UNIT_NONE
	UNIT_PIXEL
	UNIT_BIT
	UNIT_MM
	UNIT_DPI
	UNIT_PERCENT



Example us usage:
=================
>>> import sane
>>> print 'SANE version:', sane.init()
>>> print 'Available devices=', sane.get_devices()
SANE version: (16777230, 1, 0, 14)
>>> s = sane.open(sane.get_devices()[0][0])
>>> print 'Device parameters:', s.get_parameters()
Device parameters: ('L', 1, (424, 585), 1, 53)
>>> print s.resolution
50

## In order to scan a color image into a PIL object:
>>> s.mode = 'color'
>>> s.start()
>>> img = s.snap()
>>> img.show()


## In order to obtain a 16-bit grayscale image at 100DPI in a numarray object
## with bottom-right coordinates set to (160, 120) [in millimeter] :
>>> s.mode = 'gray'
>>> s.br_x=160. ; s.br_y=120.    
>>> s.resolution = 100
>>> s.depth=16
>>> s.start()
>>> s.get_parameters()[2]   # just check the size
(624, 472)
>>> arr16 = s.arr_snap()
>>> arr16
array([[63957, 64721, 65067, ..., 65535, 65535, 65535],
       [63892, 64342, 64236, ..., 65535, 65535, 65535],
       [64286, 64248, 64705, ..., 65535, 65535, 65535],
       ...,
       [65518, 65249, 65058, ..., 65535, 65535, 65535],
       [64435, 65047, 65081, ..., 65535, 65535, 65535],
       [65309, 65438, 65535, ..., 65535, 65535, 65535]], type=UInt16)
>>> arr16.shape   # inverse order of coordinates, first y, then x!
(472, 624)