halcon-skill

HALCON ビジョンスクリプト作成スキル

HALCON ビジョンプログラムを生成、リファクタリング、実行、レビューします。プロジェクトの既存の形式を維持し、新しいプログラムは、HDevelopEVO／.hscript が指定されていない限り、デフォルトで .hdev にします。形式の選択が曖昧なタスクに大きく影響する場合にのみ、確認してください。

ユーザーが別の変更を依頼していない限り、HALCON の成果物（.hdev、.hdvp、.hdpl、.hscript）を生成または編集します。

ワークフローを選択する

その形式またはツールを使用する前に、タスクに関連するリファレンスのみを読みます。

タスク	ツールと必須リファレンス
HDevelop XML およびプロシージャのドキュメントを作成または編集する	HDevelop 形式
HDevelopEVO のテキストおよびインポートを作成または編集する	HScript 形式
明示的な入力、JSON の結果、任意の SVG を指定して .hdev コードを実行する（デフォルト：名前付きローカルプロシージャまたは test_*）	scripts/hdev_call.py — Python ランナー
HDevelop を使わずに .hdev の中間状態を調査し、ステップ実行、ブレークポイント設定、ベクトルの確認、またはアイコニック値のプレビューを行う	scripts/hdev_debug.py — デバッガー
フォールバック：既存の .hdev プログラムの main() を実行する、または Python バインディングなしで実行する	hrun — 簡易フォールバックの説明
.hscript を実行する	hscriptengine — HScript エンジン

オペレーターのシグネチャ、デフォルト値、有効範囲、インストール済みの例、またはランタイムの場所については、HALCON 環境とドキュメントを読みます。オペレーターの詳細は推測せず、インストール済みのリファレンスで確認してください。

オーバーレイと注釈については、可視化を読みます。正確なカラーパレット、dev_* の使い方、サポートされる SVG オプション、制限事項が記載されています。SVG のセットアップ、呼び出し、出力ファイルについては、Python ランナーのリファレンスを読みます。

プロシージャの責務

• 公開の本番 API： 外部アプリケーション向けの各プロシージャは、実際の画像を含む Image という名前のアイコニック入力（リージョン、XLD、パス、プレースホルダーではなく、意味型が image）を受け取り、スカラーのブール値 JobPass（1 = 合格、0 = 不合格）を返す必要があります。
• プライベートヘルパー： 内部または test_* からのみ使用されるプロシージャでは、タスク固有のパラメーターのみが必要です。テストランナーからヘルパーを呼び出しても、それが公開の本番 API になるわけではありません。
• テスト： 個々の公開またはプライベートのプロシージャには test_* を使用し、明示的な入力とアサーションを指定します。Python ランナーのテストパターンに従ってください。テストの成功と本番の JobPass は別のものです。想定された拒否でもテストは合格する場合があります。
• 例： main() は例のオーケストレーションに使用し、単体テストのインターフェースとしては使用しません。例のパラメーターは先頭にまとめてください。
• テストおよび例のエントリーポイントは、公開の本番シグネチャの対象外です。隠れたグローバル状態は避けてください。テスト入力にグローバル変数は必要ありません。

ドキュメントの言語

main() または HScript の main セクションを含むすべてのプロシージャと、すべてのパラメーターをドキュメント化します。生成または更新するドキュメントには、次の方針を適用してください。

• デフォルトは常に英語です。
• ユーザーの現地語がわかっていて、英語と異なる場合は、その言語も追加します。
• 既存のプロジェクトドキュメントを確認し、さらにそのドキュメントで使われている言語も使用します。ドキュメントを更新する際は、これらの言語を維持してください。
• 通常は1～2言語ですが、既存のプロジェクトで使用されている言語によっては、さらに増える場合があります。ドイツ語や固定数の翻訳を必須にしないでください。
• XML の言語タグやコメントブロックについては、形式固有のリファレンスに従ってください。タグのないテキストをフォールバックとして使用する場合は、英語にします。このフォールバックは別の言語ではありません。

該当する場合は、目的、現実的な使用例、パラメーターの意味、有効範囲、単位、デフォルト値を記載します。翻訳間で同じ動作に関する記述を統一してください。

作成上の制約

• 画像の取得／入力、ROI、前処理、検出または測定、判定／レポートの流れを理解しやすくしてください。出力と合否の理由を明確にしてください。
• 調整可能なパラメーターは、妥当な既定値と有効範囲を文書化したうえで、プロシージャの入力として公開してください。繰り返し使うロジックやコストの高いハンドル／モデルは再利用してください。
• メートル単位の測定には、ピクセルによる近似ではなく、キャリブレーション済みの変換を使用してください。
• HALCON の慣用的な構文と、安定したタスク固有の名前を使用してください。HScript では、インポートされる API に public proc、ファイル内だけで使うヘルパーに proc、外部プロシージャに from ... import * を使用してください。
• 絶対座標の ROI を生成する場合は、関係する画像の寸法を先に取得するか、適切に clip_region を明示的に設定して、領域のクリッピングを考慮してください。
• 本番用のプロシージャでも、例やテストと同様に可視化には dev_* オペレーターを使用してください。本番用のオーバーレイは、説明対象のロジックのそばに配置してください。可視化を main() や test_* に限定しないでください。必要に応じて複数のウィンドウを使い、表示のためだけに画像を切り抜くのではなく dev_set_part を使用してください。注釈付き成果物のファイルへのエクスポートは、例／テストまたはランナー内に限り、本番用プロシージャには含めないでください。
• 可視化は任意かつノンブロッキングとし、表示を利用できない場合も適切に処理してください。ヘッドレスコードでは stop()、dev_open_dialog、対話型オペレーターを使用しないでください。エラー経路では return () または throw を使用し、想定される実行時エラーに対処してください。
• par_start／par_join は、出力が独立している処理にのみ使用してください。
• 要求されていない限り、カメラへのアクセスや外部通信（ネットワーク、産業用通信、ファイル I/O）を追加しないでください。デバッグの依頼から、装置を動作させる許可があると推測しないでください。

テストと成果物

images フォルダー、ok／nok や training／test／validation などのクラス分割、JSON／YAML アノテーションがあるか確認し、提供されたフィクスチャを適切に使用してください。要求されたテスト／実行の成果物は、既定で result/ に書き込み、テスト対象の各画像に対応するランナーの JSON または CLI ログも保存してください。テストに必要な入力だけを渡してください。

回帰テストには通常の実行を使用してください。中間状態が必要な場合のみデバッグし、仮説を立てて関連するソース／変数を調べ、プレビューは必要なものだけを選んで要求してください。

コマンド間では同じデバッガーのセッション ID を使い続けてください。セッションが running の場合は、新たに実行を開始せず status をポーリングしてください。終了したらセッションを閉じてください。閉じると、残りの文を実行せずに分離プロセスが終了します。コードを変更した場合は、新しいセッションを開始して通常の回帰テストを実行してください。カメラ、ファイル、ネットワーク、装置への副作用を伴う操作を自動的に再実行しないでください。

ネイティブデバッグサーバーにはパスワードがありません。信頼できるホスト／ネットワークを使用し、外部に公開しないでください。サーバーを起動する前に、デバッガーのリファレンスを確認してください。

提出物

要求された解決策について、実行可能なコードをすべて提示してください。重要な画像／キャリブレーション／極性／照明の前提条件を明記し、主要なオペレーターを選択した理由を説明し、調整が必要になりそうなパラメーターを特定してください。実行の証拠と残っている制約を報告し、実行していないテストが合格したとは述べないでください。