Aller au contenu principal

Module des tenseurs ONNX Runtime

Ce module est disponible à partir des versions postérieures au 20260402

Cette page décrit les fonctions et méthodes d’objet liées aux tenseurs les plus couramment utilisées dans le module onnxruntime.

Création et conversion​

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

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

Crée un tensor ORT ordinaire.

  • type est le nom du type d’élément
  • shape est le tableau de forme
  • data peut être omis ; lorsqu’il l’est, un tenseur vide est créé
  • pour un tensor numérique, un scalaire peut être transmis afin de remplir tout le tenseur avec la même valeur
  • pour un tensor string, une seule chaîne peut être transmise afin de remplir tout le tenseur avec cette même chaîne

onnxruntime.tensor_from_bytes(type, shape, bytes)​

tenseur, message_erreur = onnxruntime.tensor_from_bytes("float32", {1, 3}, octets_bruts)

Crée un tensor à partir d’octets bruts contigus.

  • prend uniquement en charge les types numériques et bool
  • la longueur des octets doit correspondre exactement à shape et type

onnxruntime.tensor_from_cv_mat(mat[, opts])​

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

Convertit un cv.mat en tensor.

Description :

  • il faut d’abord exécuter require("image.cv")
  • opts.type est le type d’élément du tensor cible

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

tenseur, message_erreur = 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",
})

Effectue un recadrage en perspective d’une zone quadrilatérale dans un cv.mat, puis produit directement un tensor ORT.

  • il faut d’abord exécuter require("image.cv")
  • quad peut recevoir directement quatre points ou une table comportant un champ points
  • les opts courants sont globalement les mêmes que pour tensor_from_image() ; les champs supplémentaires courants sont content_width, content_height et border_type
  • convient au redressement d’une seule boîte puis à sa tensorisation avant la reconnaissance OCR

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

tenseur_batch, message_erreur = 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",
})

Recadre plusieurs quadrilatères et les assemble automatiquement en tensor batch.

  • il faut d’abord exécuter require("image.cv")
  • quads doit être un tableau non vide ; chaque élément peut comporter points
  • content_width et content_height de chaque élément remplacent les champs homonymes de opts global
  • la valeur renvoyée est assemblée en batch par stack() ou concat() selon le rang du résultat ; cela convient au traitement OCR de plusieurs boîtes

onnxruntime.tensor_from_image(image[, opts])​

tenseur, informations_pretraitement = onnxruntime.tensor_from_image(objet_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",
})

Convertit directement un objet image en tenseur d’entrée utilisable par ONNX Runtime.

Champs de configuration courants :

  • 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 : prend en charge "top_left" ; dans les autres cas, le remplissage des bords est centré
  • pad_color
  • interpolation : "bilinear", "nearest"
  • alpha_mode : "ignore", "white", "black", "premultiply"
  • crop = {x, y, width, height}
  • add_batch

En cas de réussite, la deuxième valeur renvoyée est une table d’informations de prétraitement contenant :

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

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

Convertit un ensemble d’images en tensor par batch.

  • les dimensions des images d’origine peuvent différer
  • tant que la forme de sortie analysée et le data_type sont identiques pour chaque image, elles peuvent être assemblées en batch
  • la deuxième valeur renvoyée est le tableau de métadonnées correspondant à l’ordre des entrées

onnxruntime.image_from_tensor(tensor[, opts])​

objet_image, message_erreur = onnxruntime.image_from_tensor(tenseur, {
    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",
})

Restaure un objet image à partir d’un tensor 2D, 3D ou 4D, ce qui convient au débogage des entrées et sorties d’un modèle.

Champs de configuration courants :

  • layout
  • channel_order
  • batch_index : 1-based, le premier batch 1 par défaut
  • scale
  • mean
  • std
  • clamp
  • value_range : "0_255" ou "0_1"

Description :

  • seuls les tensors 2D, 3D et 4D sont pris en charge
  • le nombre de canaux doit être 1 ou 3

Méthodes de l’objet tensor​

Informations de base​

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

Description :

  • to_table() déploie le contenu dans une table Lua
  • bytes() ne prend en charge que les tensors numériques et bool

Lecture, écriture et copie​

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

