Update the launcher and fix the setup

Author: emedvedev

Diff for: MANIFEST.in

@@ -0,0 +1,2 @@
+include *.md
+include *.txt

Diff for: README.md

@@ -1,176 +1,175 @@
-# Attention-OCR
-Authours: [Qi Guo](http://qiguo.ml) and [Yuntian Deng](https://github.com/da03)
+# Attention-based OCR
 
-Visual Attention based OCR. The model first runs a sliding CNN on the image (images are resized to height 32 while preserving aspect ratio). Then an LSTM is stacked on top of the CNN. Finally, an attention model is used as a decoder for producing the final outputs.
+Visual attention-based OCR model for image recognition with additional tools for creating TFRecords datasets and exporting the trained model with weights as a [SavedModel](https://www.tensorflow.org/api_docs/python/tf/saved_model) or a frozen graph.
 
-![example image 0](http://cs.cmu.edu/~yuntiand/OCR-2.jpg)
+## Acknowledgements
 
-# Prerequsites
-Most of our code is written based on Tensorflow, but we also use Keras for the convolution part of our model. Besides, we use python package distance to calculate edit distance for evaluation. (However, that is not mandatory, if distance is not installed, we will do exact match).
+This project is based on a model by [Qi Guo](http://qiguo.ml) and [Yuntian Deng](https://github.com/da03). You can find the original model in the [da03/Attention-OCR](https://github.com/da03/Attention-OCR) repository.
 
-### Tensorflow: [Installation Instructions](https://www.tensorflow.org/install/) (tested on 1.2.0)
+## The model
 
-### Distance (Optional):
+Authors: [Qi Guo](http://qiguo.ml) and [Yuntian Deng](https://github.com/da03).
 
-```
-wget http://www.cs.cmu.edu/~yuntiand/Distance-0.1.3.tar.gz
-```
+The model first runs a sliding CNN on the image (images are resized to height 32 while preserving aspect ratio). Then an LSTM is stacked on top of the CNN. Finally, an attention model is used as a decoder for producing the final outputs.
 
-```
-tar zxf Distance-0.1.3.tar.gz
-```
+![OCR example](http://cs.cmu.edu/~yuntiand/OCR-2.jpg)
+
+## Installation
 
 ```
-cd distance; sudo python setup.py install
+pip install aocr
 ```
 
-# Usage:
+Note: Tensorflow 1.2 and Numpy will be installed as dependencies. Additional dependencies are `PIL`/`Pillow`, `distance`, and `six`.
 
-Note: We assume that the working directory is `Attention-OCR`.
+## Usage
 
-## Train
-
-### Data Preparation
-We need a file (specified by parameter `data-path`) containing the path of images and the corresponding characters, e.g.:
+### Create a dataset
 
 ```
-path/to/image1 abc
-path/to/image2 def
+aocr dataset datasets/annotations-training.txt datasets/training.tfrecords
+aocr dataset datasets/annotations-testing.txt datasets/testing.tfrecords
 ```
 
-And we also need to specify a `data-base-dir` parameter such that we read the images from path `data-base-dir/path/to/image`. If `data-path` contains absolute path of images, then `data-base-dir` needs to be set to `/`.
-
-### A Toy Example
-
-For a toy example, we have prepared a training dataset of the specified format, which is a subset of [Synth 90k](http://www.robots.ox.ac.uk/~vgg/data/text/)
+Annotations are simple text files containing the image paths (either absolute or relative to your working dir) and their corresponding labels:
 
 ```
-wget http://www.cs.cmu.edu/~yuntiand/sample.tgz
+datasets/images/hello.jpg hello
+datasets/images/world.jpg world
 ```
 
+### Train
+
 ```
-tar zxf sample.tgz
+aocr train datasets/training.tfrecords
 ```
 
+A new model will be created, and the training will start. Note that it takes quite a long time to reach convergence, since we are training the CNN and attention model simultaneously.
+
+The `--steps-per-checkpoint` parameter determines how often the model checkpoints will be saved (the default output dir is `checkpoints/`).
+
+**Important:** there is a lot of available training options. See the CLI help or the `parameters` section of this README.
+
+### Test and visualize
+
 ```
-python src/launcher.py --phase=train --data-path=sample/sample.txt --data-base-dir=sample --log-path=log.txt --no-load-model
+aocr test datasets/testing.tfrecords
 ```
 
-After a while, you will see something like the following output in `log.txt`:
+Additionally, you can visualize the attention results during testing (saved to `results/` by default):
 
 ```
-...
-2016-06-08 20:47:22,335 root  INFO     Created model with fresh parameters.
-2016-06-08 20:47:52,852 root  INFO     current_step: 0
-2016-06-08 20:48:01,253 root  INFO     step_time: 8.400597, step perplexity: 38.998714
-2016-06-08 20:48:01,385 root  INFO     current_step: 1
-2016-06-08 20:48:07,166 root  INFO     step_time: 5.781749, step perplexity: 38.998445
-2016-06-08 20:48:07,337 root  INFO     current_step: 2
-2016-06-08 20:48:12,322 root  INFO     step_time: 4.984972, step perplexity: 39.006730
-2016-06-08 20:48:12,347 root  INFO     current_step: 3
-2016-06-08 20:48:16,821 root  INFO     step_time: 4.473902, step perplexity: 39.000267
-2016-06-08 20:48:16,859 root  INFO     current_step: 4
-2016-06-08 20:48:21,452 root  INFO     step_time: 4.593249, step perplexity: 39.009864
-2016-06-08 20:48:21,530 root  INFO     current_step: 5
-2016-06-08 20:48:25,878 root  INFO     step_time: 4.348195, step perplexity: 38.987707
-2016-06-08 20:48:26,016 root  INFO     current_step: 6
-2016-06-08 20:48:30,851 root  INFO     step_time: 4.835423, step perplexity: 39.022887
+aocr test --visualize datasets/testing.tfrecords
 ```
 
-Note that it takes quite a long time to reach convergence, since we are training the CNN and attention model simultaneously.
+Example output images in `results/correct`:
 
-## Test and visualize attention results
+Image 0 (j/j):
 
-The test data format shall be the same as training data format. We have also prepared a test dataset of the specified format, which includes ICDAR03, ICDAR13, IIIT5k and SVT.
+![example image 0](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_0.jpg)
 
-```
-wget http://www.cs.cmu.edu/~yuntiand/evaluation_data.tgz
-```
+Image 1 (u/u):
 
-```
-tar zxf evaluation_data.tgz
-```
+![example image 1](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_1.jpg)
 
-We also provide a trained model on Synth 90K:
+Image 2 (n/n):
 
-```
-wget http://www.cs.cmu.edu/~yuntiand/model.tgz
-```
+![example image 2](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_2.jpg)
 
-```
-tar zxf model.tgz
-```
+Image 3 (g/g):
+
+![example image 3](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_3.jpg)
+
+Image 4 (l/l):
+
+![example image 4](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_4.jpg)
+
+Image 5 (e/e):
+
+![example image 5](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_5.jpg)
+
+### Export
 
 ```
-python src/launcher.py --phase=test --visualize --data-path=evaluation_data/svt/test.txt --data-base-dir=evaluation_data/svt --log-path=log.txt --load-model --model-dir=model --output-dir=results
+aocr export exported-model
 ```
 
-After a while, you will see something like the following output in `log.txt`:
+Load weights from the latest checkpoints and export the model into the `./exported-model` directory.
 
-```
-2016-06-08 22:36:31,638 root  INFO     Reading model parameters from model/translate.ckpt-47200
-2016-06-08 22:36:40,529 root  INFO     Compare word based on edit distance.
-2016-06-08 22:36:41,652 root  INFO     step_time: 1.119277, step perplexity: 1.056626
-2016-06-08 22:36:41,660 root  INFO     1.000000 out of 1 correct
-2016-06-08 22:36:42,358 root  INFO     step_time: 0.696687, step perplexity: 2.003350
-2016-06-08 22:36:42,363 root  INFO     1.666667 out of 2 correct
-2016-06-08 22:36:42,831 root  INFO     step_time: 0.466550, step perplexity: 1.501963
-2016-06-08 22:36:42,835 root  INFO     2.466667 out of 3 correct
-2016-06-08 22:36:43,402 root  INFO     step_time: 0.562091, step perplexity: 1.269991
-2016-06-08 22:36:43,418 root  INFO     3.366667 out of 4 correct
-2016-06-08 22:36:43,897 root  INFO     step_time: 0.477545, step perplexity: 1.072437
-2016-06-08 22:36:43,905 root  INFO     4.366667 out of 5 correct
-2016-06-08 22:36:44,107 root  INFO     step_time: 0.195361, step perplexity: 2.071796
-2016-06-08 22:36:44,127 root  INFO     5.144444 out of 6 correct
+## Google Cloud ML Engine
+
+To train the model in the [Google Cloud Machine Learning Engine](https://cloud.google.com/ml-engine/), upload the training dataset into a Google Cloud Storage bucket and start a training job with the `gcloud` tool.
+
+1. Set the environment variables:
 
 ```
+# Prefix for the job name.
+export JOB_PREFIX="aocr"
 
-Example output images in `results/correct` (the output directory is set via parameter `output-dir` and the default is `results`): (Look closer to see it clearly.)
+# Region to launch the training job in.
+# Should be the same as the storage bucket region.
+export REGION="us-central1"
 
-Format: Image `index` (`predicted`/`ground truth`) `Image file`
+# Your storage bucket.
+export GS_BUCKET="gs://aocr-bucket"
 
-Image 0 (j/j): ![example image 0](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_0.jpg)
+# Path to store your training dataset in the bucket.
+export DATASET_UPLOAD_PATH="training.tfrecords"
+```
 
-Image 1 (u/u): ![example image 1](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_1.jpg)
+2. Upload the training dataset:
 
-Image 2 (n/n): ![example image 2](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_2.jpg)
+```
+gsutil cp datasets/training.tfrecords $GS_BUCKET/$DATASET_UPLOAD_PATH
+```
 
-Image 3 (g/g): ![example image 3](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_3.jpg)
+3. Launch the ML Engine job:
 
-Image 4 (l/l): ![example image 4](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_4.jpg)
+```
+export NOW=$(date +"%Y%m%d_%H%M%S")
+export JOB_NAME="$JOB_PREFIX$NOW"
+export JOB_DIR="$GS_BUCKET/$JOB_NAME"
 
-Image 5 (e/e): ![example image 5](http://cs.cmu.edu/~yuntiand/2evaluation_data_icdar13_images_word_370.png/image_5.jpg)
+gcloud ml-engine jobs submit training $JOB_NAME \
+    --job-dir $JOB_DIR \
+    --module-name=aocr \
+    --package-path=aocr \
+    --region=$REGION \
+    --scale-tier=BASIC_GPU \
+    --runtime-version 1.2 \
+    -- \
+    train $GS_BUCKET/$DATASET_UPLOAD_PATH \
+    --steps-per-checkpoint=3000
+```
 
+## Parameters
 
-# Parameters:
+### Global
+    * `log-path`: Path for the log file.
 
-- Control
-    * `phase`: Determine whether to train or test.
-    * `visualize`: Valid if `phase` is set to test. Output the attention maps on the original image.
-    * `load-model`: Load model from `model-dir` or not.
+### Testing
+    * `visualize`: Output the attention maps on the original image.
 
-- Input and output
-    * `data-base-dir`: The base directory of the image path in `data-path`. If the image path in `data-path` is absolute path, set it to `/`.
-    * `data-path`: The path containing data file names and labels. Format per line: `image_path characters`.
-    * `model-dir`: The directory for saving and loading model parameters (structure is not stored).
-    * `log-path`: The path to put log.
-    * `output-dir`: The path to put visualization results if `visualize` is set to True.
-    * `steps-per-checkpoint`: Checkpointing (print perplexity, save model) per how many steps
+### Exporting
+    * `format`: Format for the export (either `savedmodel` or `frozengraph`).
 
-- Optimization
+### Training
+    * `steps-per-checkpoint`: Checkpointing (print perplexity, save model) per how many steps
     * `num-epoch`: The number of whole data passes.
-    * `batch-size`: Batch size. Only valid if `phase` is set to train.
-    * `initial-learning-rate`: Initial learning rate, note the we use AdaDelta, so the initial value doe not matter much.
-
-- Network
+    * `batch-size`: Batch size.
+    * `initial-learning-rate`: Initial learning rate, note the we use AdaDelta, so the initial value does not matter much.
     * `target-embedding-size`: Embedding dimension for each target.
     * `attn-use-lstm`: Whether or not use LSTM attention decoder cell.
     * `attn-num-hidden`: Number of hidden units in attention decoder cell.
     * `attn-num-layers`: Number of layers in attention decoder cell. (Encoder number of hidden units will be `attn-num-hidden`*`attn-num-layers`).
     * `target-vocab-size`: Target vocabulary size. Default is = 26+10+3 # 0: PADDING, 1: GO, 2: EOS, >2: 0-9, a-z
+    * `no-resume`: Create new weights even if there are checkpoints present.
+    * `max-gradient-norm`: Clip gradients to this norm.
+    * `no-gradient-clipping`: Do not perform gradient clipping.
+    * `gpu-id`: GPU to use.
+    * `use-gru`: Use GRU cells.
 
-
-# References
+## References
 
 [Convert a formula to its LaTex source](https://github.com/harvardnlp/im2markup)
 

Diff for: aocr/__main__.py

@@ -1,3 +1,11 @@
+# TODO: single op for prediction
+# TODO: test visualization
+# TODO: clean up
+# TODO: update the readme
+# TODO: better CLI descriptions/syntax
+# TODO: export
+# TODO: move all the training parameters inside the training parser
+
 import sys
 import argparse
 import logging
@@ -13,6 +21,8 @@
 
 def process_args(args, defaults):
     parser = argparse.ArgumentParser()
+    parser.prog = 'aocr'
+
     subparsers = parser.add_subparsers(help='Subcommands.')
 
     # Global arguments
@@ -60,11 +70,11 @@ def process_args(args, defaults):
                                    ', default=%s' % (defaults.VISUALIZE)))
 
     # Exporting
-    parser_export = subparsers.add_parser('export', help='Export the saved checkpoints for production.')
-    parser_test.set_defaults(phase='export')
-    parser_export.add_argument('export_path', metavar='path',
+    parser_export = subparsers.add_parser('export', help='Export the model with weights for production use.')
+    parser_export.set_defaults(phase='export')
+    parser_export.add_argument('export_path', nargs='?', metavar='dir',
                         type=str, default=defaults.EXPORT_PATH,
-                        help=('Path to export the model in the specified format,'
+                        help=('Directory to save the exported model to,'
                               'default=%s'
                               % (defaults.EXPORT_PATH)))
     parser_export.add_argument('--format', dest="format",
@@ -126,12 +136,12 @@ def process_args(args, defaults):
                         type=str, default=defaults.OUTPUT_DIR,
                         help=('Output directory, default=%s'
                               % (defaults.OUTPUT_DIR)))
-    parser.add_argument('--max_gradient_norm', dest="max_gradient_norm",
+    parser.add_argument('--max-gradient-norm', dest="max_gradient_norm",
                         type=int, default=defaults.MAX_GRADIENT_NORM,
                         help=('Clip gradients to this norm.'
                               ', default=%s'
                               % (defaults.MAX_GRADIENT_NORM)))
-    parser.add_argument('--no-gradient_clipping', dest='clip_gradients', action='store_false',
+    parser.add_argument('--no-gradient-clipping', dest='clip_gradients', action='store_false',
                         help=('Do not perform gradient clipping, default for clip_gradients is %s' %
                               (defaults.CLIP_GRADIENTS)))
     parser.set_defaults(clip_gradients=defaults.CLIP_GRADIENTS)

Diff for: requirements.txt

@@ -0,0 +1,6 @@
+setuptools==32.1.0
+six==1.10.0
+numpy==1.12.1
+tensorflow==1.2.1
+Pillow==4.2.1
+distance==0.1.3

Diff for: setup.py

@@ -2,26 +2,28 @@
 from setuptools import setup
 
 REQUIRED_PACKAGES = ['distance', 'tensorflow', 'numpy', 'six']
-
-
-def readme():
-    with open('README.md') as file:
-        return file.read()
+VERSION = '0.0.2'
+try:
+    import pypandoc
+    README = pypandoc.convert('README.md', 'rst')
+except(IOError, ImportError):
+    README = open('README.md').read()
 
 
 setup(
     name='aocr',
     url='https://github.com/emedvedev/attention-ocr',
+    download_url='https://github.com/emedvedev/attention-ocr/archive/{}.tar.gz'.format(VERSION),
     author='Ed Medvedev',
     author_email='[email protected]',
-    version='0.1',
+    version=VERSION,
     install_requires=REQUIRED_PACKAGES,
     packages=find_packages(),
     include_package_data=True,
     license='MIT',
-    description='''Optical character recognition model
-    for Tensorflow based on Visual Attention.''',
-    long_description=readme(),
+    description=('''Optical character recognition model '''
+                 '''for Tensorflow based on Visual Attention.'''),
+    long_description=README,
     entry_points={
         'console_scripts': ['aocr=aocr.__main__:main'],
     }