vp usb cam api manual

ViewPLUS USB Camera Control Library

VpUsbCam

ViewPLUS Inc. ( 1 )

1. 概要..................................................................................................................................3 2. リファレンスマニュアル..................................................................................................4 2-1. 関数詳細説明 ................................................................................................................5

vpcamCreateContext .......................................................................................................6 vpcamDestroyContext .....................................................................................................7 vpcamGetApiVersion.......................................................................................................8 vpcamEnumerateCameras..............................................................................................9 vpcamGetInformation ...................................................................................................10 vpcamGetSerialNumber................................................................................................11 vpcamGetFirmwareVersion ..........................................................................................12 vpcamGetDeviceName ..................................................................................................13 vpcamSetSensorRegister...............................................................................................14 vpcamGetSensorRegister ..............................................................................................15 vpcamSetParameter ......................................................................................................16 vpcamGetParameter......................................................................................................17 vpcamSetGamma16.......................................................................................................18 vpcamSetGrabMode.......................................................................................................19 vpcamGrabImage...........................................................................................................20 vpcamBayerToColor ......................................................................................................21 vpcamBayerToColorCustom..........................................................................................22 vpcamSaveImage ...........................................................................................................24 vpcamDrawMonoImage.................................................................................................25 vpcamDrawColorImage .................................................................................................26

3. 対応するカメラ ..............................................................................................................27 4. APIの使用方法................................................................................................................28

ViewPLUS Inc. ( 2 )

1. 概要

VpUsbCam は、ビュープラス製USBカメラ用のカメラ制御ライブラリです。

異なるカメラが接続されていても、共通の操作体系にて制御する方法を提供し

ます。具体的には次の機能を提供します。

・カメラの動作モード設定

・画像の取り込み/表示

・画像の保存

・画像のカラー変換

・センサーのレジスタ制御

ViewPLUS Inc. ( 3 )

2. リファレンスマニュアル

VpUsbCam には、Table2-1.に示す関数があります。

Table2-1. VpUsbCam API一覧

関数名機能概略

vpcamCreateContext カメラコンテキスト生成

vpcamDestroyContext カメラコンテキスト廃棄

vpcamGetApiVersion VpUsbCam API のバージョン情報

vpcamEnumerateCameras 接続されているデバイス数の取得

vpcamGetInformation カメラ情報取得

vpcamGetSerialNumber カメラシリアル番号を取得

vpcamGetFirmwareVersion カメラのファームウェアバージョンを取得

vpcamGetDeviceName カメラの製品名を取得

vpcamSetSensorRegister センサーレジスタ書き込み

vpcamGetSensorRegister センサーレジスタ読み込み

vpcamSetParameter カメラパラメータ書き込み

vpcamGetParameter カメラパラメータ読み込み

vpcamSetGamma16 16BPPモードにおける変換テーブル指定

vpcamSetGrabMode VpcamGrabImage の挙動を指定

vpcamGrabImage 画像取得

vpcamBayerToColor カラー変換処理

vpcamBayerToColorCustom ベイヤー配列指定のカラー変換

vpcamSaveImage 画像ファイル保存処理

vpcamDrawMonoImage モノクロまたはベイヤー画像の描画

vpcamDrawColorImage カラー画像の描画

ViewPLUS Inc. ( 4 )

2-1. 関数詳細説明

ViewPLUS Inc. ( 5 )

vpcamCreateContext

書式：

VPCAM_ERROR_T vpcamCreateContext(

int CameraId, HVPCAM_T *pHandle );

機能：

カメラコンテキストを生成する

引数：

CameraId カメラ番号（0～255）

pHandle ハンドルを格納するアドレス

返値：

VPCAM_SUCCESS 正常

VPCAM_NOT_ENOUGH_MEMORY メモリ不足で失敗

VPCAM_UNSUPPORTED 指定のカメラ番号に接続されている

デバイスはサポートしていません

VPCAM_NOT_FOUND 指定のカメラ番号には何も接続され

