README

Scantelope facilitates decoding of data matrix-labeled test tubes.
It supports a few scanners including the Avision AVA6 Plus. 

Copyright (c) 2011 Ginkgo Bioworks Inc.
Copyright (c) 2011 Daniel M Taub

This file is part of Scantelope.

Scantelope is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

DEPENDENCIES: 
  Python 2.x where x = 6 or greater
  Imagemagick 6.5.8-9 or greater
   http://www.imagemagick.org/
  OpenCV 2.2 + and python wrapper - module named "cv"
   http://sourceforge.net/projects/opencvlibrary/
  libdmtx and python wrapper -module named "pydmtx"
   http://www.libdmtx.org/
  sane 
   http://www.sane-project.org/

FILES:
  README                      this readme file
  COPYING                     GPL 3.0
  serv.py                     Main application - uses http API (described below)
  test.py                     Test application - runs 10 scans
  box_adaptors/               contains schematics for scanner jigs
  drivers/                    contains drivers for sane
  10-saned.rules              udev rules file for Avision scanner to allow 
                   running the software as any user in the 'scanner' group     
  *                           other files are subroutines, supporting files, etc

INSTALLATION:
 May need to do this on 64-bit: ln -s /usr/lib/x86_64-linux-gnu/libtiff.so.4.3.4 /usr/lib/libtiff.so.3

 NOTE: install.sh is an installation script for a debian-based (ubuntu, mint, etc) system.
 You may run this as user with sudo access, but make sure to check the SCANUSER and ARCH variables.
 WARNING: this script will replace your libsane-avision drivers with binary drivers from the manufacturer.
 The default behavior creates the 'scanner' group and adds the current user to said group. 
 ARCH defaults to 'i386' but 'amd64' and 'arm' are also valid. The script requires a good amount of space 
 in /tmp or you can change the directory/comment out the 'cd' call. Feel free to delete installation 
 directories after install. Before the scanner will work, after installing new drivers, it may be necessary
 to unplug-replug the scanner and/or restart/relogin before running serv.py.

  0) install all dependencies
    a) required packages: cmake python-numpy g++ python-dev git-core autoconf automake libtool sane
    b) ImageMagic-6.5.8-9 or later
    c) OpenCV 2.2 or later
    d) libdmtx and dmtx-wrappers/python
  
  1) install sane drivers
  2) create 'scanner' group and add chosen user(s) to it
  3) set up udev permissions 10-saned.rules 

  - test scanner visibility with 'scanimage -L'
  - run 'python serv.py' (or test.py for test)
  - browse to http://localhost:2233/scan/status


INTERFACE:
 (http API)
    http://localhost:2233{command}

 replace {command} with:       in order to:

      /scan/status             show current server settings and most recent log message
      /scan/list               list available scanners
      /scan/select/{0,1...n}   select scanner from list 

      /config/                 view current "inner" image and show options
             /use/{cfgName}      use configuration {cfgName} for current scanner
             /res/{600|300}      select resolution 
             /xoff/{integer}     select xoffset
             /yoff/{integer}     select yoffst
      /config/save             saves current configuration to a file
      /config/calibrate        automatically configure box position/boundaries and save as default

      /                        view CSV of most-recently decoded 
      /images/n_m.jpg          view image from row n (0-7) and column m (0-11)
      /images/inner.jpg        view full plate image

 The scanning should start on first http access, and will stop automatically 


SUPPORTED SCANNERS:

 Scantelope will not work with just any scanner. Since the label of a matrix 
 tube generally sits above the surface of the flatbed, it requires a scanner
 with a large depth-of-field to work properly.

 For this reason, we recommend the Avision AVA6 Plus and have included the 
 binary sane drivers as well as a schematic describing the jig we use to 
 position the rack on the bed. You can build your own, but may need to tweak
 the values in the CONFIG class of the scan.py module. 

 There is also limited support for the hp3900 which we do not intend to 
 expand at this time.