Description :

  • avec un scalaire, fill() remplit tout le tenseur ; avec une table, le nombre d’éléments doit correspondre exactement
  • copy_from_bytes() ne prend en charge que les tensors numériques et bool, et la longueur des octets doit correspondre exactement
  • la sémantique des indices de get() / set() est 1-based
  • tensor:to("string") ne prend actuellement en charge que string -> string

Forme et indexation​

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

Description :

  • start et stop de slice() sont tous deux 1-based et incluent la position finale
  • step de slice() doit être un entier positif
  • select() supprime la dimension sélectionnée
  • indices de gather() peut être un tableau Lua ou un tensor de forme [N] ; sa sémantique d’index est également 1-based
  • ces catégories de méthodes renvoient toutes de nouveaux objets tensor

Opérations numériques​

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

Description :

  • other peut être un scalaire ou un tensor de forme identique
  • matmul() prend actuellement en charge les combinaisons de tensors de rang 1 et de rang 2
  • les valeurs renvoyées par sigmoid() / exp() / matmul() sont converties vers un type de résultat flottant
  • aucune des opérations ci-dessus ne prend en charge les tensors string

Réduction, tri et probabilités​

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

Description :

  • sans axe, argmax() renvoie un indice 1-based unique
  • argmax(axis) renvoie un tensor int64, dont la sémantique d’index est également 1-based
  • sort() renvoie { values = tenseur, indices = tenseur }
  • topk() renvoie { values = tenseur, indices = tenseur }
  • les indices renvoyés par sort() / topk() sont 1-based

Pont OpenCV​

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

Description :

  • il faut d’abord exécuter require("image.cv")
  • certains types de tensor ne peuvent pas être mappés directement vers cv.mat ; dans ce cas, transmettez explicitement coreml_data_type

Fonctions auxiliaires de tenseurs au niveau du module​

Fonctions numériques de base​

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

Description :

  • clamp(), sigmoid(), exp() et matmul() partagent la même implémentation que les méthodes tensor: correspondantes
  • where() accepte un mélange de scalaires, de valeurs booléennes et de tensors, puis calcule le résultat selon les règles de broadcasting

Fonctions auxiliaires supplémentaires de post-traitement​

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

Description :

  • mask_iou() sert à calculer directement l’intersection sur union de deux masques
  • mask_iou() accepte également un troisième paramètre opts, auquel on peut transmettre compare_size = true ou fournir explicitement width / height comme dimensions de comparaison après alignement
  • db_postprocess() convient au post-traitement de détection de texte de type DB / DBNet ; l’entrée accepte [H, W], [C, H, W] ou [N, C, H, W]
  • db_postprocess() renvoie un tableau de détections, chaque élément contenant score, points et box ; meta / image_meta peuvent réutiliser directement les métadonnées renvoyées par la tensorisation d’image

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

NMS de boîtes rectangulaires ordinaires.

Options courantes :

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

La valeur renvoyée est un tensor int64, avec des indices 1-based.

onnxruntime.box_points(rotated_boxes)​

Convertit une boîte tournée [cx, cy, w, h, theta] en coordonnées de ses quatre sommets.

  • l’entrée peut être un tensor de forme [5], [1, 5] ou [N, 5]
  • pour une seule boîte, un tableau Lua de points est renvoyé ; pour plusieurs boîtes, un tableau de tableaux de points est renvoyé

onnxruntime.xywh_to_xyxy(boxes)​

Convertit une boîte rectangulaire de [cx, cy, w, h] en [x1, y1, x2, y2].

onnxruntime.xyxy_to_xywh(boxes)​

Convertit une boîte rectangulaire de [x1, y1, x2, y2] en [cx, cy, w, h].

onnxruntime.rotated_iou(box1, box2)​

Calcule l’IoU de deux boîtes tournées.

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

NMS de boîtes tournées. La valeur renvoyée est également un tensor int64, avec des indices 1-based.

  • boxes doit être un tensor de boîtes tournées de forme [N, 5]
  • scores peut être un tableau Lua ou un tensor de forme [N] / [N, 1]

onnxruntime.create_decoder(schema)​

