Skip to content

Commit

Permalink
Better examples in Frogfish release
Browse files Browse the repository at this point in the history
  • Loading branch information
dmitriykovalev committed Dec 22, 2020
1 parent 850e324 commit 276d0d6
Show file tree
Hide file tree
Showing 12 changed files with 266 additions and 42 deletions.
37 changes: 32 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,41 @@
# pycoral
# PyCoral API

This repository contains an easy-to-use Python API to work with Coral devices:
This repository contains an easy-to-use Python API to run inferences and
perform on-device transfer learning with TensorFlow Lite models on
[Coral devices](https://coral.ai/products/).

* [Dev Board](https://coral.ai/products/dev-board/)
* [USB Accelerator](https://coral.ai/products/accelerator/)
You can install this library with the Python wheels listed at
[coral.ai/software/](https://coral.ai/software/#pycoral-api).

## Documentation and examples

To learn more about how to use the PyCoral API, see our guide to [Run inference
on the Edge TPU with Python](https://coral.ai/docs/edgetpu/tflite-python/) and
check out the [PyCoral API reference](https://coral.ai/docs/reference/py/).

Several Python examples are available in the `examples/` directory. For
instructions, see the [examples README](
https://github.com/google-coral/pycoral/tree/master/examples#pycoral-api-examples).

You can run inference and do transfer learning.

## Compilation

To build the library yourself, follow these steps:

1. Clone this repo and include submodules:

```
git clone --recurse-submodules https://github.com/google-coral/pycoral
```
If you already cloned without the submodules. You can add them with this:
```
cd pycoral
git submodule init && git submodule update
```
1. Run `scripts/build.sh` to build pybind11-based native layer for different
Linux architectures. Build is Docker-based, so you need to have it
installed.
Expand Down
38 changes: 21 additions & 17 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,35 @@ This directory contains several examples that show how to use the
[PyCoral API](https://coral.ai/docs/edgetpu/api-intro/) to perform
inference or on-device transfer learning.

## Get the code
## Run the examples

Before you begin, you must
[set up your Coral device](https://coral.ai/docs/setup/).
1. [Set up your Coral device](https://coral.ai/docs/setup/) (includes steps
to install this PyCoral library).

Then simply clone this repo:
2. Clone this repo onto the host device (onto your Coral board, or if using
a Coral accelerator, then onto the host system):

```
git clone https://github.com/google-coral/pycoral
```
```
git clone https://github.com/google-coral/pycoral
```

For more pre-compiled models, see [coral.ai/models](https://coral.ai/models/).
3. Download the required model and other files required to run each sample,
using the `install_requirements.sh` script. Pass this script the filename you
want to run and it will download just the files for that example. Or exclude the
filename to download the files for all examples:

## Run the example code
```
cd pycoral

Each `.py` file includes documentation at the top with an example command you
can use to run it. Notice that they all use a pre-compiled model from the
`test_data` directory, which is a submodule dependency for this repo. So if you
want to use those files, you can clone them within the `pycoral` repo like this:
bash examples/install_requirements.sh
```

```
cd pycoral
4. Then run the example command shown at the top of each `.py` file to run
the code (using the files you just downloaded). Some examples also require
additional downloads, which are specified in the code comments at the top of the
file.

git submodule init && git submodule update
```
For more pre-compiled models, see [coral.ai/models](https://coral.ai/models/).

For more information about building models and running inference on the Edge
TPU, see the [Coral documentation](https://coral.ai/docs/).
10 changes: 6 additions & 4 deletions examples/backprop_last_layer.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,21 @@
2) curl http://download.tensorflow.org/example_images/flower_photos.tgz \
| tar xz -C /tmp/retrain
3) Start training:
3) bash examples/install_requirements.sh backprop_last_layer.py
python3 backprop_last_layer.py \
4) Start training:
python3 examples/backprop_last_layer.py \
--data_dir /tmp/retrain/flower_photos \
--embedding_extractor_path \
test_data/mobilenet_v1_1.0_224_quant_embedding_extractor_edgetpu.tflite
Weights for retrained last layer will be saved to /tmp/retrain/output by
default.
4) Run an inference with the new model:
5) Run an inference with the new model:
python3 classify_image.py \
python3 examples/classify_image.py \
--model /tmp/retrain/output/retrained_model_edgetpu.tflite \
--label /tmp/retrain/output/label_map.txt
--input test_data/sunflower.bmp
Expand Down
4 changes: 3 additions & 1 deletion examples/classify_image.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@
Example usage:
```
python3 classify_image.py \
bash examples/install_requirements.sh classify_image.py
python3 examples/classify_image.py \
--model test_data/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
--labels test_data/inat_bird_labels.txt \
--input test_data/parrot.jpg
Expand Down
6 changes: 4 additions & 2 deletions examples/detect_image.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,10 @@
Example usage:
```
python3 detect_image.py \
--model test_data/mobilenet_ssd_v2_coco_quant_postprocess_edgetpu.tflite \
bash examples/install_requirements.sh detect_image.py
python3 examples/detect_image.py \
--model test_data/ssd_mobilenet_v2_coco_quant_postprocess_edgetpu.tflite \
--labels test_data/coco_labels.txt \
--input test_data/grace_hopper.bmp \
--output ${HOME}/grace_hopper_processed.bmp
Expand Down
17 changes: 11 additions & 6 deletions examples/imprinting_learning.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,24 @@
This downloads 10 categories, 20 images for each category, saving it into
a directory named `open_image_v4_subset`.
2) Start training the new classification model:
2) Get model files:
```
bash examples/install_requirements.sh imprinting_learning.py
```
3) Start training the new classification model:
```
python3 imprinting_learning.py \
python3 examples/imprinting_learning.py \
--model_path test_data/mobilenet_v1_1.0_224_l2norm_quant_edgetpu.tflite \
--data open_image_v4_subset \
--output ${HOME}/my_model.tflite
```
3) Run an inference with the new model:
4) Run an inference with the new model:
```
python3 classify_image.py \
--model my_model.tflite \
--label my_model.txt \
python3 examples/classify_image.py \
--model ${HOME}/my_model.tflite \
--label ${HOME}/my_model.txt \
--input test_data/cat.bmp
```
Expand Down
161 changes: 161 additions & 0 deletions examples/install_requirements.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
#!/bin/bash
#
# Download models, labels, and inputs for example code
#
# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly TEST_DATA_URL="https://github.com/google-coral/test_data/raw/master/"
readonly TEST_DATA_DIR="${SCRIPT_DIR}/../test_data"

download() {
for file in $@; do
# Verify the file exists
response="$(curl -Lso /dev/null -w "%{http_code}" \
"${TEST_DATA_URL}/${file}")"
if [[ "${response}" = "200" ]]; then
echo "DOWNLOAD: ${file}"
# Handle subdirectories in the file path (such as pipeline files)
if [[ "${file}" == *"/"* ]]; then
subdir="$(dirname "${file}")"
mkdir -p "${TEST_DATA_DIR}/${subdir}"
(cd "${TEST_DATA_DIR}/${subdir}" && curl -OL "${TEST_DATA_URL}/${file}")
else
(cd "${TEST_DATA_DIR}" && curl -OL "${TEST_DATA_URL}/${file}")
fi
else
echo "NOT FOUND: ${file}"
fi
done
}

function get_backprop() {
download \
"mobilenet_v1_1.0_224_quant_embedding_extractor_edgetpu.tflite" \
"sunflower.bmp"
}

function get_classification() {
download \
"mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite" \
"mobilenet_v2_1.0_224_inat_bird_quant.tflite" \
"inat_bird_labels.txt" \
"parrot.jpg"
}

function get_detection() {
download \
"ssd_mobilenet_v2_coco_quant_postprocess_edgetpu.tflite" \
"coco_labels.txt" \
"grace_hopper.bmp"
}

function get_imprinting() {
download \
"mobilenet_v1_1.0_224_l2norm_quant_edgetpu.tflite" \
"cat.bmp"
}

function get_pipelining() {
download \
"pipeline/inception_v3_299_quant_segment_0_of_2_edgetpu.tflite" \
"pipeline/inception_v3_299_quant_segment_1_of_2_edgetpu.tflite" \
"imagenet_labels.txt" \
"parrot.jpg"
}

function get_segmentation() {
download \
"deeplabv3_mnv2_pascal_quant_edgetpu.tflite" \
"bird.bmp"
}

function get_small_detection() {
download \
"ssd_mobilenet_v2_coco_quant_no_nms_edgetpu.tflite" \
"coco_labels.txt" \
"kite_and_cold.jpg"
}

function get_two_models() {
download \
"mobilenet_v2_1.0_224_quant_edgetpu.tflite" \
"ssd_mobilenet_v2_face_quant_postprocess_edgetpu.tflite" \
"parrot.jpg"
}

function get_all() {
echo "Download all files..."
get_backprop
get_classification
get_detection
get_imprinting
get_pipelining
get_segmentation
get_small_detection
get_two_models
}

function usage() {
echo -n "Usage:
install_requirements.sh [filename]
Provide the name of an example file in this directory to
download only the files required for that example.
If no filename provided, it downloads all example files.
All files go into the pycoral/test_data/ directory."
}

function main() {
if [[ "$#" -gt 1 ]]; then
usage
exit
elif [[ "$#" -eq 0 ]]; then
get_all
exit
fi

case "$1" in
backprop_last_layer.py)
get_backprop
;;
classify_image.py)
get_classification
;;
detect_image.py)
get_detection
;;
imprinting_learning.py)
get_imprinting
;;
model_pipelining_classify_image.py)
get_pipelining
;;
semantic_segmentation.py)
get_segmentation
;;
small_object_detection.py)
get_small_detection
;;
two_models_inference.py)
get_two_models
;;
*)
usage
;;
esac
}

