前処理ノード

Preprocは、MLA推論の前に使用される、CVU画像前処理機能を統合したノードです。画像のリサイズ、アスペクト比を維持したレターボックスパディング、カラー変換、正規化、量子化、およびモデルが期待するテンソル形式へのテッセレーションを実行できます。

ほとんどのアプリケーションでは、Model::Options::preprocessを通じて前処理を設定し、モデルのルートプランナーが適切なPreprocノードを作成するようにします。nodes::Preproc(...)を直接構築するのは、完全な入力と出力の契約をすでに把握しているカスタムグラフフラグメントを構築する場合のみです。

クイックスタート

C++：

#include <neat.h>
#include <opencv2/imgcodecs.hpp>

using namespace simaai::neat;

Model::Options opt;
opt.preprocess.resize.enable = AutoFlag::On;
opt.preprocess.resize.width = 640;
opt.preprocess.resize.height = 640;
opt.preprocess.resize.mode = ResizeMode::Letterbox;
opt.preprocess.resize.pad_value = 114;
opt.preprocess.resize.scaling_type = "BILINEAR";
opt.preprocess.color_convert.input_format = PreprocessColorFormat::BGR;
opt.preprocess.color_convert.output_format = PreprocessColorFormat::RGB;
opt.preprocess.normalize.enable = AutoFlag::On;
opt.preprocess.normalize.mean = {0.0f, 0.0f, 0.0f};
opt.preprocess.normalize.stddev = {1.0f, 1.0f, 1.0f};

Model model("/path/to/model.tar.gz", opt);

cv::Mat image = cv::imread("/path/to/frame.jpg", cv::IMREAD_COLOR);
TensorList tensors = stages::Preproc({image}, model);

Python：

import cv2
import pyneat

opt = pyneat.ModelOptions()
opt.preprocess.resize.enable = pyneat.AutoFlag.On
opt.preprocess.resize.width = 640
opt.preprocess.resize.height = 640
opt.preprocess.resize.mode = pyneat.ResizeMode.Letterbox
opt.preprocess.resize.pad_value = 114
opt.preprocess.resize.scaling_type = "BILINEAR"
opt.preprocess.color_convert.input_format = pyneat.PreprocessColorFormat.BGR
opt.preprocess.color_convert.output_format = pyneat.PreprocessColorFormat.RGB
opt.preprocess.normalize.enable = pyneat.AutoFlag.On
opt.preprocess.normalize.mean = [0.0, 0.0, 0.0]
opt.preprocess.normalize.stddev = [1.0, 1.0, 1.0]

model = pyneat.Model("/path/to/model.tar.gz", opt)

image = cv2.imread("/path/to/frame.jpg", cv2.IMREAD_COLOR)
tensors = pyneat.stages.preproc(
    [image],
    model,
    image_format=pyneat.PixelFormat.BGR,
)

その使い道

ユースケース	API	ガイドライン
モデル全体のパス	Model model(path, opt); graph.add(model);	本番環境のパイプラインに推奨されます。モデルアーカイブとルートプランナーによって、正確な前処理グラフファミリーとテンソルの引き渡しが決定されます。
単独のステージ	stages::Preproc(images, model)	これは、簡単なテスト、前処理のデバッグ、またはMLAへの手動での入力に役立ちます。
ROIリスト段階	stages::Preproc(images, model, rois)	複数のソース画像にわたるランタイムウィンドウから、各出力が生成される必要がある場合に使用します。
手動ノード	nodes::Preproc(PreprocOptions{...})	高度なグラフ作成機能のみ。モデルアーカイブが利用可能な場合は、モデルによる管理された構築を推奨します。

APIのインターフェース

C++：

namespace simaai::neat::nodes {
std::shared_ptr<Node> Preproc(PreprocOptions opt = {});
}

namespace simaai::neat::stages {
TensorList Preproc(const std::vector<cv::Mat>& inputs, const Model& model);
TensorList Preproc(const std::vector<cv::Mat>& inputs, const Model& model,
                   const std::vector<PreprocessRoi>& rois);
}

Python：

pyneat.nodes.preproc(options: pyneat.PreprocOptions | None = None)

pyneat.stages.preproc(
    images: list,
    model: pyneat.Model,
    *,
    rois: list[pyneat.PreprocessRoi] | None = None,
    image_format: pyneat.PixelFormat | None = None,
    copy: bool = False,
) -> list[pyneat.Tensor]

stages::Preproc は、モデルによって解決された前処理計画を使用します。これにより、スタンドアロンの呼び出しと、完全なグラフが実行するのと同じ Preproc ノードとの整合性が保たれます。

入力と出力の契約

