SegmentDisplayOCR AviSynth Filter

1. License
----------
Copyright (c) 2014 Lcferrum

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

2. About
--------
SegmentDisplayOCR is a seven-segment display recognition filter for AviSynth.
It has built in logging functionality (it will log frame recognition results)
and also can be used in AviSynth conditional filters. The main purpose of this
filter is to process readings of various digital instruments (e.g. digital
multimeters) captured on video. So if your favourite instrument lacks interface
for connecting it to PC you can capture it's readings on cam and convert them
to computer readable format with SegmentDisplayOCR filter.

3. Where to get
---------------
You can compile SegmentDisplayOCR by yourself (refer to COMPILE.TXT that comes
with the sources) or download binary distribution from Sourceforge:

	https://sourceforge.net/projects/segmentdisplayocr/files/SegmentDisplayOCR/
	
Main project homepage is at GitHub:

	https://github.com/lcferrum/segment-display-ocr

4. Installation
---------------
Install AviSynth (SegmentDisplayOCR requires version 2.6.0 and higher). Refer
to official AviSynth wiki (http://avisynth.nl/index.php/Main_Page) for AviSynth
installation instructions. Don't forget to install necessary codecs (especially
YUV codec).

Copy SegmentDisplayOCR.dll file to AviSynth plugins directory - it's in your
AviSynth installation directory. That's all - now SegmentDisplayOCR will be
automatically loaded by AviSynth every time AVS script is run.

If you are new to AviSynth it would be a good idea to read some tutorials on
official wiki.
	
4. Usage
--------
SegmentDisplayOCR(clip [, string log_file="", bool log_append=true, 
    int interval=1, string time_format="seconds", bool debug=true,
    bool localized_output=true, bool inverted=false, string threshold="50"]) 
RtmSegmentDisplayOCR(clip [, bool inverted=false, string threshold="50"])

SegmentDisplayOCR will try to recognize each frame of input video clip. It
expects to find a clear picture of single seven-segment display in each frame.
If your video is blurry, noisy, distorted and overall of low quality it's
highly recommended to enhance video quality by applying appropriate AviSynth 
filters before SegmentDisplayOCR filter. If you have more than one 
seven-segment display on the video, it's recommended to crop video so it would
contain only single display.

You can use debug feature of SegmentDisplayOCR (turned on by default) to tune
up SegmentDisplayOCR and preceding filters parameters. While in debug mode,
SegmentDisplayOCR will add various debug info to output video that will help
determine if input video is recognized properly. If not in debug mode
SegmentDisplayOCR will output original unchanged video.

SegmentDisplayOCR will try to recognize every N-th frame starting from the 
first one. N is determined by interval variable (in seconds). For example for
PAL video (25 FPS) one second interval means that recognition will occur every
25-th frame. Recognition will only occur during forward playback of the video.
Rewinded frames won't be recognized.

Recognition results can be logged by SegmentDisplayOCR. By default logging is
turned off. Log file format is a CSV consisting of two-field records: time and
recognition result. It's perfectly safe to use single log file for several
instances of SegmentDisplayOCR filter in single AVS script - log won't get
corrupted and will contain results from every instance.

RtmSegmentDisplayOCR is a runtime function based on SegmentDisplayOCR filter.
It can be used with e.g. ConditionalFilter or WriteFile. Returns recognized
digits (as string) for current_frame of input clip.

SegmentDisplayOCR and RtmSegmentDisplayOCR can recognize all digits (0-9),
hexademical characters (A-F), decimal point, colon and minus sign. 
SegmentDisplayOCR and RtmSegmentDisplayOCR expect input video to be
non-interlaced and in one of the following color spaces: YV12, YV16, YV24 or
YV411.

Parameters:

log_file [optional, default: empty string]
    Path to log file. If empty - no logging will occur. If file doesn't exist
    it will be created. Relative path is relative to AVS script location.

log_append [optional, default: true]
    If true - log file will be appended. If false - log file will be truncated.

interval [optional, default: 1]
    Recognition interval in seconds. It means that every N seconds a frame will
    be recognized starting with frame 0. If interval is 0 - every frame will be
    recognized. Interval can't be negative number.

