Capture2Text Readme
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
What is Capture2Text?
--------------------------------------------------------------------------------

Capture2Text enables users to do the following:

  * Optical Character Recognition (OCR)

    Allows the user to quickly snapshot a small portion of the screen, OCR it
    and (by default) save the result to the clipboard.

  * Speech Recognition

    Using speech recognition the user can speak into their microphone and
    Capture2Text will convert the speech to text. If the speech recognition
    technology is not 100% sure, Capture2Text will present the user with a
    list of the most likely transcriptions. The selected result will (by default)
    be copied to the clipboard.

--------------------------------------------------------------------------------
How to Launch Capture2Text (no installation required):
--------------------------------------------------------------------------------

1) Unzip the contents of the zip file. Make sure that there are no Asain or
   other non-ASCII characters in the path where you unzipped it. Also, if you
   are on Windows 7, don't unzip it to the Program Files directory (this will
   avoid issues related to write privileges).

2) Double-click on Capture2Text.exe. You should see the Capture2Text icon on the
   bottom-right of your screen (though it might be hidden).

--------------------------------------------------------------------------------
OCR Language Support:
--------------------------------------------------------------------------------

Capture2Text can OCR the following languages:

  Bulgarian     Hungarian       Russian
  Catalan       Indonesian      Serbian
  Chinese       Italian         Slovakian
  Czech         Japanese        Slovenian
  Danish        Korean          Spanish
  Dutch         Latvian         Swedish
  English       Lithuanian      Tagalog
  Finnish       Norwegian       Turkish
  French        Polish          Ukrainian
  German        Portuguese      Vietnamese
  Greek         Romanian

  Note: By default only Chinese, English, French, German, Japanese, and Spanish are
        installed.

To acquire other languages:

  1) Download the appropriate OCR language dictionaries
     from http://code.google.com/p/tesseract-ocr/downloads/list
  2) Unzip the OCR language dictionary into Capture2Text\Utils\tesseract\tessdata
  3) Restart Capture2Text

--------------------------------------------------------------------------------
OCR Usage:
--------------------------------------------------------------------------------

Press the OCR capture key (default: Windows Key + Q) to start the capture. Now,
using your mouse, resize the capture box over the area of the screen that you want
to OCR. A preview of the captured OCR'd text will appear in the top-left corner of
the screen. Press the capture key again or the left mouse button to complete the
capture. The captured screen area will be OCR'd and the textual result will be
stored in the clipboard by default.

To cancel an OCR capture, press Esc.

To move the capture box, hold down the right mouse button and drag the mouse.

To nudge the capture box, use the arrow keys.

To toggle the active capture box corner, press the space bar.

To change the OCR language, right-click the Capture2Text tray icon, select the
OCR Language option and then select the desired language.

To quickly switch between 3 languages, use the OCR language quick access keys:
Windows Key + 1, Windows Key + 2, and Windows Key + 3.

When the Tesseract versions of Chinese or Japanese is selected, you should
specify the text direction (vertical or horizontal) using the text
direction key: Windows Key + W. The text direction will not have any effect
on the NHocr Chinese and Japanese dictionaries.

Using the Preferences dialog, you can change the following OCR settings:
  - OCR Hotkeys.
  - Current OCR Language.
  - The 3 Quick-Access OCR Languages.
  - Capture Box color and opacity.
  - Enable/Disable the preview box and change its colors, font and opacity.
  - Change the text direction (used for Chinese and Japanese).

--------------------------------------------------------------------------------
Speech Recognition Language Support:
--------------------------------------------------------------------------------

Capture2Text can perform speech recognition for the following languages:

  Afrikaans     French          Polish
  Chinese       German          Portuguese
  Czech         Italian         Russian
  Dutch         Japanese        Spanish
  English       Korean          Turkish

--------------------------------------------------------------------------------
Speech Recognition Usage:
--------------------------------------------------------------------------------

Press the speech recognition capture key (default: Windows Key + A) to start the
capture. You will see a box that says "Recording..." in the top-left corner of your
screen. Speak a word or phrase or sentence into your microphone. Capture2Text will
automatically recognize when you are done speaking and will display a box that
says "Analyzing...". The speech recognition will take a couple of seconds. When
the speech recognition is complete you will see a list of possible transcriptions
to choose from. When you choose a transcription, it will be stored in the clipboard
by default.

When the results windows is displayed, you can press Enter to select the first
transcription or use the number keys (1-9) to select the corresponding transcription.

To cancel a speech recognition capture, press Esc.

To change the speech recognition language, right-click the Capture2Text tray icon,
select the Speech Recognition Language option and then select the desired language.