契約項目	動作
入力タイプ	C++は受け入れます cv::Mat 画像、通常は CV_8UC3 RGB/BGR形式の場合 CV_8UC1 グレースケール画像の場合。Pythonでは、uint8形式のNumPy/Torch配列を受け入れます。pyneat.Tensor HWまたはHWC形式の画像。
ソースバッチ	ROI（関心領域）を使用しないオーバーロード処理は、各画像を個別に処理します。ROIリストオーバーロードは、同じサイズで同じ種類のソース画像のバッチを受け入れます。
出力順序	ROI（関心領域）を使用しないオーバーロードは、画像の順に結果を出力します。ROIリストを使用するオーバーロードは、ROIの順に結果を出力します。
出力データ型/レイアウトは、モデルの実行パスによって決定されます。具体的には、解決された前処理グラフファミリーに応じて、高密度BF16/INT8/INT16、またはタイル状のMLAレイアウトのいずれかが選択されます。
メタデータ	出力テンソルは、リサイズ、レターボックス、正規化、量子化、テッセレーション、およびROIジオメトリを記述するtensor.semantic.preprocessメタデータを持ちます。

モデルの前処理オプション

これらは、アプリケーションコードで優先的に使用すべき、ユーザー向けのオプションです。

サイズ変更とアスペクト比

オプション	意味
opt.preprocess.resize.enable を	、Auto、On、または Off に設定します。Auto を選択すると、プランナーがリサイズが必要かどうかを推測します。
opt.preprocess.resize.width / height	は、ターゲットモデルへの入力サイズです。0 は、可能な場合はモデルの定義から推測することを意味します。
opt.preprocess.resize.mode	ResizeMode::Stretch, ResizeMode::Letterboxまたは ResizeMode::Crop.
opt.preprocess.resize.pad_value	レターボックスパディングに使用する塗りつぶし値。114 は一般的な YOLO のデフォルト値です。
opt.preprocess.resize.scaling_type	：補間方式のトークン。サポートされているトークンには、BILINEAR、NEAREST_NEIGHBOUR、BICUBIC、INTERAREA、およびNO_SCALINGが含まれます。NEAREST_NEIGHBORとINTER_AREAは、許容される別名です。

ResizeMode::Letterbox は、アスペクト比を維持するために、画像または関心領域をターゲットに合わせて拡大縮小し、残りの領域をパディングします。ResizeMode::Stretch は、幅と高さを個別に拡大縮小します。ResizeMode::Crop は、等方性スケーリング後に中央部分を切り抜きます。

色、正規化、量子化、およびテッセレーション

オプション	意味
opt.preprocess.color_convert.input_format	入力フォーマットのヒント：RGB、BGR、GRAY8、NV12、I420、またはAuto。
opt.preprocess.color_convert.output_format	モデルへの入力カラーフォーマット。通常は、RGB、BGR、またはGRAY8です。
opt.preprocess.normalize.enable	平均値/標準偏差による正規化を有効または無効にします。
opt.preprocess.normalize.mean	チャンネルごとの平均値。モデルの学習時に使用した前処理と一致させる。
opt.preprocess.normalize.stddev	チャンネルごとの除数。モデルのトレーニング中に使用されたのと同じ正規化されたチャンネル統計を使用します。たとえば、ImageNetスタイルの値（{0.229,0.224,0.225}付近の値）などです。
モデルが量子化された出力を期待する場合に、プランナー/ユーザーが量子化された出力を制御できるようにします。	opt.preprocess.quantize.enable
opt.preprocess.quantize.zero_point / scale	明示的な量子化パラメータ。モデルのキャリブレーションを上書きする場合以外は、設定しないでください。
opt.preprocess.tessellate.enable	MLAタイルレイアウト出力のためのプランナー/ユーザー制御。有効にすると、Preproc は、テッセレーションされたテンソルを返します。
opt.preprocess.tessellate.slice_shape	高度なタイルジオメトリの上書き。モデルの仕様で上書きが必要な場合にのみ設定してください。

ランタイムにおける投資対効果のリスト

ROIリストは、静的なPreprocOptionsフィールドではなく、ランタイム時に選択される入力メカニズムです。スタンドアロンのステージオーバーロードに渡してください。

C++:

std::vector<cv::Mat> images = {image0, image1};
std::vector<PreprocessRoi> rois = {
    {0, 0, 0, 320, 240},      // ROI from images[0]
    {1, 100, 50, 256, 256},   // ROI from images[1]
    {0, -16, 32, 128, 128},   // partially outside images[0], padded by Preproc
};

TensorList roi_tensors = stages::Preproc(images, model, rois);

Python：

images = [image0, image1]
rois = [
    pyneat.PreprocessRoi(0, 0, 0, 320, 240),
    pyneat.PreprocessRoi(1, 100, 50, 256, 256),
    pyneat.PreprocessRoi(0, -16, 32, 128, 128),
]

roi_tensors = pyneat.stages.preproc(
    images,
    model,
    rois=rois,
    image_format=pyneat.PixelFormat.BGR,
)

