/AproLink_AVT_UniAPI_v2.00 by Emi Eguchi

Allied Vision Technologies 社カメラシリーズ開発用 I/F UniAPI の使用方法

2009.2 Ver2.00 AproLink

目次はじめに................................................................................................................................................................................................................................. 4

UniAPIコンポーネント

................................................................................................................................................................................ 5

1-1

DLLモジュール ..................................................................................................................................................................................................... 5

1-2

UniAPIフォルダ構成 .......................................................................................................................................................................................... 5

1-3

Visual StudioでのUniAPI ................................................................................................................................................................................. 6

Getting Start

....................................................................................................................................................................................................... 7

2-1

初期化とカメラ識別 ........................................................................................................................................................................................... 7

2-2

カメラの定義オプション（Optional camera configuration） ................................................................................................... 8

2-3

グラブのための必須カメラ定義 .................................................................................................................................................................. 8

2-4

シングルイメージ取得 ...................................................................................................................................................................................... 9

2-5

連続イメージ取得 ............................................................................................................................................................................................. 10

2-6

APIの開放 .............................................................................................................................................................................................................. 10

一般規約（General Convention） ....................................................................................................................................................... 11 3-1

メソッドパラメータ ......................................................................................................................................................................................... 11

3-1-1 整数型パラメータ ...................................................................................................................................................................................... 11 3-1-2 列挙型の使用方法 ...................................................................................................................................................................................... 11 3-1-3 ハンドル ......................................................................................................................................................................................................... 12 3-1-4 カメラIDパラメータ ..................................................................................................................................................................................... 12 3-1-5 メソッド返り値 ........................................................................................................................................................................................... 12 3-1-6 UniAPIの開放 ............................................................................................................................................................................................... 12

カメラ定義概要 4-1

............................................................................................................................................................................................... 13

手動カメラ定義 .................................................................................................................................................................................................. 14

4-1-1 画像フォーマット定義............................................................................................................................................................................. 14 4-1-2 追加機能定義 ............................................................................................................................................................................................... 14 4-2

自動カメラ定義 .................................................................................................................................................................................................. 15

カメラ定義 5-1

画像フォーマット ............................................................................................................................................................................................. 16

5-1-1 UCC_PrepareFixedGrab() ....................................................................................................................................................................... 16 5-1-2 UCC_PrepareFreeGrab() ......................................................................................................................................................................... 16 2

5-2

明示関数コール ................................................................................................................................................................................................... 18

5-2-1 オート機能AOI ............................................................................................................................................................................................ 18 5-2-2 ホワイトバランス ...................................................................................................................................................................................... 18 5-2-3 アドバンスドホワイトバランス .......................................................................................................................................................... 18 5-2-4 シェーディング補正 ................................................................................................................................................................................. 18 5-2-5 ルックアップテーブル(LUT) ................................................................................................................................................................. 18 5-2-6 シリアルI/O (RS232) ................................................................................................................................................................................. 19 5-2-7 デジタルI/O .................................................................................................................................................................................................. 19 5-2-8 トリガー ......................................................................................................................................................................................................... 19 5-2-9 ユーザープロファイル............................................................................................................................................................................. 19 5-2-10 テストイメージ ........................................................................................................................................................................................ 20 5-2-11 カメラ設定のXML インポート/エクスポート ............................................................................................................................ 20 5-2-12 画像フォーマットの一覧表................................................................................................................................................................. 20

デジタルI/Oとトリガー操作

画像取得(シングル)

................................................................................................................................................................. 21

...................................................................................................................................................................................... 22

7-1

タイミング動作 .................................................................................................................................................................................................. 22

7-2

バッファハンドリング .................................................................................................................................................................................... 22

7-3

ピクセルフォーマット .................................................................................................................................................................................... 22

7-3-1 Windowsビットマップ ............................................................................................................................................................................ 22 7-3-2 UCC_GrabImage メソッド ................................................................................................................................................................... 22

画像取得(シーケンス：連続イメージ)

......................................................................................................................................... 25

8-1

連続イメージの制御 ......................................................................................................................................................................................... 25

8-2

受信画像 ................................................................................................................................................................................................................. 25

Code snippets

.................................................................................................................................................................................................. 26

9-1

初期化 ..................................................................................................................................................................................................................... 26

9-2

Image Format Configuration ..................................................................................................................................................................... 27

9-3

同期画像の取得 .................................................................................................................................................................................................. 27

User Notifications

...................................................................................................................................................................................... 29

はじめに本マニュアルは AVT FirePackage に含まれる開発用 UniAPI の使用方法について説明しています。 AVT FirePackage インストール方法については、別紙マニュアルを参照ください。

