PyCoral API Documentation

The PyCoral library is organized into several functional modules designed for working with Coral Edge TPU models. Key functional areas include:

• Adapters: High-level interfaces for common tasks like image classification (pycoral.adapters.classify) and object detection (pycoral.adapters.detect).
• Utils: Utility modules for dataset management (pycoral.utils.dataset) and Edge TPU hardware interaction (pycoral.utils.edgetpu).
• Pipeline: Advanced execution patterns, such as the pycoral.pipeline.pipelined_model_runner for optimized model inference.
• Learning: Modules for model fine-tuning and adaptation, including backpropagation-based methods (pycoral.learn.backprop.softmax_regression) and imprinting engines (pycoral.learn.imprinting.engine).

PyCoral provides an API for running inferences and performing on-device transfer learning with TensorFlow Lite models on Coral devices.

• Inference Guide: For a guide on running inference on the Edge TPU with Python, see Run inference on the Edge TPU with Python.
• API Reference: Detailed technical documentation is available in the PyCoral API reference.
• Code Examples: Practical usage examples are located in the examples/ directory of this repository. See the examples README for specific instructions on running them.

PyCoral uses specific data classes to represent model outputs:

• pycoral.adapters.classify.Class: Represents a single classification result, typically containing the label/name of the category.
• pycoral.adapters.detect.Object: Represents a single detected entity in an image.
• pycoral.adapters.detect.BBox: Represents the bounding box of a detected object, providing the spatial coordinates of the detection.

When building the documentation with makedocs.sh, you can choose different output formats:

• Local Preview: Run bash makedocs.sh -p. The files are output to _build/preview/. You can view them by opening the index.html file in a browser.
• Web Publishing: Run bash makedocs.sh -w. The files are output to _build/web/ and are designed for publishing on the official Coral website.

# For local viewing
bash makedocs.sh -p

# For web publishing
bash makedocs.sh -w

The examples/install_requirements.sh script automates the downloading of models and assets required for the examples.

• To download requirements for all examples, run the script without arguments.
• To download requirements for a specific example, pass the filename of that example to the script.

# Download requirements for all examples
bash examples/install_requirements.sh

# Download requirements for a specific example (replace <filename> with the actual file)
bash examples/install_requirements.sh <filename>

If you need to build the library yourself, ensure you have version-matching builds of libcoral and libedgetpu. These are submodules of the pycoral repository and must share the same TENSORFLOW_COMMIT value.

Prerequisites

• Docker must be installed (the build process is Docker-based).
• Submodules (libcoral and libedgetpu) must be initialized.

Build Steps

1. Clone the repository with submodules:

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

   Or, if already cloned:

   cd pycoral
   git submodule init && git submodule update

2. Build the pybind11-based native layer using the provided script:

   scripts/build.sh

3. Generate and install the Python wheel:

   make wheel
   pip3 install $(ls dist/*.whl)

To install the prebuilt PyCoral library, follow the instructions at coral.ai/software/.

Important for Debian users: If you are using a Debian-based system, you must install the library using apt-get rather than pip. Using pip install may cause compatibility issues with other Coral libraries that are required to be installed via apt-get.

The pycoral.adapters.classify module provides utilities for extracting classification results from a model's output.

Key functions:

• get_scores(model, image): Returns the raw scores for each class.
• get_classes(model, image): Returns the class labels (as Class objects) for the top predictions.
• get_classes_from_scores(model, scores, threshold): Returns class labels based on a provided list of scores and a minimum threshold.
• num_classes(model): Returns the total number of classes the model is trained to recognize.

import pycoral.adapters.classify as classify

# Example usage (conceptual)
scores = classify.get_scores(model, image)
classes = classify.get_classes(model, image)
count = classify.num_classes(model)

The pycoral.adapters.detect module provides utilities for extracting detected objects from a model's output.

Key functions:

• get_objects(model, image): Returns a list of Object instances found in the image.

Each detected Object contains information about the detection, including its bounding box (BBox). The BBox class provides methods to access the coordinates of the detected area.

import pycoral.adapters.detect as detect

# Example usage (conceptual)
objects = detect.get_objects(model, image)
for obj in objects:
    bbox = obj.bbox
    # Access bbox coordinates...