Crée un objet decoder réutilisable.

  • l’objet decoder prend en charge :decode(output[, opts]), :task() et :schema()
  • convient à la fixation préalable du schema des sorties de détection, OBB ou classification, afin de le réutiliser plusieurs fois

onnxruntime.decode_yolo(output[, opts])​

Décode directement selon la logique de détection YOLO intégrée et renvoie une liste de records de détection.

onnxruntime.decode_yolo_obb(output[, opts])​

Décode directement selon la logique YOLO OBB intégrée et renvoie une liste de records de détection de boîtes tournées.

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

Sépare la sortie matricielle en table de tensors candidats selon le schema. Les champs renvoyés comprennent généralement :

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles (uniquement pour les schemas liés aux OBB, etc.)

onnxruntime.decode_dense_detection(output, opts)​

Décode la sortie d’une tête de détection dense en :

  • boxes
  • scores
  • labels

boxes, scores et labels sont tous des tensors.

  • l’entrée accepte [R, C] ou [N, R, C]
  • opts.strides est obligatoire et doit être un tableau non vide d’entiers positifs
  • decode_width et decode_height sont également obligatoires
  • seule box_encoding = "grid_center_log_wh" est actuellement prise en charge
  • les autres champs courants comprennent box_offset, score_offset, class_offset, num_classes et score_threshold
  • lorsque la sortie est transmise par batch, la valeur renvoyée est un tableau Lua organisé par batch

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

Organise les tensors [N, 4] de boîtes, scores, classes, etc. en liste de records Lua, chaque élément contenant généralement :

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

Organise les données de lignes OBB en liste de records Lua.

  • opts prend en charge x_index, y_index, width_index et height_index

onnxruntime.points_to_records(points[, opts])​

Organise un tensor de points / points clés de forme [N, P, D] ou [N, P*D] en table Lua.

  • opts prend en charge point_count / keypoint_count
  • opts prend en charge point_dim / keypoint_dim

Fonctions auxiliaires des masques​

onnxruntime.threshold_masks(masks, threshold)​

Transforme un tensor de masques continus en liste de tables de masques Lua après seuillage. Chaque masque contient :

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

Recadre la liste de masques seuillés selon les boîtes [N, 4].

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

Redimensionne la liste de masques aux dimensions indiquées.

  • seule l’option opts.interpolation = "nearest" est actuellement prise en charge

onnxruntime.mask_to_polygon(mask[, opts])​

Convertit un masque binaire unique en liste de points polygonaux.

  • opts.epsilon / opts.approx_epsilon peuvent servir à simplifier approximativement le résultat

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

Projette un masque prototype, ses coefficients et les boîtes de détection vers les dimensions de l’image cible.

  • project_masks() est son alias
  • la valeur renvoyée est une liste de tables de masques Lua et non un tensor

Fonctions auxiliaires des points clés et de la géométrie​

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

Description :

  • reshape_keypoints() prend en charge la réorganisation entre [N, K*D] et [N, K, D]
  • scale_points() analyse par défaut une disposition de points ordinaires ; scale_keypoints() analyse par défaut une disposition de points clés
  • la table liée à transform s’aligne sur les champs de métadonnées du prétraitement d’image ; les champs courants comprennent scale_x, scale_y, pad_left et pad_top

onnxruntime.tracker([opts])​

Crée un objet tracker réutilisable prenant en charge :

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

Champs de configuration courants :

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

Renvoie une valeur de la forme :

  • indices

  • text

  • confidence

  • l’entrée accepte [T, C] ou [N, T, C]

  • prend en charge blank_index, merge_repeated, apply_softmax, return_probabilities et charset

  • renvoie toujours indices

  • text n’est présent que si charset est fourni

  • confidence n’est présent que si apply_softmax ou return_probabilities est activé

  • probabilities et probability_confidence ne sont ajoutés que si return_probabilities est activé

  • lorsque l’entrée est un batch, renvoie un tableau de résultats par batch

onnxruntime.sample_logits(logits[, opts])​

Prend en charge les paramètres d’échantillonnage suivants :

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

Pour des logits 1D, renvoie un indice unique ; pour des logits sur plusieurs lignes, renvoie un tensor int64, avec une sémantique d’index 1-based.

Exemple​

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