sane

README

sane

This package provides bindings to the SANE scanner API for the Go programming language.

INSTALLING

Run go get github.com/tjgq/sane.

The bindings are generated against libsane using cgo. You will need to have the appropriate development packages installed.

USING

Read the package documentation at GoDoc.org.

A sample program is provided in the example subdirectory. It (mostly) mimics the scanimage utility shipped with SANE.

Further information about the SANE API can be found at the SANE Project website.

BUGS

All SANE functionality is supported except authentication callbacks.

The package contains a test suite that runs against the SANE test device. However, more testing with real-world devices is always welcome.

LICENSE

This library is available under the BSD 3-clause license. See LICENSE for details.

FEEDBACK

Feel free to report bugs, make suggestions, or contribute improvements!

Documentation

Overview

Package sane provides bindings to the SANE scanner API.

The package exposes all of the SANE primitives. It also provides a somewhat higher-level interface for scanning one or more images, described below.

Before anything else, you must call Init to initialize the library.

err := sane.Init()

Call Devices to get a list of the available devices.

devs, err := sane.Devices()

Open a connection to a device by calling Open with its name. The empty string opens the first available device.

c, err := sane.Open("")

Call Options to retrieve the available options. An option may be set, or its current value retrieved, by calling SetOption or GetOption. Note that setting an option may affect the value or availability of other options.

opts := c.Options()
val, err := c.GetOption(name)
inf, err := c.SetOption(name, val)

To scan an image with the current options, call ReadImage. The returned Image object implements the standard library image.Image interface.

i, err := c.ReadImage()

Although ReadImage blocks, you may interrupt a scan in progress by calling Cancel from another goroutine.

c.Cancel()

Additional images may be scanned while the connection is open. To close the connection, call Close.

c.Close()

Finally, when you are done with the library, call Exit.

sane.Exit()

If you need finer-grained control over the scanning process, use the low-level API, documented at http://www.sane-project.org/html/.

Index

• Constants
• Variables
• func Exit()
• func Init() error
• type Conn
  • func Open(name string) (*Conn, error)
  • func (c *Conn) Cancel()
  • func (c *Conn) Close()
  • func (c *Conn) GetOption(name string) (interface{}, error)
  • func (c *Conn) Options() (opts []Option)
  • func (c *Conn) Params() (Params, error)
  • func (c *Conn) Read(b []byte) (int, error)
  • func (c *Conn) ReadFrame() (*Frame, error)
  • func (c *Conn) ReadImage() (*Image, error)
  • func (c *Conn) ReadImageFromSequence() (*Image, error)
  • func (c *Conn) SetOption(name string, v interface{}) (info Info, err error)
  • func (c *Conn) Start() error
• type Device
  • func Devices() (devs []Device, err error)
• type Error
• type Format
• type Frame
  • func (f *Frame) At(x, y, ch int) uint16
• type Image
  • func (m *Image) At(x, y int) color.Color
  • func (m *Image) Bounds() image.Rectangle
  • func (m *Image) ColorModel() color.Model
• type Info
• type Option
• type Params
• type Range
• type Type
• type Unit

Constants

const (
	TypeBool   Type = C.SANE_TYPE_BOOL
	TypeInt         = C.SANE_TYPE_INT
	TypeFloat       = C.SANE_TYPE_FIXED
	TypeString      = C.SANE_TYPE_STRING
	TypeButton      = C.SANE_TYPE_BUTTON
)

Type constants.

const (
	UnitNone    Unit = C.SANE_UNIT_NONE
	UnitPixel        = C.SANE_UNIT_PIXEL
	UnitBit          = C.SANE_UNIT_BIT
	UnitMm           = C.SANE_UNIT_MM
	UnitDpi          = C.SANE_UNIT_DPI
	UnitPercent      = C.SANE_UNIT_PERCENT
	UnitUsec         = C.SANE_UNIT_MICROSECOND
)

Unit constants.

const (
	FrameGray  Format = C.SANE_FRAME_GRAY
	FrameRgb          = C.SANE_FRAME_RGB
	FrameRed          = C.SANE_FRAME_RED
	FrameGreen        = C.SANE_FRAME_GREEN
	FrameBlue         = C.SANE_FRAME_BLUE
)

Format constants.

Variables

var (
	ErrUnsupported = errors.New("sane: operation not supported")
	ErrCancelled   = errors.New("sane: operation cancelled")
	ErrBusy        = errors.New("sane: device busy")
	ErrInvalid     = errors.New("sane: invalid argument")
	ErrJammed      = errors.New("sane: feeder jammed")
	ErrEmpty       = errors.New("sane: feeder empty")
	ErrCoverOpen   = errors.New("sane: cover open")
	ErrIo          = errors.New("sane: input/output error")
	ErrNoMem       = errors.New("sane: out of memory")
	ErrDenied      = errors.New("sane: access denied")
)

Error constants.

var Auto = autoType(0)

Auto is accepted by GetOption to set an option to its automatic value.

Functions

func Exit

func Exit()

Exit releases all resources in use, closing any open connections. The package cannot be used after Exit returns and before Init is called again.

func Init

func Init() error

Init must be called before the package can be used.

Types

type Conn

type Conn struct {
	Device string // device name
	// contains filtered or unexported fields
}

Conn is a connection to a scanning device. It can be used to get and set scanning options or to read one or more frames.

