Zum Hauptinhalt springen

ML-Multidimensional-Array-Modul

MLMultiArray ist der häufigste Tensor-Typ in CoreML.
Diese Seite beschreibt die zum MLMultiArray gehörenden Funktionen auf Modulebene und Objektmethoden des coreml-Moduls, darunter:

  • Tensorerstellung
  • Konvertierung von Lua-, Bild- und OpenCV-Daten in Tensoren
  • Konvertierung zwischen MLMultiArray und ORT-Tensoren
  • Häufige mathematische Operationen, Reduktion, Sortierung und Verkettung
  • Hilfen zur Nachverarbeitung wie Detection / OBB / Mask / Keypoint / Tracker

Wenn auf Lua-Ebene Klassifikations-, Embedding-, Text-, Detection- oder andere allgemeine CoreML-Modelle verpackt werden sollen, bilden die hier beschriebenen Funktionen die wichtigste Grundlage.

Dieses Modul ist in Versionen nach 20260319 verfügbar

Erstellung und Konvertierung​

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

array, err = coreml.new_multi_array({
    shape = shape,
    data_type = data_type,
})

Erstellt ein leeres CoreML-Multidimensional-Array-Objekt zur späteren Verwendung als Modelleingabe oder Zwischentensor.

  • shape ist das Ziel-Shape, etwa {1, 3, 224, 224}.
  • data_type kann "int32", "float32", "float16" oder "double" sein; "float64" ist ein Alias für "double".
  • coreml.tensor(opts) ist ein gleichbedeutender Alias.

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

array, err = coreml.multi_array_from_table(data_table, {
    shape = shape,
    data_type = data_type,
})

Wandelt Daten aus einer Lua-Tabelle explizit in ein MLMultiArray um.

  • shape muss zur Gesamtanzahl der Daten passen.
  • Die Regeln für data_type entsprechen new_multi_array().
  • coreml.tensor_from_table(...) ist ein gleichbedeutender Alias.

coreml.tensor_from_image(image[, opts])​

array, metadata = coreml.tensor_from_image(image, opts)

Wandelt ein Bildobjekt anhand expliziter Konfiguration in einen für CoreML geeigneten Tensor um.

Häufige Konfigurationsfelder:

  • width / height
  • layout: Unterstützt nur "nchw" und "nhwc".
  • channel_order: "rgb", "bgr", "gray", "grey" oder "grayscale".
  • data_type
  • scale
  • mean
  • std
  • resize_mode："stretch"、"letterbox"、"center_crop"
  • letterbox_mode: Unterstützt "center" und "top_left"; "topleft" wird ebenfalls als "top_left" behandelt.
  • pad_color
  • interpolation："bilinear"、"nearest"
  • alpha_mode："ignore"、"white"、"black"、"premultiply"
  • crop = {x, y, width, height}

Hinweise:

  • Diese Funktion tensorisiert Bilder ausschließlich anhand der expliziten Konfiguration und bindet nicht implizit die Vorverarbeitungsregeln eines bestimmten Modells.
  • Bei Erfolg ist der zweite Rückgabewert eine Metadatentabelle der Vorverarbeitung; bei einem Fehler wird nil, err zurückgegeben.
  • Häufige Metadatenfelder sind: 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])​

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

Wandelt eine Gruppe von Bildern als Batch in MLMultiArray 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.

coreml.image_from_tensor(tensor[, opts])​

image, err = coreml.image_from_tensor(tensor, opts)

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

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.

coreml.image_to_multi_array(image[, opts])​

Dies ist der Name der älteren Schnittstelle und derzeit nur ein Kompatibilitätsalias für coreml.tensor_from_image(...). In neuem Code sollte einheitlich tensor_from_image() verwendet werden.

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

Wandelt cv.mat in ein MLMultiArray um.

  • Zuerst require("image.cv") ausführen.
  • Beide Namen sind gleichbedeutende Aliase.

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

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

Schneidet aus cv.mat perspektivisch einen viereckigen Bereich aus und gibt direkt ein MLMultiArray 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.

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

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

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.

coreml.multi_array_from_ort_tensor(tensor[, data_type])​

array, err = coreml.multi_array_from_ort_tensor(ort_tensor[, "float32"])

Wandelt einen onnxruntime.tensor durch natives Kopieren in ein MLMultiArray um.

  • Diese Funktion ist standardmäßig nicht vorhanden und wird erst nach require("onnxruntime") in das integrierte coreml-Modul eingefügt.
  • Die Konvertierung kopiert auf der nativen Ebene und durchläuft keine Lua-Tabelle.
  • string-Tensoren können nicht in MLMultiArray umgewandelt werden.

Typprüfung und Aliase​

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

is_multi_array = coreml.is_multi_array(value)

Prüft, ob ein Wert ein coreml_multi_array_object ist. is_tensor() ist ein gleichbedeutender Alias.

Hilfsfunktionen auf Modulebene​

Grundlegende Tensor-Hilfen​

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

Hinweise:

  • take() liest standardmäßig entlang der Dimension 1.
  • gather_rows() ist ein praktischer Alias für take(array, indices, 1).
  • where() unterstützt die Mischung aus Skalaren und MLMultiArray und erzeugt das Ergebnis nach Broadcast-Regeln.
  • matmul() unterstützt derzeit Kombinationen aus Rank-1- und Rank-2-Eingaben.

