Zum Hauptinhalt springen

ONNX-Runtime-Tensor-Modul

Dieses Modul ist in Versionen nach 20260402 verfügbar

Diese Seite beschreibt die wichtigsten Tensor-Funktionen und Objektmethoden des Moduls onnxruntime.

Erstellung und Konvertierung​

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

tensor, err = onnxruntime.tensor("float32", {1, 3}, {1, 2, 3})

Erstellt einen gewöhnlichen ORT-Tensor.

  • type ist der Name des Elementtyps.
  • shape ist das Shape-Array.
  • data kann entfallen; ohne data wird ein leerer Tensor erstellt.
  • Für numerische Tensoren kann ein Skalar übergeben werden, der den gesamten Tensor füllt.
  • Für string-Tensoren kann eine einzelne Zeichenkette übergeben werden, die den gesamten Tensor füllt.

onnxruntime.tensor_from_bytes(type, shape, bytes)​

tensor, err = onnxruntime.tensor_from_bytes("float32", {1, 3}, raw_bytes)

Erstellt einen Tensor aus zusammenhängenden Rohbytes.

  • Unterstützt nur numerische und bool-Typen.
  • Die Byte-Länge muss exakt zu shape und type passen.

onnxruntime.tensor_from_cv_mat(mat[, opts])​

tensor, err = onnxruntime.tensor_from_cv_mat(mat, {
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})

Wandelt cv.mat in einen Tensor um.

Hinweise:

  • Zuerst require("image.cv") ausführen.
  • opts.type ist der Elementtyp des Ziel-Tensors.

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

tensor, err = 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",
})

Schneidet aus cv.mat perspektivisch einen viereckigen Bereich aus und gibt direkt einen ORT-Tensor zurück.

  • Zuerst require("image.cv") ausführen.
  • quad kann direkt vier Punkte oder eine Tabelle mit dem Feld points erhalten.
  • Die üblichen opts entsprechen im Wesentlichen tensor_from_image(); zusätzliche häufige Felder sind content_width, content_height und border_type.
  • Geeignet zum Begradigen und Tensorisieren einzelner Boxen vor der OCR-Erkennung.

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

batch_tensor, err = 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",
})

Schneidet mehrere Vierecke als Batch aus und fügt sie automatisch zu einem Batch-Tensor zusammen.

  • Zuerst require("image.cv") ausführen.
  • quads muss ein nicht leeres Array sein; jedes Element kann points enthalten.
  • content_width und content_height eines Elements überschreiben die gleichnamigen globalen Felder in opts.
  • Der Rückgabewert wird je nach Ergebnis-Rang automatisch mit stack() oder concat() zu einem Batch zusammengesetzt und eignet sich für OCR mit mehreren Boxen.

onnxruntime.tensor_from_image(image[, opts])​

tensor, preprocess_info = onnxruntime.tensor_from_image(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",
})

Wandelt ein Bildobjekt direkt in einen von ONNX Runtime verwendbaren Eingabetensor um.

Häufige Konfigurationsfelder:

  • 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: Unterstützt "top_left"; alle anderen Werte verwenden zentriertes Padding.
  • pad_color
  • interpolation："bilinear"、"nearest"
  • alpha_mode："ignore"、"white"、"black"、"premultiply"
  • crop = {x, y, width, height}
  • add_batch

Bei Erfolg ist der zweite Rückgabewert eine Tabelle mit Vorverarbeitungsinformationen, darunter:

  • 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])​

batch_tensor, batch_metadata = onnxruntime.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})

Wandelt eine Gruppe von Bildern als Batch in Tensoren um.

  • Die Originalbilder dürfen unterschiedliche Abmessungen haben.
  • Solange Shape und data_type der analysierten Ausgabe jedes Bildes übereinstimmen, können sie zu einem Batch verbunden werden.
  • Der zweite Rückgabewert ist ein Metadatenarray in Eingabereihenfolge.

onnxruntime.image_from_tensor(tensor[, opts])​

image, err = onnxruntime.image_from_tensor(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",
})

Wandelt einen 2D-/3D-/4D-Tensor zurück in ein Bildobjekt, was zum Debuggen von Modell-Ein- und -Ausgaben geeignet ist.

Häufige Konfigurationsfelder:

  • layout
  • channel_order
  • batch_index: 1-basiert, standardmäßig der erste Batch (1).
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" oder "0_1".

Hinweise:

  • Unterstützt nur 2D-/3D-/4D-Tensoren.
  • Unterstützt nur 1 oder 3 Kanäle.

Tensor-Objektmethoden​

Grundlegende Informationen​

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

Hinweise:

  • to_table() expandiert den Inhalt in eine Lua-Tabelle.
  • bytes() unterstützt nur numerische und bool-Tensoren.

Lesen, Schreiben und Kopieren​

  • 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)

