add documentation

README.md

@@ -1,2 +1,88 @@
-# SubGen
-Semi-automatic extraction of hardcode subtitles 
+# SubGen & SubOCR
+This project aims to semi-automatically extract hardcode subtitles. It contains two submodules, `SubGen` and [`SubOCR`](/SubOCR). To do the work, in addition, you need [`VideoSubFinder`](https://sourceforge.net/projects/videosubfinder/)
+
+## Synopsis
+Sometimes, you have a low-quality video file with hardcode subtitles and an HD video file of the same movie but without subtitles. Or the hardcode subtitles are in a different language and you want to translate them. Anyways, the only options are: a) creating a new subtitle file from scratch by typing the lines on your own and b) extract the subtitles from the video file automatically. Of course, you will choose wisely.
+
+The overall workflow is as follows:
+* Use `VideoSubFinder` to open the video file with hardcode subtitles and save pictures containing subtitles with the timings
+  * This process is almost automatic. What you need to do is simply wait for about 10 to 30 minutes for a 2-hour-long movie with 800 to 1500 subtitles
+* Use `SubOCR` to scan the images and convert them into plain texts
+  * This process is almost automatic. What you need to do is simply wait about 10 minutes for 1200 subtitle images
+* Use `SubGen` to visually proofread the subtitles generated by `SubOCR`
+  * This is the only manual process. Usually, the OCR results are quite accurate, and if you are familiar with this program, you will only spend about 15 minutes for 1200 subtitles
+
+This README will introduce mainly the usage of `SubGen`. Some important notes for the other two programs will also be briefly covered. For more details about `SubOCR`, please refer to its [README](/SubOCR/README.md)
+
+
+## System requirements
+This project mainly targets Windows users. All three programs can be run on Windows XP, 7, and 10, either 32-bit or 64-bit OS.
+* `VideoSubFinder` is C++-based. Therefore, Microsoft Visual C++ Redistributable for Visual Studio 2015-2019 is needed ([Download here](https://aka.ms/vs/16/release/vc_redist.x86.exe)). However, **it is very likeyly that you have already installed it** because a lot of other softwares depend on it
+* `SubOCR` is Ruby-based and therefore cross-platform. On Windows, there is **NO** additional requirement (**NO NEED** to install Ruby, unless you, as a developer, want to use your own Ruby environment). However, you **MUST have access to the Internet** becauese the program will send requests to BaiduOCR web-based API
+* `SubGen` is .NET-based. If your OS is Win7, there is nothing you need to do. If you are running on Win10, you might need to **enable the .NET Framework 3.5**. It is very simple, though, and you can just double-click the executable and follow the system prompts
+
+## Usage
+Download [the latest release](https://github.com/Z-H-Sun/jpeg/releases/latest) for `SubOCR` and `SubGen`, and extract the zip archive, preferably in the same folder as `VideoSubFinder`
+
+### `VideoSubFinder` and `SubOCR`
+* First of all, **remember to** click "Clear folders" in `VideoSubFinder` to remove any file generated before for other videos
+* Next, set the beginning time, ending time, and the region of the subtitles; then, click "Run Search" and get the images (Fig. 1). Generally speaking, the default searching parameters are good enough
+* **NO NEED to and DO NOT run "Create Cleared Text Images."** The RGBImages will suffice for `SubOCR`, and there will be no risk of data loss (For example, in Fig. 1, the first line will be ignored by the program in the "cleared text images"); in addition, a lot of time will be saved
+* Now you can close `VideoSubFinder`
+
+<p align="center">
+<img width="80%" height="80%" src="/pic/1.png">
+</br>Fig. 1 VideoSubFinder
+</p>
+
+* Before running `SubOCR`, you need to configure the program properly by editing `SubOCR.rb` as instructed [here](/SubOCR/README.md#configurations)
+  * Especially, you **MUST** [apply for an BaiduOCR API_Key](https://console.bce.baidu.com/ai/?fromai=1#/ai/ocr/overview/index) and replace the placeholder at the beginning of `SubOCR.rb` as instructed [here](/SubOCR/README.md#baiduocr-api-application)
+* Generally speaking, the default settings are good enough. You can just double-click `SubOCR.exe` to run and the results will be saved to the `TXTResults` folder
+  * For more details, see [here](/SubOCR/README.md#how-to-operate)
+
+### General workflow for `SubGen`
+* Select the folder of `VideoSubFinder` and set the region of the subtitles in the images (Fig. 2)
+* In the revision window, you can compare the original images with the OCR results and then correct anything wrong (Fig. 3)
+  * This process can be done **in the meantime** while `SubOCR` is running to save time
+* In the review window, make final changes and save the subtitle file (Fig. 4)
+* Now you will return to the first window (Fig. 2), and you can start processing another video by repeating the steps above
+
+<p align="center">
+<img width="80%" height="80%" src="/pic/2.png">
+<br>Fig. 2 SubGen<br><br>
+<img width="80%" height="80%" src="/pic/3.png">
+<br>Fig. 3 The revision window<br><br>
+<img width="80%" height="80%" src="/pic/4.png">
+<br>Fig. 4 The review window
+</p>
+
+### Detailed info for `SubGen`
+* In the first interface (Fig. 2), the program can **automatically detect the subtitle region**. Then, you can do manual adjustion by dragging using the left mouse button (to set the left-top corner) and the right mouse button (to set the right-bottom corner)
+
+  * This needs not to be very accurate. The cropped region will be shown on the left in the revision window
+* Then, press <kbd>Enter</kbd> to proceed to the revision window (Fig. 3)
+
+  * You can hover the mouse at different places to see tips, the timing, and the corresponding filename of the OCR result
+  * There will be an asterisk mark (\*) in the caption of the window if the page has been saved before
+  * The vertical line character (|) in the text **means there was a line break**. The color of the text indicates the status:
+
+    * Black: the original OCR results
+    * Blue: the texts have been altered
+    * Red: The line segmentation is incorrect, and you may want to **transfer some lines from one textbox to another** (The cause and the workaround of this issue has been explained in the [README](/SubOCR/README.md) of `SubOCR`)
+  * The hotkeys:
+
+    * <kbd>Enter</kbd>: Save the current page and move to the next page
+    * <kbd>Esc</kbd>: Close the window and proceed to the review window **without saving**
+    * <kbd>PageUp</kbd>/<kbd>PageUp</kbd>: Move to the previous/next page **without saving**
+      * If you are already at the first page, PgUp will take you to the final one; and vice versa
+    * <kbd>↑</kbd>/<kbd>↓</kbd>: Move to the previous/next textbox
+      * If you are already at the first textbox, Up will take you to the final one; and vice versa
+    * <kbd><kbd>Shift</kbd>+<kbd>↑</kbd></kbd>/<kbd><kbd>Shift</kbd>+<kbd>↓</kbd></kbd>: Select the text from the beginning to the current position, or the other way around
+      * You can use <kbd><kbd>Shift</kbd>+<kbd>↑</kbd></kbd> + <kbd>←</kbd> to move the cursor to the left end; or vice versa
+    * <kbd><kbd>Ctrl</kbd>+<kbd>↑</kbd></kbd>/<kbd><kbd>Ctrl</kbd>+<kbd>↓</kbd></kbd>: Transfer the selected text to the previous/next textbox
+      * You cannot use this function if you are already at the first or the last textbox
+* Then, press <kbd>Esc</kbd> to proceed to the review window (Fig. 4)
+
+  * The cursor will be at the first line of the subtitles. If you scroll up, you can define the styles of the texts, etc.
+  * Press <kbd><kbd>Shift</kbd>+<kbd>Enter</kbd></kbd> or <kbd><kbd>Ctrl</kbd>+<kbd>Enter</kbd></kbd> to close the window and save
+* Done!

SubOCR/README.md

@@ -72,3 +72,17 @@ This program is Ruby-based and therefore cross-platform, and the tests on Window
 <img width="80%" height="80%" src="/SubOCR/pic/3.png">
 </br>Fig. 3 Bug reports
 </p>
+
+## For Windows developers: how to compile the executable
+\* This chapter is for Windows developers only. If you merely want to use the program, **there is no need to read this**
+* The executable for Win32 can be generated by [`ExeRb`](https://osdn.net/projects/exerb/). Note that the newest version that supports ExeRB was **Ruby 1.8.7**
+* The executable serves as a "wrapper script" that runs `SubOCR.rb`, so that you can still modify/add the functionalities by making changes to `SubOCR.rb`, and this "minimal Ruby environment" enables running the script on PCs where Ruby is not installed
+* The wrapper script, [`SubOCR.wrapper.rb`](/SubOCR/wrapper/SubOCR.wrapper.rb), does the following:
+
+  * Changing the code page to 65001 (UTF-8), which is essential since Ruby 1.8.7 does not support converting encodings
+  * Enabling `STDOUT` redirecting
+  * Running `SubOCR.rb` and showing fatal exceptions before exiting
+* You can make changes to the wrapper script and then run `exerb SubOCR.exy` in the `wrapper` folder to generate the corresponding .exe file
+
+  * The .exy file lists the dependencies of `SubOCR.rb`. You can modify the file as instructed by the `README` file of `ExeRb`
+  * The dependencies are stored in the `wrapper/lib` folder, with `libjpeg-8.dll` and `jpeg.so` **included**. However, if you want to use a different version of `libjpeg` or Ruby, you can replace the files accordingly, or you can change the paths written in `SubOCR.exy`