BUILDING

You'll need to have a C++ compiler, make, gtkmm and gstreamermm (along with the
"base" and "good" gstreamer plugins) to be able to run this program.

On Ubuntu (verified on Ubuntu 20.04) this means installing the following
packages:

    build-essential libgtkmm-3.0-dev libgstreamermm-1.0-dev
    libgstreamer-plugins-base1.0-dev libgstreamer-plugins-good1.0-dev

On ArchLinux this means installing the following packages:

    base-devel gtkmm gstreamermm gst-plugins-base gst-plugins-good

To compile just download this repository and run `make` inside this directory.
This should build the program and produce an executable called `watermeter`

USAGE

First position your camera. Try to position it so that the image is square and
try to avoid any bright reflections around the needle.

Then start the program:

    ./watermeter

Pressing the enter key will refresh the image you see. Press enter at least once
to give yourself an accurate image of what the webcam is seeing.

Pressing r will bring up a dialog to enter the current reading of the dial.
Enter the current whole number reading of the dial up to any precision that you
want. This value will be updated as the needle moves around the dial.

Click and drag with the left mouse button to draw a circle. This circle
represents where the program will search for the needle. Draw a circle around
the dial, starting from the center, stopping where the needle ends. This should
also place a green indicator line showing you where the program thinks the
needle currently is.

When satisfied with the programs detection of the needles location press the
spacebar to start collecting data. The program will begin writing the estimated
reading of the dial to DATA_FILE every OUTPUT_RATE
milliseconds (see CONFIGURATION).

CONTROLS

There is a limited set of controls when using the program:

    Click + Drag (on webcam image): Draw the circle to search for the needle.
    r: Set the current reading of the dial (See GUIDE).
    j: Increase the outer radius of the needle detection zone.
    CTRL-j: Increase the inner radius of the needle detection zone.
    k: Decrease the outer radius of the needle detection zone.
    CTRL-k: Decrease the inner radius of the needle detection zone.
    Space: Begin data collection.

COMMAND LINE OPTIONS

When running the program you can optionally specify these options:

    -s  Save the current frame every full rotation of the dial.
    -a  Save every frame.
    -t  Run the TED data collection program every hour. (Make sure to set the
        TED_PATH configuration option below)
    -d  Save debug images every frame.
    -h  Save a histogram of needle detection data every frame.

CONFIGURATION

There are some options you can configure within `config.h`:

    TED_PATH - The path to the TED data collection script. (Default:
        "~/ted/hourly/datacollection.py")
    NUM_ANGLES - An integer specifying the number of angles to check around the
        circle you draw. (Default: 512)
    OUTPUT_RATE - The number of milliseconds between data points. (Default: 5000)
    DATA_FILE - The file to write the estimated readings to. (Default:
    "meter.csv")
    HIST_FILE - The file to write the histogram data to. (Default: "hist.csv")
    IMAGES_FOLDER - the folder in which to save all images
    DEBUG_FOLDER - The folder in which to save all debug images