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 シリアル番号を格納するアドレス
返値：
備考：
なし。

ViewPLUS Inc.
( 11 )

vpcamGetFirmwareVersion
機能：
VPCAM_ERROR_T vpcamGetFirmwareVersion
HVPCAM_T Handle,
Unsigned int * pVersion );
機能：
カメラファームウェアのバージョン番号を取得する
引数：
Handle ハンドル
pVersion バージョン番号を格納するアドレス
返値：
備考：
なし。

ViewPLUS Inc.
( 12 )

vpcamGetDeviceName
書式：
VPCAM_ERROR_T vpcamGetDeviceName(
HVPCAM_T Handle, const char **ppDeviceName );
機能：
デバイス名を取得する
引数：
Handle ハンドル
ppDeviceName デバイス名のアドレスを格納するアドレス
返値：
VPCAM_INVALID_HANDLE 不正なハンドル
備考：
なし

ViewPLUS Inc.
( 13 )

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. 対応するカメラを参照してください。

ViewPLUS Inc.
( 14 )

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. 対応するカメラを参照してください。

ViewPLUS Inc.
( 15 )

vpcamSetParameter
書式：
VPCAM_ERROR_T vpcamSetParameter(
HVPCAM_T Handle,
VPCAM_PARAMETER_T ParameterId
long Value );
機能：
カメラのパラメータを書き換える
引数：
Handle ハンドル
ParameterId 書き換えたいパラメータの ID
Value 書き込む値
返値：
VPCAM_UNSUPPORTED 指定のパラメータ ID には対応していません
備考：
センサーレジスタのアドレス番号を意識せずにパラメータを変更できます。

ViewPLUS Inc.
( 16 )

vpcamGetParameter
書式：
VPCAM_ERROR_T vpcamGetParameter(
HVPCAM_T Handle,
VPCAM_PARAMETER_T ParameterId,
long *pValue );
機能：
カメラのパラメータを取得する
引数：
Handle ハンドル
ParameterId 取得したいパラメータの ID
pValue 取得したパラメータの格納先
返値：
VPCAM_UNSUPPORTED 指定のパラメータ ID には対応していません
備考：
センサーレジスタのアドレス番号を意識せずにパラメータを取得できます。

ViewPLUS Inc.
( 17 )

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 を指定すると、デフォルトテーブ
ルに置き換わります。

ViewPLUS Inc.
( 18 )

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 の内側の二つのカメラ画像を取得する

ViewPLUS Inc.
( 19 )

vpcamGrabImage
書式：
VPCAM_ERROR_T vpcamGrabImage(
HVPCAM_T Handle,
unsigned char *pImage );
機能：
最新の画像を取得する
引数：
Handle ハンドル
pImage 画像を格納するアドレス
返値：
VPCAM_INVALID_HANDLE 不正なハンドルです
備考：
pImageは、vpcamGetInformation() の VPCAM_BUFFER_SIZE で得られる
値以上のサイズ[bytes]のメモリでなければなりません。

ViewPLUS Inc.
( 20 )

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 で得られる値以上のサイズのメモリでなけれ
ばなりません。

ViewPLUS Inc.
( 21 )

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)が偶数ライン

ViewPLUS Inc.
( 22 )

RGGB の場合。

ViewPLUS Inc.
( 23 )

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 で保存する

ViewPLUS Inc.
( 24 )

vpcamDrawMonoImage
書式：
VPCAM_ERROR_T vpcamDrawMonoImage(
HVPCAM_T Handle,
HDC hDC, int x, int y,
const void *pImage );
機能：
モノクロ画像を描画する
引数：
Handle ハンドル
hDC 描画先デバイスコンテキスト
x, y 描画先デバイスコンテキスト上の位置
pImage 描画するモノクロまたはベイヤー画像
返値：
備考：
x, y は画像の左上位置を示します。

(x, y)

pImage

hDC

ViewPLUS Inc.
( 25 )

