跳到主要内容

ONNX Runtime 张量模块

本页说明 onnxruntime 模块中最常用的 tensor 相关函数和对象方法。

创建与转换​

onnxruntime.tensor(type, shape[, data])​

张量, 错误信息 = onnxruntime.tensor("float32", {1, 3}, {1, 2, 3})

用于创建一个普通 ORT tensor。

  • type 为元素类型名称
  • shape 为形状数组
  • data 可省略；省略时创建空张量
  • 数值 tensor 可以传标量，表示用同一个值填满整个张量
  • string tensor 可以传单个字符串，表示按同一个字符串填满整个张量

onnxruntime.tensor_from_bytes(type, shape, bytes)​

张量, 错误信息 = onnxruntime.tensor_from_bytes("float32", {1, 3}, 原始字节串)

用于从连续原始字节创建 tensor。

  • 只支持数值和 bool 类型
  • 字节长度必须与 shape 和 type 完全匹配

onnxruntime.tensor_from_cv_mat(mat[, opts])​

张量, 错误信息 = onnxruntime.tensor_from_cv_mat(mat, {
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})

用于把 cv.mat 转成 tensor。

说明：

  • 需要先 require("image.cv")
  • opts.type 是目标 tensor 元素类型

onnxruntime.tensor_from_quad(mat, quad[, opts])​

张量, 错误信息 = onnxruntime.tensor_from_quad(mat, {
    {x = 0, y = 0},
    {x = 100, y = 0},
    {x = 100, y = 32},
    {x = 0, y = 32},
}, {
    width = 100,
    height = 32,
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})

从 cv.mat 中按四边形区域做透视裁剪，并直接得到 ORT tensor。

  • 需要先 require("image.cv")
  • quad 可以直接传四个点，也可以传带 points 字段的表
  • 常用 opts 与 tensor_from_image() 基本一致，额外常见字段有 content_width、content_height、border_type
  • 适合 OCR 识别前的单框拉正与张量化

onnxruntime.tensor_from_quads(mat, quads[, opts])​

批量张量, 错误信息 = onnxruntime.tensor_from_quads(mat, {
    {
        points = quad1,
        content_width = 96,
        content_height = 32,
    },
    {
        points = quad2,
        content_width = 80,
        content_height = 32,
    },
}, {
    width = 96,
    height = 32,
    resize_mode = "top_left_letterbox",
    border_type = "replicate",
})

批量裁剪多个四边形并自动拼成 batch tensor。

  • 需要先 require("image.cv")
  • quads 必须是非空数组；每项可以带 points
  • 每项里的 content_width、content_height 会覆盖全局 opts 里的同名字段
  • 返回值会按结果 rank 自动走 stack() 或 concat() 拼成 batch，适合 OCR 多框批处理

onnxruntime.tensor_from_image(image[, opts])​

张量, 预处理信息 = onnxruntime.tensor_from_image(图像对象, {
    width = 224,
    height = 224,
    layout = "nchw",
    channel_order = "rgb",
    data_type = "float32",
    scale = 1 / 255,
    mean = {0.485, 0.456, 0.406},
    std = {0.229, 0.224, 0.225},
    resize_mode = "letterbox",
})

用于把图片对象直接转换成 ONNX Runtime 可用的输入张量。

常用配置字段：

  • width / height
  • layout："nchw"、"nhwc"、"chw"、"hwc"
  • channel_order："rgb"、"bgr"、"gray"、"grey"、"grayscale"
  • data_type
  • scale
  • mean
  • std
  • resize_mode："stretch"、"letterbox"、"center_crop"
  • letterbox_mode：支持 "top_left"，其余情况按居中补边处理
  • pad_color
  • interpolation："bilinear"、"nearest"
  • alpha_mode："ignore"、"white"、"black"、"premultiply"
  • crop = {x, y, width, height}
  • add_batch