cv2.imreadで読み込んだ画像にはimage_format=pyneat.PixelFormat.BGR、RGB画像にはRGB、HWグレースケール画像にはGRAY8を使用します。Pythonの画像バッファーが、ステージの処理完了前に変更または解放される可能性がある場合にのみ、copy=Trueを設定します。

PreprocessRoi

フィールド	意味
batch_index	は、images ベクトル内のソース画像のインデックスです。
x, y	ソース画像のピクセル単位でのROIの左上座標。符号付きの値を使用できるため、ROIはフレームの外から開始できます。
width, height	ROIのサイズをピクセル単位で指定します。両方の値は正の値である必要があります。

ROIリストのセマンティクス

ルール	動作
出力数/順序	要求された各ROIに対して1つのテンソルを、ROIベクトルの順序に従って返します。空のROIベクトルが入力された場合、空のTensorListが返されます。
1つの画像に複数のROI（関心領域）を設定できます。	複数のエントリで、同じbatch_indexを使用できます。
一括処理可能なソース画像	すべてのソース画像が同じサイズ、タイプ、およびチャンネル数を持つ場合にサポートされます。
フレーム外のピクセル：	RGB/BGR/GRAY画像でサポートされており、ソース範囲外のピクセルは、設定されたパディング値でパディングされます。
入力形式	ランタイムでは、ROIリストのソース画像として、パックされた8ビットRGB/BGR (CV_8UC3) およびGRAY/GRAY8 (CV_8UC1) がサポートされます。NV12/I420 ROIリストは、この段階のAPIには意図的に含まれていません。
リサイズ動作	ROIは、フルフレームの前処理と同じリサイズモード、スケーリングタイプ、アスペクト比ポリシー、正規化、データ型、およびテッセレーション設定を使用します。
メタデータ	各出力テンソルには、スカラーROIメタデータと、モデル/前処理された座標からソースフレーム座標へのアフィン変換が追加されます。

直接、PreprocOptions フィールドを指定します。

これらは、手動でのノード構築にのみ使用してください。モデルによって管理される構築では、アーカイブと解決された前処理計画から、これらのほとんどが自動的に入力されます。

フィールドグループ	フィールド
の形状は、	、input_shape、output_shape、slice_shape、scaled_width、scaled_height、batch_size です。
変換コントロール	は、normalize、aspect_ratio、tessellate、dynamic_input_dims、channel_mean、channel_stddev を制御します。
形式は、	、input_img_type、output_img_type、output_dtype、scaling_type、padding_type、pad_value です
量子化	q_zp、q_scale
ランタイムの接続設定：	グラフ名：graph_name、ノード名：node_name、要素名：element_name、CPU：cpu、次のCPU：next_cpu、アップストリーム名：upstream_name、グラフ入力名：graph_input_name
高度なバッファー制御	single_output_handoff、num_buffers、num_buffers_model、num_buffers_locked、model_managed_contract

メタデータとBoxDecode

Preproc は、後続のノードが画像変換を正しく逆変換できるように、前処理メタデータを書き込みます。特に、SimaBoxDecode は、このメタデータを使用して、検出ボックスを元の画像または ROI 座標空間にマッピングします。

重要なメタデータフィールドには、以下のようなものがあります。

• original_width / original_height
• resized_width / resized_height
• scaled_width / scaled_height
• pad_left, pad_right, pad_top, pad_bottom
• resize_mode, color_in, color_out
• normalize, quantize, tessellate
• affine_* 変換フィールド
• roi_list_enabled、rois、roi_affines、およびROIの数/容量フィールド

トラブルシューティング

症状	確認
バウンディングボックスがシフトまたはスケーリングされます。	次のパラメータを確認してください：resize.mode、pad_value、およびダウンストリームのデコード処理がtensor.semantic.preprocessを正しく読み取ることを確認してください。
ROIの出力結果がすべて同じになっているようです。	batch_index、x、y、width、およびheightの値が想定どおりに異なっているか、また、元の画像がそれぞれ異なっているかを確認してください。
ROIリストの呼び出し時にエラーが発生する前に、	次の点を確認してください。画像バッチが空でないこと、すべての画像のサイズ、タイプ、チャンネルが一致していること、batch_index が有効であること、およびROIの幅と高さが正の値であること。
予期しないデータ型/レイアウト	model.resolved_preprocess_plan() と出力テンソルの意味を調べてください。量子化/テッセレーションはモデルの処理に従います。
レターボックス処理の結果、予期しないパディングが発生しています。	ResizeMode::Letterbox、ターゲットサイズ、ROIのアスペクト比、およびpad_valueを確認してください。

関連項目

• ROIリストの前処理
• 推論前に画像を前処理する
• データ形式
• ノードのプログラミングモデル
• BoxDecode デコードの種類