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. Send comments, questions, and bug reports concerning this module to amk1@erols.com, or possibly to image-sig@python.org . 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() [('qcam:0x378', 'Connectix', 'B&W QuickCam', 'video camera'), ('pnm:0', 'Noname', 'PNM file reader', 'virtual device')] open(devicename) Open a device, given a string containing its name. SANE devices have names like _"qcam:0x378"_ or _"pnm:0"_. 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. 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). format -- 'L' for greyscale image, 'RGB' for RGB image, or one of 'R', 'G', 'B' 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() Snap a single frame of data, returning a PIL Image object containing the data. If the scanner is one that requires several frames to return all the image data, it's the caller's responsibility to call the _start()_ and _snap()_ methods again for the next frame, and to combine the frames into a single image afterwards. 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. For example, 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. For an option like _filename_ and a SaneDev object _obj_, _obj.opt_filename_ returns the SaneOption object for the option, and _obj.filename_ returns the option's current value. The current value may be an integer, floating-point value, or string, depending on the nature of the option. optlist A list containing the _py_name_ values for all the options supported by this device. >>> import sane ; s=sane.open('pnm:0') ; s.optlist ['filename', 'brightness', 'contrast', 'grayify', 'three_pass', 'hand_scanner', 'default_enhancements'] 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. Methods: 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. 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