time_format [optional, default: "seconds"]
    String which determines time format for log file. This parameter can be one
    of the following values:
        "seconds"   - seconds elapsed from the video start
        "mseconds"  - millisecond elapsed from the video start
        "timestamp" - time elapsed from the video start in the form of
                      timestamp "HH:MM:SS.mmm"
        "frame"     - number of current frame
        "realtime"  - current system time in the form of timestamp which is 
                      determined by localized_output parameter
    All time formats, except the last one, are calculated based on current
    frame number and counted from the start of the video.

debug [optional, default: true]
    Add debug information to output video. If debug is false - output video is
    complete copy of input. Debug information includes: timestamp, frame
    number, last recognized value and edges of recognized characters. Also,
    input video becomes monochrome in debug mode. Text information is colored
    according to current recognition state: green - current frame is processed,
    orange - current frame is skipped, red - current frame was
    already skipped or processed.

localized_output [optional, default: true]
    If true - gets decimal point, minus sign, CSV separator and realtime
    timestamp format from system locale. If false - uses locale indifferent
    values: "." for decimal point, "-" for minus sign, "," for CSV separator,
    "YYYY-MM-DD HH:MM:SS" for realtime timestamp. RtmSegmentDisplayOCR always
    uses locale indifferent values.

inverted [optional, default: false]
    If true - assumes that seven-segment display on the video has white digits
    on black background (instead of black digits on white background).

threshold [optional, default: "50"]
    Sets the threshold (in percents, can be real number) used to distinguish
    dark pixels from white pixels. By default threshold is adapted to actual
    luminance range of each frame. You can change this behaviour by adding
    modificator to the number (that's why threshold is a string):
        "a" - absolute threshold (won't be adapted to a frame)
        "i" - iterative threshold (threshold adapted to a frame using
              one-dimensional k-means clustering), best suited for blurry
              images
    For example, "39.5i" means 39.5% iterative threshold.

5. Use cases
------------

5.1 Getting started
-------------------
Start with this simple script:

	AviSource("input.avi")
	SegmentDisplayOCR()

Instead of AviSource you can use other apporpriate media input filter - check
out "Internal filters" article on AviSynth wiki. Now open this script in your
favorite video player and watch SegmentDisplayOCR debug output. This will help
you determine if video is recognized properly by SegmentDisplayOCR, so you can
tweak some parameters or add other filters before SegmentDisplayOCR to enhance
input video quality.

5.2 Processing whole video file
-------------------------------
After your video recognition script is set up and you are sure that recognition
process is working ok for your input video file, it's time to get log file with
recognition results. Basically, you need to do just two things to get the log:
turn on the logging for SegmentDisplayOCR filter and make AviSynth process
whole video.

First step is trivial (refer to Usage section). In the second step you should
in one way or another request all of the frames from your video so AviSynth
would pass each of them through SegmentDisplayOCR. This can be done by simply
playing AVS script in (almost) any video player or processing AVS script with
some kind of video editor or converter. The most suitable software I have found
for this purpose is avs2avi converter. This program is able to do no actual
converting and just cycle through all of the frames producing no output. Run it
like this with your script:

	avs2avi input.avs -c null -o n

5.3 Working with video camera
-----------------------------
You can actually recognize video directly from your camera in realtime using
AviSynth magick. To do this connect your camera to AviSynth using GRF file. GRF
file consists of DirectShow filter graph which can also include various video
sources such as your camera connected to PC.

GRF files are created in GraphEdit (part of Microsoft DirectShow SDK) and it's
various clones (e.g. GraphStudio). Open GraphEdit (or something similar), click
"Insert Filters" and under "WDM Streaming Capture Devices" category you should
find your camera - add it to the project. Now save it as GRF file.

Open resulting GRF file like this:

	DirectShowSource("camera.grf", audio=false, framecount=2147483647)
	SegmentDisplayOCR()
	
You should explicitly set video length via framecount parameter if using live
input. Framecount in this example is maximum possible framecount that AviSynth
supports. Though there is no guarantee that your player/editor/converter will
work with input video of such length.