chore: import upstream snapshot with attribution

tensorflow/lite/g3doc/r1/convert/cmdline_examples.md

@@ -0,0 +1,376 @@
+# Converter command line examples
+
+This page shows how to use the TensorFlow Lite Converter in the command line.
+
+_Note: If possible, use the **recommended** [Python API](python_api.md)
+instead._
+
+## Command-line tools <a name="tools"></a>
+
+### Starting from TensorFlow 1.9
+
+There are two approaches to running the converter in the command line.
+
+*   `tflite_convert` (**recommended**):
+    *   *Install*: TensorFlow using
+        [pip](https://www.tensorflow.org/install/pip).
+    *   *Example*: `tflite_convert --output_file=...`
+*   `bazel`:
+    *   *Install*: TensorFlow from
+        [source](https://www.tensorflow.org/install/source).
+    *   *Example*: `bazel run tensorflow/lite/python:tflite_convert --
+        --output_file=...`
+
+*All of the following examples use `tflite_convert` for simplicity.
+Alternatively, you can replace '`tflite_convert`' with '`bazel run
+tensorflow/lite/python:tflite_convert --`'*
+
+### Prior to TensorFlow 1.9 <a name="pre_tensorflow_1.9"></a>
+
+The recommended approach for using the converter prior to TensorFlow 1.9 is the
+[Python API](python_api.md). Only in TensorFlow 1.7, a command line tool `toco`
+was available (run `toco --help` for additional details).
+
+## Usage <a name="usage"></a>
+
+### Setup <a name="download_models"></a>
+
+Before we begin, download the models required to run the examples in this
+document:
+
+```
+echo "Download MobileNet V1"
+curl https://storage.googleapis.com/download.tensorflow.org/models/mobilenet_v1_0.50_128_frozen.tgz \
+  | tar xzv -C /tmp
+
+echo "Download Inception V1"
+curl https://storage.googleapis.com/download.tensorflow.org/models/inception_v1_2016_08_28_frozen.pb.tar.gz \
+  | tar xzv -C /tmp
+```
+
+### Basic examples <a name="basic"></a>
+
+The following section shows examples of how to convert a basic model from each
+of the supported data formats into a TensorFlow Lite model.
+
+#### Convert a SavedModel <a name="savedmodel"></a>
+
+```
+tflite_convert \
+  --saved_model_dir=/tmp/saved_model \
+  --output_file=/tmp/foo.tflite
+```
+
+#### Convert a tf.keras model <a name="keras"></a>
+
+```
+tflite_convert \
+  --keras_model_file=/tmp/keras_model.h5 \
+  --output_file=/tmp/foo.tflite
+```
+
+#### Convert a Frozen GraphDef <a name="graphdef"></a>
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/mobilenet_v1_0.50_128/frozen_graph.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1
+```
+
+Frozen GraphDef models (or frozen graphs) are produced by
+[freeze_graph.py](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/tools/freeze_graph.py)
+and require additional flags `--input_arrays` and `--output_arrays` as this
+information is not stored in the model format.
+
+### Advanced examples
+
+#### Convert a quantization aware trained model into a quantized TensorFlow Lite model
+
+If you have a quantization aware trained model (i.e, a model inserted with
+`FakeQuant*` operations which record the (min, max) ranges of tensors in order
+to quantize them), then convert it into a quantized TensorFlow Lite model as
+shown below:
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/some_mobilenetv1_quantized_frozen_graph.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1 \
+  --inference_type=INT8 \
+  --mean_values=-0.5 \
+  --std_dev_values=127.7
+```
+
+*If you're setting `--inference_type=UINT8` then update `--mean_values=128` and
+`--std_dev_values=127`*
+
+#### Convert a model with \"dummy-quantization\" into a quantized TensorFlow Lite model
+
+If you have a regular float model and only want to estimate the benefit of a
+quantized model, i.e, estimate the performance of the model as if it were
+quantized aware trained, then perform "dummy-quantization" using the flags
+`--default_ranges_min` and `--default_ranges_max`. When specified, they will be
+used as default (min, max) range for all the tensors that lack (min, max) range
+information. This will allow quantization to proceed and help you emulate the
+performance of a quantized TensorFlow Lite model but it will have a lower
+accuracy.
+
+The example below contains a model using Relu6 activation functions. Therefore,
+a reasonable guess is that most activation ranges should be contained in [0, 6].
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/mobilenet_v1_0.50_128/frozen_graph.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1 \
+  --inference_type=INT8 \
+  --mean_values=-0.5 \
+  --std_dev_values=127.7 \
+  --default_ranges_min=0 \
+  --default_ranges_max=6
+```
+
+*If you're setting `--inference_type=UINT8` then update `--mean_values=128` and
+`--std_dev_values=127`*
+
+#### Convert a model with select TensorFlow operators.
+
+Since TensorFlow Lite only supports a limited number of TensorFlow operators,
+not every model is convertible. For details, refer to
+[operator compatibility](https://www.tensorflow.org/lite/guide/ops_compatibility).
+To allow conversion, users can enable the usage of
+[certain TensorFlow ops](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/compiler/mlir/lite/delegates/flex/allowlisted_flex_ops.cc)
+in their TensorFlow Lite model, as shown in the following example.
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/foo.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1 \
+  --target_ops=TFLITE_BUILTINS,SELECT_TF_OPS
+```
+
+When building and running `tflite_convert` with `bazel`, please pass
+`--define=tflite_convert_with_select_tf_ops=true` as an additional argument.
+
+```
+bazel run --define=tflite_convert_with_select_tf_ops=true tflite_convert -- \
+  --graph_def_file=/tmp/foo.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1 \
+  --target_ops=TFLITE_BUILTINS,SELECT_TF_OPS
+```
+
+#### Convert a model with multiple input arrays
+
+The flag `input_arrays` takes in a comma-separated list of input arrays as seen
+in the example below. This is useful for models or subgraphs with multiple
+inputs. Note that `--input_shapes` is provided as a colon-separated list. Each
+input shape corresponds to the input array at the same position in the
+respective list.
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/inception_v1_2016_08_28_frozen.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=InceptionV1/InceptionV1/Mixed_3b/Branch_1/Conv2d_0a_1x1/Relu,InceptionV1/InceptionV1/Mixed_3b/Branch_2/Conv2d_0a_1x1/Relu,InceptionV1/InceptionV1/Mixed_3b/Branch_3/MaxPool_0a_3x3/MaxPool,InceptionV1/InceptionV1/Mixed_3b/Branch_0/Conv2d_0a_1x1/Relu \
+  --input_shapes=1,28,28,96:1,28,28,16:1,28,28,192:1,28,28,64 \
+  --output_arrays=InceptionV1/Logits/Predictions/Reshape_1
+```
+
+#### Convert a model with multiple output arrays
+
+The flag `--output_arrays` takes in a comma-separated list of output arrays as
+seen in the example below. This is useful for models or subgraphs with multiple
+outputs.
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/inception_v1_2016_08_28_frozen.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=InceptionV1/InceptionV1/Mixed_3b/Branch_1/Conv2d_0a_1x1/Relu,InceptionV1/InceptionV1/Mixed_3b/Branch_2/Conv2d_0a_1x1/Relu
+```
+
+### Convert a model by specifying subgraphs
+
+Any array in the input file can be specified as an input or output array in
+order to extract subgraphs out of an input model file. The TensorFlow Lite
+Converter discards the parts of the model outside of the specific subgraph. Use
+[visualization](#visualization) to identify the input and output arrays that
+make up the desired subgraph.
+
+The follow command shows how to extract a single fused layer out of a TensorFlow
+GraphDef.
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/inception_v1_2016_08_28_frozen.pb \
+  --output_file=/tmp/foo.pb \
+  --input_arrays=InceptionV1/InceptionV1/Mixed_3b/Branch_1/Conv2d_0a_1x1/Relu,InceptionV1/InceptionV1/Mixed_3b/Branch_2/Conv2d_0a_1x1/Relu,InceptionV1/InceptionV1/Mixed_3b/Branch_3/MaxPool_0a_3x3/MaxPool,InceptionV1/InceptionV1/Mixed_3b/Branch_0/Conv2d_0a_1x1/Relu \
+  --input_shapes=1,28,28,96:1,28,28,16:1,28,28,192:1,28,28,64 \
+  --output_arrays=InceptionV1/InceptionV1/Mixed_3b/concat_v2
+```
+
+Note that the final representation in TensorFlow Lite models tends to have
+coarser granularity than the very fine granularity of the TensorFlow GraphDef
+representation. For example, while a fully-connected layer is typically
+represented as at least four separate operations in TensorFlow GraphDef
+(Reshape, MatMul, BiasAdd, Relu...), it is typically represented as a single
+"fused" op (FullyConnected) in the converter's optimized representation and in
+the final on-device representation. As the level of granularity gets coarser,
+some intermediate arrays (say, the array between the MatMul and the BiasAdd in
+the TensorFlow GraphDef) are dropped.
+
+When specifying intermediate arrays as `--input_arrays` and `--output_arrays`,
+it is desirable (and often required) to specify arrays that are meant to survive
+in the final form of the model, after fusing. These are typically the outputs of
+activation functions (since everything in each layer until the activation
+function tends to get fused).
+
+## Visualization <a name="visualization"></a>
+
+### Using `--dump_graphviz_dir`
+
+The first way to get a Graphviz rendering is to pass the `--dump_graphviz_dir`
+flag, specifying a destination directory to dump Graphviz rendering to.
+
+```
+tflite_convert \
+  --graph_def_file=/tmp/mobilenet_v1_0.50_128/frozen_graph.pb \
+  --output_file=/tmp/foo.tflite \
+  --input_arrays=input \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1 \
+  --dump_graphviz_dir=/tmp
+```
+
+This generates a few files in the destination directory. The two most important
+files are `toco_AT_IMPORT.dot` and `/tmp/toco_AFTER_TRANSFORMATIONS.dot`.
+
+-   `toco_AT_IMPORT.dot` represents the original model containing only the
+    transformations done at import time. This tends to be a complex
+    visualization with limited information about each node. It is useful in
+    situations where a conversion command fails.
+
+-   `toco_AFTER_TRANSFORMATIONS.dot` represents the model after all
+    transformations were applied to it, just before it is exported. Typically,
+    this is a much smaller model with more information about each node.
+
+These can be rendered to PDFs:
+
+```
+dot -Tpdf /tmp/toco_*.dot -O
+```
+
+And the resulting `.dot.pdf` can be viewed in any PDF viewer, but we suggest one
+with a good ability to pan and zoom across a very large page. Google Chrome does
+well in that respect.
+
+```
+google-chrome /tmp/foo.dot.pdf
+```
+
+Sample output files can be seen here below. Note that it is the same
+`AveragePool` node in the top right of each image.
+
+<table><tr>
+  <td>
+    <a target="_blank" href="https://storage.googleapis.com/download.tensorflow.org/example_images/toco_AT_IMPORT.dot.pdf">
+      <img src="../images/convert/sample_before.png"/>
+    </a>
+  </td>
+  <td>
+    <a target="_blank" href="https://storage.googleapis.com/download.tensorflow.org/example_images/toco_AFTER_TRANSFORMATIONS.dot.pdf">
+      <img src="../images/convert/sample_after.png"/>
+    </a>
+  </td>
+</tr>
+<tr><td>before</td><td>after</td></tr>
+</table>
+
+### Using `--output_format=GRAPHVIZ_DOT` <a name="using_output_format_graphviz_dot"></a>
+
+*Note: This only works when you set flag `experimental_new_converter=False`.
+Also, as this format leads to loss of TFLite specific transformations, we
+recommend that you use `--dump_graphviz_dir` instead to get a final
+visualization with all graph transformations.*
+
+The second way to get a Graphviz rendering is to pass `GRAPHVIZ_DOT` into
+`--output_format`. This results in a plausible visualization of the model. This
+reduces the requirements that exist during conversion from a TensorFlow GraphDef
+to a TensorFlow Lite model. This may be useful if the conversion to TFLite is
+failing.
+
+```
+tflite_convert \
+  --experimental_new_converter=False
+  --graph_def_file=/tmp/mobilenet_v1_0.50_128/frozen_graph.pb \
+  --output_format=GRAPHVIZ_DOT \
+  --output_file=/tmp/foo.dot \
+  --output_format=GRAPHVIZ_DOT \
+  --input_arrays=input \
+  --input_shape=1,128,128,3 \
+  --output_arrays=MobilenetV1/Predictions/Reshape_1
+
+```
+
+The resulting `.dot` file can be rendered into a PDF as follows:
+
+```
+dot -Tpdf /tmp/foo.dot -O
+```
+
+And the resulting `.dot.pdf` can be viewed in any PDF viewer, but we suggest one
+with a good ability to pan and zoom across a very large page. Google Chrome does
+well in that respect.
+
+```
+google-chrome /tmp/foo.dot.pdf
+```
+
+### Video logging
+
+When `--dump_graphviz_dir` is used, one may additionally pass
+`--dump_graphviz_video`. This causes a model visualization to be dumped after
+each individual model transformation, resulting in thousands of files.
+Typically, one would then bisect into these files to understand when a given
+change was introduced in the model.
+
+### Legend for the Visualizations <a name="graphviz_legend"></a>
+
+*   Operators are red square boxes with the following hues of red:
+    *   Most operators are
+        <span style="background-color:#db4437;color:white;border:1px;border-style:solid;border-color:black;padding:1px">bright
+        red</span>.
+    *   Some typically heavy operators (e.g. Conv) are rendered in a
+        <span style="background-color:#c53929;color:white;border:1px;border-style:solid;border-color:black;padding:1px">darker
+        red</span>.
+*   Arrays are octagons with the following colors:
+    *   Constant arrays are
+        <span style="background-color:#4285f4;color:white;border:1px;border-style:solid;border-color:black;padding:1px">blue</span>.
+    *   Activation arrays are gray:
+        *   Internal (intermediate) activation arrays are
+            <span style="background-color:#f5f5f5;border:1px;border-style:solid;border-color:black;border:1px;border-style:solid;border-color:black;padding:1px">light
+            gray</span>.
+        *   Those activation arrays that are designated as `--input_arrays` or
+            `--output_arrays` are
+            <span style="background-color:#9e9e9e;border:1px;border-style:solid;border-color:black;padding:1px">dark
+            gray</span>.
+    *   RNN state arrays are green. Because of the way that the converter
+        represents RNN back-edges explicitly, each RNN state is represented by a
+        pair of green arrays:
+        *   The activation array that is the source of the RNN back-edge (i.e.
+            whose contents are copied into the RNN state array after having been
+            computed) is
+            <span style="background-color:#b7e1cd;border:1px;border-style:solid;border-color:black;padding:1px">light
+            green</span>.
+        *   The actual RNN state array is
+            <span style="background-color:#0f9d58;color:white;border:1px;border-style:solid;border-color:black;padding:1px">dark
+            green</span>. It is the destination of the RNN back-edge updating
+            it.

tensorflow/lite/g3doc/r1/convert/cmdline_reference.md

@@ -0,0 +1,188 @@
+# Converter command line reference
+
+This page is complete reference of command-line flags used by the TensorFlow
+Lite Converter's command line tool.
+
+## High-level flags
+
+The following high level flags specify the details of the input and output
+files. The flag `--output_file` is always required. Additionally, either
+`--saved_model_dir`, `--keras_model_file` or `--graph_def_file` is required.
+
+*   `--output_file`. Type: string. Specifies the full path of the output file.
+*   `--saved_model_dir`. Type: string. Specifies the full path to the directory
+    containing the SavedModel.
+*   `--keras_model_file`. Type: string. Specifies the full path of the HDF5 file
+    containing the tf.keras model.
+*   `--graph_def_file`. Type: string. Specifies the full path of the input
+    GraphDef file frozen using
+    [freeze_graph.py](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/tools/freeze_graph.py).
+*   `--output_format`. Type: string. Default: `TFLITE`. Specifies the format of
+    the output file. Allowed values:
+    *   `TFLITE`: TensorFlow Lite model format.
+    *   `GRAPHVIZ_DOT`: GraphViz `.dot` format containing a visualization of the
+        graph after graph transformations. *Note: This only works when you set
+        flag `experimental_new_converter=False`. Also, as this format leads to
+        loss of TFLite specific transformations, we recommend that you use
+        `--dump_graphviz_dir` instead to get a final visualization with all
+        graph transformations.*
+*   `--experimental_new_converter`. Type: bool. Default: True (from TF 2.2). To
+    leverage MLIR-based conversion, Google's cutting edge compiler technology
+    for machine learning. This enables conversion of new classes of models,
+    including Mask R-CNN, Mobile BERT, etc and supports models with functional
+    control flow.
+
+The following flags specify optional parameters when using SavedModels.
+
+*   `--saved_model_tag_set`. Type: string. Default: "serve" (for more options,
+    refer to
+    [tag_constants.h](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/cc/saved_model/tag_constants.h)).
+    Specifies a comma-separated set of tags identifying the MetaGraphDef within
+    the SavedModel to analyze. All tags in the tag set must be specified.
+*   `--saved_model_signature_key`. Type: string. Default: "serving_default" (for
+    more options, refer to
+    [tf.compat.v1.saved_model.signature_constants](https://www.tensorflow.org/api_docs/python/tf/compat/v1/saved_model/signature_constants)).
+    Specifies the key identifying the SignatureDef containing inputs and
+    outputs.
+
+## Model flags
+
+*Model flags* provide additional information about the model stored in the input
+file.
+
+*   `--input_arrays`. Type: comma-separated list of strings. Specifies the list
+    of names of input tensors.
+*   `--output_arrays`. Type: comma-separated list of strings. Specifies the list
+    of names of output tensors.
+
+The following flags define properties of the input tensors. Each item in the
+`--input_arrays` flag should correspond to each item in the following flags
+based on index.
+
+*   `--input_shapes`. Type: colon-separated list of comma-separated lists of
+    integers. Each comma-separated list of integers gives the shape of one of
+    the input arrays.
+    *   Example: `--input_shapes=1,60,80,3` for a typical vision model means a
+        batch size of 1, an input image height of 60, an input image width of
+        80, and an input image depth of 3 (representing RGB channels).
+    *   Example: `--input_arrays=foo,bar --input_shapes=2,3:4,5,6` means "foo"
+        has a shape of [2, 3] and "bar" has a shape of [4, 5, 6].
+*   `--std_dev_values`, `--mean_values`. Type: comma-separated list of floats.
+    These specify the (de-)quantization parameters of the input array, when it
+    is quantized. Only needed if `inference_input_type` is `INT8` or `UINT8`.
+    *   The meaning of `mean_values` and `std_dev_values` is as follows: each
+        quantized value in the quantized input array will be interpreted as a
+        mathematical real number (i.e. as an input activation value) according
+        to the following formula:
+        *   `real_value = (quantized_value - mean_value) / std_dev_value`.
+    *   When performing float inference (`--inference_type=FLOAT`) on a
+        quantized input, the quantized input would be immediately dequantized by
+        the inference code according to the above formula, before proceeding
+        with float inference.
+    *   When performing quantized inference (`inference_type` is `INT8` or
+        `UINT8`), no dequantization is performed by the inference code. However,
+        the quantization parameters of all arrays, including those of the input
+        arrays as specified by `mean_value` and `std_dev_value`, determine the
+        fixed-point multipliers used in the quantized inference code.The
+        `mean_value` must be an integer when performing quantized inference.
+
+## Transformation flags
+
+*Transformation flags* specify options of the transformations to be applied to
+the graph, i.e. they specify requested properties that the output file should
+have.
+
+*   `--inference_type`. Type: string. Default: `FLOAT`. Data type of all
+    real-number arrays in the output file except for input arrays (defined by
+    `--inference_input_type`). Must be `{FLOAT, INT8, UINT8}`.
+
+    This flag only impacts real-number arrays including float and quantized
+    arrays. This excludes all other data types including plain integer arrays
+    and string arrays. Specifically:
+
+    *   If `FLOAT`, then real-numbers arrays will be of type float in the output
+        file. If they were quantized in the input file, then they get
+        dequantized.
+    *   If `INT8`, then real-numbers arrays will be quantized as int8 in the
+        output file. If they were float in the input file, then they get
+        quantized.
+    *   If `UINT8`, then real-numbers arrays will be quantized as uint8 in the
+        output file. If they were float in the input file, then they get
+        quantized.
+
+*   `--inference_input_type`. Type: string. Data type of a real-number input
+    array in the output file. By default the `--inference_type` is used as type
+    of all of the input arrays. Flag is primarily intended for generating a
+    float-point graph with a quantized input array. A Dequantized operator is
+    added immediately after the input array. Must be `{FLOAT, INT8, UINT8}`.
+
+    The flag is typically used for vision models taking a bitmap as input but
+    requiring floating-point inference. For such image models, the uint8 input
+    is quantized and the quantization parameters used for such input arrays are
+    their `mean_value` and `std_dev_value` parameters.
+
+*   `--default_ranges_min`, `--default_ranges_max`. Type: floating-point.
+    Default value for the (min, max) range values used for all arrays without a
+    specified range. Allows user to proceed with quantization of non-quantized
+    or incorrectly-quantized input files. These flags produce models with low
+    accuracy. They are intended for easy experimentation with quantization via
+    "dummy quantization".
+
+*   `--post_training_quantize`. Type: boolean. Default: False. Boolean
+    indicating whether to quantize the weights of the converted float model.
+    Model size will be reduced and there will be latency improvements (at the
+    cost of accuracy).
+
+*   `--quantize_to_float16`. Type: boolean. Default: False. Boolean indicating
+    whether to quantize weights to fp16 instead of the default int8 when
+    `--post_training_quantize=True`.
+
+*   `--reorder_across_fake_quant`. Type: boolean. Default: False. Indicates
+    whether to reorder FakeQuant nodes in unexpected locations. Used when the
+    location of the FakeQuant nodes is preventing graph transformations
+    necessary to convert the graph. Results in a graph that differs from the
+    quantized training graph, potentially causing differing arithmetic behavior.
+
+*   `--change_concat_input_ranges`. Type: boolean. Default: False. Boolean to
+    change behavior of min/max ranges for inputs and outputs of the concat
+    operator for quantized models. Changes the ranges of concat operator overlap
+    when true.
+
+*   `--drop_control_dependency`. Type: boolean. Default: True. Indicates whether
+    to drop control dependencies silently. This is due to TensorFlow Lite not
+    supporting control dependencies.
+
+*   `--target_ops`. Type: string. Default: TFLITE_BUILTINS. Experimental flag,
+    subject to change. Set of OpsSet options indicating which converter to use.
+    Options: TF LITE_BUILTINS,SELECT_TF_OPS,TFLITE_BUILTINS_INT8,EXPER
+    IMENTAL_TFLITE_BUILTINS_ACTIVATIONS_INT16_WEIGHTS_INT8 . One or more option
+    may be specified.
+
+*   `--allow_custom_ops`. Type: bool. Default: False. Indicates whether to allow
+    custom operations. When False, any unknown operation is an error. When True,
+    custom ops are created for any op that is unknown. The developer will need
+    to provide these to the TensorFlow Lite runtime with a custom resolver.
+
+*   `--custom_opdefs`. Type: string. String representing a list of custom ops
+    OpDefs delineated with commas that are included in the GraphDef. Required
+    when using custom operations with `--experimental_new_converter`.
+
+## Logging flags
+
+The following flags generate graph visualizations of the graph as
+[GraphViz](https://www.graphviz.org/) `.dot` files at various points during
+graph transformations:
+
+*   `--dump_graphviz_dir`. Type: string. Specifies the full path of the
+    directory to output GraphViz `.dot` files. Outputs the graph immediately
+    after reading in the graph and after all of the transformations have been
+    completed.
+*   `--dump_graphviz_video`. Type: boolean. Outputs GraphViz after every graph
+    transformation. Requires `--dump_graphviz_dir` to be specified.
+
+The following flag controls generating the conversion logs. The conversion log
+includes a protocol buffer of analytics collected during conversion, and an HTML
+file where user can preview the conversion summary.
+
+*   `--conversion_summary_dir`. Type: string. Specifies the full path of the
+    directory to output conversion logs.

tensorflow/lite/g3doc/r1/convert/index.md

@@ -0,0 +1,48 @@
+# TensorFlow Lite converter
+
+The TensorFlow Lite converter takes a TensorFlow model and generates a
+TensorFlow Lite model, which is an optimized
+[FlatBuffer](https://google.github.io/flatbuffers/) (identified by the `.tflite`
+file extension).
+
+Note: This page contains documentation on the converter API for TensorFlow 1.x.
+The API for TensorFlow 2.0 is available
+[here](https://www.tensorflow.org/lite/models/convert).
+
+## Options
+
+The TensorFlow Lite Converter can be used in two ways:
+
+*   [Python API](python_api.md) (**recommended**): Using the Python API makes it
+    easier to convert models as part of a model development pipeline and helps
+    mitigate compatibility issues early on.
+*   [Command line](cmdline_examples.md)
+
+## Workflow
+
+### Why use the 'FlatBuffer' format?
+
+FlatBuffer is an efficient open-source cross-platform serialization library. It
+is similar to [protocol buffers](https://developers.google.com/protocol-buffers)
+used in the TensorFlow model format, with the distinction that FlatBuffers do
+not need a parsing/unpacking step to a secondary representation before data can
+be accessed, avoiding per-object memory allocation. The code footprint of
+FlatBuffers is an order of magnitude smaller than protocol buffers.
+
+### Convert the model
+
+The converter supports the following input formats:
+
+*   [SavedModels](https://www.tensorflow.org/guide/saved_model)
+*   `tf.keras` H5 models.
+*   Frozen `GraphDef` models generated using
+    [freeze_graph.py](https://www.tensorflow.org/code/tensorflow/python/tools/freeze_graph.py).
+*   `tf.Session` models (Python API only).
+
+### Run inference
+
+The TensorFlow Lite model is then deployed to a client device, and the
+TensorFlow Lite interpreter uses the compressed model for on-device inference.
+This conversion process is shown in the diagram below:
+
+![TFLite converter workflow](../images/convert/workflow.svg)

tensorflow/lite/g3doc/r1/convert/python_api.md

@@ -0,0 +1,226 @@
+# Converter Python API guide
+
+This page describes how to convert TensorFlow models into the TensorFlow Lite
+format using the
+[`tf.compat.v1.lite.TFLiteConverter`](https://www.tensorflow.org/api_docs/python/tf/compat/v1/lite/TFLiteConverter)
+Python API. It provides the following class methods based on the original format
+of the model:
+
+*   `tf.compat.v1.lite.TFLiteConverter.from_saved_model()`: Converts a
+    [SavedModel](https://www.tensorflow.org/guide/saved_model).
+*   `tf.compat.v1.lite.TFLiteConverter.from_keras_model_file()`: Converts a
+    [Keras](https://www.tensorflow.org/guide/keras/overview) model file.
+*   `tf.compat.v1.lite.TFLiteConverter.from_session()`: Converts a GraphDef from
+    a session.
+*   `tf.compat.v1.lite.TFLiteConverter.from_frozen_graph()`: Converts a Frozen
+    GraphDef from a file. If you have checkpoints, then first convert it to a
+    Frozen GraphDef file and then use this API as shown [here](#checkpoints).
+
+In the following sections, we discuss [basic examples](#basic) and
+[complex examples](#complex).
+
+## Basic examples <a name="basic"></a>
+
+The following section shows examples of how to convert a basic model from each
+of the supported model formats into a TensorFlow Lite model.
+
+### Convert a SavedModel <a name="basic_savedmodel"></a>
+
+The following example shows how to convert a
+[SavedModel](https://www.tensorflow.org/guide/saved_model) into a TensorFlow
+Lite model.
+
+```python
+import tensorflow as tf
+
+# Convert the model.
+converter = tf.compat.v1.lite.TFLiteConverter.from_saved_model(saved_model_dir)
+tflite_model = converter.convert()
+
+# Save the model.
+with open('model.tflite', 'wb') as f:
+  f.write(tflite_model)
+```
+
+### Convert a Keras model file <a name="basic_keras_file"></a>
+
+The following example shows how to convert a
+[Keras](https://www.tensorflow.org/guide/keras/overview) model file into a
+TensorFlow Lite model.
+
+```python
+import tensorflow as tf
+
+# Convert the model.
+converter = tf.compat.v1.lite.TFLiteConverter.from_keras_model_file('keras_model.h5')
+tflite_model = converter.convert()
+
+# Save the model.
+with open('model.tflite', 'wb') as f:
+  f.write(tflite_model)
+```
+
+The Keras file contains both the model and the weights. A comprehensive example
+is given below.
+
+```python
+import numpy as np
+import tensorflow as tf
+
+# Generate tf.keras model.
+model = tf.keras.models.Sequential()
+model.add(tf.keras.layers.Dense(2, input_shape=(3,)))
+model.add(tf.keras.layers.RepeatVector(3))
+model.add(tf.keras.layers.TimeDistributed(tf.keras.layers.Dense(3)))
+model.compile(loss=tf.keras.losses.MSE,
+              optimizer=tf.keras.optimizers.RMSprop(lr=0.0001),
+              metrics=[tf.keras.metrics.categorical_accuracy],
+              sample_weight_mode='temporal')
+
+x = np.random.random((1, 3))
+y = np.random.random((1, 3, 3))
+model.train_on_batch(x, y)
+model.predict(x)
+
+# Save tf.keras model in H5 format.
+keras_file = 'keras_model.h5'
+tf.keras.models.save_model(model, keras_file)
+
+# Convert the model.
+converter = tf.compat.v1.lite.TFLiteConverter.from_keras_model_file(keras_file)
+tflite_model = converter.convert()
+
+# Save the model.
+with open('model.tflite', 'wb') as f:
+  f.write(tflite_model)
+```
+
+### Convert a GraphDef from a session <a name="basic_graphdef_sess"></a>
+
+The following example shows how to convert a GraphDef from a `tf.Session` object
+into a TensorFlow Lite model .
+
+```python
+import tensorflow as tf
+
+img = tf.placeholder(name='img', dtype=tf.float32, shape=(1, 64, 64, 3))
+var = tf.get_variable('weights', dtype=tf.float32, shape=(1, 64, 64, 3))
+val = img + var
+out = tf.identity(val, name='out')
+
+with tf.Session() as sess:
+  sess.run(tf.global_variables_initializer())
+
+  # Convert the model.
+  converter = tf.compat.v1.lite.TFLiteConverter.from_session(sess, [img], [out])
+  tflite_model = converter.convert()
+
+  # Save the model.
+  with open('model.tflite', 'wb') as f:
+    f.write(tflite_model)
+```
+
+### Convert a Frozen GraphDef from file <a name="basic_graphdef_file"></a>
+
+The following example shows how to convert a Frozen GraphDef (or a frozen
+graph), usually generated using the
+[freeze_graph.py](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/tools/freeze_graph.py)
+script, into a TensorFlow Lite model.
+
+The example uses
+[Mobilenet_1.0_224](https://storage.googleapis.com/download.tensorflow.org/models/mobilenet_v1_1.0_224_frozen.tgz).
+
+```python
+import tensorflow as tf
+
+# Convert the model.
+converter = tf.compat.v1.lite.TFLiteConverter.from_frozen_graph(
+    graph_def_file='/path/to/mobilenet_v1_1.0_224/frozen_graph.pb',
+                    # both `.pb` and `.pbtxt` files are accepted.
+    input_arrays=['input'],
+    input_shapes={'input' : [1, 224, 224,3]},
+    output_arrays=['MobilenetV1/Predictions/Softmax']
+)
+tflite_model = converter.convert()
+
+# Save the model.
+with open('model.tflite', 'wb') as f:
+  f.write(tflite_model)
+```
+
+#### Convert checkpoints <a name="checkpoints"></a>
+
+1.  Convert checkpoints to a Frozen GraphDef as follows
+    (*[reference](https://laid.delanover.com/how-to-freeze-a-graph-in-tensorflow/)*):
+
+    *   Install [bazel](https://docs.bazel.build/versions/master/install.html)
+    *   Clone the TensorFlow repository: `git clone
+        https://github.com/tensorflow/tensorflow.git`
+    *   Build freeze graph tool: `bazel build
+        tensorflow/python/tools:freeze_graph`
+        *   The directory from which you run this should contain a file named
+            'WORKSPACE'.
+        *   If you're running on Ubuntu 16.04 OS and face issues, update the
+            command to `bazel build -c opt --copt=-msse4.1 --copt=-msse4.2
+            tensorflow/python/tools:freeze_graph`
+    *   Run freeze graph tool: `bazel run tensorflow/python/tools:freeze_graph
+        --input_graph=/path/to/graph.pbtxt --input_binary=false
+        --input_checkpoint=/path/to/model.ckpt-00010
+        --output_graph=/path/to/frozen_graph.pb
+        --output_node_names=name1,name2.....`
+        *   If you have an input `*.pb` file instead of `*.pbtxt`, then replace
+            `--input_graph=/path/to/graph.pbtxt --input_binary=false` with
+            `--input_graph=/path/to/graph.pb`
+        *   You can find the output names by exploring the graph using
+            [Netron](https://github.com/lutzroeder/netron) or
+            [summarize graph tool](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/tools/graph_transforms#inspecting-graphs).
+
+2.  Now [convert the Frozen GraphDef file](#basic_graphdef_file) to a TensorFlow
+    Lite model as shown in the example above.
+
+## Complex examples <a name="complex"></a>
+
+For models where the default value of the attributes is not sufficient, the
+attribute's values should be set before calling `convert()`. Run
+`help(tf.compat.v1.lite.TFLiteConverter)` in the Python terminal for detailed
+documentation on the attributes.
+
+### Convert a quantize aware trained model <a name="complex_quant"></a>
+
+The following example shows how to convert a quantize aware trained model into a
+TensorFlow Lite model.
+
+The example uses
+[Mobilenet_1.0_224](https://storage.googleapis.com/download.tensorflow.org/models/mobilenet_v1_1.0_224_frozen.tgz).
+
+```python
+import tensorflow as tf
+
+# Convert the model.
+converter = tf.compat.v1.lite.TFLiteConverter.from_frozen_graph(
+    graph_def_file='/path/to/mobilenet_v1_1.0_224/frozen_graph.pb',
+    input_arrays=['input'],
+    input_shapes={'input' : [1, 224, 224,3]},
+    output_arrays=['MobilenetV1/Predictions/Softmax'],
+)
+converter.quantized_input_stats = {'input' : (0., 1.)}  # mean, std_dev (input range is [-1, 1])
+converter.inference_type = tf.int8 # this is the recommended type.
+# converter.inference_input_type=tf.uint8 # optional
+# converter.inference_output_type=tf.uint8 # optional
+tflite_model = converter.convert()
+
+# Save the model.
+with open('quantized_model.tflite', 'wb') as f:
+  f.write(tflite_model)
+```
+
+## Convert models from TensorFlow 1.12 <a name="pre_tensorflow_1.12"></a>
+
+Reference the following table to convert TensorFlow models to TensorFlow Lite in
+and before TensorFlow 1.12. Run `help()` to get details of each API.
+
+TensorFlow Version | Python API
+------------------ | ---------------------------------
+1.12               | `tf.contrib.lite.TFLiteConverter`
+1.9-1.11           | `tf.contrib.lite.TocoConverter`
+1.7-1.8            | `tf.contrib.lite.toco_convert`