Geometrie- und Detection-Hilfen​

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

Hinweise:

  • boxes von nms() muss [N, 4] sein, scores muss [N] oder [N, C] sein.
  • boxes von rotated_nms() muss [N, 5] sein; scores wird derzeit als numerisches Lua-Array verwendet.
  • Beide geben ein MLMultiArray mit 1-basierten Indizes zurück.

Decoder- und Record-Hilfen​

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

Hinweise:

  • create_decoder() gibt ein Decoderobjekt mit :decode(), :task() und :schema() zurück.
  • decode_dense_detection() gibt { boxes, scores, labels } zurück; bei einer Batch-Eingabe ein Batch-Ergebnisarray.
  • opts.strides von decode_dense_detection() ist erforderlich und muss ein nicht leeres Array positiver Ganzzahlen sein.
  • decode_dense_detection() erfordert außerdem decode_width und decode_height; derzeit wird nur box_encoding = "grid_center_log_wh" unterstützt.
  • records_from_boxes(), obb_records_from_rows() und points_to_records() bereiten Tensorergebnisse als für Lua geeignete Record-Tabelle auf.

Masken-, Keypoint- und Tracker-Hilfen​

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

Hinweise:

  • project_masks() ist ein Alias für proto_masks().
  • 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 aus der Bildtensorisierung direkt wiederverwendet werden.
  • tracker() gibt ein Trackerobjekt mit :update(), :reset(), :state() und :close() zurück.
  • ctc_greedy_decode() unterstützt Eingaben mit [T, C] oder [N, T, C].
  • ctc_greedy_decode() unterstützt blank_index, merge_repeated, apply_softmax, return_probabilities und charset.
  • ctc_greedy_decode() gibt immer indices zurück; text nur bei charset; confidence nur bei aktiviertem apply_softmax oder return_probabilities; probabilities und probability_confidence nur bei aktiviertem return_probabilities.
  • sample_logits() unterstützt argmax, temperature, top_k, top_p, min_p und seed.
  • Für 1D-Logits gibt sample_logits() einen einzelnen 1-basierten Index zurück, für gebatchte Logits einen Index-MLMultiArray.

Grundlegende Objektmethoden​

Grundlegende Abfragen​

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

Hinweise:

  • data_type() gibt "int32", "float32", "float16" oder "double" zurück.
  • Für to_cv_mat() muss zuerst require("image.cv") ausgeführt werden.

ORT-Bridge​

  • array:to_ort_tensor([data_type])

Diese Methode ist standardmäßig nicht vorhanden und wird erst nach require("onnxruntime") in coreml_multi_array_object eingefügt.

Typ- und Shape-Transformationen​

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

Hinweise:

  • reshape(), transpose(), squeeze(), unsqueeze() und flatten() geben standardmäßig eine View zurück und kopieren die zugrunde liegenden Daten nicht.
  • reshape() / flatten() schlagen bei nicht zusammenhängendem Layout fehl; in diesem Fall zuerst clone() aufrufen.
  • slice() und select() geben neue zusammenhängende Tensoren statt Views zurück.
  • Die Indexsemantik von slice() / select() / gather() / take() bleibt wie auf der ONNX-Seite einheitlich 1-basiert.

Numerische und Indexmethoden​

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

Hinweise:

  • add/sub/mul/div unterstützen Skalare und begrenztes Broadcasting.
  • Die Ergebnisse von sigmoid(), exp() und matmul() werden auf eine Gleitkommaausgabe angehoben.

Reduktion, Sortierung und Auswahl​

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

Hinweise:

  • Ohne Achse gibt argmax() den 1-basierten linearen Index des Maximums im gesamten Array zurück.
  • argmax(axis) gibt ein MLMultiArray mit den Indizes zurück.
  • topk() gibt { values = tensor, indices = tensor } zurück.
  • sort() gibt ein neues sortiertes MLMultiArray zurück und liefert keine zusätzliche Indextabelle.

Geometrie- und Nachverarbeitungs-Objektmethoden​

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

Diese Methoden verwenden dieselbe zugrunde liegende Implementierung wie die gleichnamigen Funktionen auf Modulebene; das aktuelle Array wird lediglich als erstes Argument übergeben.

Empfehlungen zur Verwendung​

  • Für die neuen allgemeinen CoreML-Schnittstellen ist MLMultiArray der native Standarddatentyp; eine zu frühe Umwandlung in eine Lua-Tabelle wird nicht empfohlen.
  • Die meisten Batch-Operationen sollten möglichst am Tensorobjekt ausgeführt werden. to_table() erst für Debugging, kleine Datenausgaben oder Kompatibilität mit älterem Code aufrufen.
  • Regeln der Bildvorverarbeitung sollten über die Argumente von tensor_from_image() explizit festgelegt werden, damit die Vorverarbeitung eines bestimmten Modells nicht in den allgemeinen Ablauf fest verdrahtet wird.
  • Für eine unabhängige Kopie oder zum Umwandeln eines nicht zusammenhängenden Layouts in einen zusammenhängenden Tensor explizit clone() aufrufen.

Beispiel​

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