BEAMFINDER

Section: User Commands (1)
Updated: July 2012
Index Return to Main Contents

NAME

beamfinder - locate the brightest beams within an image

SYNOPSIS

Find and print the co-ordinates of the brightest beams within an image. Used to align the optics with the Hawaii chip.
Co-ordinates are wrt the Hawaii chip, NOT X11-standard.

DESCRIPTION

Beamfinder: search a TIFF file to find the positions and strengths of the light-beams falling on the sensor.
This is used to align (and check) the beam positions on the sensor, and to select which pixels to read out.
The algorithm stops after finding at most 32 beams, and 'grows' each beam to 225 pixels at most.

   USAGE:     man/../src/beamfinder   [OPTS]  infile.tiff
   OPTIONS:   -h                 show help
              -p                 plot the file: display a normalised image, with the detected beam positions in red
              -t   threshold     adjust luminosity-threshold for pixel/peak_pixel detection. (default: 0.03).
                                 higher values (0.2 - 1.0) improve noise-immunity, but discard faint pixels as noise.

   OUTPUT:    This is designed for ease of parsing. Stdout/stderr are separated. Headers begin with '#'.
              Stars are listed in descending order [of brightest pixel], up to at most 32. The columns are:
              * Hawaii_Coordinates (Quad,X,Y):  the (integer) positions of the centroidal pixel in each beam.
              * Beam Pixels:                    number of pixels bright enough to be considered "in" the beam.
              * Focus & Alignment:              fraction of the beam that lies in the centroidal pixel. Ideally 1.0
              * Valid Beam?:                    heuristic: is this detected beam (plausibly) good? yes/no.
              * Beam Total Luminosity:          sum of the pixel-values in the beam, scaled (/256) to the .cam units
              * Average Luminosity:             calculated as: total luminosity / pixel count.
              * Centroid Position (X,Y):        positions of the beam centroid, floats, in X11-coordinate system.

Note 1: A well-aligned, and sharply focused system should have a Focus & Alignment score of nearly 1.0. This means
that all of the beam illumination falls within the size of a single-pixel, AND the beam position is well-aligned
with the pixel-grid (rather than falling across part of each of 2 or 4 pixels). The true beam-center is given
(in X11-coordinates) by the Centroid position; this is rounded to the nearest integer to get the best pixel to
select for Hawaii-CDSM-readout. See 'cam2tiff -h' for a diagram.

Note 2: The algorithm is as follows:
  * Find the brightest pixel in the image. Let B = that brightness value.
  * [Check whether it should be merged into an existing, adjacent star.]
  * Iteratively "grow" a star around it:
  *    - for each pixel adjacent to the star, if (brightness > B *  0.03), add it to the star.
  *    - stop: when there are no adjacent pixels of sufficient brightness, or after 225 pixels (considered a "whiteout").
  * Remove this set of pixels from the pool.
  * Repeat, till there are no non-zero pixels left, or until at most 32 candidate beams have been found.
  * For each "star", calculate the intensity-weighted position (centroid), then round and convert to Hawaii-coords.
  * The "Magic Numbers" are #defined in the source: LUM_THRESHOLD=0.03, MAX_PIXELS_PERSTAR=225, MAX_STARS=32.
  * There is a tradeoff in the value of LUM_THRESHOLD between 'collecting' all the star-material vs noise-immunity.

Note 3: A side-benefit of the chosen grow-star algorithm is that it makes artefacts look obviously and visibly bad.

AUTHOR

The author of beamfinder and this manual page is Richard Neill, <cam2tiff#AT(spamblock)#richardneill.org>
Copyright July 2012; this is Free Software (GPL v3+), see the source for copying conditions.