Módulo de matrices multidimensionales ML

MLMultiArray es el tipo de tensor más común de CoreML. Esta página reúne las funciones del módulo coreml y los métodos de objeto relacionados con creación, conversión, operaciones matemáticas, detección, máscaras, puntos clave y seguimiento.

Esta página incluye:

• creación de tensores
• conversión de datos de Lua, imágenes y OpenCV a tensores
• conversión entre MLMultiArray y tensores ORT
• operaciones matemáticas, reducciones, ordenación y concatenación habituales
• ayudas de posprocesamiento para detección, OBB, máscaras, puntos clave y seguimiento

Si quieres encapsular en Lua modelos de clasificación, embeddings, texto, detección u otros modelos CoreML generales, las capacidades de esta página son la base principal.

Disponible en versiones posteriores a 20260319

Creación y conversión

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

matriz, información_del_error = coreml.new_multi_array({
    shape = matriz_de_forma,
    data_type = tipo_de_datos,
})

Crea una matriz multidimensional CoreML vacía para usarla como entrada del modelo o tensor intermedio.

• shape es la forma objetivo, por ejemplo {1, 3, 224, 224}
• data_type puede ser "int32", "float32", "float16" o "double"; "float64" es un alias aceptado de "double"
• coreml.tensor(opts) es un alias equivalente

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

matriz, información_del_error = coreml.multi_array_from_table(datos, {
    shape = matriz_de_forma,
    data_type = tipo_de_datos,
})

Convierte explícitamente los datos de una tabla Lua en MLMultiArray.

• shape debe coincidir con la cantidad total de elementos
• data_type sigue las mismas reglas que new_multi_array()
• coreml.tensor_from_table(...) es un alias equivalente

coreml.tensor_from_image(image[, opts])

matriz, metadatos = coreml.tensor_from_image(imagen, opciones)

Convierte un objeto de imagen en un tensor según una configuración explícita.

Opciones habituales:

• width / height
• layout: solo admite "nchw" y "nhwc"
• channel_order: "rgb", "bgr", "gray", "grey" o "grayscale"
• data_type
• scale
• mean
• std
• resize_mode: "stretch", "letterbox" o "center_crop"
• letterbox_mode: admite "center" y "top_left"; "topleft" se trata como "top_left"
• pad_color
• interpolation: "bilinear" o "nearest"
• alpha_mode: "ignore", "white", "black" o "premultiply"
• crop = {x, y, width, height}

Notas:

• Esta función solo realiza la tensorización de imágenes configurada explícitamente; no vincula silenciosamente reglas de preprocesamiento de un modelo concreto.
• Si tiene éxito, el segundo retorno es una tabla de metadatos de preprocesamiento; si falla, devuelve nil, información_del_error.
• Los metadatos suelen incluir 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 y letterbox_mode.

coreml.tensor_from_images(images[, opts])

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

Convierte varias imágenes en un tensor por lotes.

• Los tamaños de las imágenes originales pueden ser distintos
• El lote se puede formar siempre que cada imagen produzca la misma forma de salida y data_type
• El segundo retorno es una matriz de metadatos alineada con el orden de entrada

coreml.image_from_tensor(tensor[, opts])

objeto_de_imagen, información_del_error = coreml.image_from_tensor(tensor, opts)

Restaura un tensor 2D, 3D o 4D MLMultiArray como objeto de imagen.

Opciones habituales:

• layout

• channel_order

• batch_index: basado en 1; el valor predeterminado es el primer lote 1

• scale

• mean

• std

• clamp

• value_range: "0_255" o "0_1"

• Solo admite tensores 2D, 3D o 4D.

• El número de canales solo puede ser 1 o 3.

coreml.image_to_multi_array(image[, opts])

Es el nombre antiguo de coreml.tensor_from_image(...) y se conserva como alias compatible. El código nuevo debería usar tensor_from_image().

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

Convierte un cv.mat en MLMultiArray.

• Primero hay que ejecutar require("image.cv")
• Ambos nombres son alias equivalentes

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

matriz, información_del_error = 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",
})

Recorta en perspectiva una región cuadrilateral de un cv.mat y la convierte directamente en MLMultiArray.

