This tutorial will guide you from scratch through setting up the SpireCV-Pro intelligent perception platform in a Windows WSL2 environment and running a YOLO11 object detection visualization example.

01 Install WSL2 + Ubuntu 22.04

1.1 Enable WSL

Open PowerShell as administrator and run:

wsl --install

 This command automatically enables WSL2 and installs the default Ubuntu distribution. Restart your computer after the installation completes.

If an older version of WSL is already installed, first upgrade it to WSL2:

wsl --update wsl --set-default-version 2

1.2 Install Ubuntu 22.04

If Ubuntu 22.04 was not installed automatically in the previous step, install it manually:

wsl --install -d Ubuntu-22.04

 During installation, you will be prompted to create a username and password (remember this password; sudo will be required later).

1.3 Enter WSL

In PowerShell, enter:

wsl

 This enters the Ubuntu 22.04 terminal. All subsequent operations are performed in this terminal.

02 Install CUDA for WSL

WSL2 can directly use the NVIDIA driver on the Windows host, so you do not need to install the GPU driver inside WSL.

2.1 Confirm that the NVIDIA driver is installed on Windows

Run the following in Windows PowerShell:

nvidia-smi

 If GPU information is displayed, the driver is ready. If not, download and install it from NVIDIA's official website.

2.2 Install the CUDA Toolkit inside WSL

Return to the WSL terminal and run the following commands to install CUDA 12.6 (the WSL-specific version):

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600 wget https://developer.download.nvidia.com/compute/cuda/12.8.2/local_installers/cuda-repo-wsl-ubuntu-12-8-local_12.8.2-1_amd64.deb sudo dpkg -i cuda-repo-wsl-ubuntu-12-8-local_12.8.2-1_amd64.deb sudo cp /var/cuda-repo-wsl-ubuntu-12-8-local/cuda-*-keyring.gpg /usr/share/keyrings/ sudo apt-get update sudo apt-get -y install cuda-toolkit-12-8

 2.3 Configure environment variables

echo 'export PATH=/usr/local/cuda-12.8/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

 Verify the installation:

nvcc --version

  

03 Install Python 3.10

Ubuntu 22.04 uses Python 3.10 by default. Confirm the version:

python3 --version

 If it is not installed or the version is incorrect:

sudo apt update sudo apt install -y python3.10 python3.10-venv python3.10-dev python3-pip

 It is recommended to create a virtual environment:

python3.10 -m venv ~/spirecv_env source ~/spirecv_env/bin/activate

 

04 Install PyTorch (CUDA Version)

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128 # If the speed is slow, you can add a mirror source # -i https://repo.huaweicloud.com/repository/pypi/simple

 Verify whether PyTorch can use CUDA:

python3 -c "import torch; print('CUDA available:', torch.cuda.is_available())"

 Outputting CUDA available: True means the setup is successful. 

05 Install SpireMS

SpireMS is the communication framework for SpireCV-Pro and needs to be installed first.

sudo apt update sudo apt install -y build-essential cmake git python3-pip libcurl4-openssl-dev libeigen3-dev libssl-dev libncurses-dev cd ~ git clone https://gitee.com/spirecv/spirecv-pro.git cd spirecv-pro/scripts/spirecv2/ ./opencv4110-install.sh pip install opencv-python==4.11.0.86 opencv-contrib-python==4.11.0.86 yacs cd ~ wget https://spireai.top/download/spirems/spirems-0.8.1_ubuntu_x86_64.deb sudo dpkg -i spirems-0.8.1_ubuntu_x86_64.deb # Note: if your Python version is not 3.10, change cp310 in the command below; cp38-cp313 are supported wget https://spireai.top/download/spirems/spirems-0.8.1-cp310-cp310-linux_x86_64.whl pip install spirems-0.8.1-cp310-cp310-linux_x86_64.whl # If the sms ls command does not work properly, install it again with sudo # sudo pip install spirems-0.8.1-cp310-cp310-linux_x86_64.whl # If installation is slow, you can add the following option to switch to Huawei Cloud's server # -i https://repo.huaweicloud.com/repository/pypi/simple

 Verify the installation:

python3 -c "import spirems; print(spirems.__version__)"

  

06 Install SpireCV-Pro

6.1 Enter the SpireCV-Pro repository

cd ~/spirecv-pro

6.2 Install dependencies

pip install ultralytics pip install -e . # If the smsrun ls command does not work properly, install it again with sudo # sudo pip install -e . ./build_spirecv2_x86_cuda.sh

 pip install -e . installs SpireCV-Pro in development mode and also registers the smsrun command-line tool.

6.3 Verify the installation

smsrun ls

 If you see the node list and Launch list, the installation was successful. The displayed result is as follows:

07 Run Examples

The two examples below both use built-in video files and do not require a camera.

7.1 Start SpireMS Core

Open a WSL terminal, activate the virtual environment, and start Core:

source ~/spirecv_env/bin/activate smscore

 Keep this terminal running. Core is the communication hub for all nodes.

7.2 Example 1: YOLO11 Object Detection Visualization

Open another WSL terminal and run:

source ~/spirecv_env/bin/activate smsrun viddet_yolo11_vis_cuda

 This Launch file automatically starts three nodes:

 Expected result: an OpenCV window pops up; vehicles, pedestrians, and other targets in the image are marked with red boxes, and class names and confidence scores are displayed. Press the q key or Ctrl+C to exit.

Custom parameters:

smsrun viddet_yolo11_vis_cuda confidence=0.3 pt_model=sms::yolo11m.pt

 

 

7.3 Example 2: ArUco Marker Detection and Pose Estimation

source ~/spirecv_env/bin/activate cd ~/spirecv-pro smsrun viddet_aruco_det

 

Started nodes:

Expected result: an OpenCV window pops up; the marker is outlined with a green box, 3D coordinate axes (red X / green Y / blue Z) are drawn, and the marker ID is displayed. Press the q key or Ctrl+C to exit.

Custom parameters:

smsrun viddet_aruco_det marker_lengths=[0.05] dictionary_id=4

 

 

08 FAQ

Q: CUDA nodes do not appear in smsrun ls?

Confirm that PyTorch CUDA is available:

python3 -c "import torch; print(torch.cuda.is_available())"

 If it returns False, check whether the Windows NVIDIA driver is installed and whether the WSL version is WSL2.

Q: The prompt says spirems cannot be found?

Confirm that the virtual environment is activated and spirems is installed:

source ~/spirecv_env/bin/activate pip install spirems

 Q: How do I view all available Launch files and nodes?

smsrun ls        # View nodes and Launch files available on the current platform smsrun ls -a     # View all nodes (including those incompatible with the current platform)

09 Next Steps

• Read the SpireCV-Pro manual to learn more features

• Read the SpireMS manual to understand the communication framework

• Try other Launch files, such as multi-object tracking and RTSP streaming