ていません

備考：

他の vpcam関数を使う前にまず本関数でハンドルを取得する必要があります。

失敗した場合（VPCAM_SUCCESSが返らなかった場合）、*pHandleにはNULL

が格納されます。

本関数で生成したハンドルは、アプリケーション終了前に必ず

vpcamDestroyContext() で廃棄する必要があります。

ViewPLUS Inc. ( 6 )

vpcamDestroyContext

書式：

VPCAM_ERROR_T vpcamDestroyContext(

HVPCAM_T *pHandle );

機能：

カメラコンテキストを廃棄する

引数：

pHandle ハンドルが格納されているアドレス

返値：


VPCAM_INVALID_HANDLE ハンドルが不正です

備考：

本関数はハンドルを削除後、*pHandle に NULL を書き込みます。

*pHandle が NULL の場合、VPCAM_INVALID_HANDLE を返します。

別スレッドで本関数実行中に、廃棄対象のハンドルを使ったアクセスを行って

はいけません。

ViewPLUS Inc. ( 7 )

vpcamGetApiVersion

書式：

unsigned int vpcamGetApiVersion( void );

機能：

VpUsbCam API のバージョンを取得する

引数：

なし

返値：

バージョン値

備考：

１６進数8桁で示され、0xMMMMAARR のうち、MMMMがメジャーバージョ

ン。AAがAPI バージョン。RRがリビジョン。

API 構成に大幅な変更があった場合にメジャーバージョンが更新されます。

API 群の互換性は保たれるものの、機能が拡張された場合や新 API が追加された

場合にAPI バージョンが更新されます。

バグフィックスなど使い方に影響のない修正が入った場合にリビジョンが更新さ

れます。

ViewPLUS Inc. ( 8 )

vpcamEnumerateCameras

書式：

unsigned int vpcamEnumerateCameras( void ); 機能：

接続されているデバイスの数を調べる

引数：

なし

返値：

接続されているデバイス数（動作中のデバイスも含めます）

備考：

なし。

ViewPLUS Inc. ( 9 )

vpcamGetInformation

機能：

VPCAM_ERROR_T vpcamGetInformation(

HVPCAM_T Handle,

VPCAM_INFORMATION_T InformationId,

long *pValue );

機能：

カメラに関する情報を取得する

引数：

Handle ハンドル

InformationId 情報番号

pValue 情報を格納するアドレス

返値：


VPCAM_UNSUPPORTED 指定の情報番号には対応していません


備考：

情報番号には次の値を指定できます。

VPCAM_BAYER_PATTERN ベイヤ配列の構造

VPCAM_SENSOR_WIDTH 画像水平画素数

VPCAM_SENSOR_HEIGHT 画像垂直画素数

VPCAM_IMAGE_SIZE 画像サイズ

VPCAM_BUFFER_SIZE 必要グラブメモリサイズ

VPCAM_NUMBER_OF_SENSOR イメージセンサ搭載数

VPCAM_COLOR_IMAGE_SIZE カラー画像サイズ

ペイヤ配列の構造は、VPCAM_FORCC の形で返されます。

たとえば、

G R

B G の配列の場合は、VPCAM_FOURCC(‘G’,’R’,’B’,’G’)の

値が *pValue にセットされます。

VPCAM_XXX_SIZE で返されるサイズ値は byte単位になります。

本関数で得られる情報はカメラ固有の固定値であり、動作中に変化しません。

ViewPLUS Inc. ( 10 )

vpcamGetSerialNumber

機能：

VPCAM_ERROR_T vpcamGetSerialNumber

HVPCAM_T Handle,

Unsigned int * pNumber );

機能：

カメラのシリアル番号を取得する

引数：

Handle ハンドル

pNumber シリアル番号を格納するアドレス

返値：



備考：

なし。


vpcamGetFirmwareVersion

機能：

VPCAM_ERROR_T vpcamGetFirmwareVersion

HVPCAM_T Handle,

