# TF Lite Extractor

This tool is used to extract a smaller subgraph from a larger graph.

The **tflite-extractor** can be used in the following modes:

1. Extract a subgraph that is delimited by a list of **input tensors** and a list of **output tensors**.
    - In this case the extractor will extract only one subgraph.
   ```
   tflite-extractor --input <input_path> --output <output_path> --input-tensors <tensor_list> --output-tensors <tensor_list>
   ```
2. Extract a subgraph defined by a list of **operators**.
    - In this case the extractor will identify clusters of adjacent operators and will extract for each cluster a
      separate subgraph in the same model.
    - In this case the extractor will extract one or multiple subgraphs depending on the adjacency pattern of the
      operators.
   ```
   tflite-extractor --input <input_path> --output <output_path> --operators <operator_list>
   ```
3. Extract a subgraph defined by a contiguous range (start, stop) of **operators**.
    - In this case the extractor will identify clusters of adjacent operators and will extract for each cluster a
      separate subgraph in the same model.
    - In this case the extractor will extract one or multiple subgraphs depending on the adjacency pattern of the
      operators.
   ```
   tflite-extractor --input <input_path> --output <output_path> --operators-between <operator-start>,<operator-stop>
   ```

The parameters:

- `input` - The path of the input TensorFlowLite model (mandatory).
- `output` - The path of the output extracted TensorFlowLite model (optional). If not provided the output model will be
  written in the same directory as the input model with the suffix **_extracted** added to the name.
- `input-tensors`
    - Input tensors which limit the extracted subgraph (list of comma separated names or indices).
    - The input tensors must be variables and are NOT allowed to be constants or stateful (persistent) variables.
- `output-tensors`
    - Output tensors which limit the extracted subgraph (list of comma separated names or indices).
    - The output tensors must be variables and are NOT allowed to be constants or stateful (persistent) variables.
- `operators`
    - Operators which should be included in the extracted subgraph (list of comma separated names or indices).
    - Operators are identified with the name of the output tensor or the index (location) in the model.
    - For example use `--operators 13,14` or `--operators name13,name14` to extract the operator instances whose output
      tensors have locations **13**,**14** and names **name13** and **name14**.
- `operators-between`
    - Operator range which should be included in the extracted subgraph (pair of comma separated names or indices). The
      operator start (included) and operator stop (included) must be specified.
    - Operators are identified with the name of the output tensor or the index (location) in the model.
    - For example use `--operators-between 0,14` or `--operators-between name0,name14` to extract all the operators
      between those two whose output tensors have locations **0**,**14** and names **name0** and **name14**.
- `keep-graphs` - Option to keep the original graphs used for extraction in the model. Default is false.
- `graph-name` - In case the model has multiple graphs this is the name of the graph used for extraction. In case the
  model has a single graph this parameter is not used.
- `allow-duplicated-inputs` - In case an operator consumes the same tensor multiple times, decide wether it needs to be
  duplicated and show up as different tensors.

Note that for the above options:

- Tensors are identified either by their index (e.g. the `location` attribute that you can view in the Netron
  visualizer) or their name (the `name` attribute that you can view in the Netron visualizer).
    - To be noted that tensor names are not guaranteed to be unique so in order to avoid any potential ambiguity it is
      recommended to use the index and not the name because the tensor index is unique.
- Operators are identified either by their index (e.g. the `location` attribute that you can view in the Netron
  visualizer) or the name of the output tensor (since operators do not have a standalone `name` attribute).
    - If the operator has multiple output tensors then the name of the first output tensor will be considered as
      operator name identifier.