2.4 Python Usage Guide

This guide covers the essentials of using Python on the Bianbu ROS system.

Common Commands Summary

Function	Command
Install virtual environment tools	`sudo apt install python3-venv python3-pip`
Create virtual environment	`python3 -m venv myenv`
Activate virtual environment	`source myenv/bin/activate`
Upgrade pip	`pip install --upgrade pip`
Set PyPI source	`pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple` `pip config set global.extra-index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple`
Deactivate virtual environment	`deactivate`

Using Python in the System Environment

The Bianbu ROS system includes a default Python interpreter. You can access it by typing python3 in the terminal:

Exit the interpreter with Ctrl + D.

Check Python Location Use which python3 to find the Python interpreter’s path:
```
bianbu@bianbu:~$ which python3

# Output example
/usr/bin/python3
```
Install Packages in the System Environment Use apt (not pip) to manage Python packages in the system environment. For example, to install the scientific computing library scipy:
```
sudo apt install python3-scipy
```
To find available Python packages, use:
```
apt search python3-
```
Example: The numpy package is listed as python3-numpy.

Note: Do not use pip to install packages in the system environment to avoid conflicts.

Using a Virtual Environment

To use a virtual environment, create an isolated environment to hold your Python packages. There are several ways to do this, depending on how you plan to use Python. Here, we use the venv tool as an example.

Install venv in the system Python environment:
```
sudo apt install python3-venv python3-pip
```
Run the following command to create a folder for your virtual environment (replace myenv with any name you prefer):
```
python3 -m venv myenv
```
Execute the bin/activate script inside the virtual environment folder to enter the virtual environment:
```
source myenv/bin/activate
```
Your terminal prompt changes to indicate the active environment:
```
(myenv) ➜  ~
```
The myenv prefix in the command prompt indicates that the current terminal session is inside the virtual environment named myenv.
To verify the virtual environment, use pip list to view the list of installed packages:
```
(myenv) ➜  ~ pip list
Package Version
------- -------
pip     24.0
```
The list should be shorter than the list of packages installed in the system Python environment.
You can now safely install Python packages using pip. Here are the key points to remember:
- Packages installed with pip will exist only in your current virtual environment. Your system-wide Python environment will not be affected.
- When your virtual environment is activated:
  - The python and python3 commands will automatically use the virtual environment's interpreter
  - All imported packages will come from the virtual environment, not the system
To ensure proper use of pip, upgrade it to the latest version:
```
pip install --upgrade pip
```
Example: install the wheel package using pip:
```
(myenv) ➜  ~ pip install wheel
Collecting wheel
  Downloading wheel-0.44.0-py3-none-any.whl.metadata (2.3 kB)
Downloading wheel-0.44.0-py3-none-any.whl (67 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 67.1/67.1 kB 27.9 kB/s eta 0:00:00
Installing collected packages: wheel
Successfully installed wheel-0.44.0
```
Verify installation in Python by running python3 and then importing the installed module:
```
(myenv) ➜  ~ python3
Python 3.12.3 (main, Apr 10 2024, 05:33:47) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import wheel
```

Verify the interpreter path by using the sys module to check that the current interpreter path matches the expected virtual environment:

>>> import sys
>>> print("Current Python interpreter path:", sys.executable)
Current Python interpreter path: /home/zq-card/myenv/bin/python3

Use exit() to quit the interactive mode:
```
>>> exit()
(myenv) ➜  ~
```
To exit the virtual environment, run the following command:
```
(myenv) ➜  ~ deactivate
```

Configuring SpacemiT PyPI Source

When installing Python packages in a virtual environment using pip, you may encounter the following issue on RISC-V platforms:

If no precompiled .whl (wheel) file is available, pip will download the source code and try to build it locally.
Packages that include C/C++ code can take a long time to compile and may fail if system dependencies are missing.

To improve efficiency and avoid build errors, SpacemiT provides precompiled wheel files for common Python packages such as numpy. This section explains how to configure pip to use SpacemiT’s package source.

Configure as an extra source

By default, pip supports one main index-url (the main package source). You can add an additional source using extra-index-url.

Run the following commands to add the SpacemiT source as an additional location to search for packages:

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.extra-index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple

You can verify the configuration with:

pip config list

If successful, you will see output similar to:

global.extra-index-url='https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple'
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'

Install PyPI Packages

To install a package from the SpacemiT source, use the following command:
```
pip install --index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple <package_name>
```
Replace <package_name> with the desired package.

Using ONNX Runtime

Please make sure you have completed the previous sections before proceeding.

This section explains how to set up onnxruntime with SpacemiT’s custom execution provider (spacemit_ort), verify the installation, and run a sample inference demo.