Conn implements the Reader interface. However, it only makes sense to call Read after acquisition of a new frame is started by calling Start.

func Open

func Open(name string) (*Conn, error)

Open opens a connection to a device with a given name. The empty string opens the first available device.

func (*Conn) Cancel

func (c *Conn) Cancel()

Cancel cancels the currently pending operation as soon as possible. It returns immediately; when the actual cancellation occurs, the canceled operation returns with ErrCancelled.

func (*Conn) Close

func (c *Conn) Close()

Close closes the connection, rendering it unusable for further operations.

func (*Conn) GetOption

func (c *Conn) GetOption(name string) (interface{}, error)

GetOption gets the current value for the named option. If successful, it returns a value of the appropriate type for the option.

func (*Conn) Options

func (c *Conn) Options() (opts []Option)

Options returns a list of available scanning options. The list of options usually remains valid until the connection is closed, but setting some options may affect the value or availability of others.

func (*Conn) Params

func (c *Conn) Params() (Params, error)

Params retrieves the current scanning parameters. The parameters are guaranteed to be accurate between the time the scan is started and the time the request is completed or cancelled. Outside that window, they are best-effort estimates for the next frame.

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

Read reads up to len(b) bytes of data from the current frame. It returns the number of bytes read and an error, if any. If the frame is complete, a zero count is returned together with an io.EOF error.

func (*Conn) ReadFrame

func (c *Conn) ReadFrame() (*Frame, error)

ReadFrame reads and returns a whole frame.

func (*Conn) ReadImage

func (c *Conn) ReadImage() (*Image, error)

ReadImage reads an image from the connection.

func (*Conn) ReadImageFromSequence

func (c *Conn) ReadImageFromSequence() (*Image, error)

ReadImageFromSequence reads an image from a stream in the connection (e.g. an automated document feeder). defer c.Cancel()

for {
  img, err := c.ReadImageFromSequence()
  if err == sane.ErrEmpty {
    break
  }
  if err != nil {
    return err
  }
  ...
}

func (*Conn) SetOption

func (c *Conn) SetOption(name string, v interface{}) (info Info, err error)

SetOption sets the value of the named option, which should be either of the corresponding type, or Auto for automatic mode. If successful, info contains information on the effects of setting the option.

func (*Conn) Start

func (c *Conn) Start() error

Start initiates the acquisition of a frame.

type Device

type Device struct {
	Name, Vendor, Model, Type string
}

Device represents a scanning device.

func Devices

func Devices() (devs []Device, err error)

Devices lists all available devices.

type Error

type Error error

Error represents a scanning error.

type Format

type Format int

Format represents the format of a frame.

type Frame

type Frame struct {
	Format   Format // frame format
	Width    int    // width in pixels
	Height   int    // height in pixels
	Channels int    // number of channels
	Depth    int    // bits per sample
	IsLast   bool   // whether this is the last frame
	// contains filtered or unexported fields
}

A Frame represents one or more channels in an image.

func (*Frame) At

func (f *Frame) At(x, y, ch int) uint16

At returns the sample at coordinates (x,y) for channel ch. Note that values are not normalized to the uint16 range, so you need to interpret them relative to the color depth.

type Image

type Image struct {
	// contains filtered or unexported fields
}

Image is a scanned image, corresponding to one or more frames.

It implements the image.Image interface.

func (*Image) At

func (m *Image) At(x, y int) color.Color

At returns the color of the pixel at (x, y).

func (*Image) Bounds

func (m *Image) Bounds() image.Rectangle

Bounds returns the domain for which At returns valid pixels.

func (*Image) ColorModel

func (m *Image) ColorModel() color.Model

ColorModel returns the Image's color model.

type Info

type Info struct {
	Inexact      bool // option set to an approximate value
	ReloadOpts   bool // option affects value or availability of other options
	ReloadParams bool // option affects scanning parameters
}

Info signals the side effects of setting an option.

type Option

type Option struct {
	Name         string        // option name
	Group        string        // option group
	Title        string        // option title
	Desc         string        // option description
	Type         Type          // option type
	Unit         Unit          // units
	Length       int           // vector length for vector-valued options
	ConstrSet    []interface{} // constraint set
	ConstrRange  *Range        // constraint range
	IsActive     bool          // whether option is active
	IsSettable   bool          // whether option can be set
	IsDetectable bool          // whether option value can be detected
	IsAutomatic  bool          // whether option has an auto value
	IsEmulated   bool          // whether option is emulated
	IsAdvanced   bool          // whether option is advanced
	// contains filtered or unexported fields
}

Option represents a scanning option.

type Params

type Params struct {
	Format        Format // frame format
	IsLast        bool   // true if last frame in multi-frame image
	BytesPerLine  int    // bytes per line, including any padding
	PixelsPerLine int    // pixels per line
	Lines         int    // number of lines, -1 if unknown
	Depth         int    // bits per sample
}

Params describes the properties of a frame.

type Range

type Range struct {
	Min   interface{} // minimum value
	Max   interface{} // maximum value
	Quant interface{} // quantization step
}

A Range is a set of discrete integer or fixed-point values. Value x is in the range if there is an integer k >= 0 such that Min <= k*Quant <= Max. The type of Min, Max and Quant is either int or float64 for all three.

type Type

type Type int

Type represents the data type of an option.

type Unit

type Unit int

Unit represents the physical unit of an option.