Crate xq_vision

Expand description

High-performance Chinese chessboard vision primitives and ONNX inference.

The crate exposes a compact end-to-end API through XqVision while keeping the board detector, piece recognizer, and board warp operation reusable for callers that need finer control.

use xq_vision::{ModelSource, XqVision};

let mut vision = XqVision::builder()
    .board_model(ModelSource::file("models/board.onnx"))
    .piece_model(ModelSource::file("models/piece.onnx"))
    .build()?;

let image = image::open("board.jpg")?.to_rgb8();
let result = vision.recognize(&image)?;
println!("{}", result.to_fen());

§Concurrency

XqVision (along with BoardDetector and PieceRecognizer) is Send but intentionally not Sync. recognize takes &mut self because it reuses an internal tensor scratch buffer between calls, so an instance is owned by exactly one task at a time.

Recommended async model — give each worker its own XqVision:

// Share model bytes cheaply via Arc; each task builds its own session.
let board_bytes: std::sync::Arc<[u8]> = std::fs::read("models/board.onnx")?.into();
let piece_bytes: std::sync::Arc<[u8]> = std::fs::read("models/piece.onnx")?.into();

let mut vision = XqVision::builder()
    .board_model(ModelSource::Memory(board_bytes.clone()))
    .piece_model(ModelSource::Memory(piece_bytes.clone()))
    .build()?;
// ...use `vision` from a single task...

If a single instance must be shared, wrap it in tokio::sync::Mutex<XqVision> or std::sync::Mutex<XqVision> — inference will be serialized.