Hinweise:

  • fill() füllt bei einem Skalar den gesamten Tensor; bei einer Tabelle muss die Elementanzahl exakt übereinstimmen.
  • copy_from_bytes() unterstützt nur numerische und bool-Tensoren; die Byte-Länge muss exakt passen.
  • Die Indizes von get() / set() sind 1-basiert.
  • tensor:to("string") unterstützt derzeit nur string -> string.

Shape und Indizes​

  • 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)

Hinweise:

  • start und stop von slice() sind 1-basiert und schließen die Endposition ein.
  • step von slice() muss eine positive Ganzzahl sein.
  • select() entfernt die ausgewählte Dimension.
  • indices von gather() kann ein Lua-Array oder ein Tensor mit Shape [N] sein; auch hier sind die Indizes 1-basiert.
  • Diese Methoden geben jeweils neue Tensorobjekte zurück.

Numerische Operationen​

  • 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)

Hinweise:

  • other kann ein Skalar oder ein Tensor mit passendem Shape sein.
  • matmul() unterstützt derzeit Kombinationen aus Rank-1- und Rank-2-Tensoren.
  • Die Rückgabewerte von sigmoid() / exp() / matmul() werden auf einen Gleitkomma-Ergebnistyp angehoben.
  • Keine der obigen Operationen unterstützt string-Tensoren.

Reduktion, Sortierung und Wahrscheinlichkeiten​

  • 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])

Hinweise:

  • Ohne Achse gibt argmax() einen einzelnen 1-basierten Index zurück.
  • argmax(axis) gibt einen int64-Tensor zurück; auch seine Indizes sind 1-basiert.
  • sort() gibt { values = tensor, indices = tensor } zurück.
  • topk() gibt { values = tensor, indices = tensor } zurück.
  • Die von sort() / topk() zurückgegebenen Indizes sind 1-basiert.

OpenCV-Bridge​

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

Hinweise:

  • Zuerst require("image.cv") ausführen.
  • Einige Tensor-Typen lassen sich nicht direkt auf cv.mat abbilden; in diesem Fall muss coreml_data_type explizit angegeben werden.

Tensor-Hilfen auf Modulebene​

Grundlegende numerische Hilfen​

  • 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])

Hinweise:

  • clamp(), sigmoid(), exp() und matmul() verwenden dieselbe Implementierung wie die entsprechenden tensor:-Methoden.
  • where() unterstützt die Mischung aus Skalaren, Booleans und Tensoren und berechnet das Ergebnis nach den Broadcast-Regeln.

Weitere Nachverarbeitungshilfen​

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

Hinweise:

  • mask_iou() berechnet direkt die Intersection-over-Union zweier Masken.
  • mask_iou() unterstützt außerdem das dritte Argument opts, entweder mit compare_size = true oder explizit mit width / height als ausgerichteten Vergleichsabmessungen.
  • db_postprocess() eignet sich für Texterkennungs-Nachverarbeitung wie DB / DBNet; Eingaben mit [H, W], [C, H, W] oder [N, C, H, W] werden unterstützt.
  • db_postprocess() gibt ein Detection-Array zurück, dessen Elemente score, points und box enthalten; meta / image_meta kann direkt aus der Bildtensorisierung wiederverwendet werden.

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

NMS für gewöhnliche Rechteckboxen.

Häufige Optionen:

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

Der Rückgabewert ist ein int64-Tensor mit 1-basierten Indizes.

onnxruntime.box_points(rotated_boxes)​

Wandelt die Rotationsbox [cx, cy, w, h, theta] in die Koordinaten ihrer vier Eckpunkte um.

  • Die Eingabe kann ein Tensor mit Shape [5], [1, 5] oder [N, 5] sein.
  • Für eine einzelne Box wird eine Lua-Punkttabelle, für mehrere Boxen ein Array von Punkttabellen zurückgegeben.

onnxruntime.xywh_to_xyxy(boxes)​

Wandelt Rechteckboxen von [cx, cy, w, h] in [x1, y1, x2, y2] um.

onnxruntime.xyxy_to_xywh(boxes)​

Wandelt Rechteckboxen von [x1, y1, x2, y2] in [cx, cy, w, h] um.

onnxruntime.rotated_iou(box1, box2)​

Berechnet die IoU zweier Rotationsboxen.

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

NMS für Rotationsboxen. Der Rückgabewert ist ebenfalls ein int64-Tensor mit 1-basierten Indizes.

  • boxes muss ein Rotationsbox-Tensor mit Shape [N, 5] sein.
  • scores kann ein Lua-Array oder ein Tensor mit Shape [N] / [N, 1] sein.

onnxruntime.create_decoder(schema)​

