matlab-integrate-pytorch-vision

MPyReq MATLAB インターフェースビルダー

MPyReq フレームワークを使用して、Python／PyTorch モデルリポジトリ用の MATLAB インターフェースを構築します。

使用する場合

• MATLAB を Python の画像処理モデルまたはコンピュータービジョンモデル（セグメンテーション、深度推定、物体検出、画像生成、超解像、姿勢推定、オプティカルフロー、顕著物体検出など）に接続したいとユーザーが求めている場合
• ユーザーがビジョン／画像モデルの GitHub リポジトリ URL を提示し、MATLAB から呼び出したいと希望している場合
• ユーザーが画像／CV モデル用の「MPyReq ラッパー」または「MPyReq デモ」の作成を求めている場合
• pip でインストール可能なビジョンモデルライブラリ（例：Cellpose、SAM2、Depth-Pro、BiRefNet、StarDist）を MATLAB から実行したいとユーザーが希望している場合

使用しない場合

• 汎用的な Python と MATLAB の連携（ビジョン／画像モデルが関係しない場合）
• ビジョン以外のモデル：NLP、音声、表形式データ、強化学習、時系列
• モデルのデプロイ、コンテナ化、推論サーバー
• Python への依存がない MATLAB の画像処理ワークフロー
• Python コードの作成（このスキルでは、Python を呼び出す MATLAB コードを作成します）

前提条件：MATLAB のパスに MPyReq があること

デモスクリプトを生成する前に、MPyReq が利用可能であることを確認してください。利用可能な場合は MATLAB MCP サーバー経由で which MPyReq を実行するか、ユーザーに確認を依頼してください。

MPyReq が MATLAB のパスにない場合：

1. MATLAB File Exchange からMPyReq をダウンロードします： https://mathworks.com/matlabcentral/fileexchange/182230-matlab-based-python-requirements-manager
2. インストールします。方法は次のいずれかです：
   • ダウンロードした .mltbx ファイルを MATLAB で開く（ダブルクリックする）と、MATLAB アドオンとして自動的にインストールされます。または、
   • ファイルを展開し、MPyReq.m を含むフォルダーを MATLAB のパスに追加します：

     addpath("/path/to/mpyreq");
     savepath; % persist across sessions
     

3. MATLAB で which MPyReq を実行して確認します。MPyReq.m へのパスが返されるはずです。

MPyReq がパスにあることを確認するまで、デモの生成に進まないでください。

入力

ユーザーに次の情報を尋ねます：

1. GitHub リポジトリ URL — 接続対象となる Python モデルリポジトリ
2. モデルの機能（任意）— 適切な推論例を特定するために使用します

ステップ 1：リポジトリを分析する

GitHub リポジトリを取得して分析し、次の項目を特定します：

• Python のバージョン要件 — setup.py、setup.cfg、pyproject.toml、または README で必要な Python のバージョンを確認します。指定がない場合は "3.12" を既定値とします。プロジェクトで古いバージョンとの互換性が必要な場合は "3.11" を使用します。
• インストール方法 — プロジェクトのインストール方法を特定します：
  • torch.hub.load() を使用する場合：pip パッケージとして必要なのは torch と torchvision のみです（モデルは自動的にダウンロードされます）
  • pip でインストール可能なパッケージの場合：MPyReq.pipPackage() を使用します
  • パッケージ化されていない git リポジトリの場合：requirements.txt が存在すれば、MPyReq.gitrepo() と MPyReq.requirementTextFile() を使用します
  • pip install git+<url> が必要な場合：MPyReq.pipPackage("git+<url>", Name="<ProjectName>") を使用します
• 追加の依存関係 — 必要な追加の pip パッケージ（例：torch、torchvision など）
• モデルの重み — 重みの読み込み方法を特定します：
  • torch.hub.load() — 重みは自動的にダウンロードされるため、MPyReq.weights() は不要です
  • URL から直接ダウンロードする場合 — チェックポイント URL を指定して MPyReq.weights() を使用します
  • HuggingFace の .from_pretrained() — 重みはライブラリ経由で自動的にダウンロードされます
• 推論例 — README またはサンプルスクリプトから、主要な推論／予測コードを探します
• 前処理の要件 — モデルに特定の入力正規化（例：ImageNet の平均／標準偏差）、リサイズ、またはセンタークロップが必要か確認します

ステップ 2：MPyReq セットアップスクリプトを生成する

デモファイルのパターンに従って、Python 環境をセットアップする MATLAB の .m ファイルを作成します：

必須：インストールフォルダーの設定

生成するすべてのスクリプトの先頭には、必ず MPyReq.setInstallFolder() を記述してください。これにより、Python、パッケージ、モデルの重みをダウンロードする場所を MPyReq に指定します。これがないと、MPyReq は GUI ダイアログを表示し、非対話型の実行がブロックされます。また、対話型の確認プロンプトを避けるため、MPyReq.autoAcceptDownloadPrompts(true) も含めてください。