• Primero hay que ejecutar require("image.cv")
• quad puede ser una lista de cuatro puntos o una tabla que contenga points
• Las opciones habituales coinciden con tensor_from_image(); también admite content_width, content_height y border_type
• Es apropiado para rectificar un cuadro y tensorizarlo antes del OCR

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

batch, información_del_error = 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",
})

Recorta varios cuadriláteros y los combina automáticamente en un tensor por lotes.

• Primero hay que ejecutar require("image.cv")
• quads debe ser una matriz no vacía y cada elemento puede contener points
• content_width y content_height de cada elemento sobrescriben los campos globales de opts
• El retorno se combina mediante stack() o concat() según el rango; es apropiado para procesar varios cuadros de OCR

coreml.multi_array_from_ort_tensor(tensor[, data_type])

matriz, información_del_error = coreml.multi_array_from_ort_tensor(tensor_ORT[, "float32"])

Copia un tensor onnxruntime.tensor nativo en MLMultiArray.

• La función solo existe después de ejecutar require("onnxruntime"), que la inyecta en el módulo coreml integrado
• La conversión copia los datos en la capa nativa y no pasa por una tabla Lua
• Los tensores de cadenas no se pueden convertir

Comprobación de tipos y alias

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

es_matriz = coreml.is_multi_array(valor_a_comprobar)
es_matriz = coreml.is_tensor(valor_a_comprobar)

is_tensor() es un alias de is_multi_array() dentro de coreml.

Se utiliza para comprobar si un valor es un objeto coreml_multi_array_object.

Funciones auxiliares del módulo

Ayudas básicas de tensores

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

Notas:

• take() toma valores a lo largo de la primera dimensión de forma predeterminada
• gather_rows() es un alias práctico de take(array, indices, 1)
• where() admite escalares y MLMultiArray combinados, y genera el resultado según las reglas de difusión
• matmul() admite actualmente combinaciones de entradas de rango 1 y 2

Las ayudas geométricas y de detección son nms, box_points, xywh_to_xyxy, xyxy_to_xywh, rotated_iou y rotated_nms. nms usa cajas [N, 4]; rotated_nms, cajas [N, 5]; ambos devuelven índices basados en 1.

Ayudas geométricas y de detección

• 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])
• nms() exige boxes con forma [N, 4] y scores con forma [N] o [N, C]
• rotated_nms() exige boxes con forma [N, 5]; actualmente scores usa una matriz de números Lua
• Ambas funciones devuelven un MLMultiArray con índices basados en 1

Las ayudas de decodificación son create_decoder, decode_yolo, decode_yolo_obb, decode_matrix_candidates, decode_dense_detection, records_from_boxes, obb_records_from_rows y points_to_records. Las ayudas de máscaras, puntos clave y seguimiento incluyen threshold_masks, crop_masks_by_boxes, resize_masks, mask_iou, mask_to_polygon, proto_masks, project_masks, db_postprocess, tracker, reshape_keypoints, scale_boxes, clip_boxes, scale_points, scale_keypoints, clip_keypoints, ctc_greedy_decode y sample_logits.

Ayudas de decodificación y registros

• 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])
• create_decoder() devuelve un objeto decoder con :decode(), :task() y :schema()
• decode_dense_detection() devuelve { boxes, scores, labels }; con entrada por lotes devuelve una matriz de resultados por lote. La misma función decode_dense_detection() puede procesar cada salida del lote.
• decode_dense_detection() exige opts.strides, una matriz no vacía de enteros positivos
• También exige decode_width, decode_height y actualmente solo admite box_encoding = "grid_center_log_wh"
• records_from_boxes() y obb_records_from_rows() organizan los resultados tensoriales en tablas de registros más cómodas para Lua; points_to_records() hace lo mismo con puntos.

Ayudas de máscaras, puntos clave y seguimiento

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

• project_masks() es un alias de proto_masks().

• mask_iou() calcula directamente la intersección sobre unión de dos máscaras.

• mask_iou() admite un tercer argumento opts, incluido compare_size = true o un width / height explícito.