Erstellt ein wiederverwendbares Decoderobjekt.

  • Das Decoderobjekt unterstützt :decode(output[, opts]), :task() und :schema().
  • Geeignet, um das Schema von Detection-/OBB-/Klassifikationsausgaben festzulegen und wiederzuverwenden.

onnxruntime.decode_yolo(output[, opts])​

Dekodiert direkt nach der integrierten YOLO-Detection-Logik und gibt eine Liste von Detection-Records zurück.

onnxruntime.decode_yolo_obb(output[, opts])​

Dekodiert direkt nach der integrierten YOLO-OBB-Logik und gibt eine Liste von Detection-Records für Rotationsboxen zurück.

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

Teilt eine Matrixausgabe nach dem Schema in eine Tabelle von Kandidatentensoren auf. Übliche Rückgabefelder sind:

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles (nur für OBB und verwandte Schemas)

onnxruntime.decode_dense_detection(output, opts)​

Dekodiert die Ausgabe eines dichten Detection-Heads zu:

  • boxes
  • scores
  • labels

Dabei sind boxes / scores / labels Tensoren.

  • Unterstützte Eingabe-Shapes sind [R, C] und [N, R, C].
  • opts.strides ist erforderlich und muss ein nicht leeres Array positiver Ganzzahlen sein.
  • decode_width und decode_height sind ebenfalls erforderlich.
  • Derzeit wird nur box_encoding = "grid_center_log_wh" unterstützt.
  • Weitere häufige Felder sind box_offset, score_offset, class_offset, num_classes und score_threshold.
  • Bei einer gebatchten Ausgabe ist der Rückgabewert ein nach Batch organisiertes Lua-Array.

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

Bereitet Tensoren mit [N, 4]-Boxen, Scores und Klassen als Lua-Recordliste auf; jedes Element enthält typischerweise:

  • 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]]])​

Bereitet OBB-Zeilendaten als Lua-Recordliste auf.

  • opts unterstützt x_index, y_index, width_index und height_index.

onnxruntime.points_to_records(points[, opts])​

Bereitet Punkt-/Keypoint-Tensoren mit [N, P, D] oder [N, P*D] als Lua-Tabelle auf.

  • opts unterstützt point_count / keypoint_count.
  • opts unterstützt point_dim / keypoint_dim.

Maskenhilfen​

onnxruntime.threshold_masks(masks, threshold)​

Wandelt einen kontinuierlichen Maskentensor anhand eines Schwellenwerts in eine Liste von Lua-Maskentabellen um. Jede Maske enthält:

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

Schneidet die thresholded Maskenliste anhand von [N, 4]-Boxen aus.

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

Skaliert die Maskenliste auf die angegebene Größe.

  • Derzeit wird nur opts.interpolation = "nearest" unterstützt.

onnxruntime.mask_to_polygon(mask[, opts])​

Wandelt eine einzelne binäre Maske in eine Punktliste eines Polygons um.

  • opts.epsilon / opts.approx_epsilon können zur approximativen Vereinfachung verwendet werden.

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

Projiziert Prototypmasken, Maskenkoeffizienten und Detection-Boxen auf die Zielbildgröße zurück.

  • project_masks() ist ein Alias dafür.
  • Der Rückgabewert ist eine Liste von Lua-Maskentabellen, kein Tensor.

Keypoint- und Geometriehilfen​

  • 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])

Hinweise:

  • reshape_keypoints() unterstützt die Umformung zwischen [N, K*D] und [N, K, D].
  • scale_points() interpretiert standardmäßig ein gewöhnliches Punktlayout; scale_keypoints() standardmäßig ein Keypoint-Layout.
  • Die zu transform gehörige Tabelle entspricht den Metadatenfeldern der Bildvorverarbeitung; häufige Felder sind scale_x, scale_y, pad_left und pad_top.

onnxruntime.tracker([opts])​

Erstellt ein wiederverwendbares Trackerobjekt mit:

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

Häufige Konfigurationsfelder:

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

Gibt eine Struktur der Form zurück:

  • indices

  • text

  • confidence

  • Unterstützte Eingabe-Shapes sind [T, C] und [N, T, C].

  • Unterstützt blank_index, merge_repeated, apply_softmax, return_probabilities und charset.

  • indices wird immer zurückgegeben.

  • text wird nur bei übergebenem charset zurückgegeben.

  • confidence wird nur bei aktiviertem apply_softmax oder return_probabilities zurückgegeben.

  • probabilities und probability_confidence werden nur bei aktiviertem return_probabilities zusätzlich zurückgegeben.

  • Bei einer Batch-Eingabe wird ein Batch-Ergebnisarray zurückgegeben.

onnxruntime.sample_logits(logits[, opts])​

Unterstützt folgende Sampling-Parameter:

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

1D-Logits geben einen einzelnen Index zurück; mehrzeilige Logits geben einen int64-Tensor zurück, dessen Indizes 1-basiert sind.

Beispiel​

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