成功时第二个返回值是预处理信息表，包含：

  • src_width / src_height
  • crop_x / crop_y / crop_width / crop_height
  • dst_width / dst_height
  • resized_width / resized_height
  • layout
  • channel_order
  • resize_mode
  • scale_x / scale_y / ratio
  • offset_x / offset_y
  • pad_left / pad_top / pad_right / pad_bottom

onnxruntime.tensor_from_images(images[, opts])​

批量张量, 批量元信息 = onnxruntime.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})

用于把一组图像批量转换成 tensor。

  • 原图尺寸可以不同
  • 只要每张图解析后的输出 shape 与 data_type 一致，就能拼成 batch
  • 第二个返回值是与输入顺序对应的元信息数组

onnxruntime.image_from_tensor(tensor[, opts])​

图像对象, 错误信息 = onnxruntime.image_from_tensor(张量, {
    layout = "nchw",
    channel_order = "rgb",
    batch_index = 1,
    scale = 1 / 255,
    mean = {0.485, 0.456, 0.406},
    std = {0.229, 0.224, 0.225},
    value_range = "0_1",
})

用于把 2D / 3D / 4D tensor 还原成图像对象，适合调试模型输入输出。

常用配置字段：

  • layout
  • channel_order
  • batch_index：1-based，默认第 1 个 batch
  • scale
  • mean
  • std
  • clamp
  • value_range："0_255" 或 "0_1"

说明：

  • 仅支持 2D / 3D / 4D tensor
  • 通道数仅支持 1 或 3

张量对象方法​

基础信息​

  • tensor:shape()
  • tensor:rank()
  • tensor:size()
  • tensor:type()
  • tensor:to_table()
  • tensor:bytes()

说明：

  • to_table() 会把内容展开成 Lua 表
  • bytes() 只支持数值和 bool tensor

读写与复制​

  • tensor:get(index1[, index2, ...])
  • tensor:set(index1[, index2, ...], value)
  • tensor:fill(value_or_table)
  • tensor:clone()
  • tensor:copy_from_bytes(raw_bytes)
  • tensor:to(type)

说明：

  • fill() 传标量时会填满整个张量，传表时元素数必须完全匹配
  • copy_from_bytes() 只支持数值和 bool tensor，字节长度必须完全匹配
  • get() / set() 的索引语义是 1-based
  • tensor:to("string") 目前只支持 string -> string

形状与索引​

  • tensor:reshape(shape)
  • tensor:transpose([axes])
  • tensor:flatten([start_dim[, end_dim]])
  • tensor:squeeze([dim])
  • tensor:unsqueeze(dim)
  • tensor:slice(dim, start, stop[, step])
  • tensor:select(dim, index)
  • tensor:gather(dim, indices)

说明：

  • slice() 的 start 和 stop 都是 1-based 且包含结束位置
  • slice() 的 step 必须为正整数
  • select() 会移除被选中的那一维
  • gather() 的 indices 可以是 Lua 数组，也可以是形状 [N] 的 tensor；索引语义同样是 1-based
  • 这几类方法返回的都是新的 tensor 对象

数值运算​

  • tensor:add(other)
  • tensor:sub(other)
  • tensor:mul(other)
  • tensor:div(other)
  • tensor:clamp(min, max)
  • tensor:sigmoid()
  • tensor:exp()
  • tensor:matmul(other)
  • tensor:dot(other)

说明：

  • other 可以是标量，也可以是形状一致的 tensor
  • matmul() 当前支持 rank-1 / rank-2 tensor 组合
  • sigmoid() / exp() / matmul() 的返回值会提升到浮点结果类型
  • 以上运算都不支持 string tensor

归约、排序与概率​

  • tensor:argmax([axis])
  • tensor:sum([axis])
  • tensor:mean([axis])
  • tensor:max([axis])
  • tensor:min([axis])
  • tensor:softmax([axis])
  • tensor:normalize([axis])
  • tensor:sort([axis[, descending]])
  • tensor:topk(k[, axis])

说明：

  • argmax() 不传轴时返回单个 1-based 索引
  • argmax(axis) 返回 int64 tensor，索引语义也是 1-based
  • sort() 返回 { values = 张量, indices = 张量 }
  • topk() 返回 { values = 张量, indices = 张量 }
  • sort() / topk() 返回的索引都是 1-based

