Add FAQ to object detection and replace...

Add FAQ to object detection and replace tf.contrib.slim.tfexample_decoder.BackupHandler with object_detection.data_decoders.tf_example_decoder.BackupHandler.

PiperOrigin-RevId: 188191275

research/object_detection/README.md

@@ -83,6 +83,8 @@ tensorflow/models GitHub
 [issue tracker](https://github.com/tensorflow/models/issues), prefixing the
 issue name with "object_detection".
 
+Please check [FAQ](g3doc/faq.md) for frequently asked questions before
+reporting an issue.
 
 
 ## Release information

research/object_detection/data_decoders/tf_example_decoder.py

@@ -20,6 +20,9 @@ protos for object detection.
 """
 import tensorflow as tf
 
+from tensorflow.python.ops import array_ops
+from tensorflow.python.ops import control_flow_ops
+from tensorflow.python.ops import math_ops
 from object_detection.core import data_decoder
 from object_detection.core import standard_fields as fields
 from object_detection.protos import input_reader_pb2
@@ -28,6 +31,40 @@ from object_detection.utils import label_map_util
 slim_example_decoder = tf.contrib.slim.tfexample_decoder
 
 
+class BackupHandler(slim_example_decoder.ItemHandler):
+  """An ItemHandler that tries two ItemHandlers in order."""
+
+  def __init__(self, handler, backup):
+    """Initializes the BackupHandler handler.
+
+    If the first Handler's tensors_to_item returns a Tensor with no elements,
+    the second Handler is used.
+
+    Args:
+      handler: The primary ItemHandler.
+      backup: The backup ItemHandler.
+
+    Raises:
+      ValueError: if either is not an ItemHandler.
+    """
+    if not isinstance(handler, slim_example_decoder.ItemHandler):
+      raise ValueError('Primary handler is of type %s instead of ItemHandler' %
+                       type(handler))
+    if not isinstance(backup, slim_example_decoder.ItemHandler):
+      raise ValueError(
+          'Backup handler is of type %s instead of ItemHandler' % type(backup))
+    self._handler = handler
+    self._backup = backup
+    super(BackupHandler, self).__init__(handler.keys + backup.keys)
+
+  def tensors_to_item(self, keys_to_tensors):
+    item = self._handler.tensors_to_item(keys_to_tensors)
+    return control_flow_ops.cond(
+        pred=math_ops.equal(math_ops.reduce_prod(array_ops.shape(item)), 0),
+        true_fn=lambda: self._backup.tensors_to_item(keys_to_tensors),
+        false_fn=lambda: item)
+
+
 class TfExampleDecoder(data_decoder.DataDecoder):
   """Tensorflow Example proto decoder."""
 
@@ -165,7 +202,11 @@ class TfExampleDecoder(data_decoder.DataDecoder):
           default_value=-1)
       # If the label_map_proto is provided, try to use it in conjunction with
       # the class text, and fall back to a materialized ID.
-      label_handler = slim_example_decoder.BackupHandler(
+      # TODO(lzc): note that here we are using BackupHandler defined in this
+      # file(which is branching slim_example_decoder.BackupHandler). Need to
+      # switch back to slim_example_decoder.BackupHandler once tf 1.5 becomes
+      # more popular.
+      label_handler = BackupHandler(
           slim_example_decoder.LookupTensor(
               'image/object/class/text', table, default_value=''),
           slim_example_decoder.Tensor('image/object/class/label'))

research/object_detection/data_decoders/tf_example_decoder_test.py

@@ -19,10 +19,19 @@ import os
 import numpy as np
 import tensorflow as tf
 
+from tensorflow.core.example import example_pb2
+from tensorflow.core.example import feature_pb2
+from tensorflow.python.framework import constant_op
+from tensorflow.python.framework import dtypes
+from tensorflow.python.ops import array_ops
+from tensorflow.python.ops import lookup_ops
+from tensorflow.python.ops import parsing_ops
 from object_detection.core import standard_fields as fields
 from object_detection.data_decoders import tf_example_decoder
 from object_detection.protos import input_reader_pb2
 
+slim_example_decoder = tf.contrib.slim.tfexample_decoder
+
 
 class TfExampleDecoderTest(tf.test.TestCase):
 
@@ -57,6 +66,68 @@ class TfExampleDecoderTest(tf.test.TestCase):
       return tf.train.Feature(bytes_list=tf.train.BytesList(value=value))
     return tf.train.Feature(bytes_list=tf.train.BytesList(value=[value]))
 
+  def _Int64FeatureFromList(self, ndarray):
+    return feature_pb2.Feature(
+        int64_list=feature_pb2.Int64List(value=ndarray.flatten().tolist()))
+
+  def _BytesFeatureFromList(self, ndarray):
+    values = ndarray.flatten().tolist()
+    for i in range(len(values)):
+      values[i] = values[i].encode('utf-8')
+    return feature_pb2.Feature(bytes_list=feature_pb2.BytesList(value=values))
+
+  def testDecodeExampleWithBranchedBackupHandler(self):
+    example1 = example_pb2.Example(
+        features=feature_pb2.Features(
+            feature={
+                'image/object/class/text':
+                    self._BytesFeatureFromList(
+                        np.array(['cat', 'dog', 'guinea pig'])),
+                'image/object/class/label':
+                    self._Int64FeatureFromList(np.array([42, 10, 900]))
+            }))
+    example2 = example_pb2.Example(
+        features=feature_pb2.Features(
+            feature={
+                'image/object/class/text':
+                    self._BytesFeatureFromList(
+                        np.array(['cat', 'dog', 'guinea pig'])),
+            }))
+    example3 = example_pb2.Example(
+        features=feature_pb2.Features(
+            feature={
+                'image/object/class/label':
+                    self._Int64FeatureFromList(np.array([42, 10, 901]))
+            }))
+    # 'dog' -> 0, 'guinea pig' -> 1, 'cat' -> 2
+    table = lookup_ops.index_table_from_tensor(
+        constant_op.constant(['dog', 'guinea pig', 'cat']))
+    keys_to_features = {
+        'image/object/class/text': parsing_ops.VarLenFeature(dtypes.string),
+        'image/object/class/label': parsing_ops.VarLenFeature(dtypes.int64),
+    }
+    backup_handler = tf_example_decoder.BackupHandler(
+        handler=slim_example_decoder.Tensor('image/object/class/label'),
+        backup=slim_example_decoder.LookupTensor('image/object/class/text',
+                                                 table))
+    items_to_handlers = {
+        'labels': backup_handler,
+    }
+    decoder = slim_example_decoder.TFExampleDecoder(keys_to_features,
+                                                    items_to_handlers)
+    obtained_class_ids_each_example = []
+    with self.test_session() as sess:
+      sess.run(lookup_ops.tables_initializer())
+      for example in [example1, example2, example3]:
+        serialized_example = array_ops.reshape(
+            example.SerializeToString(), shape=[])
+        obtained_class_ids_each_example.append(
+            decoder.decode(serialized_example)[0].eval())
+
+    self.assertAllClose([42, 10, 900], obtained_class_ids_each_example[0])
+    self.assertAllClose([2, 0, 1], obtained_class_ids_each_example[1])
+    self.assertAllClose([42, 10, 901], obtained_class_ids_each_example[2])
+
   def testDecodeJpegImage(self):
     image_tensor = np.random.randint(256, size=(4, 5, 3)).astype(np.uint8)
     encoded_jpeg = self._EncodeImage(image_tensor)

research/object_detection/g3doc/faq.md

+# Frequently Asked Questions
+
+## Q: AttributeError: 'module' object has no attribute 'BackupHandler'
+A: This BackupHandler (tf.contrib.slim.tfexample_decoder.BackupHandler) was
+introduced in tensorflow 1.5.0 so runing with earlier versions may cause this
+issue. It now has been replaced by
+object_detection.data_decoders.tf_example_decoder.BackupHandler. Whoever sees
+this issue should be able to resolve it by syncing your fork to HEAD.
+
+## Q: Why can't I get the inference time as reported in model zoo?
+A: The inference time reported in model zoo is mean time of testing hundreds of
+images with a internal machine. As mentioned in
+[Tensorflow detection model zoo](detection_model_zoo.md), this speed depends
+highly on one's specific hardware configuration and should be treated more as
+relative timing.