Package architecture

1 UniAPI コンポーネント 1-1

DLL モジュール

UniAPI は AVT カメラシリーズを使用してアプリケーションを開発するための C 言語をベースとしたプログラミングインターフェースです。UniAPI は 2 つの DLL モジュールを含んでいます。

UniControl DLL 画像取得におけるカメラ制御と、AVT Smart Feature の反映方法

UniTransform DLL UniTransform DLL はドライバーは独立した UniAPI コンポーネントであり、画像フォーマットの変換やカラー補正のトランザクションを可能とします。主にカラーカメラで Raw 画像を出力する（例：GUPPY）カメラをサポートするためにデザインされています。

1-2

UniAPI フォルダ構成

Include：UniAPI ヘッダーファイルを格納 Lib：UniAPI ライブラリを格納 Sample：サンプルプログラムフォルダ

ディレクトリ

機能概要

対応言語 C++

Grab2Con

MicroView Base

コマンドプロンプトでのサンプル最小限の機能を持つカメラビューワー

2005

Vs6

Borland

2003

2005

(ソフトトリガーでシングルショット) Deinterlace_Resample

インターレース解除サンプル

2003

2005

Exposure_Bracketing

カメラ機能の使用方法確認用サンプル

2003

2005

LUT

LUT サンプル

2003

2005

OpenCv

CV ライブラリを使用したイメージ取得サン

2003

2005

2003

2005

2003

2005

2003

2005

プル SIS

SmartFeature SecureImageStamp を使用したサンプル

Deinterlace

インターレースカメラ設定方法確認用サンプル

EnumFormats

画像フォーマットごとの設定方法を確認するシンプルなサンプル

Grab

連続画像取得を行うサンプル

2003

2005

MatroxImaging

MatroxImage ライブラリを使用したイメー

2003

2005

2003

2005

ジ取得サンプル OpenEVision

Evision ライブラリを使用したイメージ取得サンプル

CppCLI

Grab2Console

コマンドプロンプトでのサンプル

2005

Csharp

MicroView.Net

C#版カメラビューワー

2005

1-3

Visual Studio での UniAPI

VisualStudio で UniAPI を使用した独自のプロジェクトを作成するには、以下の手順です。 1. VisualStudio を開き、ビルトウィザードを使用してプロジェクトを作成します。 2. 以下のヘッダーファイルにインクルード記述を追加します。 #include "UniControl.h" #include "UniTransform.h" 3. 必要に応じて SDK サンプルのソースコードを追加します。 4. プロジェクト→プロジェクトのプロパティ→リンカ→入力→追加の依存ファイルで以下のライブラリを追加します。 UniControl.lib UniTransform.lib

5.プロジェクトを保存してコンパイルを行います。 6

Getting Start

このセクションは、AVT カメラで最初にイメージ取得を成功する事を目的としています。

2-1

初期化とカメラ識別

まず API は ”UCC_Init” を使用して初期化を行う必要があります。次に ”UCC_OpenCamera” でカメラをオープンします。カメラは、通常それぞれのカメラ ID(シリアル番号)で識別されます。カメラ ID が不明な場合、全ての使用可能なカメラのリストを取得するために ”UCC_GetCameras” を使用してください。

※初期化のサンプルは UniControl ヘルプの Code snippets で確認出来ます｡

2-2

カメラの定義オプション（Optional camera configuration）

画像を取得する場合､事前に様々なカメラへの定義オプションが必要です。定義オプションについては、GettingStart チュートリアルで確認できます｡ Camera configuration - Overview、それに続く章に詳細な説明が記述されています。カメラ設定が xml 形式で保存された定義ファイルを使用する場合、”UCC_LoadSettings”でロードしてください。

2-3

グラブのための必須カメラ定義

カメラ通信に影響する解像度、カラーフォーマットなどは、画像をグラブする前に定義設定が必要です。これらは”UCC_PrepareFreeGrab”

あるいは

”UCC_PrepareFixedGrab”で定義します。

詳細については Camera configuration - Image Format を参照ください。

※”UCC_PrepareFreeGrab” のサンプルは、UniControl ヘルプで確認できます。

2-4

シングルイメージ取得

“UCC_GrabBitmapImage” または “UCC_GrabPlanesImage” を使用してシングルイメージのグラブを行います。 Image acqusition のページに、シングルイメージとこのファンクションの詳細を記述しています。

**P22 参照

※シングル画像取得のサンプルは、UniControl ヘルプで確認出来ます。

2-5