To quickly toggle between 2 languages, use the speech recognition language hotkey:
Windows Key + 4

Using the Preferences dialog, you can change the following speech recognition settings:
  - Speech recognition Hotkeys.
  - Current speech recognition Language.
  - The 2 speech recognition languages to toggle between.
  - The properties of the Results window (font, color, number of results).
  - How much silence to wait for before recording stops.

--------------------------------------------------------------------------------
Output Options:
--------------------------------------------------------------------------------

By default, the OCR'd or speech recognized text will be placed in the clipboard.

You also have 3 more ways to output the text.

To send the text to a pop-up window you can right-click the Capture2Text tray
icon and select Show Popup Window.

To send the text to whichever textbox currently contains the blinking
cursor/I-beam, right-click the Capture2Text tray icon and select Send to Cursor.

Advanced:
To send the text directly to a window/control (for example, Notepad++), first
fill in the Send to Control settings in the Preferences dialog. Once this is done
you may enable/disable the option by right-clicking the Capture2Text tray icon and
selecting Send to Control.

Using the Preferences dialog, you can change the following output settings:
  - Text to prepend/append to the captured text.
  - Enable/Disable outputting to the clipboard.
  - Enable/Disable outputting to a popup window.
  - Popup window properties (default width and height).
  - Enable/Disable sending the output text to the cursor.
  - Enable/Disable outputting to a control.
  - Additional command to send to the output control.

--------------------------------------------------------------------------------
Configuration:
--------------------------------------------------------------------------------

Right-click the Capture2Text tray icon in the bottom-right of your screen and
then select the "Preferences..." option to bring up the Preferences dialog.

--------------------------------------------------------------------------------
Substitions:
--------------------------------------------------------------------------------

Sometimes Capture2Text consistantly makes the same OCR mistakes such as
recognizing an "M" as "I\/|".

By editing the subtitutions.txt file in the Capture2Text directory, you may
tell Capture2Text to substitute one text string for another text string.

Just find the appropriate language section and add one substitution
per line in this format:
  from_text = to_text

Example (adding 2 substitutions to the English section):
  English:
    I\/| = M
    >< = X

To create a substitution regardless of language, add the substitution to
the "All:" section.

