Pillow-1.7.8.zip

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 str