連続イメージ取得

連続イメージを取得する場合、転送する画像データをアプリケーションへ通知するイベント「user notification」を使用します。 “E_UNI_NOTIFICATION_FRAME_READY “ で “UCC_RegisterFrameReadyNotification” と “UCC_RegisterNotification” の登録が可能です。画像取得は”UCC_GrabStart”で開始され、転送画像データのアプリケーションへの通知が実行されると、画像取得ため UCC_Get...Image：“UCC_GetImage”, “UCC_GetBitmapImage”, “UCC_GetNativeImage”または”UCC_GetPlanesImage”のうち 1 つがコールされます。

2-6

**P25 参照

API の開放

プログラム終了前に”UCC_Release”を必ずコールしてください。

3 一般規約（General Convention）このセクションでは、UniAPI 全ての関数やデータ型など、プログラムのルールや原則について説明します。まず最初にこの章を読むことを推奨します。

メソッド名この API におけるすべてのメソッド名は、必ず"UCC_”で始まります。それに続くメソッド名の多くは、自身の機能名を使用しています。

3-1 メソッドパラメータ 3-1-1

整数型パラメータ

言語間での相互作用を良くする為にスモールセットのパラメータタイプを使用しており、ほとんどのパラメータは '32 bit unsigned'タイプです。関数パラメータの返り値でポインタを引き渡します。データが関数パラメータによってどの方向に通されるかを示す為に、型定義のラベルは 'IN', 'OUT'と'INOUT'を使用しています。32bit のパラメータタイプは以下の通り定義されています。

typedef UINT32_TYPE

UINT32_IN_TYPE;

// 32 bit unsigned integer type for input

typedef UINT32_TYPE * UINT32_INOUT_TYPE; // 32 bit unsigned integer type for input and output typedef UINT32_TYPE * UINT32_OUT_TYPE;

// 32 bit unsigned integer type for output

'INOUT'と'OUT'は同じタイプとして定義されています。 8、16、64bit タイプに対応する定義も用意されています。

3-1-2

列挙型の使用方法

関数パラメータの説明は、互換性のため enum（列挙型）定義をベースとした UNIT32 タイプとして定義しています。下のサンプルは、これらのパラメータを広範囲に使用する”UCC_SerialIO_SetConfig”関数の呼び出し方法です。

UINT32_TYPE nRate = E_SIOBAUDRATE_19200; UINT32_TYPE nCharsize = 8; UINT32_TYPE nParity = E_SIOPARITY_EVEN; UINT32_TYPE nStopbits = E_SIOSTOPBITS_1; UINT32_TYPE nMode = E_SIOMODE_RECEIVETRANSMIT;

UCC_SerialIO_SetConfig(nCamId, nRate, nCharsize, nParity, nStopbits, nMode);

3-1-3

ハンドル

ある関数は特殊なハンドルタイプのパラメータを持っていますが、ユーザーが作成したり、修正することは出来ません。以下のハンドルタイプが UniAPI で使用されています。

UNI_NOTIFICATION_HANDLE PRESETS_ENUMERATION COLORCODE_ENUMERATION

3-1-4 カメラ ID パラメータ特殊カメラのアドレッシングを行う各メソッドは、最初のパラメータに AVT カメラ ID（ID_TYPE）を持っています。

3-1-5

メソッド返り値

返り値は常に UNI_RETURN_TYPE タイプですので、常に定義されているエラーコードを返す事が可能です。全ての処理が OK である場合、メソッドは”S_OK”を返し、それ以外は特定のエラーコードを返します。 API エラーの場合、0x88xxxxxx のコードを、FireGrab のエラーの場合、0x8Axxxxxx(uni_defines.h を参照)のコードを返します。読める形式に記述したエラーコードの送信は、“UCC_GetErrorInfo”が提供しています。 API エラーの概要は以下の通りです。

基本返り値 UNI_RESULT_API_NOT_INITIALIZED “UCC_Init” がコールされていません

UNI_RESULT_CAMERA_NOT_FOUND カメラに与えられた ID がバス上に見つかりませんカメラがオープンしていないか、カメラにアクセスできない事が原因です。

パラメータ返り値 UNI_RESULT_PARAMETER_INVALID_n n 番目のパラメータが不正です

3-1-6

UniAPI の開放

UniAPI は、使用する前に必ず初期化を行います。初期化には”UCC_Init()”メソッドを使用します。コールバックメソッドのポインタまたはウィンドウズハンドル、それにメッセージなどイベント発生時にコールされるコールバックメソッドを定義でき、”UCC_Release”で開放されます。