• db_postprocess() es apropiado para el posprocesamiento de detección de texto DB / DBNet y acepta entradas con forma [H, W], [C, H, W] o [N, C, H, W].

• db_postprocess() devuelve una matriz de detecciones con score, points y box en cada elemento; los metadatos meta / image_meta pueden reutilizar directamente los devueltos por la tensorización de imágenes.

• tracker() devuelve un objeto de seguimiento con :update(), :reset(), :state() y :close().

• ctc_greedy_decode() acepta entradas con forma [T, C] o [N, T, C].

• ctc_greedy_decode() admite blank_index, merge_repeated, apply_softmax, return_probabilities y charset.

• ctc_greedy_decode() siempre devuelve indices; solo incluye text si se proporciona charset, confidence si se activa apply_softmax o return_probabilities, y probabilities y probability_confidence si se activa return_probabilities.

• sample_logits() admite argmax, temperature, top_k, top_p, min_p y seed.

• sample_logits() devuelve un índice único basado en 1 para logits 1D y un MLMultiArray de índices para logits por lotes.

Métodos básicos del objeto

Consultas básicas

Los métodos básicos son shape(), data_type(), count(), strides(), to_table() y to_cv_mat([opts]); to_cv_mat requiere require("image.cv"). to_ort_tensor([data_type]) se inyecta después de cargar ONNX Runtime.

• array:shape()
• array:data_type()
• array:count()
• array:strides()
• array:to_table()
• array:to_cv_mat([opts])
• data_type() devuelve "int32", "float32", "float16" o "double"
• to_cv_mat() requiere ejecutar antes require("image.cv")

Puente ORT

• array:to_ort_tensor([data_type])

Este método solo existe después de ejecutar require("onnxruntime"), que lo inyecta en coreml_multi_array_object.

Transformaciones de tipo y forma

Las transformaciones son astype, clone, reshape, transpose, slice, select, squeeze, unsqueeze y flatten.

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

• reshape(), transpose(), squeeze(), unsqueeze() y flatten() devuelven por defecto una vista sin copiar los datos subyacentes.

• reshape() y flatten() pueden fallar con una disposición no contigua; en ese caso usa antes clone().

• slice() y select() devuelven tensores nuevos y contiguos, no vistas.

• Los índices de slice(), select(), gather() y take() siguen la convención basada en 1 de la página de ONNX.

Métodos numéricos y de índices

Las operaciones numéricas son gather, take, l2_norm, dot, max, min, add, sub, mul, div, clamp, sigmoid, exp, matmul y scale.

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

• add/sub/mul/div admiten escalares y broadcasting limitado.

• Los resultados de sigmoid(), exp() y matmul() se promocionan a una salida de punto flotante.

Reducciones, ordenación y selección

Las reducciones y ordenaciones son sum, mean, softmax, normalize, argmax, topk y sort. argmax sin eje devuelve un índice lineal basado en 1; topk devuelve { values = tensor, indices = tensor } y sort no devuelve una tabla adicional de índices.

• array:sum([axis])

• array:mean([axis])

• array:softmax([axis])

• array:normalize([axis])

• array:argmax([axis])

• array:topk(k[, axis])

• array:sort([axis[, descending]])

• argmax() sin eje devuelve el índice lineal basado en 1 del máximo global.

• argmax(axis) devuelve un MLMultiArray de índices.

• topk() devuelve { values = tensor, indices = tensor }.

• sort() devuelve un MLMultiArray nuevo ordenado y no devuelve una tabla de índices adicional.

Métodos geométricos y de posprocesamiento

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

Recomendaciones de uso

• Para un modelo CoreML general nuevo, MLMultiArray es el tipo de datos de primera clase predeterminado y no conviene convertirlo demasiado pronto en una tabla Lua.
• Mantén las operaciones por lotes en objetos tensoriales siempre que sea posible y ejecuta to_table() principalmente para depuración, datos pequeños o compatibilidad con scripts antiguos.
• Especifica explícitamente las reglas de preprocesamiento mediante tensor_from_image() para evitar codificar en el flujo general el preprocesamiento de un modelo concreto.
• Usa clone() cuando necesites una copia independiente o una disposición contigua.

Ejemplo

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