Filelist for program 'spotfinder':
  spotfinder.cc
  libdistl.h
  libdistl.cc
  makefile

Compiling:
  In 'makefile', make changes to the IMAGE_LIB_DIR and IMAGE_INCLD_DIR lines to your own local settings.
  You may also need to change the compiler, the CC line, to something available on your system.

  Then run 'make'. An executable 'spotfinder' shows up. 
  
Run './spotfinder' with no arguments for help message.

Library 'libdistl' consists of two files: libdistl.h and libdistl.cc.

Program 'spotfinder' illustrates the use of library 'libdistl', and in its own right
is a useful utility.


=============
Revision history 
=============

--------
02/27/04

Added Python script distlsum for spreadsheet filling.

--------
01/27/04

Spot shape measure is in place. 
It uses the coefficient of variation (std/mean) of distances
between spot center and all border pixels.
Spot center of center of gravity weighted by pixel value.

Added two 'badness of curve' for both image resolution estimates.
They measure the violation to the monotonic trend in the curve.

There're several things to look at in the log file for evaluating image quality:
1) number of spots
2) number of spots vs number of overloaded, multi-max, with-close-neighbor spots.
3) number of icering and, if existent, strength of icering.
4) spot shape median, usually (0, 1), the bigger the better (more roundish).
5) badness of the curve in image resolution estimate Method 1, [0, 1], the smaller the better.
6) badness of the curve in image resolution estimate Method 2, [0, 1], the smaller the better.
7) closeness of the two image resolution estimates, from Method 1 and 2, respectively.
   If both are high (small value), good; both are low (large value), bad; very different, fishy.


12/17/03

Modified spot shape measure.


--------
12/16/03

Modified ice-ring strength measure.


-------
11/21/03

Modified the spotfinder output format.
Now numbers are shifted to the left, text explanation is shifted to the right.
This output format is easier to read and parse.

Added a safeguard for false multimaxima spots:
if all maxima are close together, it is viewed as a single-maxima spot.


Modified the output image markup for maxima:
  it used to walk through the maxima list and mark the pixels;
  now it walks through the spot list and descend into the spot's maxima list.
This is intended to work around this problem:
  if multiple maxima on a spot are merged in the above step, they are still in the global maxima list.
There seems to be a bug:
  some spots have two neighboring maxima, which should have been merged but were not;
  however, the spot is not labeled as a multi-maxima spot, 
  because otherwise the spot would have white border in 'img' image.


-------
10/03/03

Modified the help message.


-------
8/26/03

1.
Improved the color scheme for output images.

2.
Fixed a bug in libdistl::resol_to_r2().


-------
8/25/03

Added JPEG output.
SMV *.img output is discouraged.


-------
8/22/03

Added the option to output image of localized signal height.


-------
8/21/03

libdistl is mofified to reflect the philosophy that
the library keeps its finderings as much as possible, 
the user decides what to take and what to discard.

1.
Point class has two new members:
  int value;
  double intensity;
for holding pixel value and pixel signal height, respectively.

2.
Spot class has a new member
  list<point> maximas;
nmaxima is removed. Use maximas.size() instead.

3.
Spot 'center' and related quantities are removed.
Just use 'peak' and corresponding quantities.
Remember 'peak' is a 'point' object.

4.
Spot filter of size upper bound and peak intensity upper bound is removed.
This filter can be applied, if one chooses to, while writing out border image file
or spot list file in program 'spotfinder'.

5.
Spots with a overloaded peak are kept.
Compare 'spot.peak.value' with 'overloadvalue' to filter out overloaded spots wherever needed.

6.
Spot has a new member
  int ncloseneighbors;
Use 'spot.ncloseneighbors < 1' to ignore certain spots if needed.

7.
Restriction on min distance from spot to beam center (2 * theta < 2.9)
is removed. Impose this manually whenever needed.

8.
In summary, after spot searching, the following spots are discarded:
  a) size below threshold
  b) touch on ice-ring
Every spot that passes the above filters is kept but may be ignored
for a particular purpose later on.
Mainly there're three places to further filter spots:

At image resolution estimation, ignore spots that
  a) 2 * theta < 2.9, or
  b) peak.value >= overloadvalue, or
  c) maximas.size() > 1, or
  d) ncloseneighbors > 0

While writing border image file in spotfinder.cc,
all spots are shown, except one later decides to put in some filtering.

While writing spot list in spotfinder.cc,
only a fractoin of the spots are choosen so that MOSFML can handle it.

9.
Other minor changes.

10.
Overall image assessment and some summary output in spotfinder.cc are tedious to update.
Don't take them too serious for now.



-------
8/14/03

1. 
Changed library name from 'diffspot' to 'distl'. 
Changed file names, libdiffspot.* -> libdistl.*.
Made necessary changes inside files accordingly.

2. 
Moved subroutine 'summarize' from the library to demonstration program 'spotfinder'.
Because there're many possible ways to summarize the findings; it's not the library's job.

3.
Modified command-line options to 'spotfinder'.
Removed several options.
Added options for specifying beam center location.

4.
Added option to output one single spot list file for multiple images.
This is trigered by specifying a name for the file at command line.

5.
In 'screen_spots', added
a) remove spots if 2 * theta < 2.9 degrees
b) if two spots are close together, both are discarded.

6.
Added 'method 2' for image resolution estimation.
A plot similar to that for 'method 1' is output in the log file.

7.
Added various class member data to help control some old and new features.
Most class members remain public.

8.
Removed 'directional anomaly'.

9.
Modified ice-ring detecting to ensure it works on large images.
Extra large image will still cause problem; in that case, further work is needed.