4 カメラ定義概要ここでは、接続したカメラに関連した定義オプションの概要を説明します。 1394 バス定義や UniAPI ログ機能についての情報は UniControl ヘルプで確認できます。

4-1 手動カメラ定義 4-1-1

画像フォーマット定義

画像形式の定義は必須定義です。 “UCC_PrepareFixedGrab”または“UCC_PrepareFreeGrab”のどちらもイメージ取得前にコールする必要があります。より詳細な情報はヘルプファイルで確認出来ます。

4-1-2

追加機能定義

カメラ定義を操作する上で３つの方法があります。

明示ファンクションコールサンプル: UCC_Lut_Use

カメラレジスタアクセスでの定義 “UCC_SetRegister”と”UCC_GetRegister”のメソッドを使用します。これらのメソッドでは、フルロング IIDC アドレス(32bit)を使用し 32bit の値が必要です。

統合機能アクセスでの定義統合した方法で機能を定義するために、いくつかの方法があります: UCC_HasFeature UCC_GetFeatureValue UCC_SetFeatureValue UCC_GetFeatureStatus UCC_SetFeatureStatus UCC_HasFeatureStatus UCC_GetFeatureMin UCC_GetFeatureMax

これらの関数は、E_UniFeature タイプの識別 ID で動作します。より詳細な説明は次のセクションに記述しています。

4-2

自動カメラ定義

ユーザー定義の「.xml」ファイルにカメラ定義を記録することで、カメラ定義を維持することが可能です。 ”UCC_SaveSettings()”で行い、カメラ定義の再読込は簡単に実行可能です。 UCC_LoadSettings()で前に設定したファイルをカメラに書き出します。使用する「.xml」ファイルの DTD については、 UniControl ヘルプに記述されています。

※表示パラメータをカメラパラメータに合わせるには、カメラ構成をプログラムへ読み込んでください。

5 カメラ定義 5-1 画像フォーマットここでは、画像転送に使用する画像フォーマットの定義について説明します。画像フォーマットの定義は画像取得の前に必要な手順です。

概要画像フォーマットは、”UCC_PrepareFixedGrab”または”UCC_PrepareFreeGrab”で定義します。 2 つのファンクションがある理由は、IIDC 規格に起因しており、'format'や'mode'の指標で使用される、解像度・カラーフォーマットの多くの定義をサポートしています。ほとんどのフォーマット/モードの組合せは固定解像度で記述されており、format7 は、画像解像度を調整する'free modes'を指しています。

5-1-1

UCC_PrepareFixedGrab()

“UCC_PrepareFixedGrab”は、IIDC formats 1-2 の定義に優先的に使用されます。いくつかのパラメータの設定がデフォルト解像度には必要です。あらかじめ定義されたフォーマットの記述については、IIDS 標準仕様を参照してください。注意: いくつかの制限を考慮すれば、Format7 モードは “UCC_PrepareFixedGrab”でも設定できます。Format7 モードは、この関数で定義できない追加の定義パラメータを必要とします。これらの定義がすでに設定( 例えば”UCC_PrepareFreeGrab”のコールなどによって)されていれば、 “UCC_PrepareFixedGrab”でモードの切り替えを素早く行うことが出来るでしょう。

5-1-2

UCC_PrepareFreeGrab()

format 7 モードのみ対応する多くのオプションが”UCC_PrepareFreeGrab”で用意されています。 format 7 モードの「自由定義」という特性によって規制が取り除かれますので、ほとんどの場合 ”UCC_PrepareFreeGrab” の使用を推奨します。 “UCC_PrepareFixedGrab”は、IIDC フォーマットによく使われています。

※ “UCC_PrepareFreeGrab”を使用したサンプルは、UniControl ヘルプで確認できます。

5-2 明示関数コール 5-2-1

オート機能 AOI

以下の関数は、AOI 機能の自動関数です。 UCC_AutoFunctionAOI_Set() UCC_AutoFunctionAOI_Get()

同様の機能は統合機能アクセスで提供されています。”E_FEAT_AUTOFUNCTIONAOI_LEFT” と関連記述を確認ください。

5-2-2

ホワイトバランス

標準のホワイトバランスは以下の関数で制御します。 UCC_Whitebalance_Set() UCC_Whitebalance_Get()

統合機能を使わない場合は、”E_FEAT_WHITEBALANCE_UB”と”E_FEAT_WHITEBALANCE_VR”を使用します。

5-2-3

アドバンスドホワイトバランス

カメラのセンサーでホワイトバランスを補うには以下の関数を使用します。 UCC_Whitebalance_GMCY_Set() UCC_Whitebalance_GMCY_Get()

