2.4 Using Python

This section introduces key points for using Python on the Bianbu ROS system, including system vs virtual environments, package management, and hardware-related Python libraries.

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

When you open a terminal, you are in the system's default Python environment. You can start the interpreter by typing:
```
python3
```
Exit the interpreter with Ctrl + D.
Use which python3 to check the location of the Python interpreter:
```
bianbu@bianbu:~$ which python3
/usr/bin/python3
```
Managing Packages
- Python packages in the system environment are managed via apt, not pip.
- Example: to install the scientific computing library scipy:
```
sudo apt install python3-scipy
```
- To search for Python packages published via apt, use apt search. In most cases, Python packages use prefix python3-; for example, python3-numpy corresponds to the Python numpy package.

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 a container to hold the Python environment. 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 by using pip list to view the list of installed packages:
```
(myenv) ➜  ~ pip list
Package Version
------- -------
pip     24.0
```
The list should be much shorter than the packages installed in the system Python. You can now safely install packages using pip. Any packages installed with pip inside the virtual environment will only be installed in that environment. Within the virtual environment, the python or python3 command will automatically use the Python packages from the virtual environment instead of the system Python packages.
Upgrade pip To ensure proper use of pip, upgrade pip to the lastest version:
```
pip install --upgrade pip
```

Install packages As example below, to 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 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 a problem 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 save time and avoid build errors, SpacemiT provides precompiled wheel files for common Python packages (for example, 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 package you want to install.

Using onnxruntime

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

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

1. Create a Virtual Environment

python3 -m venv ort_env

Activate it:

source ort_env/bin/activate

2. Install `spacemit_ort`

pip install spacemit_ort

If successful, the terminal will show an installation summary similar to this:

3. 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']

Press Ctrl + D to leave Python.

4. Installing Demo Dependencies

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

5. Download Models, Labels, and Images

SpacemiT provide 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 the demo 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

6. Write 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)

7. 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.

1. Install system dependencies

Run this command to install gpiozero with the necessary system permissions for GPIO access:

sudo apt install python3-gpiozero

2. 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 guide: Using GPIO from Python.

2.4 Using Python

Common Commands Summary​

Using Python in the System Environment​

Using a Virtual Environment​

Configuring SpacemiT PyPI Source​

Using onnxruntime​

1. Create a Virtual Environment​

2. Install spacemit_ort​

3. Verify the Installation​

4. Installing Demo Dependencies​

5. Download Models, Labels, and Images​

6. Write the Demo Script​

7. Run the Demo​

API Reference​

Using gpiozero​

1. Install system dependencies​

2. Install inside Virtual Environment​