Aller au contenu principal

Module de tableaux multidimensionnels ML

MLMultiArray est le type de tenseur le plus courant dans CoreML.
Cette page décrit de manière unifiée les fonctions au niveau du module et les méthodes d’objet liées à MLMultiArray dans le module coreml, notamment :

  • créer des tenseurs ;
  • convertir des données Lua, image ou OpenCV en tenseurs ;
  • convertir dans les deux sens entre MLMultiArray et les tenseurs ORT ;
  • effectuer les opérations mathématiques, réductions, tris et concaténations courants ;
  • fournir des fonctions auxiliaires de post-traitement pour la détection, les OBB, les masques, les points clés, les trackers, etc.

Si vous encapsulez dans Lua un modèle CoreML générique de classification, d’embedding, de texte, de détection ou autre, les fonctionnalités de cette page constituent la base principale.

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

Création et conversion​

coreml.new_multi_array(opts) / coreml.tensor(opts)​

objet_multi_array, message_erreur = coreml.new_multi_array({
    shape = tableau_forme,
    data_type = type_donnees,
})

Crée un objet tableau multidimensionnel CoreML vide, destiné à être utilisé ensuite comme entrée de modèle ou tenseur intermédiaire.

  • shape est la forme cible, par exemple {1, 3, 224, 224}
  • data_type accepte éventuellement "int32", "float32", "float16" ou "double" ; "float64" peut servir d’alias à "double"
  • coreml.tensor(opts) est un alias synonyme

coreml.multi_array_from_table(data, opts) / coreml.tensor_from_table(data, opts)​

objet_multi_array, message_erreur = coreml.multi_array_from_table(tableau_donnees, {
    shape = tableau_forme,
    data_type = type_donnees,
})

Convertit explicitement les données d’une table Lua en MLMultiArray.

  • shape doit correspondre à la quantité totale de données
  • les règles de data_type sont les mêmes que pour new_multi_array()
  • coreml.tensor_from_table(...) est un alias synonyme

coreml.tensor_from_image(image[, opts])​

objet_multi_array, metadonnees = coreml.tensor_from_image(image, configuration)

Convertit un objet image en tenseur utilisable par CoreML selon une configuration explicite.

Champs de configuration courants :

  • width / height
  • layout : prend uniquement en charge "nchw" et "nhwc"
  • channel_order : "rgb", "bgr", "gray", "grey" ou "grayscale"
  • data_type
  • scale
  • mean
  • std
  • resize_mode : "stretch", "letterbox" ou "center_crop"
  • letterbox_mode : prend en charge "center" et "top_left" ; "topleft" est également traité comme "top_left"
  • pad_color
  • interpolation : "bilinear" ou "nearest"
  • alpha_mode : "ignore", "white", "black" ou "premultiply"
  • crop = {x, y, width, height}

Description :

  • cette fonction ne fait que tensoriser l’image selon une configuration explicite ; elle n’associe implicitement aucune règle de prétraitement à un modèle particulier
  • en cas de réussite, la deuxième valeur renvoyée est une table de métadonnées du prétraitement ; en cas d’échec, elle renvoie nil, message_erreur
  • les champs courants des métadonnées comprennent :
    src_width, src_height, crop_x, crop_y, crop_width, crop_height, dst_width, dst_height, resized_width, resized_height, scale_x, scale_y, ratio, pad_left, pad_top, pad_right, pad_bottom, resize_mode, offset_x, offset_y, letterbox_mode

coreml.tensor_from_images(images[, opts])​

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

Convertit un ensemble d’images en tenseur MLMultiArray 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

coreml.image_from_tensor(tensor[, opts])​

objet_image, message_erreur = coreml.image_from_tensor(tenseur, opts)

Restaure un objet image à partir d’un MLMultiArray 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 tenseurs 2D, 3D et 4D sont pris en charge
  • le nombre de canaux doit être 1 ou 3

coreml.image_to_multi_array(image[, opts])​

Il s’agit de l’ancien nom d’interface ; il n’est actuellement qu’un alias de compatibilité de coreml.tensor_from_image(...). Dans le nouveau code, il est recommandé d’utiliser uniformément tensor_from_image().

coreml.tensor_from_cv_mat(mat[, opts]) / coreml.multi_array_from_cv_mat(mat[, opts])​

Convertit un cv.mat en MLMultiArray.

  • il faut d’abord exécuter require("image.cv")
  • les deux noms sont des alias synonymes

coreml.tensor_from_quad(mat, quad[, opts]) / coreml.multi_array_from_quad(mat, quad[, opts])​

objet_multi_array, message_erreur = coreml.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",
    data_type = "float32",
})

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

  • 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