OpenCV 桥接​

  • tensor:to_cv_mat([opts])
mat, 错误信息 = tensor:to_cv_mat({
    layout = "hwc",
    channel_order = "rgb",
    coreml_data_type = "uint8",
})

说明：

  • 需要先 require("image.cv")
  • 某些 tensor 类型不能直接映射到 cv.mat，这种情况需要显式传 coreml_data_type

模块级张量辅助​

基础数值辅助​

  • onnxruntime.clamp(tensor, min, max)
  • onnxruntime.sigmoid(tensor)
  • onnxruntime.exp(tensor)
  • onnxruntime.where(condition, x, y)
  • onnxruntime.matmul(lhs, rhs)
  • onnxruntime.concat(tensors[, axis])
  • onnxruntime.stack(tensors[, axis])

说明：

  • clamp()、sigmoid()、exp()、matmul() 与对应的 tensor: 方法共享同一套实现
  • where() 支持标量 / 布尔值 / tensor 混用，并按广播规则计算结果

额外后处理辅助​

  • onnxruntime.mask_iou(lhs_mask, rhs_mask)
  • onnxruntime.db_postprocess(score_map[, opts])

说明：

  • mask_iou() 用于直接计算两张 mask 的交并比
  • mask_iou() 还支持第三个参数 opts，可传 compare_size = true，或显式传 width / height 作为对齐后的比较尺寸
  • db_postprocess() 适合 DB / DBNet 一类文本检测后处理；输入支持 [H, W]、[C, H, W] 或 [N, C, H, W]
  • db_postprocess() 返回检测数组，每项都带 score、points 和 box；meta / image_meta 可直接复用图像张量化返回的元信息

onnxruntime.nms(boxes, scores[, opts])​

普通矩形框 NMS。

常用选项：

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

返回值是 int64 tensor，索引为 1-based。

onnxruntime.box_points(rotated_boxes)​

把旋转框 [cx, cy, w, h, theta] 转成四个顶点坐标。

  • 输入可以是形状 [5]、[1, 5] 或 [N, 5] 的 tensor
  • 单个框返回一个 Lua 点表；多个框返回点表数组

onnxruntime.xywh_to_xyxy(boxes)​

把矩形框从 [cx, cy, w, h] 转成 [x1, y1, x2, y2]。

onnxruntime.xyxy_to_xywh(boxes)​

把矩形框从 [x1, y1, x2, y2] 转成 [cx, cy, w, h]。

onnxruntime.rotated_iou(box1, box2)​

计算两个旋转框的 IoU。

onnxruntime.rotated_nms(boxes, scores[, opts])​

旋转框 NMS。返回值同样是 int64 tensor，索引为 1-based。

  • boxes 必须是 [N, 5] 的旋转框 tensor
  • scores 可以是 Lua 数组，也可以是形状 [N] / [N, 1] 的 tensor

onnxruntime.create_decoder(schema)​

创建一个可复用 decoder 对象。

  • decoder 对象支持 :decode(output[, opts])、:task()、:schema()
  • 适合把检测 / OBB / 分类输出的 schema 先固化，再多次复用

onnxruntime.decode_yolo(output[, opts])​

直接按内置 YOLO 检测逻辑解码，返回 detection record 列表。

onnxruntime.decode_yolo_obb(output[, opts])​

直接按内置 YOLO OBB 逻辑解码，返回旋转框 detection record 列表。

onnxruntime.decode_matrix_candidates(output, schema[, opts])​

按 schema 把矩阵输出拆成候选张量表，返回字段通常包括：

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles（仅 OBB 等相关 schema）

onnxruntime.decode_dense_detection(output, opts)​

把 dense detection head 输出解码成：

  • boxes
  • scores
  • labels