vpcamDrawColorImage
書式：
VPCAM_ERROR_T vpcamDrawColorImage(
HVPCAM_T Handle,
HDC hDC, int x, int y,
const void *pImage );
機能：
カラー画像を描画する
引数：
Handle ハンドル
hDC 描画先デバイスコンテキスト
x, y 描画先デバイスコンテキスト上の位置
pImage 描画するカラー画像
返値：
備考：
x, y は画像の左上位置を示します。

(x, y)

pImage

hDC

ViewPLUS Inc.
( 26 )

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

Table3-1. 対応するカメラ一覧
カメラ名特徴外観
MiniBee ４眼
USB2.0HighSpeed 対応高速
転送
VGA-カラーまたは VGA-モ
ノクロ

3-1. MiniBee
４つ搭載されているセンサーとレジスタアクセス関数
vpcamGetSensorRegister, vpcamSetSensorRegister の引数の対応を
Fig3-1-1.に示します。

VPCAM_SENSOR_D

VPCAM_SENSOR_C

VPCAM_SENSOR_B

VPCAM_SENSOR_A

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

ViewPLUS Inc.
( 27 )

搭載される４つのセンサーは同期してキャプチャーされますが、USB の性質上、
複数台の MiniBee で同期を取ることはできません。

4. API の使用方法
本頁は、VpUsbCam ライブラリの概念的説明を掲載します。具体的な利用手順は、
別途チュートリアルマニュアルも参照ください。

4.1.ハンドルアーキテクチャとコンテキスト
VpUsbCam は複数カメラの接続に対応しています。そのため、カメラと１対１
に対応するリソース格納場所（コンテキスト）を確保して利用する方式を採用して
います。このリソース格納場所は VpUsbCam の内部構造に強く依存しているため、
VpUsbCam のバージョンアップに伴って大幅に構造改革が行われる可能性もあり
ます。そのような不確定要素を内部に隠蔽し、コンテキストを一意に識別するキー
としてハンドル値を利用します。
カメラを制御する関数には、必ずこのハンドル値を指定します。複数のカメラが接
続されていても、カメラとハンドルは１対１で対応するため、目的のカメラのみを
制御できます。このイメージを Fig4-1-1.に示します。

1 1
指示 hCamera1
への
ラ1
カメハンドルカメラ1
Application
カメ
ラ2
へ
の
指 1 1
示 hCamera2

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

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

4.2.画像取り込みまでの手順
もっとも一般的な用途である画像取り込みの手順について記載します。
処理シーケンスは、Fig4-2-1.のようになります。

ViewPLUS Inc.
( 28 )

Application VpUsbCam OS

vpcamCreateContext()

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

vpcamGetInformation(VPCAM_BUFFER_SIZE)

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

malloc(バッファサイズ)

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

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

確保したメモリへ画像が格納される
(A)
vpcamSaveImage(VPCAM_MONO_BMP_IMAGE)

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 のように配置されます。

ViewPLUS Inc.
( 29 )

メモリの開始アドレス
VPCAM_IMAGE_SIZE SensorA
で得られるサイズ画像

SensorB
画像

VPCAM_BUFFER_SIZE
SensorC で得られるサイズ
画像

SensorD
画像

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

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

画像バッファの先頭から画像が配置されます。この画像はセンサーから得られる生
のデータを配置したもので、カラーセンサーであればベイヤー配列、モノクロセン
サーであれば輝度が Fig.4-2-3 の順で並んでいます。

画像

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

ViewPLUS Inc.
( 30 )

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 -

ViewPLUS Inc.
( 31 )

Vp Usb Cam Api Manual

Recomendados

Recomendados

Mais conteúdo relacionado

Destaque

Destaque (10)

Semelhante a Vp Usb Cam Api Manual

Semelhante a Vp Usb Cam Api Manual (20)

Último

Último (12)

Vp Usb Cam Api Manual