% Set installation folder (SSD recommended, ~15+ GB free space)
% Change this path to a suitable location on your machine
MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);

パターン A：シンプルな pip パッケージ（Cellpose など）

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.12");
MPyReq.pipPackage("<package_name>");

パターン B：pip パッケージとしての Git リポジトリ（SAM2 など）

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.12");
MPyReq.pipPackage("git+https://github.com/<org>/<repo>.git", Name="<RepoName>");

パターン C：Git リポジトリ + requirements.txt（VGGT、BiRefNet など）

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.11");
MPyReq.gitrepo("https://github.com/<org>/<repo>.git");
reqTxt = MPyReq.pathTo("<repo>") + filesep + "requirements.txt";
MPyReq.requirementTextFile(reqTxt, Name="<repo>Packages");

パターン D：torch.hub モデル（DINOv2、ResNet など）

モデルが torch.hub.load() を使用する場合、git clone や重みのダウンロードは不要です。torch/torchvision をインストールするだけです。

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.12");
MPyReq.pipPackage("torch");
MPyReq.pipPackage("torchvision");
% Model loads automatically via torch.hub:
model = py.torch.hub.load('org/repo', 'model_name');

重みのダウンロードパターン

重みが torch.hub.load() または .from_pretrained() で処理されない場合にのみ必要です。

MPyReq.weights("<weights_url>", DownloadTo=MPyReq.pathTo("<RepoName>") + filesep + "checkpoints");

ステップ 3：MATLAB 推論インターフェイスを作成する

Python の推論例を MATLAB に変換します。変換規則とパターンについては、次のリソースファイルを参照してください。

• references/python_matlab_conversions.md — Python から MATLAB への構文変換表
• references/image_conversion_patterns.md — 画像テンソルの変換（MATLAB と Python 間）、次元の並べ替え、表示パターン

ステップ 4：最終スクリプトを組み立てる

明確なセクションを含む単一の demo<ModelName>.m ファイルを作成します。

%% Setup Python Environment
% Start with clean state (only if switching projects)
% terminate(pyenv); clear MPyReq

% Set installation folder (SSD recommended, ~15+ GB free space)
% Change this path to a suitable location on your machine
MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("<version>");
% ... package installation calls ...

%% Reference Python Code
%{
<paste the original Python inference code as a comment block>
%}

%% Load Model
% ... model loading code ...

%% Run Inference
% ... load input, run model, extract results ...

%% Visualize Results
% ... display/plot results ...

ステップ 5：MATLAB MCP サーバーでテストする

現在のセッションで MATLAB MCP サーバーのツールが利用可能か確認します（matlabRunCode、matlab_run などの MCP ツールを探してください）。

MATLAB MCP サーバーが利用可能な場合：

1. セットアップセクションを実行する — MATLAB MCP サーバーを通じて MPyReq.python() とパッケージのインストール呼び出しを実行し、Python 環境が正しくインストールされることを確認します。
2. 推論セクションを実行する — モデルの読み込みと推論のコードを実行し、エンドツーエンドで機能することを確認します。
3. エラーに応じて修正する — いずれかの手順で失敗した場合は、エラー出力を読み、生成したコードを修正して再実行します。

試行回数の上限と適切なフォールバック

修正して再試行するサイクルを 1 回の試行として数えます。最大 5 回の試行後に停止してください（セットアップと推論を合わせた回数）。5 回の試行後もコードが完全に動作しない場合：

1. 試行を停止します。 同じ、または類似した方法で再試行を続けないでください。
2. 最良のバージョンの demo<ModelName>.m を保存します（最も進展したバージョン。例：セットアップは成功したが推論に失敗した、または推論の一部が実行されたバージョン）。
3. 構造化された引き継ぎ情報を添えて、スクリプトをユーザーに返します。

## What Works
- <list sections/steps that executed successfully>

## What Needs Attention
- <describe the remaining failure: error message, which line/section fails>
- <root cause hypothesis if known>

## Recommended Next Steps
1. <most likely fix — e.g., "Try Python 3.11 instead of 3.12 due to package compatibility">
2. <alternative approach — e.g., "Install system dependency X before running">
3. <manual verification — e.g., "Run `pip install <pkg>` in the MPyReq venv directly to check build logs">

## Environment Details
- Python version attempted: <version>
- Platform: <OS>
- Errors encountered: <brief summary of distinct errors across attempts>

4. コメントを使って、スクリプト内で検証済みのセクションと未検証のセクションを明確に示します。

%% Setup Python Environment — VERIFIED
% ... (code that ran successfully) ...

%% Run Inference — NEEDS MANUAL VERIFICATION
% The following section encountered errors during automated testing.
% See recommended next steps above.
% ... (best-effort code) ...

早期終了条件（5 回の試行より前に停止）：

• 同じエラーが新しい情報なしに 2 回以上繰り返される — 直ちに停止します
• MATLAB の制御範囲外の環境／プラットフォームの問題（例：システムライブラリの不足、ネットワークのブロック、GPU ドライバーの不一致）— 停止して報告します
• システムレベルの対応が必要なパッケージのビルド失敗（例：C コンパイラーの不足、CUDA バージョンの不一致）— 停止して報告します

