Add tutorial

README.md

@@ -76,10 +76,12 @@ Run `labelme --help` for detail.
 
 ```bash
 labelme  # Open GUI
-labelme static/apc2016_obj3.jpg  # Specify file
-labelme static/apc2016_obj3.jpg -O static/apc2016_obj3.json  # Close window after the save
+labelme tutorial/apc2016_obj3.jpg  # Specify file
+labelme tutorial/apc2016_obj3.jpg -O tutorial/apc2016_obj3.json  # Close window after the save
 ```
 
+<img src=".readme/apc2016_obj3_screenshot.jpg" width="50%" />
+
 The annotations are saved as a [JSON](http://www.json.org/) file. The
 file includes the image itself.
 
@@ -88,35 +90,55 @@ file includes the image itself.
 To view the json file quickly, you can use utility script:
 
 ```bash
-labelme_draw_json static/apc2016_obj3.json
+labelme_draw_json tutorial/apc2016_obj3.json
 ```
 
+<img src=".readme/apc2016_obj3_draw_json.jpg" width="70%" />
+
 **Convert to Dataset**
 
 To convert the json to set of image and label, you can run following:
 
 
 ```bash
-labelme_json_to_dataset static/apc2016_obj3.json
+labelme_json_to_dataset tutorial/apc2016_obj3.json -o tutorial/apc2016_obj3_json
 ```
 
-
-Sample
-------
-
-- [Original Image](https://github.com/wkentaro/labelme/blob/master/static/apc2016_obj3.jpg)
-- [Screenshot](https://github.com/wkentaro/labelme/blob/master/static/apc2016_obj3_screenshot.jpg)
-- [Generated Json File](https://github.com/wkentaro/labelme/blob/master/static/apc2016_obj3.json)
-- [Visualized Json File](https://github.com/wkentaro/labelme/blob/master/static/apc2016_obj3_draw_json.jpg)
+It generates standard files from the JSON file.
+
+- [img.png](tutorial/apc2016_obj3_json/img.png): Image file.
+- [label.png](tutorial/apc2016_obj3_json/label.png): Int32 label file.
+- [label_viz.png](tutorial/apc2016_obj3_json/label_viz.png): Visualization of `label.png`.
+- [label_names.txt](tutorial/apc2016_obj3_json/label_names.txt): Label names for values in `label.png`.
+
+Note that loading `label.png` is a bit difficult
+(`scipy.misc.imread`, `skimage.io.imread` may not work correctly),
+and please use `PIL.Image.open` to avoid unexpected behavior:
+
+```python
+# see tutorial/load_label_png.py also.
+>>> import numpy as np
+>>> import PIL.Image
+
+>>> label_png = 'tutorial/apc2016_obj3_json/label.png'
+>>> lbl = np.asarray(PIL.Image.open(label_png))
+>>> print(lbl.dtype)
+dtype('int32')
+>>> np.unique(lbl)
+array([0, 1, 2, 3], dtype=int32)
+>>> lbl.shape
+(907, 1210)
+```
 
 
 Screencast
 ----------
 
-<img src="https://github.com/wkentaro/labelme/raw/master/static/screencast.gif" width="70%"/>
+<img src=".readme/screencast.gif" width="70%"/>
 
 
 Acknowledgement
 ---------------
 
-This repo is the fork of [mpitid/pylabelme](https://github.com/mpitid/pylabelme), whose development has already stopped.
+This repo is the fork of [mpitid/pylabelme](https://github.com/mpitid/pylabelme),
+whose development has already stopped.

scripts/labelme_draw_json

@@ -19,7 +19,8 @@ def main():
     img = utils.img_b64_to_array(data['imageData'])
     lbl, lbl_names = utils.labelme_shapes_to_label(img.shape, data['shapes'])
 
-    lbl_viz = utils.draw_label(lbl, img, lbl_names)
+    captions = ['%d: %s' % (l, name) for l, name in enumerate(lbl_names)]
+    lbl_viz = utils.draw_label(lbl, img, captions)
 
     plt.subplot(121)
     plt.imshow(img)

scripts/labelme_json_to_dataset

@@ -1,10 +1,12 @@
-#!/usr/bin/python
+#!/usr/bin/env python
 
 import argparse
 import json
 import os
 import os.path as osp
+import warnings
 
+import numpy as np
 import PIL.Image
 import yaml
 
@@ -14,31 +16,41 @@ from labelme import utils
 def main():
     parser = argparse.ArgumentParser()
     parser.add_argument('json_file')
+    parser.add_argument('-o', '--out', default=None)
     args = parser.parse_args()
 
     json_file = args.json_file
 
-    out_dir = osp.basename(json_file).replace('.', '_')
-    out_dir = osp.join(osp.dirname(json_file), out_dir)
-    os.mkdir(out_dir)
+    if args.out is None:
+        out_dir = osp.basename(json_file).replace('.', '_')
+        out_dir = osp.join(osp.dirname(json_file), out_dir)
+    else:
+        out_dir = args.out
+    if not osp.exists(out_dir):
+        os.mkdir(out_dir)
 
     data = json.load(open(json_file))
 
     img = utils.img_b64_to_array(data['imageData'])
     lbl, lbl_names = utils.labelme_shapes_to_label(img.shape, data['shapes'])
 
-    lbl_viz = utils.draw_label(lbl, img, lbl_names)
+    captions = ['%d: %s' % (l, name) for l, name in enumerate(lbl_names)]
+    lbl_viz = utils.draw_label(lbl, img, captions)
 
     PIL.Image.fromarray(img).save(osp.join(out_dir, 'img.png'))
     PIL.Image.fromarray(lbl).save(osp.join(out_dir, 'label.png'))
     PIL.Image.fromarray(lbl_viz).save(osp.join(out_dir, 'label_viz.png'))
 
-    info = dict(label_names=lbl_names)
+    with open(osp.join(out_dir, 'label_names.txt'), 'w') as f:
+        for lbl_name in lbl_names:
+            f.write(lbl_name + '\n')
 
+    warnings.warn('info.yaml is being replaced by label_names.txt')
+    info = dict(label_names=lbl_names)
     with open(osp.join(out_dir, 'info.yaml'), 'w') as f:
         yaml.safe_dump(info, f, default_flow_style=False)
 
-    print('wrote data to %s' % out_dir)
+    print('Saved to: %s' % out_dir)
 
 
 if __name__ == '__main__':

tutorial/apc2016_obj3_json/info.yaml

@@ -0,0 +1,5 @@
+label_names:
+- background
+- highland_6539_self_stick_notes
+- mead_index_cards
+- kong_air_dog_squeakair_tennis_ball

tutorial/apc2016_obj3_json/label_names.txt

@@ -0,0 +1,4 @@
+background
+highland_6539_self_stick_notes
+mead_index_cards
+kong_air_dog_squeakair_tennis_ball

tutorial/load_label_png.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+
+from __future__ import print_function
+
+import os.path as osp
+
+import numpy as np
+import PIL.Image
+
+
+here = osp.dirname(osp.abspath(__file__))
+
+
+def main():
+    label_png = osp.join(here, 'apc2016_obj3_json/label.png')
+    print('Loading:', label_png)
+    print()
+
+    lbl = np.asarray(PIL.Image.open(label_png))
+    labels = np.unique(lbl)
+
+    label_names_txt = osp.join(here, 'apc2016_obj3_json/label_names.txt')
+    label_names = [name.strip() for name in open(label_names_txt)]
+    print('# of labels:', len(labels))
+    print('# of label_names:', len(label_names))
+    if len(labels) != len(label_names):
+        print('Number of unique labels and label_names must be same.')
+        quit(1)
+    print()
+
+    print('label: label_name')
+    for label, label_name in zip(labels, label_names):
+        print('%d: %s' % (label, label_name))
+
+
+if __name__ == '__main__':
+    main()