Unsigned int * pVersion );

機能：

カメラファームウェアのバージョン番号を取得する

引数：

Handle ハンドル

pVersion バージョン番号を格納するアドレス

返値：



備考：

なし。


vpcamGetDeviceName

書式：

VPCAM_ERROR_T vpcamGetDeviceName(

HVPCAM_T Handle, const char **ppDeviceName );

機能：

デバイス名を取得する

引数：

Handle ハンドル

ppDeviceName デバイス名のアドレスを格納するアドレス

返値：


VPCAM_INVALID_HANDLE 不正なハンドル

備考：

なし


vpcamSetSensorRegister

書式：

VPCAM_ERROR_T vpcamSetSensorRegister(

HVPCAM_T Handle,

VPCAM_SENSOR_T Sensor,

unsigned int Register,

long Value );

機能：

イメージセンサーのレジスタへ値を書き込む

引数：

Handle ハンドル

Sensor センサー番号

Register レジスタアドレス

Value 書き込み値

返値：


VPCAM_ILLEGAL_PARAMETER 不正なセンサー番号です


備考：

センサー番号には次の値の組み合わせを指定できます。

VPCAM_SENSOR_A

VPCAM_SENSOR_B

VPCAM_SENSOR_C

VPCAM_SENSOR_D

VPCAM_SENSOR_E

VPCAM_SENSOR_F

VPCAM_SENSOR_G

VPCAM_SENSOR_H

複数指定する場合は | で結合して Sensor に指定できます。

センサーとセンサー番号の対応関係は 3. 対応するカメラを参照してください。


vpcamGetSensorRegister

書式：

VPCAM_ERROR_T vpcamGetSensorRegister(

HVPCAM_T Handle,


unsigned int Register,

long *pValue );

機能：

イメージセンサーのレジスタ値を読み取る

引数：

Handle ハンドル

Sensor センサー番号

Register レジスタアドレス

pValue 読み取った値を書き込むアドレス

返値：


VPCAM_ILLEGAL_PARAMETER 不正なセンサー番号です


備考：

センサー番号には次の値のいずれか１つを指定できます。

VPCAM_SENSOR_A

VPCAM_SENSOR_B

VPCAM_SENSOR_C

VPCAM_SENSOR_D

VPCAM_SENSOR_E

VPCAM_SENSOR_F

VPCAM_SENSOR_G

VPCAM_SENSOR_H

複数のセンサーを指定した場合は VPCAM_ILLEGAL_PARAMETER が返さ

れます。

センサーとセンサー番号の対応関係は 3. 対応するカメラを参照してください。


vpcamSetParameter

書式：

VPCAM_ERROR_T vpcamSetParameter(

HVPCAM_T Handle,


VPCAM_PARAMETER_T ParameterId

long Value );

機能：

カメラのパラメータを書き換える

引数：

Handle ハンドル

ParameterId 書き換えたいパラメータの ID

Value 書き込む値

返値：



VPCAM_UNSUPPORTED 指定のパラメータ IDには対応していません

備考：

センサーレジスタのアドレス番号を意識せずにパラメータを変更できます。


vpcamGetParameter

書式：

VPCAM_ERROR_T vpcamGetParameter(

HVPCAM_T Handle,


VPCAM_PARAMETER_T ParameterId,

long *pValue );

機能：

カメラのパラメータを取得する

引数：

Handle ハンドル

ParameterId 取得したいパラメータの ID

pValue 取得したパラメータの格納先

返値：



VPCAM_UNSUPPORTED 指定のパラメータ IDには対応していません

備考：

センサーレジスタのアドレス番号を意識せずにパラメータを取得できます。


vpcamSetGamma16

書式：

VPCAM_ERROR_T vpcamSetGamma16( HVPCAM_T Handle,

const unsigned char *pRedGamma,

const unsigned char *pGreenGamma,

const unsigned char *pBlueGamma );

機能：

16BPPモードにおけるカラー処理の8BPP変換テーブルの設定