統合機能の場合、 ”E_FEAT_WHITEBALANCE_GR” , “E_FEAT_WHITEBALANCE_MG”, “E_FEAT_WHITEBALANCE_CY” , ”E_FEAT_WHITEBALANCE_YE” 等を使用します。

5-2-4

シェーディング補正

以下の関数はシェーディング画像の生成、アップロード、ダウンロードを許可します。 UCC_Shading_GetInfo() UCC_Shading_Upload() UCC_Shading_Download() UCC_Shading_Build()

シェーディング画像を有効にする方法は

5-2-5

”E_FEAT_SHADING”

を確認ください。

ルックアップテーブル(LUT)

LUT 機能の定義は以下の関数で行います。 UCC_Lut_GetInfo() UCC_Lut_GetStatus() 18

UCC_Lut_Use() UCC_Lut_Upload()

LUT 機能は、統合機能 ”E_FEAT_LUT” ”E_FEAT_LUT_MAXSIZE”

5-2-6

”E_FEAT_LUT_BITSPERVAL”

や

でも提供しています。

シリアル I/O (RS232)

以下の関数は、カメラのシリアル I/O ポートへのアクセスを許可します。 UCC_SerialIO_SetConfig() UCC_SerialIO_GetConfig() UCC_SerialIO_Transmit() UCC_SerialIO_Receive()

5-2-7

デジタル I/O

カメラのデジタル I/O ピンの定義は以下の関数で行います。 UCC_InputPin_Get() UCC_InputPin_Set() UCC_OutputPin_Get() UCC_OutputPin_Set()

デジタル I/O やトリガー定義については、「デジタル I/O とトリガー操作」でも確認できます。

5-2-8

トリガー

トリガー撮影は以下の関数で制御します。 UCC_Trigger_Get() UCC_Trigger_Set()

デジタル I/O やトリガー定義については、「デジタル I/O とトリガー操作」でも確認できます。

5-2-9

ユーザープロファイル

カメラのユーザープロファイルの管理は以下の関数で行います。 UCC_UserProfile_Load() UCC_UserProfile_Save() UCC_UserProfile_SetDefault() UCC_UserProfile_GetErrorStatus() UCC_UserProfile_GetInfo()

ユーザープロファイル機能の一部へは、”E_FEAT_USERPROFILE” からもアクセスできます。 19

5-2-10

テストイメージ

テストイメージを有効にします。 UCC_TestImage_GetInfo() UCC_TestImage_Set()

5-2-11

カメラ設定の XML インポート/エクスポート

XML ファイルからカメラ設定の書出しや読込みは以下の関数で行います。 UCC_LoadSettings() UCC_SaveSettings()

5-2-12

画像フォーマットの一覧表

以下の関数は、カメラがサポートする標準の画像フォーマットの一覧表を制御します。 UCC_PresetToResolution() UCC_CreatePresetsEnum() UCC_DestroyPresetsEnum() UCC_EnumPresets() UCC_CreateColorCodeEnum() UCC_DestroyColorCodeEnum() UCC_EnumColorCode() UCC_GetBitsPerPixel() UCC_GetSupportedFixedFormats()

これらの関数は、主にサポートする標準の画像形式を表示するリスト(ビューワーアプリケーションで一般的に見られるもの)を作成するのに役立ちます。

6 デジタル I/O とトリガー操作この章はデジタル I/O とトリガー機能の使用方法を説明します。

Digital IO デジタル I/O は関数 ”UCC_InputPin_Get()” “UCC_InputPin_Set()” “UCC_OutputPin_Get()” “UCC_OutputPin_Set()” で定義を行います。それぞれの I/O ピンは、操作モードやポラリティに従い、別々に定義できます。出力ピンの状態は、入力 PIN の状態が読込み許可(“UCC_InputPin_Get” )、”UCC_OutputPin_Set()“で設定を行ない、”UCC_OutputPin_Get()”で状態を読み込みます。

※サポートしている入力・出力モードはマニュアルを確認ください。

トリガートリガー機能は、一つかそれ以上の入力ピンの制御により画像取得を許可します。トリガー定義については、”UCC_Trigger_Set() “と “UCC_Trigger_Get()”の記述を確認ください。トリガー機能の使用には、トリガーモードを定義する為に最低１つの入力ピンが必要です。（mode2）カメラトリガー機能は、IIDC 規格で定義する各種操作モードをサポートします。 AVT カメラは、図のトリガーモードをサポートしています。

モード

説明