coreml.tensor_from_quads(mat, quads[, opts]) / coreml.multi_array_from_quads(mat, quads[, opts])​

tenseur_batch, message_erreur = coreml.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 tenseur 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

coreml.multi_array_from_ort_tensor(tensor[, data_type])​

objet_multi_array, message_erreur = coreml.multi_array_from_ort_tensor(tenseur_ORT[, "float32"])

Copie nativement un onnxruntime.tensor en MLMultiArray.

  • cette fonction n’existe pas par défaut ; elle est injectée dans le module coreml intégré uniquement après l’exécution de require("onnxruntime")
  • la conversion effectue une copie au niveau natif, sans passer par une table Lua
  • un tenseur string ne peut pas être converti en MLMultiArray

Détermination du type et alias​

coreml.is_multi_array(value) / coreml.is_tensor(value)​

est_multi_array = coreml.is_multi_array(valeur_a_tester)

Détermine si une valeur est un coreml_multi_array_object. is_tensor() est un alias synonyme.

Fonctions auxiliaires du module​

Fonctions auxiliaires de base des tenseurs​

  • coreml.concat(arrays, axis)
  • coreml.stack(arrays, axis)
  • coreml.gather(array, dim, indices)
  • coreml.take(array, indices[, dim])
  • coreml.gather_rows(array, indices)
  • coreml.clamp(array, min, max)
  • coreml.sigmoid(array)
  • coreml.exp(array)
  • coreml.where(condition, x, y)
  • coreml.matmul(lhs, rhs)

Description :

  • take() prélève les valeurs le long de la première dimension 1 par défaut
  • gather_rows() est un alias pratique de take(array, indices, 1)
  • where() accepte un mélange de scalaires et de MLMultiArray, et produit le résultat selon les règles de broadcasting
  • matmul() prend actuellement en charge les combinaisons d’entrées de rang 1 et de rang 2

Fonctions auxiliaires géométriques et de détection​

  • coreml.nms(boxes, scores[, opts])
  • coreml.box_points(rotated_boxes)
  • coreml.xywh_to_xyxy(boxes)
  • coreml.xyxy_to_xywh(boxes)
  • coreml.rotated_iou(lhs, rhs)
  • coreml.rotated_nms(boxes, scores[, opts])

Description :

  • boxes de nms() doit être [N, 4] et scores doit être [N] ou [N, C]
  • boxes de rotated_nms() doit être [N, 5] ; actuellement, scores utilise un tableau Lua de nombres
  • les deux fonctions renvoient un MLMultiArray contenant des indices 1-based

Fonctions auxiliaires de décodage et de records​

  • coreml.create_decoder(schema)
  • coreml.decode_yolo(output[, opts])
  • coreml.decode_yolo_obb(output[, opts])
  • coreml.decode_matrix_candidates(output, schema[, opts])
  • coreml.decode_dense_detection(output, opts)
  • coreml.records_from_boxes(boxes, scores, class_ids[, keep_indices])
  • coreml.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])
  • coreml.points_to_records(points[, opts])

Description :

  • create_decoder() renvoie un objet decoder prenant en charge :decode(), :task() et :schema()
  • decode_dense_detection() renvoie { boxes, scores, labels } ; lorsque l’entrée est un batch, elle renvoie un tableau de résultats par batch
  • opts.strides de decode_dense_detection() est obligatoire et doit être un tableau non vide d’entiers positifs
  • decode_dense_detection() exige également decode_width et decode_height, et ne prend actuellement en charge que box_encoding = "grid_center_log_wh"
  • records_from_boxes(), obb_records_from_rows() et points_to_records() organisent les résultats tensoriels en tables de records mieux adaptées à Lua

Fonctions auxiliaires des masques, points clés et suivis​

  • coreml.threshold_masks(masks, threshold)
  • coreml.crop_masks_by_boxes(masks, boxes)
  • coreml.resize_masks(masks, width, height[, opts])
  • coreml.mask_iou(lhs_mask, rhs_mask)
  • coreml.mask_to_polygon(mask[, opts])
  • coreml.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])
  • coreml.project_masks(proto, coeffs, boxes, image_width, image_height[, opts])
  • coreml.db_postprocess(score_map[, opts])
  • coreml.tracker([opts])
  • coreml.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])
  • coreml.scale_boxes(boxes, transform)
  • coreml.clip_boxes(boxes, clip_width, clip_height)
  • coreml.scale_points(points, transform[, opts])
  • coreml.scale_keypoints(points, transform[, opts])
  • coreml.clip_keypoints(points, clip_width, clip_height[, opts])
  • coreml.ctc_greedy_decode(logits[, opts])
  • coreml.sample_logits(logits[, opts])