Special tokens and escape characters:
  %A_Space% = Single space character ( )
  %A_Tab%   = Single tab character (	)
  `,        = Comma (,)
  `%        = Percent sign (%)
  ``        = Backtick (`)
  `n        = Single linefeed character (\n)
  `r        = Single carriage return character (\r)

You may disable a substitution by adding a "#" in front.

--------------------------------------------------------------------------------
Command Line Options:
--------------------------------------------------------------------------------

You may OCR the screen via command line by calling Capture2Text in this format:

Capture2Text.exe x1 y1 x2 y2 [output_file]

  Required arguments:
    x1 - X1-Coordinate of the screen
    y1 - Y1-Coordinate of the screen
    x2 - X2-Coordinate of the screen
    y2 - Y2-Coordinate of the screen

  Optional arguments:
    output_file - The OCR'd text will be written to this file if specified.

Capture2Text will read settings.ini to determine settings such as OCR language
and output options (clipboard, popup, etc.).

Examples:
  Capture2Text.exe 10 152 47 321 output.txt
  Capture2Text.exe 10 152 47 321

--------------------------------------------------------------------------------
Contact:
--------------------------------------------------------------------------------

Christopher Brochtrup
cb4960@gmail.com

--------------------------------------------------------------------------------
Acknowledgements/Tools used:
--------------------------------------------------------------------------------

NHocr         - OCR utility for Japanese/Chinese
Tesseract     - OCR utility for other languages (also includes Japanese and Chinese)
DevIL         - Image library
SoX           - Audio utility used here to capturing voice to FLAC file
Google        - Voice recogition service
wget          - Utility used here to send voice recognition request to Google
ScreenCapture - AutoHotKey screen capture script

--------------------------------------------------------------------------------
Notes About the OCR Languages:
--------------------------------------------------------------------------------

- "Japanese (NHocr)"
  - Uses the NHocr OCR tool.
  - ACSII characters are supported, but not reliable.
  - Kana has a higher than expected miss-rate.
  - Vertical text has a higher miss-rate than horizontal text.
  - Grain, noise, blurry characters and surrounding lines or ruby characters
    will confuse the OCR tool.
  - Miss-rate increases with smaller characters.
  - Some kanji are harder to OCR than other kanji. Especially if the
    kanji has whitespace in between it's primitive elements.
  - Handwritten text is not supported.

- "Japanese (Tesseract)"
  - Uses the Tesseract OCR tool.
  - The notes from the "Japanese" section apply here except that ASCII
    characters and kana have a lower miss-rate and kanji has a higher miss-rate.
  - You must select the text direction: vertical or horizontal. The default
    key for this is Windows Key + W.

- "Chinese (NHocr)"
  - This uses the NHocr OCR tool.
  - Most of the notes from "Japanese" section also apply here

- "Chinese - Simplified (Tesseract)" and "Chinese - Traditional (Tesseract)"
  - These use the Tesseract OCR tool.
  - Most of the notes from "Japanese (Tesseract)" section also apply here

- All other languages
  - These use the Tesseract OCR tool.
  - OCR is very good as long as the characters aren't too small (8-pt and below)


--------------------------------------------------------------------------------
Tips to Increase OCR Accuracy:
--------------------------------------------------------------------------------

- Make sure that what you are viewing is >= its original size. That is,
  make sure that your image viewer isn't zoomed out too much.


--------------------------------------------------------------------------------
Version History:
--------------------------------------------------------------------------------

[Version 2.1 (10-7-2012)]
- Added the substitutions feature.
- Added command line options

[Version 2.0 (3-10-2012)]
- Added the Preferences dialog. No more editing settings.ini by hand.
- The popup window is now multi-lined.
- Added option to preserve newline characters.
- Limited preview to 150 characters. A trailing "..." will appear if necassary.
- Added Speech Recognition Language option to right-click menu.
- Cleaned up the right-click menu.
- On the first run, inform user how to access the Preferences dialog.

[Version 1.10a (2-18-2012)]
- Removed GdiPlus.dll from distribution.

[Version 1.10 (12-31-2011)]
- Added preview box (and corresponding settings)

[Version 1.09 (11-10-2011)]
- Fixed speech recording stopping in the middle of a sentence.
- Fixed VoiceMaxResults not working correctly. Also increased to 9 as default.

[Version 1.08 (11-06-2011)]
- Upgraded Tesseract to version 3.01 (it has better vertical text support and
  doesn't ignore small captures as much)
- When using Tesseract Chinese or Japanese, you can now select the text
  direction (vertical or horizontal). To support this, added
  TextDirectionToggleKey and textDirection to settings.ini.
- Changed default for ScaleFactor from 4.0 to 3.0 in settings.ini.
- Changed menu text for Chinese and Japanese to reflect the OCR engine being used.

[Version 1.07 (11-05-2011)]
- Added voice recognition support via unofficial Google voice recognition service
- Added the "Send To Cursor" option to menu. The setting.ini file includes:
    SendToCursor
    SendToCursorApplyBeforeAndAfterCommands
- Renamed OCRAdjustment to OCRSpecific in settings.ini
- Moved the CaptureBox section in settings.ini to the OCRSpecific section
- Added VoiceSpecific to settings.ini. Section includes:
    VoiceMaxResults
    VoiceResultsWindowWidth
    VoiceResultsWindowFont
    VoiceResultsWindowFontSize
    VoiceSilenceBeforeStop
    VoiceLanguage
- Added StartVoiceCapture to Hotkey section in settings.ini
- Added VoiceLanguageToggleKey to Hotkey section in settings.ini
- Removed scaleFilter from settings.ini
- Removed the scaleFactor option from the menu (it's still in settings.ini)

[Version 1.06 (12-12-2010)]
- Added language quick access keys.
- For Chinese and Japanese delete newlines. For other languages replace
  newlines with spaces.

[Version 1.05 (12-04-2010)]
- Fixed issue where the checkboxes in the language menu wouldn't disappear.

[Version 1.04 (12-04-2010)]
- Added ability to move the capture box by right-clicking
- Added languages supported by the Tesseract OCR tool
- Created a right-click menu that allow the user to select language, output type,
  capture box settings, and scale factor
- Removed unnecessary items from settings.ini

[Version 1.03 (11-27-2010)]
- Added ability to change dictionary when the Dictionary setting in settings.ini
- Added Chinese dictionary

[Version 1.02 (11-27-2010)]
- Changed CaptureKey to StartAndEndCaptureKey in settings.ini
- Added EndOnlyCaptureKey to settings.ini
- Added ToggleActiveCaptureCornerKey to setting.ini

[Version 1.01 (11-27-2010)]
- Added ReplaceControlText to settings.ini
- Added ability to use linefeeds, carriage returns, and tabs in PrependText and AppendText
- Added an "About" item to the tray menu.
- Removed the capture box showing up in the taskbar
- Removed the PassThruKey settings in settings.ini. They are no longer needed.
- Changed the tray tooltip text
- Cleaned up code and put the ScreenCapture routines in a seperate file

[Version 1.00 (11-26-2010)]
- Initial version

--------------------------------------------------------------------------------

