Open Images Challenge 2018 tools, minor fixes and refactors. (#4661)

* Merged commit includes the following changes:
202804536  by Zhichao Lu:

    Return tf.data.Dataset from input_fn that goes into the estimator and use PER_HOST_V2 option for tpu input pipeline config.

    This change shaves off 100ms per step resulting in 25 minutes of total reduced training time for ssd mobilenet v1 (15k steps to convergence).

--
202769340  by Zhichao Lu:

    Adding as_matrix() transformation for image-level labels.

--
202768721  by Zhichao Lu:

    Challenge evaluation protocol modification: adding labelmaps creation.

--
202750966  by Zhichao Lu:

    Add the explicit names to two output nodes.

--
202732783  by Zhichao Lu:

    Enforcing that batch size is 1 for evaluation, and no original images are retained during evaluation when use_tpu=False (to avoid dynamic shapes).

--
202425430  by Zhichao Lu:

    Refactor input pipeline to improve performance.

--
202406389  by Zhichao Lu:

    Only check the validity of `warmup_learning_rate` if it will be used.

--
202330450  by Zhichao Lu:

    Adding the description of the flag input_image_label_annotations_csv to add
      image-level labels to tf.Example.

--
202029012  by Zhichao Lu:

    Enabling displaying relationship name in the final metrics output.

--
202024010  by Zhichao Lu:

    Update to the public README.

--
201999677  by Zhichao Lu:

    Fixing the way negative labels are handled in VRD evaluation.

--
201962313  by Zhichao Lu:

    Fix a bug in resize_to_range.

--
201808488  by Zhichao Lu:

    Update ssd_inception_v2_pets.config to use right filename of pets dataset tf records.

--
201779225  by Zhichao Lu:

    Update object detection API installation doc

--
201766518  by Zhichao Lu:

    Add shell script to create pycocotools package for CMLE.

--
201722377  by Zhichao Lu:

    Removes verified_labels field and uses groundtruth_image_classes field instead.

--
201616819  by Zhichao Lu:

    Disable eval_on_tpu since eval_metrics is not setup to execute on TPU.
    Do not use run_config.task_type to switch tpu mode for EVAL,
    since that won't work in unit test.
    Expand unit test to verify that the same instantiation of the Estimator can independently disable eval on TPU whereas training is enabled on TPU.

--
201524716  by Zhichao Lu:

    Disable export model to TPU, inference is not compatible with TPU.
    Add GOOGLE_INTERNAL support in object detection copy.bara.sky

--
201453347  by Zhichao Lu:

    Fixing bug when evaluating the quantized model.

--
200795826  by Zhichao Lu:

    Fixing parsing bug: image-level labels are parsed as tuples instead of numpy
    array.

--
200746134  by Zhichao Lu:

    Adding image_class_text and image_class_label fields into tf_example_decoder.py

--
200743003  by Zhichao Lu:

    Changes to model_main.py and model_tpu_main to enable training and continuous eval.

--
200736324  by Zhichao Lu:

    Replace deprecated squeeze_dims argument.

--
200730072  by Zhichao Lu:

    Make detections only during predict and eval mode while creating model function

--
200729699  by Zhichao Lu:

    Minor correction to internal documentation (definition of Huber loss)

--
200727142  by Zhichao Lu:

    Add command line parsing as a set of flags using argparse and add header to the
    resulting file.

--
200726169  by Zhichao Lu:

    A tutorial on running evaluation for the Open Images Challenge 2018.

--
200665093  by Zhichao Lu:

    Cleanup on variables_helper_test.py.

--
200652145  by Zhichao Lu:

    Add an option to write (non-frozen) graph when exporting inference graph.

--
200573810  by Zhichao Lu:

    Update ssd_mobilenet_v1_coco and ssd_inception_v2_coco download links to point to a newer version.

--
200498014  by Zhichao Lu:

    Add test for groundtruth mask resizing.

--
200453245  by Zhichao Lu:

    Cleaning up exporting_models.md along with exporting scripts

--
200311747  by Zhichao Lu:

    Resize groundtruth mask to match the size of the original image.

--
200287269  by Zhichao Lu:

    Having a option to use custom MatMul based crop_and_resize op as an alternate to the TF op in Faster-RCNN

--
200127859  by Zhichao Lu:

    Updating the instructions to run locally with new binary. Also updating pets configs since file path naming has changed.

--
200127044  by Zhichao Lu:

    A simpler evaluation util to compute Open Images Challenge
    2018 metric (object detection track).

--
200124019  by Zhichao Lu:

    Freshening up configuring_jobs.md

--
200086825  by Zhichao Lu:

    Make merge_multiple_label_boxes work for ssd model.

--
199843258  by Zhichao Lu:

    Allows inconsistent feature channels to be compatible with WeightSharedConvolutionalBoxPredictor.

--
199676082  by Zhichao Lu:

    Enable an override for `InputReader.shuffle` for object detection pipelines.

--
199599212  by Zhichao Lu:

    Markdown fixes.

--
199535432  by Zhichao Lu:

    Pass num_additional_channels to tf.example decoder in predict_input_fn.

--
199399439  by Zhichao Lu:

    Adding `num_additional_channels` field to specify how many additional channels to use in the model.

--

PiperOrigin-RevId: 202804536

* Add original model builder and docs back.

Author: pkulzc

research/object_detection/README.md

@@ -72,6 +72,8 @@ Extras:
       Inference and evaluation on the Open Images dataset</a><br>
   * <a href='g3doc/instance_segmentation.md'>
       Run an instance segmentation model</a><br>
+  * <a href='g3doc/challenge_evaluation.md'>
+      Run the evaluation for the Open Images Challenge 2018.</a><br>
 
 ## Getting Help
 
@@ -90,6 +92,20 @@ reporting an issue.
 
 ## Release information
 
+### June 25, 2018
+
+Additional evaluation tools for the [Open Images Challenge 2018](https://storage.googleapis.com/openimages/web/challenge.html) are out.
+Check out our short tutorial on data preparation and running evaluation [here](g3doc/challenge_evaluation.md)!
+
+<b>Thanks to contributors</b>: Alina Kuznetsova
+
+### June 5, 2018
+
+We have released the implementation of evaluation metrics for both tracks of the [Open Images Challenge 2018](https://storage.googleapis.com/openimages/web/challenge.html) as a part of the Object Detection API - see the [evaluation protocols](g3doc/evaluation_protocols.md) for more details.
+Additionally, we have released a tool for hierarchical labels expansion for the Open Images Challenge: check out [oid_hierarchical_labels_expansion.py](dataset_tools/oid_hierarchical_labels_expansion.py).
+
+<b>Thanks to contributors</b>: Alina Kuznetsova, Vittorio Ferrari, Jasper Uijlings
+
 ### April 30, 2018
 
 We have released a Faster R-CNN detector with ResNet-101 feature extractor trained on [AVA](https://research.google.com/ava/) v2.1.

research/object_detection/builders/dataset_builder.py

@@ -24,129 +24,76 @@
 import functools
 import tensorflow as tf
 
-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
-from object_detection.utils import dataset_util
 
 
-def _get_padding_shapes(dataset, max_num_boxes=None, num_classes=None,
-                        spatial_image_shape=None):
-  """Returns shapes to pad dataset tensors to before batching.
+def make_initializable_iterator(dataset):
+  """Creates an iterator, and initializes tables.
+
+  This is useful in cases where make_one_shot_iterator wouldn't work because
+  the graph contains a hash table that needs to be initialized.
 
   Args:
-    dataset: tf.data.Dataset object.
-    max_num_boxes: Max number of groundtruth boxes needed to computes shapes for
-      padding.
-    num_classes: Number of classes in the dataset needed to compute shapes for
-      padding.
-    spatial_image_shape: A list of two integers of the form [height, width]
-      containing expected spatial shape of the image.
+    dataset: A `tf.data.Dataset` object.
 
   Returns:
-    A dictionary keyed by fields.InputDataFields containing padding shapes for
-    tensors in the dataset.
-
-  Raises:
-    ValueError: If groundtruth classes is neither rank 1 nor rank 2.
+    A `tf.data.Iterator`.
   """
+  iterator = dataset.make_initializable_iterator()
+  tf.add_to_collection(tf.GraphKeys.TABLE_INITIALIZERS, iterator.initializer)
+  return iterator
 
-  if not spatial_image_shape or spatial_image_shape == [-1, -1]:
-    height, width = None, None
-  else:
-    height, width = spatial_image_shape  # pylint: disable=unpacking-non-sequence
-
-  num_additional_channels = 0
-  if fields.InputDataFields.image_additional_channels in dataset.output_shapes:
-    num_additional_channels = dataset.output_shapes[
-        fields.InputDataFields.image_additional_channels].dims[2].value
-  padding_shapes = {
-      # Additional channels are merged before batching.
-      fields.InputDataFields.image: [
-          height, width, 3 + num_additional_channels
-      ],
-      fields.InputDataFields.image_additional_channels: [
-          height, width, num_additional_channels
-      ],
-      fields.InputDataFields.source_id: [],
-      fields.InputDataFields.filename: [],
-      fields.InputDataFields.key: [],
-      fields.InputDataFields.groundtruth_difficult: [max_num_boxes],
-      fields.InputDataFields.groundtruth_boxes: [max_num_boxes, 4],
-      fields.InputDataFields.groundtruth_instance_masks: [
-          max_num_boxes, height, width
-      ],
-      fields.InputDataFields.groundtruth_is_crowd: [max_num_boxes],
-      fields.InputDataFields.groundtruth_group_of: [max_num_boxes],
-      fields.InputDataFields.groundtruth_area: [max_num_boxes],
-      fields.InputDataFields.groundtruth_weights: [max_num_boxes],
-      fields.InputDataFields.num_groundtruth_boxes: [],
-      fields.InputDataFields.groundtruth_label_types: [max_num_boxes],
-      fields.InputDataFields.groundtruth_label_scores: [max_num_boxes],
-      fields.InputDataFields.true_image_shape: [3],
-      fields.InputDataFields.multiclass_scores: [
-          max_num_boxes, num_classes + 1 if num_classes is not None else None
-      ],
-  }
-  # Determine whether groundtruth_classes are integers or one-hot encodings, and
-  # apply batching appropriately.
-  classes_shape = dataset.output_shapes[
-      fields.InputDataFields.groundtruth_classes]
-  if len(classes_shape) == 1:  # Class integers.
-    padding_shapes[fields.InputDataFields.groundtruth_classes] = [max_num_boxes]
-  elif len(classes_shape) == 2:  # One-hot or k-hot encoding.
-    padding_shapes[fields.InputDataFields.groundtruth_classes] = [
-        max_num_boxes, num_classes]
-  else:
-    raise ValueError('Groundtruth classes must be a rank 1 tensor (classes) or '
-                     'rank 2 tensor (one-hot encodings)')
-
-  if fields.InputDataFields.original_image in dataset.output_shapes:
-    padding_shapes[fields.InputDataFields.original_image] = [
-        None, None, 3 + num_additional_channels
-    ]
-  if fields.InputDataFields.groundtruth_keypoints in dataset.output_shapes:
-    tensor_shape = dataset.output_shapes[fields.InputDataFields.
-                                         groundtruth_keypoints]
-    padding_shape = [max_num_boxes, tensor_shape[1].value,
-                     tensor_shape[2].value]
-    padding_shapes[fields.InputDataFields.groundtruth_keypoints] = padding_shape
-  if (fields.InputDataFields.groundtruth_keypoint_visibilities
-      in dataset.output_shapes):
-    tensor_shape = dataset.output_shapes[fields.InputDataFields.
-                                         groundtruth_keypoint_visibilities]
-    padding_shape = [max_num_boxes, tensor_shape[1].value]
-    padding_shapes[fields.InputDataFields.
-                   groundtruth_keypoint_visibilities] = padding_shape
-  return {tensor_key: padding_shapes[tensor_key]
-          for tensor_key, _ in dataset.output_shapes.items()}
-
-
-def build(input_reader_config,
-          transform_input_data_fn=None,
-          batch_size=None,
-          max_num_boxes=None,
-          num_classes=None,
-          spatial_image_shape=None,
-          num_additional_channels=0):
+
+def read_dataset(file_read_func, input_files, config):
+  """Reads a dataset, and handles repetition and shuffling.
+
+  Args:
+    file_read_func: Function to use in tf.contrib.data.parallel_interleave, to
+      read every individual file into a tf.data.Dataset.
+    input_files: A list of file paths to read.
+    config: A input_reader_builder.InputReader object.
+
+  Returns:
+    A tf.data.Dataset of (undecoded) tf-records based on config.
+  """
+  # Shard, shuffle, and read files.
+  filenames = tf.gfile.Glob(input_files)
+  num_readers = config.num_readers
+  if num_readers > len(filenames):
+    num_readers = len(filenames)
+    tf.logging.warning('num_readers has been reduced to %d to match input file '
+                       'shards.' % num_readers)
+  filename_dataset = tf.data.Dataset.from_tensor_slices(filenames)
+  if config.shuffle:
+    filename_dataset = filename_dataset.shuffle(
+        config.filenames_shuffle_buffer_size)
+  elif num_readers > 1:
+    tf.logging.warning('`shuffle` is false, but the input data stream is '
+                       'still slightly shuffled since `num_readers` > 1.')
+  filename_dataset = filename_dataset.repeat(config.num_epochs or None)
+  records_dataset = filename_dataset.apply(
+      tf.contrib.data.parallel_interleave(
+          file_read_func,
+          cycle_length=num_readers,
+          block_length=config.read_block_length,
+          sloppy=config.shuffle))
+  if config.shuffle:
+    records_dataset = records_dataset.shuffle(config.shuffle_buffer_size)
+  return records_dataset
+
+
+def build(input_reader_config, batch_size=None, transform_input_data_fn=None):
   """Builds a tf.data.Dataset.
 
   Builds a tf.data.Dataset by applying the `transform_input_data_fn` on all
   records. Applies a padded batch to the resulting dataset.
 
   Args:
     input_reader_config: A input_reader_pb2.InputReader object.
-    transform_input_data_fn: Function to apply to all records, or None if
-      no extra decoding is required.
-    batch_size: Batch size. If None, batching is not performed.
-    max_num_boxes: Max number of groundtruth boxes needed to compute shapes for
-      padding. If None, will use a dynamic shape.
-    num_classes: Number of classes in the dataset needed to compute shapes for
-      padding. If None, will use a dynamic shape.
-    spatial_image_shape: A list of two integers of the form [height, width]
-      containing expected spatial shape of the image after applying
-      transform_input_data_fn. If None, will use dynamic shapes.
-    num_additional_channels: Number of additional channels to use in the input.
+    batch_size: Batch size. If batch size is None, no batching is performed.
+    transform_input_data_fn: Function to apply transformation to all records,
+      or None if no extra decoding is required.
 
   Returns:
     A tf.data.Dataset based on the input_reader_config.
@@ -173,24 +120,31 @@ def build(input_reader_config,
         instance_mask_type=input_reader_config.mask_type,
         label_map_proto_file=label_map_proto_file,
         use_display_name=input_reader_config.use_display_name,
-        num_additional_channels=num_additional_channels)
+        num_additional_channels=input_reader_config.num_additional_channels)
 
     def process_fn(value):
-      processed = decoder.decode(value)
+      """Sets up tf graph that decodes, transforms and pads input data."""
+      processed_tensors = decoder.decode(value)
       if transform_input_data_fn is not None:
-        return transform_input_data_fn(processed)
-      return processed
+        processed_tensors = transform_input_data_fn(processed_tensors)
+      return processed_tensors
 
-    dataset = dataset_util.read_dataset(
+    dataset = read_dataset(
         functools.partial(tf.data.TFRecordDataset, buffer_size=8 * 1000 * 1000),
-        process_fn, config.input_path[:], input_reader_config)
-
+        config.input_path[:], input_reader_config)
+    # TODO(rathodv): make batch size a required argument once the old binaries
+    # are deleted.
+    if batch_size:
+      num_parallel_calls = batch_size * input_reader_config.num_parallel_batches
+    else:
+      num_parallel_calls = input_reader_config.num_parallel_map_calls
+    dataset = dataset.map(
+        process_fn,
+        num_parallel_calls=num_parallel_calls)
     if batch_size:
-      padding_shapes = _get_padding_shapes(dataset, max_num_boxes, num_classes,
-                                           spatial_image_shape)
       dataset = dataset.apply(
-          tf.contrib.data.padded_batch_and_drop_remainder(batch_size,
-                                                          padding_shapes))
+          tf.contrib.data.batch_and_drop_remainder(batch_size))
+    dataset = dataset.prefetch(input_reader_config.num_prefetch_batches)
     return dataset
 
   raise ValueError('Unsupported input_reader_config.')