推理

每次调用处理一张图（一帧）。连续采集请循环调用 infer_image，不要每帧重新 open。阻塞调用；耗时随 Provider / 硬件而定。不承诺硬实时——PLC 侧按架构在扫描周期外进程 / 线程调用，结果经过程映像回 PLC。

提示

• 打开会话见 构造。
• ImageDesc / ImageFormat 见 类型。

类别	属性	类型	访问	说明
推理	infer_image	Result<String, Error>	方法	对一张图（一帧）跑推理，结果 JSON。同一会话可并发；吞吐扩展推荐每线程一个会话
	infer_image_json	Result<Value, Error>	方法	同 infer_image，feature json 下解析为 serde_json::Value
图像描述	ImageDesc::auto	ImageDesc	关联函数	编码字节流（JPG/PNG/BMP），按魔数自嗅探。裸缓冲禁止用 auto
	ImageDesc::rgb888	ImageDesc	关联函数	裸 RGB888。stride=0 表示紧凑（= width×3）
	ImageDesc::bgr888	ImageDesc	关联函数	裸 BGR888（工业相机常见）。stride=0 表示紧凑

推理

infer_image()

pub fn infer_image(&self, image: &[u8], desc: &ImageDesc) -> Result<String, Error>

对一张图（一帧）跑推理。相机 / 采集循环里每拿到一帧调一次。

参数:

• image (&[u8]) — Auto / Encoded = 编码文件字节流；裸缓冲 = 像素内存。裸缓冲长度必须 ≥ stride * height（stride 为 0 时按 format 紧凑宽度计：RGB888/BGR888 = width * 3）
• desc (&ImageDesc) — 见 ImageDesc。绑定自动填 FFI size

返回值:

• Result<String, Error> — 结果 JSON（envelope 随 meta 的 task 字段而变：detect → box，classify → top-k，segment → 掩码）。绑定把 Core 分配的堆字符串收成 String，调用方无需释放

典型错误：IoDenied（裸缓冲指针不可读）/ Internal（调用方契约违反：裸缓冲缺宽高、len 不足）。

同一会话的 infer_image 允许多线程并发（Session: Sync）。吞吐扩展仍推荐每线程一个会话，而不是多线程抢一个会话。

示例:

use darra_ai::{ImageDesc, Session};

let jpeg = std::fs::read("photo.jpg")?;
let json = session.infer_image(&jpeg, &ImageDesc::auto())?;
println!("{json}");

循环帧：

for frame in frames {
    let json = session.infer_image(&frame, &desc)?;
    handle(&json);
}

infer_image_json()

#[cfg(feature = "json")]
pub fn infer_image_json(
    &self,
    image: &[u8],
    desc: &ImageDesc,
) -> Result<serde_json::Value, Error>

同 infer_image，feature json 下解析为 serde_json::Value。默认 feature 已打开 json。

参数:

• image (&[u8]) — 同 infer_image
• desc (&ImageDesc) — 同 infer_image

返回值:

• Result<serde_json::Value, Error> — 解析后的结果 JSON

编码字节流（JPG / PNG / BMP）

ImageDesc::auto() 按字节魔数自嗅探。也可显式声明 ImageFormat::Encoded（行为同 Auto）：

use darra_ai::{ImageDesc, ImageFormat};

let encoded = ImageDesc {
    format: ImageFormat::Encoded,
    width: 0,
    height: 0,
    stride: 0,
};
let json = session.infer_image(&jpeg, &encoded)?;

Auto / Encoded 时 width / height / stride 忽略（填 0）。

工业相机裸缓冲 BGR888

裸缓冲禁止 ImageDesc::auto()——嗅探不出通道序。stride = 0 表示紧凑排列（= width × 3）。

use darra_ai::ImageDesc;

let desc = ImageDesc::bgr888(1920, 1080, 0);
let json = session.infer_image(&frame, &desc)?;

RGB888：

let desc = ImageDesc::rgb888(1920, 1080, 0);
let json = session.infer_image(&frame, &desc)?;

带行对齐（例如每行 2048 字节、有效宽 1920）：

let desc = ImageDesc::bgr888(1920, 1080, 2048);

Rgb888 / Bgr888 时 width / height 必填（>0）；缺宽高 = Error::Internal（调用方 bug，不崩溃）。

本绑定的 ImageFormat 目前为 Auto / Encoded / Rgb888 / Bgr888。头文件另有 GRAY8 / RGBA8888，Rust 枚举尚未露出。

并发与硬实时

• 不同会话可并发（Session: Send）。
• 同一会话 infer_image 可多线程并发（Session: Sync）。
• Drop（close）禁止与在飞调用并发。
• 禁止把 infer_image 放进 PLC 扫描周期。不承诺硬实时。