MATLAB MCP サーバーが利用できない場合：

1. 生成した demo<ModelName>.m ファイルをユーザーに返します。
2. 次の項目をまとめたセットアップ手順を提示します。
   • 前提条件（MATLAB のバージョン、パス上の MPyReq）
   • 実行される MPyReq コマンドと、それらがインストールするもの
   • 初回実行時に想定される動作（Python とパッケージをダウンロードするため、数分かかる場合があります）
   • 実行方法：MATLAB でスクリプトを開き、セクションごとに実行します（Ctrl+Enter）
3. プラットフォーム固有の考慮事項（例：Windows の CUDA セットアップ、UV_EXTRA_INDEX_URL）があれば記載します。

重要な注意事項

• ユーザーに明示的に許可を求めずに、クローンしたリポジトリのソースコード（設定ファイルの編集や Python モジュールへのパッチ適用など）を変更してはなりません。 回避策としてソースの編集が必要な場合は、変更内容を説明し、ユーザーの判断を仰いでください。
• MATLAB では Python のダンダーメソッド（__enter__、__exit__、__init__ など）を使用してはなりません。二重アンダースコアは MATLAB の構文として無効です。torch.no_grad() や torch.inference_mode() などのコンテキストマネージャーでは、with 文のパターンではなく、同等の関数 API（例：py.torch.set_grad_enabled(false/true)）を使用してください。
• 出力は必ず MATLAB の次元順序に戻してください。PyTorch は NCHW（バッチが先、チャンネルが次）を使用します。MATLAB ではバッチが最後、チャンネルが最後から 2 番目（H x W x C x B）です。permute で並べ替えてから、squeeze でサイズ 1 のバッチ次元を削除してください。
• バウンディングボックスを MATLAB 形式に変換してください。Python のモデルは通常、[x1, y1, x2, y2]（角のペア）を返します。MATLAB では M x 4 の [startX, startY, width, height] が必要です。幅には boxes(:,3) - boxes(:,1)、高さには boxes(:,4) - boxes(:,2) を使って変換してください。
• 画像の読み込みには必ず imread を使用してください。Python の画像ライブラリ（PIL、OpenCV など）は使用しないでください。画像の入出力は MATLAB 側で行い、Python 用にテンソルへ変換してください。
• 参照用として、元の Python 推論コードを必ず %{ %} コメントブロックに含めてください。
• py.module.submodule で直接アクセスできない場合（深い階層の場合）は、py.importlib.import_module() を使用してください。
• Windows で GPU／CUDA をサポートする場合は、UV_EXTRA_INDEX_URL の設定が必要になることがあります。
• リポジトリで特定のディレクトリへの cd（相対パスの設定ファイルを読み込む場合など）が必要な場合は、cd(MPyReq.pathTo("<Name>")) を使用してください。
• 該当する場合、生成されたコードが GPU と CPU の両方の実行パスに対応していることをテストしてください。
• MATLAB の画像型、表示関数、データ構造を使用して、MATLAB らしいインターフェイスにしてください。

その他の注意点（クラス ID のマッピング、opencv-python の問題、insertObjectAnnotation のヒント）については、references/common_gotchas.md を参照してください。

参照ファイル

以下の参照ファイルが、このスキルに同梱されています。スキルの references/ ディレクトリから参照してください。

デモの例（期待される出力形式）

• references/demo-cellpose.md — シンプルな pip パッケージのパターン
• references/demo-sam2.md — 重みを含む git+pip のパターン
• references/demo-depthpro.md — 重みを含む git リポジトリ + pip install のパターン
• references/demo-birefnet.md — git リポジトリ + requirements.txt + 重み
• references/demo-stardist.md — 複雑な依存関係の管理
• references/demo-vggt.md — git リポジトリ + requirements.txt、点群の出力

変換ガイド

• references/python_matlab_conversions.md — Python から MATLAB への構文変換表
• references/image_conversion_patterns.md — 画像テンソルの変換と表示のパターン
• references/common_gotchas.md — クラス ID のマッピング、opencv-python の問題、アノテーションのヒント

MPyReq のドキュメント

• references/readme.md — MPyReq ドキュメントの概要

MPyReq クラスはプロジェクトの mpyreq/MPyReq.m にあります。

スキルへのフィードバック

このスキルのガイダンスが誤っていた、不完全だった、または機能しなかった場合は、応答にプレーンテキストのフィードバックマーカーを出力してから、タスクを続けてください。

形式：IPCV-SKILL-FEEDBACK [matlab-integrate-pytorch-vision] [category]: what failed; what you did instead カテゴリ：wrong-command（誤りまたは古いコマンド）、missing-guidance（手順の記載漏れ）、 discovery-failure（推奨された方法が機能しなかった）、platform-issue（環境固有の問題）

---

Copyright 2026 The MathWorks, Inc.

---