固定シャッターモード：トリガーモードで ”E_FEAT_SHUTTER“ と ”E_FEAT_EXTENDEDSHU TTER”で設定された固定の露光時間によるシングルイメージの取得を開始します。

インテグレーションモード：画像の露光は、トリガーの入力信号がアクティブな間行われます。

バルクトリガー：最初のトリガー・パルスだけがカウントされます。このトリガー・パルスの検出時に、画像取得モードによりシングルイメージまたは連続イメージのどちらかが取得されます。

“E_FEAT_TRIGGERDELAYADV”でディレイの設定を行います。”E_FEAT_DELAYEDINTEGRATIONENABLE”では、インテグレーションモードにおいて、露光開始時のディレイなど追加のカスタマイズを行います。

※トリガーオペレーションの詳細はカメラマニュアルを確認ください。 21

7 画像取得(シングル) UniAPI は、既に設定が行われているカメラからシングルイメージを取り出す機能を提供しています。各種フォーマットをサポートする関数と同様に、サポートするフォーマットごとに別々の関数も提供しています。シングルイメージの取得は、高フレームレートを必要とするアプリケーションには推奨しません。その場合、連続イメージで画像取得を行います。ユーザーが連続イメージの取得を計画している場合も、最初にこのページを読んでください。データバッファのハンドリングや画像フォーマットの用意など多くのイメージ取得の詳細な方法は同じです。このページはこれらのトピックスについての記述も含んでいます。以下は、連続イメージの取得に適用される内容に焦点をあわせています。

7-1 タイミング動作シングルイメージ取得コマンドは同期して処理されます：ファンクションコールで、画像取得の定義、シングル露光し PC に画像転送を実行します。画像取得が終了すると、データは出力フォーマットに変換されます。これらのステップが完了するまで次のファンクションは使用できません。

7-2 バッファハンドリング画像データに使用するデータバッファはユーザーが用意します。画像取得関数は十分なサイズのメモリを必要とし、ユーザーは、選択した画像とカラーフォーマットに一致するメモリスペースの準備が必要です。

7-3 ピクセルフォーマット 7-3-1

Windows ビットマップ

画像データは、Windows で一般的に使用されている「'BGR'ビットマップフォーマット」に変換できます。一つのピクセルは、 3 バイトの画像データとなります。このフォーマットのイメージは、 UCC_GrabBitmapImage または UCC_GrabImage の使用によって取得できます。UCC_GrabImage を使用した場合、S_UNI_IMAGE 構造は、機能呼び出しと S_UNI_IMAGE の前にユーザーによって初期化が必要です。：uImageformat は、E_IF_BGR にセットする必要があります。

7-3-2

UCC_GrabImage メソッド

フォーマット特有のメソッドとは別に、UCC_GrabImage は、対応するフォーマットでの画像取得が可能です。 S_UNI_IMAGE 構造体は画像データの形式独立コンテナとして使用されます。 UCC_GrabImage ファンクションがコールされる前に、S_UNI_IMAGE は、ユーザーによって作成または初期化する必 22

要があります。最初に、S_UNI_IMAGE::uImageformat メンバーに、必要な画像フォーマットを設定します。サポートしている値は以下の通りです： E_IF_MONO8 モノクロ 8bit/pixel

E_IF_BGR Windows 24bit 'BGR' ビットマップフォーマット

E_IF_ABGR Windows 32bit 'ABGR' アルファチャンネルビットマップフォーマット

E_IF_RGB_PLANES RGB PLANAR（平面）フォーマット 8bit/pixel 各 3 planes

E_IF_RGBY_PLANES RGBY PLANAR フォーマット 8bit/pixel 各 4 planes

E_IF_NATIVE ネイティブフォーマット

大小さまざまのサイズ対応

If E_IF_MONO8, E_IF_BGR, E_IF_ABGR または E_IF_NATIVE の場合、システムメモリのシングルバッファを用意し、S_UNI_IMAGE::pImageAsSinglePlane "pImageAsSinglePlane"をメモリバッファのポイントに設定する必要があります。平面的なフォーマットの 1 つが使用された場合、3 または 4 のメモリバッファへ、要求する画像で提供されます。赤、緑そして青のイメージ面のスペースは、それぞれ pImageRed, pImageGreen そして pImageBlue が指すアドレスで確認できます。明るさはオプションで pImageY を使用します。

※UCC_GrabImage のサンプルは、UniControl ヘルプで確認できます。

8 画像取得(シーケンス：連続イメージ) 連続イメージの取得について説明します。提供するファンクションは、シングルイメージ取得とよく似ています。

シングルイメージ

連続イメージ