main "$@"
9 changes: 6 additions & 3 deletions examples/model_pipelining_classify_image.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,13 @@
install the Edge TPU runtime (`libedgetpu.so`) and `tflite_runtime`. For
device setup instructions, see g.co/coral/setup.
Example usage (use `install_requirements.sh` to get these files):
Example usage:
```
python3 model_pipelining_classify_image.py \
--models test_data/inception_v3_299_quant_segment_%d_of_2_edgetpu.tflite \
bash examples/install_requirements.sh model_pipelining_classify_image.py
python3 examples/model_pipelining_classify_image.py \
--models \
test_data/pipeline/inception_v3_299_quant_segment_%d_of_2_edgetpu.tflite \
--labels test_data/imagenet_labels.txt \
--input test_data/parrot.jpg
```
Expand Down
6 changes: 5 additions & 1 deletion examples/semantic_segmentation.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,15 @@
The following command runs this script and saves a new image showing the
segmented pixels at the location specified by `output`:
```
bash examples/install_requirements.sh semantic_segmentation.py
python3 examples/semantic_segmentation.py \
--model test_data/deeplabv3_mnv2_pascal_quant_edgetpu.tflite \
--input test_data/bird.bmp \
--keep_aspect_ratio \
--output ${HOME}/segmentation_result.jpg
```
"""

import argparse
Expand Down Expand Up @@ -126,7 +130,7 @@ def main():
output_img.paste(resized_img, (0, 0))
output_img.paste(mask_img, (width, 0))
output_img.save(args.output)
print('Please check ', args.output)
print('Done. Results saved at', args.output)

if __name__ == '__main__':
main()
Loading

0 comments on commit 276d0d6

Please sign in to comment.