引数：

Handle ハンドル

pRedGamma 65536byte の赤変換テーブルアドレス

pGreenGamma 65536byte の緑変換テーブルアドレス

pBlueGamma 65536byte の青変換テーブルアドレス

返値：


備考：

pRedGamma[ 16BPPの輝度値 ] = 8BPPの輝度値となるような変換テーブル

を指定します。テーブルアドレスとして NULL を指定すると、デフォルトテーブ

ルに置き換わります。


vpcamSetGrabMode

書式：

VPCAM_ERROR_T vpcamSetGrabMode( HVPCAM_T Handle,

VPCAM_GRAB_MODE_T GrabMode );

機能：

vpcamGrabImage() の挙動を変更する

引数：

Handle ハンドル

GrabMode 挙動を示すＩＤ

返値：


VPCAM_UNSUPPORTED サポートしていない ID

備考：

GrabMode に指定できるモードは下記です。

サポートしているか否かは、カメラの種類によって異なります。

VPCAM_NORMAL すべてのカメラがサポートしています

VPCAM_MINIBEE_XXXX MiniBEE のみサポートしています。

VPCAM_NORMAL 通常のモード

(デフォルト)

VPCAM_MINIBEE_8BPP RGBの各値を8bit で取得する

(デフォルト)

VPCAM_MINIBEE_12BPP RGBの各値を12bit で取得する

VPCAM_MINIBEE_4CAMERA ４つのカメラ画像を取得する

(デフォルト)

VPCAM_MINIBEE_2CAMERA_OUTSIDE ADの外側の二つのカメラ画像を取得する

VPCAM_MINIBEE_2CAMERA_INSIDE BCの内側の二つのカメラ画像を取得する


vpcamGrabImage

書式：

VPCAM_ERROR_T vpcamGrabImage(

HVPCAM_T Handle,

unsigned char *pImage );

機能：

最新の画像を取得する

引数：

Handle ハンドル

pImage 画像を格納するアドレス

返値：


VPCAM_INVALID_HANDLE 不正なハンドルです

備考：

pImageは、vpcamGetInformation() の VPCAM_BUFFER_SIZE で得られる

値以上のサイズ[bytes]のメモリでなければなりません。


vpcamBayerToColor

書式：

VPCAM_ERROR_T vpcamBayerToColor(

HVPCAM_T Handle,

unsigned char *pColorImage,

const unsigned char *pBayerImage );

機能：

ベイヤパターン画像を24bit カラー画像へ変換する

引数：

Handle ハンドル

pColorImage カラー画像を格納するアドレス

pImage 変換するベイヤパターン画像

返値：



備考：

ベイヤ配列構造は内部で自動的に判断されます。

変換処理は pImage から始まる１センサー分の画像のみが対象となります。

pColorImage は、vpcamGetInformation()

の VPCAM_COLOR_IMAGE_SIZE で得られる値以上のサイズのメモリでなけれ

ばなりません。


vpcamBayerToColorCustom

書式：

VPCAM_ERROR_T vpcamBayerToColorCustom(

HVPCAM_T Handle,

unsigned char *pColorImage,

const unsigned char *pBayerImage,

VPCAM_COLOR_PATTERN_T ColorPattern );

機能：

ベイヤパターン画像を24bit カラー画像へ変換する

引数：

Handle ハンドル

pColorImage カラー画像を格納するアドレス

pImage 変換するベイヤパターン画像

ColorPattern ベイヤー配列構造

返値：


VPCAM_UNSUPPORTED 不正な ColorPattern

備考：

ベイヤ配列構造は、指定された画像やハンドルに関係なく ColorPattern に指定

された構造として処理されます。

変換処理は pImage から始まる１センサー分の画像のみが対象となります。

pColorImage は、vpcamGetInformation()

の VPCAM_COLOR_IMAGE_SIZE で得られる値以上のサイズのメモリでなけ

ればなりません。