UCC_GrabImage

UCC_GetImage

UCC_GrabBitmapImage

UCC_GetBitmapImage

UCC_GrabPlanesImage

UCC_GetPlanesImage

UCC_GrabNativeImage

UCC_GetNativeImage

対応している関数は同じ目的で使用されます。画像フォーマット選択やバッファハンドリングの方法はどちらも同じです。画像取得(シングル)のページでこれらのトピックを参照ください。

8-1 連続イメージの制御連続イメージ取得は、 “UCC_GrabStart” で開始されます。 ( 実行する前に “UCC_PrepareFixedGrab” または ” UCC_PrepareFreeGrab”を完了する必要があります。) “UCC_GrabStart”が終了すると、カメラは連続イメージを転送します。転送データは UniAPI で受け取り、ユーザーの手続きなしで内部にストアされます。連続イメージの取得停止は“UCC_GrabStop”を使用します。 E_FEATSTATE_OFF に E_FEAT_STARTIMMEDIATELY がセットされると転送開始の指示を受け取るまでカメラは転送を開始しません。非同期通信の速度は独立しており、転送速度は"UCC_SetStreamSpeed ”で設定できます。現在の速度は “UCC_GetStreamSpeed”、最大速度は“UCC_GetStreamSpeedMax”で確認できます。

8-2 受信画像一旦、連続画像の取得を開始すると、 Get...Image ファンクションのうちの 1 つをコールします。画像を受け取った場合、すぐにリターンし、内部バッファが空いていない場合、タイムアウト値が指定されます。タイムアウト値の重要性はアプリケーションのデザインに依存します。すでに取得した新しいイメージがファクションコールのタイミングで確保された場合、ファンクションブロックを消去するためにタイムアウト 0 が使用されます。簡単なデザインのアプリケーションでは、Notifications を使用する代わりにポーリング装置が使用されます。この場合、適切なタイムアウト値を使用します。

9 Code snippets このセクションでは、標準的な画像取得におけるコードの記述を説明します。

9-1 初期化以下のコードで、API の初期化と接続されているカメラのリストをオープンします。

if ( FAILED( UCC_Init() ) ) { ; // todo: error handling, init failed }

// create an array for up to 64 camera ids UINT32_TYPE arrId[64], nCnt=64;

// get camera ids if ( FAILED( UCC_GetCameras( &nCnt, arrId ) ) ) { ; // todo: error handling, UCC_GetCameras failed } if ( nCnt == 0 ) { ; // todo: error handling, no camera found } else { // select the first camera listed ID_TYPE nCamId = arrId[0];

// open camera if ( FAILED( UCC_OpenCamera(nCamId) ) ) { ; // todo: error handling, UCC_OpenCamera failed }

// image acquisition code may be added here...

}

9-2 Image Format Configuration 320x200 ピクセルの解像度で YUV422 カラーフォーマットの画像設定例

UINT32_TYPE nMode = 0; UINT32_TYPE nColorFormat = E_CC_YUV422; UINT32_TYPE nHorizontalResolution = 320; UINT32_TYPE nVerticalResolution = 200; UCC_PrepareFreeGrab

( nCamId, &nMode, &nColorFormat, &nHorizontalResolution,

&nVerticalResolution, NULL, NULL, NULL, NULL);

フル解像度での標準的な画像取得のコードです。

UINT32_TYPE nMode = 0; UINT32_TYPE nColorFormat = E_CC_YUV422; UINT32_TYPE nHorizontalResolution = 0; UINT32_TYPE nVerticalResolution = 0; UCC_GetCameraCapabilities

(

nCamId,

&nHorizontalResolution,

&nVerticalResolution, NULL, NULL ); UCC_PrepareFreeGrab

( nCamId, &nMode, &nColorFormat, &nHorizontalResolution,

&nVerticalResolution, NULL, NULL, NULL, NULL);

※画像フォーマットの定義は、「5-1 画像フォーマット」を参照ください。

9-3 同期画像の取得

UCC_GrabBitmapImage 以下のコードは、シングルの RGB ビットマップ画像取得に”UCC_GrabBitmapImage “を使用しています。ビットマップバッファには ATL::CImage がデータストレージとして使用されています。サンプルでは、使用するカメラはカラーと想定しています。

// The variables below are expected to be defined properly. // The 'extern' declaration is only chosen for syntactical correctness // as stand-alone example. extern ID_TYPE nCamId;

// id of an already opened camera

extern UINT32_TYPE nHorizontalResolution; // the currently configured image size extern UINT32_TYPE nVerticalResolution;

// 27