Create a Virtual Environment

python3 -m venv ort_env

Activate it:

source ort_env/bin/activate

Install spacemit_ort
```
pip install spacemit_ort
```
If successful, the terminal will show an installation summary similar to this:
Verify the Installation
- Launch Python inside the virtual environment with the following commands:
```
python
>>> import onnxruntime as ort
>>> import spacemit_ort
>>> available_providers = ort.get_available_providers()
>>> print(available_providers)
['SpaceMITExecutionProvider', 'CPUExecutionProvider']
```
  If everything is installed correctly, the output should include: ['SpaceMITExecutionProvider', 'CPUExecutionProvider']
- Exit Python with Ctrl + D.

Installing Demo Dependencies

source ort_env/bin/activate
pip install opencv-python pillow matplotlib onnx

Download Models, Labels, and Images

SpacemiT provides quantized open-source models, which can be downloaded from ModelZoo.

In theory, ONNX models can also be used for inference, but their performance may be slightly lower than our quantized versions.

Download and extract the model and related files:

wget https://archive.spacemit.com/spacemit-ai/ModelZoo/classification.tar.gz
tar -zxf classification.tar.gz
wget -P classification https://archive.spacemit.com/spacemit-ai/ModelZoo/classification/kitten.jpg
wget -P classification https://archive.spacemit.com/spacemit-ai/ModelZoo/classification/synset.txt

Run the Demo Script

Create a file called demo.py:

vim demo.py

Paste the following code into it:

import onnx
import numpy as np
import onnxruntime as ort
import spacemit_ort
from PIL import Image
import cv2
import matplotlib.pyplot as plt
import time

# Image loading
def get_image(path, show=False):
   with Image.open(path) as img:
     img = np.array(img.convert('RGB'))
   if show:
     plt.imshow(img)
     plt.axis('off')
   return img

# Image Preprocessing
# Preprocess the input image for inference -> scale to 0~1, resize to 256x256, take a 224x224 center crop, normalize the image, transpose to NCHW format, convert to float32, and add a batch dimension.
def preprocess(img):
 img = img / 255.
 img = cv2.resize(img, (256, 256))
 h, w = img.shape[0], img.shape[1]
 y0 = (h - 224) // 2
 x0 = (w - 224) // 2
 img = img[y0 : y0+224, x0 : x0+224, :]
 img = (img - [0.485, 0.456, 0.406]) / [0.229, 0.224, 0.225]
 img = np.transpose(img, axes=[2, 0, 1])
 img = img.astype(np.float32)
 img = np.expand_dims(img, axis=0)
 return img

# Prediction
def predict(path):
 img = get_image(path, show=True)
 img = preprocess(img)
 ort_inputs = {session.get_inputs()[0].name: img}
 start = time.time()
 preds = session.run(None, ort_inputs)[0]
 end = time.time()
 preds = np.squeeze(preds)
 a = np.argsort(preds)[::-1]
 print('time=%.2fms; class=%s; probability=%f' % (round((end-start) * 1000, 2), labels[a[0]], preds[a[0]]))

# Load model, labels, and run inference
with open('classification/synset.txt', 'r') as f:
 labels = [l.rstrip() for l in f]

# Set the number of inference threads
session_options = ort.SessionOptions()
session_options.intra_op_num_threads = 2

# IMPORTANT: Specified SpaceMITExecutionProvider providers
session = ort.InferenceSession('classification/resnet50/resnet50.q.onnx', sess_options=session_options, providers=["SpaceMITExecutionProvider"])

img_path = 'classification/kitten.jpg'
predict(img_path)

Run the Demo

source ort_env/bin/activate
python demo.py

Expected output (your numbers may vary slightly):

time=95.15ms; class=n02123045 tabby, tabby cat; probability=13.498201

API Reference

For more information about available APIs, see the official API Overview.

Using gpiozero

The Python gpiozero library can be used to control the GPIO pins on the board, enabling basic input/output, PWM, and other functions.

Install system dependencies

Run this command to install gpiozero with the necessary system permissions for GPIO access:
```
sudo apt install python3-gpiozero
```

Install inside Virtual Environment

# Create a virtual environment named gpioenv
python3 -m venv gpioenv

# Activate the environment
source gpioenv/bin/activate

# Install gpiozero using the SpacemiT package source
pip install gpiozero --index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple

For a detailed usage guide, see the official section Using GPIO from Python.

Common Commands Summary​

Using Python in the System Environment​

Using a Virtual Environment​

Configuring SpacemiT PyPI Source​

Using ONNX Runtime​

API Reference​

Using gpiozero​