通常はこの関数を使わずに vpcamBayerToColor() を使います。この関数は、

モノクロセンサーとカラーセンサーが混在しているような特殊カメラ向けです。

ColorPattern 設定値意味

VPCAM_MONOTONE モノクロ画像

VPCAM_BAYER_RGGB 偶数ライン RG, 奇数ラインGB

VPCAM_BAYER_GBRG 偶数ラインGB, 奇数ラインRG

VPCAM_BAYER_GRBG 偶数ラインGR, 奇数ラインBG

※画像の最上ライン(Y=0)が偶数ライン


RGGBの場合。


vpcamSaveImage

書式：

VPCAM_ERROR_T vpcamSaveImage(

HVPCAM_T Handle,

const char *pcsFileName,

VPCAM_SAVE_MODE_T SaveMode,

const char *pImage );

機能：

画像をファイルへ保存する

引数：

Handle ハンドル

pcsFileName ファイル名

SaveMode 保存モード

pImage 保存する画像データ

返値：


VPCAM_FAILURE 書き込みに失敗しました

VPCAM_ILLEGAL_PARAMETER 不正な保存モード指定です


備考：

pImage から始まる１センサー分の画像のみが保存対象となります。

SaveMode には次の値を指定できます。

VPCAM_MONO_BMP_IMAGE モノクロ/ベイヤパターンをBMPで保存する

VPCAM_COLOR_BMP_IMAGE 24bit カラー画像をBMPで保存する


vpcamDrawMonoImage

書式：

VPCAM_ERROR_T vpcamDrawMonoImage(

HVPCAM_T Handle,

HDC hDC, int x, int y,

const void *pImage );

機能：

モノクロ画像を描画する

引数：

Handle ハンドル

hDC 描画先デバイスコンテキスト

x, y 描画先デバイスコンテキスト上の位置

pImage 描画するモノクロまたはベイヤー画像

返値：



備考：

x, y は画像の左上位置を示します。

hDC

pImage

(x, y)


vpcamDrawColorImage

書式：

VPCAM_ERROR_T vpcamDrawColorImage(

HVPCAM_T Handle,

HDC hDC, int x, int y,

const void *pImage );

機能：

カラー画像を描画する

引数：

Handle ハンドル

hDC 描画先デバイスコンテキスト

x, y 描画先デバイスコンテキスト上の位置

pImage 描画するカラー画像

返値：



備考：

x, y は画像の左上位置を示します。

hDC

pImage

(x, y)


3. 対応するカメラ

VpUsbCam は Table3-1. に示すカメラに対応しています。

Table3-1. 対応するカメラ一覧

カメラ名特徴外観

MiniBee ４眼

USB2.0HighSpeed 対応高速

転送

VGA-カラーまたは VGA-モ

ノクロ

3-1. MiniBee

４つ搭載されているセンサーとレジスタアクセス関数

vpcamGetSensorRegister, vpcamSetSensorRegister の引数の対応を

Fig3-1-1.に示します。

VPCAM_SENSOR_A

VPCAM_SENSOR_B

VPCAM_SENSOR_C

VPCAM_SENSOR_D

Fig3-1-1. MiniBee のセンサーと IDの対応関係


搭載される４つのセンサーは同期してキャプチャーされますが、USB の性質上、

複数台のMiniBee で同期を取ることはできません。

4. API の使用方法

本頁は、VpUsbCamライブラリの概念的説明を掲載します。具体的な利用手順は、

別途チュートリアルマニュアルも参照ください。

4.1.ハンドルアーキテクチャとコンテキスト

VpUsbCam は複数カメラの接続に対応しています。そのため、カメラと１対１

に対応するリソース格納場所（コンテキスト）を確保して利用する方式を採用して

います。このリソース格納場所はVpUsbCamの内部構造に強く依存しているため、

VpUsbCamのバージョンアップに伴って大幅に構造改革が行われる可能性もあり

ます。そのような不確定要素を内部に隠蔽し、コンテキストを一意に識別するキー

