Complete Usage Guide

Saving PyTorch Model as TorchScript

Your model must be saved in TorchScript format for conversion:

import torch

# Your trained model
model = YourModel()
model.load_state_dict(torch.load('weights.pth'))
model.eval()

# Create example input (must match your model's expected input)
example_input = torch.randn(1, 3, 224, 224)

# Export as TorchScript using trace
traced_model = torch.jit.trace(model, example_input)
traced_model.save('model.pt')

print("Model saved successfully!")

Supported Model Types

Compilation Process

1. Select Target Platform

   Choose your target: Linux x86_64 (PC/Server), Raspberry Pi 4/5 64-bit, or other ARM boards

2. Select Precision
   • FP32: Highest accuracy, largest size
   • FP16: Good balance of accuracy and size
   • INT8: Smallest size, fastest, slight accuracy loss
3. Set License Duration & Thread Count
   • License Duration: How many days the library will be valid (1-365)
   • Thread Count: Number of CPU threads for inference (1-16, recommended: 4)
4. Upload Model

   Drag & drop or click to select your .pt or .onnx file

5. Auto Analysis

   System automatically detects input shape, model type, and normalization

6. Download Package

   Get your compiled library with embedded model

Linux x86_64: If you select Linux x86_64 (PC/Server), the compilation server must have YBPU built for host and OpenCV installed. See Docs → Supported Platforms for build prerequisites.

Project Setup

After downloading, extract the package. You'll get 3 files:

ybpu_model_rpi4-64_fp32/
├── libybpu_model.a    # Static library (with embedded model)
├── ybpu_model.h       # C++ header file
└── model.lic          # License file (required at runtime)

Copy these files to your project:

my_project/
├── CMakeLists.txt
├── main.cpp
├── lib/
│   └── libybpu_model.a
├── include/
│   └── ybpu_model.h
└── model.lic          # Must be in executable directory!

CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(my_inference_app)

set(CMAKE_CXX_STANDARD 11)

# Find OpenCV (required dependency)
find_package(OpenCV REQUIRED)

# Include header directories
include_directories(${CMAKE_SOURCE_DIR}/include)
include_directories(${OpenCV_INCLUDE_DIRS})

# Your application
add_executable(my_app main.cpp)

# Link with YBPU model library + OpenCV + pthread
target_link_libraries(my_app 
    ${CMAKE_SOURCE_DIR}/lib/libybpu_model.a
    ${OpenCV_LIBS}
    pthread
)

Alternative: Direct g++ Compilation

Important: You must put libybpu_model.a at the end of the link line. Otherwise you get undefined reference to YbpuModel::.... Two ways:

Method 1 — Use -L and -lybpu_model (library last):

g++ -O2 -fopenmp -o my_app main.cpp \
    -I./include \
    $(pkg-config --cflags --libs opencv4) \
    -lpthread -lgomp \
    -L./lib -lybpu_model

Method 2 — Use full path to the .a file (recommended, e.g. on Raspberry Pi):

g++ -O2 -fopenmp -o my_app main.cpp \
    -I./include \
    $(pkg-config --cflags --libs opencv4) \
    -lpthread -lgomp \
    ./lib/libybpu_model.a

#include "ybpu_model.h"
#include <opencv2/opencv.hpp>
#include <iostream>
#include <vector>
#include <algorithm>