Description :

  • project_masks() est un alias de proto_masks()
  • 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
  • tracker() renvoie un objet de suivi prenant en charge :update(), :reset(), :state() et :close()
  • l’entrée de ctc_greedy_decode() accepte [T, C] ou [N, T, C]
  • ctc_greedy_decode() prend en charge blank_index, merge_repeated, apply_softmax, return_probabilities et charset
  • ctc_greedy_decode() 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é
  • sample_logits() prend en charge argmax, temperature, top_k, top_p, min_p et seed
  • pour des logits 1D, sample_logits() renvoie un indice 1-based unique ; pour des logits par batch, elle renvoie un MLMultiArray d’indices

Méthodes de base des objets​

Requêtes de base​

  • array:shape()
  • array:data_type()
  • array:count()
  • array:strides()
  • array:to_table()
  • array:to_cv_mat([opts])

Description :

  • data_type() renvoie "int32", "float32", "float16" ou "double"
  • to_cv_mat() nécessite d’abord l’exécution de require("image.cv")

Pont ORT​

  • array:to_ort_tensor([data_type])

Cette méthode n’existe pas par défaut ; elle est injectée dans coreml_multi_array_object uniquement après l’exécution de require("onnxruntime").

Transformations de type et de forme​

  • array:astype(data_type)
  • array:clone()
  • array:reshape(shape)
  • array:transpose(axes)
  • array:slice(dim, start, stop[, step])
  • array:select(dim, index)
  • array:squeeze([dim])
  • array:unsqueeze(dim)
  • array:flatten([start_dim[, end_dim]])

Description :

  • reshape(), transpose(), squeeze(), unsqueeze() et flatten() renvoient par défaut une vue sans copier les données sous-jacentes
  • reshape() / flatten() échouent pour une disposition non contiguë ; dans ce cas, appelez d’abord clone()
  • slice() et select() renvoient de nouveaux tenseurs contigus, et non une vue
  • la sémantique des indices de slice() / select() / gather() / take() est cohérente avec la page ONNX et reste 1-based

Méthodes numériques et d’indexation​

  • array:gather(dim, indices)
  • array:take(indices[, dim])
  • array:l2_norm()
  • array:dot(other)
  • array:max([axis])
  • array:min([axis])
  • array:add(other)
  • array:sub(other)
  • array:mul(other)
  • array:div(other)
  • array:clamp(min, max)
  • array:sigmoid()
  • array:exp()
  • array:matmul(other)
  • array:scale(number)

Description :

  • add/sub/mul/div prennent en charge les scalaires et un broadcasting limité
  • les résultats de sigmoid(), exp() et matmul() sont convertis en sortie flottante

Réduction, tri et sélection​

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

Description :

  • sans axe, argmax() renvoie l’indice linéaire 1-based de la valeur maximale de tout le tableau
  • argmax(axis) renvoie un MLMultiArray contenant les indices
  • topk() renvoie { values = tenseur, indices = tenseur }
  • sort() renvoie un nouveau MLMultiArray trié et ne renvoie pas de table d’indices supplémentaire

Méthodes d’objet géométriques et de post-traitement​

  • array:clip_boxes(clip_width, clip_height)
  • array:xywh_to_xyxy()
  • array:xyxy_to_xywh()
  • array:reshape_keypoints([keypoint_count[, keypoint_dim|opts]])
  • array:scale_points(transform[, opts])
  • array:clip_keypoints(clip_width, clip_height[, opts])

Ces méthodes et les fonctions de module du même nom partagent la même implémentation sous-jacente ; elles transmettent simplement le tableau courant comme premier paramètre.

Recommandations d’utilisation​

  • pour les nouvelles interfaces CoreML génériques, MLMultiArray est le type de données de première classe par défaut ; il n’est pas recommandé de le convertir trop tôt en table Lua
  • la plupart des opérations par batch doivent autant que possible être effectuées sur l’objet tenseur ; n’appelez to_table() que pour le débogage, les petites sorties ou la compatibilité avec l’ancien code
  • les règles de prétraitement des images doivent être spécifiées explicitement via les paramètres de tensor_from_image(), afin d’éviter de coder en dur le prétraitement d’un modèle dans un flux générique
  • si vous avez besoin d’une copie indépendante ou souhaitez rendre contiguë une disposition non contiguë, appelez explicitement clone()

Exemple​

local arr = assert(coreml.tensor({
    shape = {2, 3},
    data_type = "float32",
}))

local filled = assert(coreml.tensor_from_table({
    {1, 2, 3},
    {4, 5, 6},
}, {
    shape = {2, 3},
    data_type = "float32",
}))

local merged = assert(coreml.concat({filled, filled}, 1))
print(coreml.is_tensor(merged))
print(merged:shape())