3D Scanner Control
Version 1.0
2009-03-06

(c) 2009 by Malte Marwedel

Terms of Use: GPL Version 2 or Later.

------------ Quick start ------------------------------------------------------
1. Compile
  Go into the src directory and run ./Compile.sh or .bat under Windows)
2. Start program
  Run ./3DScannerControl.sh (or .bat under Windows)
3. Start a scan
  a) Open the proper port
  b) Select a range for scanning by selecting a start point with the middle and
     a final point with the left mouse button in the right black field.
  c) Click "Scan vector". Depending on the area to scan, this takes from a few
     seconds to up to three hours.
  d) Save your scan
  e) Export it with PovRay and have fun. ("Scan linear" is not suitable for
     PovRay export.)     

------------ Description of the 3draw file format -----------------------------
3draw = 3D raw data
The file is a gzip compressed Object output stream. Look in the class
  ScannerData to see how reading and writing is done.
The the first object is an UTF String for identifying the file format
  and version. (3DScannerDataFile-V002)
The second object is an int, indicating the values in X direction. (currently
  always 256)
The third object is an int, indicating the values in Y direction. (currently
  always 256)
The fourth object is an int, indicating the values per point. (currently
  always 6) 
After that, int values from the 3d scanner follows.
Each point consists of six ints: X, Y, Z, light, size, recording mode
  X, Y, Z: Are the calculated values from the position in the room. If the
    scan was not a vector scan, the value is stored in Z and X, Y will be
    read 0.
  light: Is the raw value from the light sensor.
  size: Indicates with which resolution the point was scanned.
  recording mode: Indicates in which mode the scan was made. 1 = raw value,
    2 = linear value, 3 = vector value
  All points where no scan was done, are read as 0.
The first point represents the scanned position X=0, Y=0 (scanner is left
  down) the second point  X=1, Y=0 and so on.

------------ Bugs -------------------------------------------------------------
Scanning with multiple resolutions within a single image at similar positions
may result in wrong partial redrawing.
Workaround: Change the contrast to produce a full redraw.

Moreover as the lower resolution pixels may still be present, they are exported
to the PovRay file and will overlap finer resolution objects.
Workaround: Make sure a scan with a finer resolution exactly matches the
positions of the pixels with a lower resolution. -> Requirements:
GroaserResolution modulo FinerResolution = 0
AND
GroaserResolutionStartPoint + FinerResolution*X = FinerResolutionStartPoint
AND
X must be an integer.

------------- Notes------------------------------------------------------------
On every exit, the program saves the current scan in the file
  lastExitDimp.3draw. The used directory depends on the current one.
For storing the previously used directory in safe and open dialogues, a file
 ".3dscannercontrolcfg" is created in the home directory.
If a serial port over a bluetooth connection is made, the serial lib does not
  show up the devicename. A symlink from the bluetooth connection device to an
  usb device name (eg ttyUSB42) helps here. (However this requires root
  privileges).   