int main(int argc, char** argv) {
    if (argc < 2) {
        std::cerr << "Usage: " << argv[0] << " <image_path>" << std::endl;
        return 1;
    }

    // ========================================
    // Step 1: Create Model Instance
    // ========================================
    // Model is EMBEDDED in the library - no external files needed!
    YbpuModel model;
    
    if (!model.is_loaded()) {
        std::cerr << "Failed to load model: " << model.get_last_error() << std::endl;
        return 1;
    }
    
    // Print model info
    std::cout << "Model loaded!" << std::endl;
    std::cout << "  Input: " << model.get_input_width() << "x" 
              << model.get_input_height() << "x"
              << model.get_input_channels() << std::endl;

    // ========================================
    // Step 2: Load Image with OpenCV
    // ========================================
    cv::Mat image = cv::imread(argv[1]);
    if (image.empty()) {
        std::cerr << "Failed to load image" << std::endl;
        return 1;
    }
    
    std::cout << "Image: " << image.cols << "x" << image.rows << std::endl;

    // ========================================
    // Step 3: Run Inference
    // ========================================
    // Preprocessing (resize, normalize) is AUTOMATIC!
    std::vector<float> output = model.inference(image);
    
    std::cout << "Output size: " << output.size() << std::endl;

    // ========================================
    // Step 4: Process Results
    // ========================================
    
    // For Classification: Find top prediction
    if (output.size() > 0 && output.size() < 10000) {
        auto max_it = std::max_element(output.begin(), output.end());
        int class_id = std::distance(output.begin(), max_it);
        float confidence = *max_it;
        
        std::cout << "Predicted class: " << class_id << std::endl;
        std::cout << "Confidence: " << confidence << std::endl;
    }
    
    // For Detection: Parse bounding boxes
    // Output format: [x, y, w, h, confidence, class_scores...]
    
    // For Segmentation: Output is pixel-wise class map
    
    return 0;
}

# On your target device (e.g., Raspberry Pi)

# 1. Install OpenCV
sudo apt update
sudo apt install libopencv-dev

# 2. Build your project
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

# 3. Copy license file to executable directory (IMPORTANT!)
cp ../model.lic .

# 4. Run inference
./my_app test_image.jpg

Understanding the License

Every compiled model includes a time-limited license that you specify during compilation (1-365 days).

Machine Binding

The library binds to the first machine it runs on. After the first run, it cannot be copied to another computer; if you try, you will see: This library is bound to another machine and cannot run on this device. To use the same model on another device, compile and download a separate package for that device.

Checking License Status in Code

#include "ybpu_model.h"
#include <iostream>

int main() {
    // Check license BEFORE creating model
    if (!YbpuModel::is_license_valid()) {
        std::cerr << "License expired on: " 
                  << YbpuModel::get_license_expire_date() << std::endl;
        std::cerr << "Please renew your license." << std::endl;
        return 1;
    }
    
    // Show remaining days
    int days_left = YbpuModel::get_license_days_remaining();
    std::cout << "License valid for " << days_left << " more days" << std::endl;
    
    // If license expires within 7 days, show warning
    if (days_left <= 7) {
        std::cout << "WARNING: License expiring soon!" << std::endl;
    }
    
    // Now safe to create model
    YbpuModel model;
    
    if (!model.is_loaded()) {
        std::cerr << "Error: " << model.get_last_error() << std::endl;
        return 1;
    }
    
    // ... rest of inference code
    return 0;
}

License Renewal

When your license expires:

1. Re-upload your model to the compiler website
2. Select your desired new license duration
3. Download the new package
4. Replace only the model.lic file (the library stays the same)

Automatic Performance Optimization

When you first run your model, the library automatically benchmarks your hardware to find the optimal configuration. On x86 and other supported platforms, it automatically uses the best available processor for your machine.

Using Auto-Tune API

#include "ybpu_model.h"
#include <iostream>

int main() {
    YbpuModel model;
    
    // Check if auto-tune completed
    if (model.is_auto_tuned()) {
        std::cout << "Auto-tune complete!" << std::endl;
        std::cout << "Config: " << model.get_auto_tune_config() << std::endl;
    }
    
    // Optional: Force re-benchmark (e.g., after hardware upgrade)
    // model.force_auto_tune();
    
    // Get cache file location
    std::cout << "Cache at: " << YbpuModel::get_cache_path() << std::endl;
    
    return 0;
}

When to Re-run Auto-Tune

• Hardware change: After upgrading CPU or changing device
• OS update: Major kernel updates may affect performance
• Different target: When deploying to a new device type

To re-run, either call force_auto_tune() or delete the cache file at ~/.ybpu_cache/

YbpuModel Class

Input Requirements

• Format: OpenCV cv::Mat (BGR, 8-bit unsigned)
• Size: Any size - auto-resized to model input
• Preprocessing: Automatic (resize, normalize)

License Static Methods