ATL::CImage Image; Image.Create( nHorizontalResolution , -1 * nVerticalResolution , 24 ); UNI_RETURN_TYPE hr = UCC_GrabBitmapImage( nCamId , (UINT8_TYPE*) Image.GetBits() , INFINITE );

UCC_GrabImage UCC_GrabImage を使用することで同様な結果を得ることができます。

// The variables below are expected to be defined properly. // The 'extern' declaration is only chosen for syntactical correctness // as stand-alone example. extern ID_TYPE nCamId;

// id of an already opened camera

extern UINT32_TYPE nHorizontalResolution; // the currently configured image size extern UINT32_TYPE nVerticalResolution;

ATL::CImage Image; Image.Create( nHorizontalResolution , -1 * nVerticalResolution , 24 );

UINT32_TYPE bColor=0; S_UNI_IMAGE MyImageStruct;

MyImageStruct.uImageformat = E_IF_BGR; MyImageStruct.sImageData.pImageAsSinglePlane = (UINT8_TYPE*) Image.GetBits();

UNI_RETURN_TYPE hr = UCC_GrabImage( m_CamId, &MyImageStruct , &bColor, INFINITE );

※シングルイメージの詳細は「7 画像取得(シングル画像)」を参照ください

10 User Notifications 以下のコードは、'nodelist changed'イベントにどのようにノーティフィケーションを登録するかを表しています。

//register a windows message S_UNI_NOTIFICATION

Notification;

UNI_NOTIFICATION_HANDLE Handle; Notification.m_NotificationType

= E_UNI_NOTIFICATION_MESSAGE;

Notification.m_NotificationWindowsMessage.m_hWnd

= YourWindowHandle;

Notification.m_NotificationWindowsMessage.m_Msg

= WM_YOUR_USER_MESSAGE;

Notification.m_NotificationWindowsMessage.m_wParam

E_UNI_NOTIFICATION_NODELIST_CHANGED; UCC_RegisterNodeListChangedNotification( &Handle,&Notification);

// add additional application code here

UCC_UnRegisterNotification( Handle);

// unregisters a single notification

explicitly UCC_Release()

// implicitly unregisters all notifications

以下のコードも'nodelist changed'のノーティフィケーションを登録しますが、ノーティフィケーションのメカニズムではコールバック関数が使用されます。

//register a callback function

struct MyContext { // This custom defined struct may be used to provide context information for // the callback function below. // define arbitrary struct members here }; VOID_TYPE NOTIFICATION_CALLING_CONVENTION MyCallback( S_UNI_CALLBACK_ARGUMENT arg) { MyContext *This =reinterpret_cast<MyContext*>(arg.m_Parameter); // add event handling code here // warning: time-consuming operations may cause severe performance issues }

S_UNI_NOTIFICATION

Notification; 29

UNI_NOTIFICATION_HANDLE

Handle;

MyContext

CallingContext;

// add code to fill CallingContext with information

Notification.m_NotificationType

E_UNI_NOTIFICATION_CALLBACK; Notification.m_CamId

= YOUR_FAV_CAMERA_TO_USE;

Notification.m_NotificationCallback.m_Arg.m_Parameter Notification.m_NotificationCallback.m_Callback

= &CallingContext; = MyCallback;

UCC_RegisterNodeListChangedNotification( &Handle,&Notification);

// add additional application code here

UCC_UnRegisterNotification( Handle);

// unregisters a single notification

explicitly UCC_Release()

// implicitly unregisters all notifications

Notifications には Windows のイベントオブジェクトも使用できます。

//register a windows event S_UNI_NOTIFICATION

Notification;

UNI_NOTIFICATION_HANDLE

Handle;

HANDLE

BusResetEvent

CreateEvent(NULL,TRUE,FALSE,NULL);

if( NULL == BusResetEvent ) HandleError(); Notification.m_NotificationType

= E_UNI_NOTIFICATION_EVENT;

Notification.m_CamId

= UNI_ALL_CAMERAS;

Notification.m_NotificationEvent.m_Event

= BusResetEvent;

UCC_RegisterNotification( &Handle,E_UNI_NOTIFICATION_NODELIST_CHANGED,&Notifica tion);

// add additional application code here

UCC_UnRegisterNotification( Handle);

// unregisters a single notification

explicitly UCC_Release()

// implicitly unregisters all notifications 30

ReleaseHandle(BusResetEvent);

※詳細は UniAPI ヘルプの User notifications の項目を参照ください。

以上

改定履歴日付

内容

Version

2008/9/5

初版

1.00

2009/2/4

詳細内容追加

2.00