としてハンドル値を利用します。

カメラを制御する関数には、必ずこのハンドル値を指定します。複数のカメラが接

続されていても、カメラとハンドルは１対１で対応するため、目的のカメラのみを

制御できます。このイメージを Fig4-1-1.に示します。

hCamera1

hCamera2

1 1

1 1

Applicationカメラ1へ

の指示

カメラ2への

指示

ハンドル

ハンドルカメラ1

カメラ2

Fig4-1-1. カメラとハンドル値の一意な対応

※USBの性質上、複数台のカメラを接続するとフレームレートが落ちる場合があります。

4.2.画像取り込みまでの手順

もっとも一般的な用途である画像取り込みの手順について記載します。

処理シーケンスは、Fig4-2-1.のようになります。


Application VpUsbCam

vpcamCreateContext()

ハンドル値, エラーコード返却

vpcamGetInformation(VPCAM_BUFFER_SIZE)

画像取り込みに必要なバッファサイズを返却

OS

malloc(バッファサイズ)

確保したメモリアドレスを返却

vpcamGrabImage(確保したメモリアドレス)

確保したメモリへ画像が格納される

vpcamSaveImage(VPCAM_MONO_BMP_IMAGE)

(A)

vpcamDestroyContext()

ハンドル値が消去される

Fig4-2-1. 画像を１枚取得するための一連の流れ

vpcamGetInformation() のオプション VPCAM_IMAGE_SIZE でセンサー１

つ分の画像サイズが、VPCAM_NUMBER_OF_SENSORでセンサーの数が得られ

ますが、VPCAM_BUFFER_SIZE はその２値を掛け合わせたものとは限りません。

VPCAM_BUFFER_SIZE にはカメラから受け取ったデータを画像に変換するた

めに必要なワーク領域なども含まれていますので、画像取り込み用のメモリは必ず

VPCAM_BUFFER_SIZE で得られるサイズを用意してください。

vpcamGrabImage() で得られる画像データは、Fig4-2-2のように配置されます。


SensorA画像

SensorB画像

SensorC画像

SensorD画像

ワーク領域（カメラにより異なる）

メモリの開始アドレス

VPCAM_IMAGE_SIZEで得られるサイズ

VPCAM_BUFFER_SIZEで得られるサイズ

Fig4-2-2. vpGrabImage() 直後の画像バッファの内容

画像バッファの先頭から画像が配置されます。この画像はセンサーから得られる生

のデータを配置したもので、カラーセンサーであればベイヤー配列、モノクロセン

サーであれば輝度が Fig.4-2-3 の順で並んでいます。

画像

Fig4-2-3. メモリ上における画素並び順


vpcamSaveImage() は、画像１枚分しか保存しませんので、画像取り込み用メ

モリの先頭アドレスを指定すると SensorA の画像しか保存されません。

SensorB の画像を保存するには次のようなコードを実行します。

vpcamSaveImage( hCamera, "SensorB.bmp", pBuffer + ImageSize,

VPCAM_MONO_BMP_IMAGE );

ImageSize は、vpcamGetInformation( hCamera, VPCAM_IMAGE_SIZE,

&ImageSize ) で得た値です。

SensorC の場合は、+ImageSize の代わりに +ImageSize*2 を、SensorD の場

合には +ImageSize*3 を指定します。

カラー対応カメラで撮影した画像をカラー変換した形で保存したい場合、別途

vpcamGetInformation の VPCAM_COLOR_IMAGE_SIZE で得られるサイズ

のメモリを確保して、vpcamBayerToColor() の変換結果格納先として指定します。

変換結果は vpcamSaveImage() に VPCAM_COLOR_BMP_IMAGE を指定す

ることで保存できます。

Fig.4-2-1 のシーケンスにおいて (A) の部分が画像の取得と保存になります。こ

こを繰り返すだけで複数枚の連続撮影ができます。

- Document Version 1.0.1 -


vp usb cam api manual

Technology