TROUBLESHOOTING

What to do when things go wrong
===============================

In general, you can try to adjust the magic values in defs.py to improve
recognition and work around errors that you get. If you need to change
something, pĺease drop us a line.

Matrix could not be recognized
------------------------------

This means SDAPS could not find all four edge markers.

Please have a look at the following:
 * Check that the scan is OK.
   * Does it have black/white lines? This can happen in the scanner is not
     clean.
   * Check that the resolution is set to 300dpi
   * Check there is no black line at one side
 * Try modifying the magic recognition parameters in defs.py
   image_line_width and image_line_coverage. However, it is unlikely
   that this is neccessary.

Recognition quality is bad
--------------------------

If you want to analyse the heuristics you can run the tool "boxgallery".
  $ sdaps project_dir boxgallery
This creates a PDF for every heuristic, showing the returned value. Boxes
with a bold label are considered checked by SDAPS.
You can adjust the criteria by changing the checkbox_metrics dictionary in
defs.py. Each of the entries is a list that maps the heuristic to checkbox
and quality measures.

Should you find better values, please share them!

NOTE: If you want to remove the errors arising from the possibility to
correct mistakes, you can modify the lists to never consider a checkbox
corrected.

Text boxes are recognized even though they are empty
----------------------------------------------------

This can happen because of dirt on the page or because the scanner is not
very accurate and the outline is detected as writing.

If dirt is detected, try to adjust the textbox_scan_* values in defs.py.

If the outline is detected than probably something worst is going on. You
can adjust the textbox_*_padding values, or adjusting the image_line_*
values might also help (as these are used to find the corners of the
textbox).

If the above does not help
==========================

Mail the authors :-)
It may be neccessary to have all the data to help. So if you can try to
always provide examples where things fail.

NOTE: It may be that this document is not always up to date.