其中 boxes / scores / labels 都是 tensor。

  • 输入支持 [R, C] 或 [N, R, C]
  • opts.strides 是必填项，且必须是非空正整数数组
  • decode_width、decode_height 也是必填项
  • 当前只支持 box_encoding = "grid_center_log_wh"
  • 其余常用字段包括 box_offset、score_offset、class_offset、num_classes、score_threshold
  • 当传入 batched 输出时，返回值是按 batch 组织的 Lua 数组

onnxruntime.records_from_boxes(boxes, scores, class_ids[, keep_indices])​

把 [N, 4] 框、分数、类别等 tensor 整理成 Lua record 列表，每项通常会带：

  • box
  • score
  • class_id
  • row_index
  • x1 / y1 / x2 / y2
  • width / height
  • cx / cy

onnxruntime.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])​

把 OBB 行数据整理成 Lua record 列表。

  • opts 支持 x_index、y_index、width_index、height_index

onnxruntime.points_to_records(points[, opts])​

把 [N, P, D] 或 [N, P*D] 的点 / 关键点 tensor 整理成 Lua table。

  • opts 支持 point_count / keypoint_count
  • opts 支持 point_dim / keypoint_dim

掩码辅助​

onnxruntime.threshold_masks(masks, threshold)​

把连续 mask tensor 阈值化为 Lua mask table 列表。每个 mask 会包含：

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

按 [N, 4] 框裁剪阈值化后的 mask 列表。

onnxruntime.resize_masks(masks, width, height[, opts])​

把 mask 列表缩放到指定尺寸。

  • 当前仅支持 opts.interpolation = "nearest"

onnxruntime.mask_to_polygon(mask[, opts])​

把单个二值 mask 转为多边形点列。

  • opts.epsilon / opts.approx_epsilon 可用于近似简化

onnxruntime.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])​

把原型 mask、mask 系数和检测框投影回目标图像尺寸。

  • project_masks() 是它的别名
  • 返回值是 Lua mask table 列表，而不是 tensor

关键点与几何辅助​

  • onnxruntime.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])
  • onnxruntime.scale_boxes(boxes, transform)
  • onnxruntime.clip_boxes(boxes, clip_width, clip_height)
  • onnxruntime.scale_points(points, transform[, opts])
  • onnxruntime.scale_keypoints(points, transform[, opts])
  • onnxruntime.clip_keypoints(points, clip_width, clip_height[, opts])

说明：

  • reshape_keypoints() 支持 [N, K*D] 与 [N, K, D] 之间整理
  • scale_points() 默认按普通点布局解析；scale_keypoints() 默认按关键点布局解析
  • transform 相关 table 与图像预处理元信息字段对齐，常见字段包括 scale_x、scale_y、pad_left、pad_top

onnxruntime.tracker([opts])​

创建一个可复用的跟踪器对象，支持：

  • tracker:update(detections[, timestamp])
  • tracker:reset()
  • tracker:state()
  • tracker:close()

常用配置字段：

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

返回形如：

  • indices

  • text

  • confidence

  • 输入支持 [T, C] 或 [N, T, C]

  • 支持 blank_index、merge_repeated、apply_softmax、return_probabilities、charset

  • 一定返回 indices

  • 只有传了 charset 才会带 text

  • 只有启用 apply_softmax 或 return_probabilities 才会带 confidence

  • 只有启用 return_probabilities 才会额外带 probabilities 和 probability_confidence

  • 当输入为 batch 时，返回 batch result 数组

onnxruntime.sample_logits(logits[, opts])​

支持以下采样参数：

  • argmax
  • temperature
  • top_k
  • top_p
  • min_p
  • seed

1D logits 返回单个索引；多行 logits 返回 int64 tensor，索引语义为 1-based。

示例​

local ort = require("onnxruntime")

local tensor = assert(ort.tensor("float32", {2, 3}, {
    1, 9, 3,
    8, 2, 7,
}))

local sliced = assert(tensor:slice(2, 2, 3))
print(sliced:to_table()[1]) -- 9

local topk = assert(tensor:topk(2, 2))
print(topk.values:to_table()[1])  -- 9
print(topk.indices:to_table()[1]) -- 2