Перейти к основному содержимому

Модуль многомерных массивов ML

MLMultiArray — наиболее распространённый тип тензора в CoreML.
На этой странице описаны модульные функции и методы объектов coreml, связанные с MLMultiArray, включая:

  • создание тензоров
  • преобразование данных Lua / изображений / OpenCV в тензоры
  • преобразование между MLMultiArray и ORT tensor
  • распространённые математические операции, редукцию, сортировку и объединение
  • вспомогательные средства постобработки detection / OBB / mask / keypoint / tracker и других типов

Если вы создаёте на уровне Lua оболочку для классификации, Embedding, текстовой или детекционной модели либо другой универсальной модели CoreML, возможности этой страницы составляют её основную основу.

Доступно в версиях после 20260319

Создание и преобразование​

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

многомерный_массив, сообщение_об_ошибке = coreml.new_multi_array({
    shape = массив_формы,
    data_type = тип_данных,
})

Создаёт пустой объект многомерного массива CoreML для последующего использования в качестве входа модели или промежуточного тензора.

  • shape задаёт целевую форму, например {1, 3, 224, 224}
  • data_type может быть "int32", "float32", "float16" или "double"; "float64" является псевдонимом "double"
  • coreml.tensor(opts) — синонимичный псевдоним

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

многомерный_массив, сообщение_об_ошибке = coreml.multi_array_from_table(таблица_данных, {
    shape = массив_формы,
    data_type = тип_данных,
})

Явно преобразует данные таблицы Lua в MLMultiArray.

  • shape должна соответствовать общему числу элементов данных
  • Правила data_type совпадают с new_multi_array()
  • coreml.tensor_from_table(...) — синонимичный псевдоним

coreml.tensor_from_image(image[, opts])​

многомерный_массив, метаданные = coreml.tensor_from_image(изображение, конфигурация)

Преобразует объект изображения в поддерживаемый CoreML тензор согласно явной конфигурации.

Распространённые поля конфигурации:

  • width / height
  • layout: поддерживаются только "nchw" и "nhwc"
  • channel_order: "rgb", "bgr", "gray", "grey" или "grayscale"
  • data_type
  • scale
  • mean
  • std
  • resize_mode: "stretch", "letterbox", "center_crop"
  • letterbox_mode: поддерживаются "center", "top_left"; "topleft" также обрабатывается как "top_left"
  • pad_color
  • interpolation: "bilinear", "nearest"
  • alpha_mode: "ignore", "white", "black", "premultiply"
  • crop = {x, y, width, height}

Описание:

  • Функция отвечает только за явное преобразование изображения в тензор по конфигурации и не привязывается неявно к правилам предварительной обработки конкретной модели
  • При успехе второе возвращаемое значение — таблица метаданных предварительной обработки; при ошибке возвращаются nil, сообщение_об_ошибке
  • Распространённые поля метаданных: 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])​

пакетный_тензор, пакетные_метаданные = coreml.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})

Пакетно преобразует набор изображений в MLMultiArray.

  • Размеры исходных изображений могут различаться
  • Изображения можно объединить в batch, если форма результата после разбора и data_type у каждого изображения совпадают
  • Второе возвращаемое значение — массив метаданных в порядке входных изображений

coreml.image_from_tensor(tensor[, opts])​

объект_изображения, сообщение_об_ошибке = coreml.image_from_tensor(тензор, opts)

Восстанавливает объект изображения из 2D / 3D / 4D MLMultiArray, что удобно для отладки входов и выходов модели.

Распространённые поля конфигурации:

  • layout
  • channel_order
  • batch_index: начинается с 1, по умолчанию используется batch 1
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" или "0_1"

Описание:

  • Поддерживаются только тензоры 2D / 3D / 4D
  • Поддерживается только 1 или 3 канала

coreml.image_to_multi_array(image[, opts])​

Это старое имя интерфейса, теперь являющееся только совместимым псевдонимом coreml.tensor_from_image(...). В новом коде рекомендуется использовать tensor_from_image().

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

Преобразует cv.mat в MLMultiArray.

  • Сначала необходимо выполнить require("image.cv")
  • Оба имени являются синонимичными псевдонимами

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

многомерный_массив, сообщение_об_ошибке = 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",
})

Выполняет перспективное кадрирование четырёхугольной области в cv.mat и непосредственно возвращает MLMultiArray.

  • Сначала необходимо выполнить require("image.cv")
  • quad можно передать как четыре точки или как таблицу с полем points
  • Основные opts почти совпадают с tensor_from_image(); дополнительные поля: content_width, content_height, border_type
  • Подходит для выравнивания одной рамки и преобразования в тензор перед OCR

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

пакетный_тензор, сообщение_об_ошибке = 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",
})

Пакетно кадрирует несколько четырёхугольников и автоматически объединяет их в batch-тензор.

  • Сначала необходимо выполнить require("image.cv")
  • quads должен быть непустым массивом; каждый элемент может содержать points
  • content_width и content_height элемента имеют приоритет над одноимёнными полями глобального opts
  • В зависимости от rank результата функция автоматически объединяет его через stack() или concat(), что удобно для пакетной обработки нескольких рамок OCR

coreml.multi_array_from_ort_tensor(tensor[, data_type])​

многомерный_массив, сообщение_об_ошибке = coreml.multi_array_from_ort_tensor(тензор_ORT[, "float32"])

Нативно копирует onnxruntime.tensor в MLMultiArray.

  • По умолчанию функция отсутствует; она внедряется во встроенный модуль coreml только после require("onnxruntime")
  • Преобразование выполняется копированием на native-уровне, без таблицы Lua
  • string tensor нельзя преобразовать в MLMultiArray

Проверка типов и псевдонимы​

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

это_многомерный_массив = coreml.is_multi_array(проверяемое_значение)

Проверяет, является ли значение объектом coreml_multi_array_object. is_tensor() — синонимичный псевдоним.

Вспомогательные функции модуля​

Базовые операции с тензорами​

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

Описание:

  • take() по умолчанию выбирает значения по измерению 1
  • gather_rows() — удобный псевдоним take(array, indices, 1)
  • where() поддерживает совместное использование скаляров и MLMultiArray и создаёт результат по правилам broadcasting
  • matmul() сейчас поддерживает комбинации входов rank-1 / rank-2

Геометрия и обнаружение​

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

Описание:

  • boxes в nms() должны иметь форму [N, 4], а scores — [N] или [N, C]
  • boxes в rotated_nms() должны иметь форму [N, 5]; сейчас scores передаются как числовой массив Lua
  • Обе функции возвращают MLMultiArray с индексами 1-based

Вспомогательные функции декодирования и record​

  • 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() возвращает объект decoder с поддержкой :decode(), :task(), :schema()
  • decode_dense_detection() возвращает { boxes, scores, labels }, а при batch-входе — массив batch-результатов
  • opts.strides для decode_dense_detection() обязателен и должен быть непустым массивом положительных целых чисел
  • decode_dense_detection() также требует decode_width, decode_height и сейчас поддерживает только box_encoding = "grid_center_log_wh"
  • records_from_boxes(), obb_records_from_rows(), points_to_records() преобразуют результаты тензоров в более удобные для Lua таблицы record

Маски, ключевые точки и трекинг​

  • 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() — псевдоним proto_masks()
  • mask_iou() непосредственно вычисляет IoU двух масок
  • mask_iou() также принимает третий параметр opts: можно передать compare_size = true или явно указать width / height выровненного размера сравнения
  • db_postprocess() подходит для постобработки обнаружения текста DB / DBNet; вход поддерживает [H, W], [C, H, W] и [N, C, H, W]
  • db_postprocess() возвращает массив обнаружений, каждый элемент содержит score, points и box; meta / image_meta можно напрямую повторно использовать как метаданные преобразования изображения в тензор
  • tracker() возвращает объект трекера с поддержкой :update(), :reset(), :state(), :close()
  • ctc_greedy_decode() принимает [T, C] или [N, T, C]
  • ctc_greedy_decode() поддерживает blank_index, merge_repeated, apply_softmax, return_probabilities, charset
  • ctc_greedy_decode() всегда возвращает indices; text добавляется только при передаче charset; confidence добавляется только при apply_softmax или return_probabilities; probabilities и probability_confidence добавляются только при return_probabilities
  • sample_logits() поддерживает argmax, temperature, top_k, top_p, min_p, seed
  • Для 1D logits sample_logits() возвращает один индекс 1-based, для batched logits — индекс MLMultiArray

Базовые методы объекта​

Базовые запросы​

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

Описание:

  • data_type() возвращает "int32", "float32", "float16" или "double"
  • Для to_cv_mat() необходимо сначала выполнить require("image.cv")

Мост ORT​

  • array:to_ort_tensor([data_type])

По умолчанию этот метод отсутствует; он внедряется в coreml_multi_array_object только после require("onnxruntime").

Преобразование типов и форм​

  • 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(), flatten() по умолчанию возвращают view без копирования базовых данных
  • reshape() / flatten() завершаются ошибкой для непоследовательной раскладки; сначала можно вызвать clone()
  • slice() и select() возвращают новые непрерывные тензоры, а не view
  • Семантика индексов slice() / select() / gather() / take() согласована с ONNX и использует 1-based индексы

Числовые операции и индексы​

  • 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 поддерживают скаляры и ограниченный broadcasting
  • Результаты sigmoid(), exp(), matmul() преобразуются в значения с плавающей точкой

Редукция, сортировка и выбор​

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

Описание:

  • Без оси argmax() возвращает линейный индекс максимального значения всего массива 1-based
  • argmax(axis) возвращает MLMultiArray с индексами
  • topk() возвращает { values = тензор, indices = тензор }
  • sort() возвращает новый отсортированный MLMultiArray и не возвращает дополнительную таблицу индексов

Методы геометрии и постобработки​

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

Эти методы используют ту же базовую реализацию, что и одноимённые функции модуля, но передают текущий массив первым параметром.

Рекомендации​

  • Для новых универсальных интерфейсов CoreML MLMultiArray является основным типом данных по умолчанию; не рекомендуется преждевременно преобразовывать его в таблицу Lua
  • Большинство пакетных операций следует выполнять непосредственно над объектом тензора, а to_table() вызывать только для отладки, вывода небольших данных или совместимости со старыми скриптами
  • Правила предварительной обработки изображений задавайте явно параметрами tensor_from_image(), не встраивая обработку конкретной модели в общий процесс
  • Если нужна независимая копия или требуется сделать непоследовательную раскладку непрерывным тензором, явно вызовите clone()

Пример​

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