SDK开发说明书
陕西维视数字图像技术有限公司https://www.doczj.com/doc/743668409.html,
公司简介
维视数字图像技术有限公司是专业从事机器视觉图像采集产品的研发、机器视觉应用领域设备、计算机图像处理系统解决方案专业提供的高科技企业。
公司主要研发生产图像采集卡、工业相机、工业智能相机、嵌入式图像开发平台，机器视觉图像处理软件，根据客户特殊要求专门开发的机器视觉产品和设备,同时是国外先进的机器视觉部件及视觉系统专业代理及技术服务提供商。
维视图像长期致力于图形图像应用领域的研究，在图像采集处理、计算机模式识别、机器视觉、图像处理与算法等领域具有多年的经验积累，技术力量雄厚，掌握了视觉领域相关的核心技术，提供机器视觉硬件平台、图像处理分析算法、视频分析处理、工业智能化控制等机器视觉系统及应用全方位解决方案。
公司机器视觉产品、系统广泛应用于医疗、电子、半导体、烟草、智能交通、食品卫生、汽车制造、金属加工、包装、制药、纺织、科学研究等行业。维视图像努力成为一家在视觉检测、测量、图像识别、视觉定位等方面具有领先水平的视觉图像产品、设备解决方案提供者。
公司建立了完善的研发生产、市场销售和技术服务体系，坚实的技术后盾，良好的技术输出，铸定了企业在计算机视觉领域的位置，与客户和合作伙伴一起，为促进相关领域的发展提供及时、优质的服务。
目录
1 概述 (4)
1.1 全局函数： (4)
1.2 保存内存数据到磁盘 (4)
1.2.1 Grabber类 (4)
1.2.2 GrabberListener类 (5)
1.2.3 FrameHandlerSink类 (5)
1.2.4 MemBuffer类 (5)
1.2.5 MemBufferCollection类 (6)
1.2.6 MediaStreamSink类 (6)
1.2.7 Codec类 (6)
2. Grabber类的常用成员函数： (7)
2.1 打开关闭设备 (7)
2.2 视频显示操作： (7)
2.3 外触发操作 (8)
2.4 拷贝数据到内存操作 (8)
2.5 数据流回调操作 (8)
2.6 保存视频文件到磁盘 (8)
2.7 设置视频参数 (8)
2.8 添加滤镜，实现部分图像处理功能 (9)
3 常用类函数中文说明 (9)
3.1 Grabber类函数说明 (9)
3.2 FrameHandlerSink类函数说明 (30)
3.3 GrabberListener类函数说明 (34)
3.4 MemBuffer类函数说明 (35)
3.5 MemBufferCollection类函数说明 (39)
3.6 OverlayBitmap类函数说明 (43)
3.7 VCDProperty类函数说明 (52)
4 常用功能实现 (57)
4.1 精准曝光时间设置 (57)
4.2 增益设置 (58)
4.2 Gamma设置 (58)
4.3属性项说明 (58)
4.4属性项自动功能 (59)
5 常用类型定义 (59)
6 常用枚举类型 (62)
7 数据流向示意 (63)
1 概述
为了方便的使用这一系列图像产品，定义了几个全局函数和很多不同功能类，所有这些定义都包含在DirectShowLib这个命名空间中。下面就几个最常用全局函数和类及其类的常用成员函数作简要说明：
1.1 全局函数：
bool InitLibrary( const char* pLicenseKey, DWORD coinitmode = 0 );
初始化函数类库，在编写应用程序前必须调用
例：
if( !DirectShowLib::InitLibrary( " your license key" ) )
{
return FALSE;
}
saveToFileBMP( const IFrame& buf, const wchar_t* pFilename );
saveToFileJPEG( const IFrame& buf, const wchar_t* pFilename, int quality = 75 );
1.2 保存内存数据到磁盘
1.2.1 Grabber类
Grabber是其中最重要的一个类，提供了控制图像数据从采集设备到计算机缓存或磁盘文件这个过程的基本功能。
使用这个类，你可以实现如下功能:
z选择视频源（摄像机）
z设置视频参数
z实时显示图像
z控制图像数据到缓存或
z存储图像数据到磁盘
1.2.2 GrabberListener类
GrabberListener是数据流回调的一个基类，所有的数据流回调类必须从该类继承，并重载需要的回调函数。可能需要重载函数有：
virtual void deviceLost(Grabber& caller)
virtual void frameReady(Grabber& caller, smart_ptr
FrameNumber)
DWORD
virtual void overlayCallback(Grabber& caller,
pBitmap, const tsMediaSampleDesc& desc) smart_ptr
上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。
1.2.3 FrameHandlerSink类
FrameHandlerSink是复制数据到内存的关键类，包括数据流回调。
常用的成员函数有：
tFrameHandlerSinkPtr create
smart_ptr
void setSnapMode( bool mode );
mode=false，grab模式，实时显示的同时复制数据到内存
mode =true，snap模式，显示时不复制数据内存，需要调用下面的函数手动复制数据到内存
Error snapImages( unsigned int count, DWORD timeout = INFINITE );
Error snapImagesAsync( unsigned int count );
上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。
1.2.4 MemBuffer类
MemBuffer类是内存图像数据操作的主要类。
常用的成员函数有：
save( const wchar_t* pFilename ) const;
把内存图像数据保存成bmp图片
如果要保存成JPEG，需要用到全局函数
DirectShowLib::
saveToFileJPEG(const IFrame& buf,const wchar_t* pFilename,int quality = 75 ) 上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。
1.2.5 MemBufferCollection类
MemBufferCollection是包含一系列MemBuffer类的集合类。
常用成员函数有：
tMemBufferCollectionPtr create
Grabber::tMemBufferPtr getBuffer( DWORD pos ) const;
上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。
1.2.6 MediaStreamSink类
MediaStreamSink是关于保存视频文件到磁盘的类。
常用成员函数有：
bool setFilename( const std::string& str ) const;
设置录像文件名
tSinkModes setSinkMode( tSinkModes mode );
设置该类的属性
上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。
1.2.7 Codec类
Codec是录像编码类，供保存视频文件到磁盘选用。
常用成员函数有：
static tCodecListPtr getAvailableCodecs();
std::string getName() const;
上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。2. Grabber类的常用成员函数：
2.1 打开关闭设备
tVidCapDevListPtr getAvailableVideoCaptureDevices() const;
枚举系统中可用的视频设备
openDev 打开视频设备
openDevByDisplayName打开视频设备
openDevByUniqueName打开视频设备
bool isDevValid() const;判断视频设备是否有效
bool isDevOpen() const;判断视频设备是否打开
bool closeDev();关闭视频设备
还有一种打开视频设备的方法，就是显示设备属性页，用到下面函数：bool showDevicePage( HWND hParent = 0 );
2.2 视频显示操作：
bool setHWND( HWND hwnd ); 设置视频显示窗口
bool setWindowPosition( long posx, long posy ); 设置视频显示位置
bool setDefaultWindowPosition( bool bDefault ); 锁定视频显示窗口大小bool setWindowSize( long width, long height ); 设置视频显示窗口大小
bool startLive( bool show = true );开始实时显示视频
bool stopLive();停止实时显示视频
2.3 外触发操作
bool hasExternalTrigger() const;
bool setExternalTrigger( bool newValue );
bool getExternalTrigger() const;
2.4 拷贝数据到内存操作
bool setSinkType( smart_ptr
2.5 数据流回调操作
void addListener( GrabberListener* pListener, DWORD callback = -1 );
bool removeListener(GrabberListener* pListener, DWORD callback = -1);
注意：拷贝数据到内存和数据流回调需要用到FrameHandlerSink类2.6 保存视频文件到磁盘
bool setSinkType( smart_ptr
注意：保存数据到磁盘需要用到MediaStreamSink类
2.7 设置视频参数
第一种方法
调用属性页设置
bool showDevicePage( HWND hParent = 0 );
可以设置视频源，视频格式，帧率，分辨率
bool showVCDPropertyPage( HWND hParent, const std::wstring& title );
可以设置外触发、亮度、对比度、快门控制、白平衡、色彩等
第二种方法
调用Grabber类的成员函数实现
2.8 添加滤镜，实现部分图像处理功能
下面就已标准滤镜文件stdfiltersiat.ftf为例，举例说明：
stdfiltersiat.ftf包含了旋转和开窗功能，调用其功能步骤如下：
(1)创建滤镜
DirectShowLib::FilterLoader::createFilter( L"Rotate Flip",
);
L"stdfiltersiat.ftf"
(2)添加滤镜
bool setDeviceFrameFilters( IFrameFilter* pFilter );
bool setDisplayFrameFilters( IFrameFilter* pFilter );
(3)设置参数
IFrameFilter::setParameter
上述函数的具体说明参见“说明文档\开发说明\iatclasslib.chm” 文件。
3 常用类函数中文说明
3.1 Grabber类函数说明
头文件：iatudshl.h
命名空间：DirectShowLib
1、函数：Grabber
原型：Grabber();
参数：无
返回值：无
说明：Grabber类的构造函数
2、函数：addListener
原型：void addListener( GrabberListener* pListener, DWORD callback = -1 );
参数：pListener
数据流回调类指针，回调句柄对象是由GrabberListener类派
生
callback 回调的事件类型
eDEVICELOST 设备丢失事件
eFRAMEREADY 数据传送结束，可以进行处理
eOVERLAYCALLBACK 数据开始传送，可以进行叠加
eALL 即-1，包含以上3种事件
返回值：无
说明：注册数据流回调类
例：
Grabber *grabber = new DirectShowLib::Grabber();
CListener *pcListener = new CListener(); //创建GrabberListener类的对象，CListener为GrabberListener的派生类
//注册 pcListener
grabber->addListener( pcListener, DirectShowLib::GrabberListener::eFRAMEREADY|
DirectShowLib::GrabberListener::eOVERLAYCALLBACK );
grabber->startLive( true ); // 开始采集
fflush(stdin);
printf("Press [enter] to stop!");
getchar();
// 取消GrabberListener对象的注册
//首先,取消注册 frame ready 事件
grabber->removeListener(pcListener, DirectShowLib::GrabberListener::eFRAMEREADY);
// 接着，取消注册叠加图回调事件.
grabber->removeListener(pcListener, DirectShowLib::GrabberListener::eOVERLAYCALLBACK); // 制止所有移除所有GrabberListener类注册的事件
while( grabber->isListenerRegistered( pcListener, eALL) )
{
Sleep( 0 ); // Wait
}
//安全回收对象
delete pcListener;
grabber->stopLive(); //停止采集
delete grabber;
3、函数：closeDev
原型：bool closeDev();
参数：无
返回值：成功返回true，否则返回false
说明：关闭当前采集设备
4、函数：getAcqSizeMaxX
原型：long getAcqSizeMaxX() const;
参数：无
返回值：成功返回true，否则返回false
说明：得到当前采集设备最大分辨率的宽度
5、函数：getAcqSizeMaxY
原型：long getAcqSizeMaxY() const;
参数：无
返回值：成功返回true，否则返回false
说明：得到当前采集设备最大分辨率的高度
6、函数：getAvailableFPS
原型：tFPSListPtr getAvailableFPS() const;
tFPSListPtr getAvailableFPS( const VideoFormatItem& op ) const;
参数：VideoFormatItem 数据格式
返回值：返回包含指定数据格式的可用帧率的指针，如果没有指定数据格式，则返回当前格式的可用帧率
说明：得到当前采集设备的可用帧率
7、函数：getAvailableFrameRates
原型：tFrameRateListPtr getAvailableFrameRates () const;
tFrameRateListPtr getAvailableFrameRates ( VideoFormatItem& item ) const;
参数：VideoFormatItem 数据格式
返回值：返回包含指定数据格式支持的帧率的指针，如果没有指定数据格式，则返回当前格式支持的帧率
说明：得到当前采集设备支持的帧率
8、函数：getAvailableVCDProperties
原型：smart_com
参数：无
返回值：返回参数列表
说明：枚举当前设备可以设置的参数
9、函数：getAvailableVideoCaptureDevices
原型：tVidCapDevListPtr getAvailableVideoCaptureDevices() const;
参数：无
返回值：返回当前可用的视频采集设备的列表
说明：返回当前可用的视频采集设备
例：
tVidCapDevListPtr devlist = m_Grabber.getAvailableVideoCaptureDevices();
if (devlist==0||devlist->empty())
{
AfxMessageBox("未找到设备");
}
10、函数：getAvailableVideoFormats
原型：tVidFmtListPtr getAvailableVideoFormats() const;
参数：无
返回值：成功返回当前采集设备的可用数据格式列表，否则返回0
说明：返回当前采集设备的可用数据格式
例：
tVidFmtListPtr pVidFmtList = m_Grabber.getAvailableVideoFormats();
if(pVidFmtList == 0)
{
std::cerr << "Error : " << grabber.getLastError().toString() << std::endl;
}
else
{
unsigned int counter = 0;
for( Grabber::tVidFmtList::iterator it = pVidFmtList->begin(); it != pVidFmtList->end(); ++it ) {
std::cout << "\t[" << counter++ << "] " << it->toString() << std::endl;
}
}
11、函数：getCurrentActualFPS
原型：double getCurrentActualFPS() const;
参数：无
返回值：成功返回当前采集设备采集一帧需要的时间，即帧率的倒数，否则返回0 说明：返回当前采集设备的当前帧率，连续模式有效
12、函数：getCurrentActualFrameRate
原型：long getCurrentActualFrameRate() const;
参数：无
返回值：成功返回当前采集设备采集一帧需要的时间，即帧率的倒数，否则返回0
说明：返回当前采集设备的当前帧率，连续模式有效
注意：在带宽够用的条件下函数getCurrentActualFPS和getCurrentActualFrameRate无区别，在带宽不够用的条件下，建议用getCurrentActualFrameRate，因为getCurrentActualFPS返回的是设置好的帧率，但不一定能达到。
13、函数：getCurrentMaxAvailableFPS
原型：double getCurrentMaxAvailableFPS() const;
参数：无
返回值：成功返回当前采集设备的最大帧率，否则返回0
说明：返回当前采集设备可以达到的最大帧率
14、函数：getDeBayerTransform
原型：smart_ptr
参数：无
返回值：返回当前采集设备的拜尔转换类指针
说明：返回当前采集设备的拜尔转换类指针
15、函数：getDefaultWindowPosition
原型：bool getDefaultWindowPosition();
参数：无
返回值：显示窗口可以被缩放返回true，否则返回false
说明：返回当前采集设备的显示窗口是否可以被缩放
16、函数：getDev
原型：tVideoCaptureDeviceItem getDev() const;
参数：无
返回值：返回当前采集设备指针
说明：获取当前视频采集设备
17、函数：getDeviceFrameFilters
原型：const tFrameFilterList getDeviceFrameFilters() const; 参数：无
返回值：返回当前采集设备的设备滤镜列表指针
说明：获取当前视频采集设备的设备滤镜
18、函数：getDisplayFrameFilters
原型：const tFrameFilterList getDisplayFrameFilters() const; 参数：无
返回值：返回当前采集设备的显示滤镜列表指针
说明：获取当前视频采集设备的显示滤镜
19、函数：getExternalTrigger
原型：bool getExternalTrigger() const;
参数：无
返回值：触发模式返回true，否则返回false
说明：判断当前设备是触发模式还是连续模式
20、函数：getFPS
原型：double getFPS() const;
参数：无
返回值：返回当前设置的帧率
说明：获取当前设置的帧率
例：
double FPS =m_Grabber.getFPS();
21、函数：getFrameCount
原型：DWORD getFrameCount() const;
参数：无
返回值：返回当前采集的帧数
说明：获取当前采集的帧数，从开始采集开始计数，到下次开始采集归0
22、函数：getFrameRate
原型：long getFrameRate() const;
参数：无
返回值：返回第n帧开始和第n+1帧开始之间的时间，以毫秒为单位
说明：获取两帧之间的时间差
23、函数：getHWND
原型：HWND getHWND() const;
参数：无
返回值：返回显示窗口的句柄或NULL
说明：获取显示窗口的句柄
24、函数：getLastError
原型：Error getLastError();
参数：无
返回值：返回错误类指针或0（没出错）
说明：获取错误信息
25、函数：getOverlay
原型：smart_ptr
smart_ptr
返回值：获取指定路径的叠加类句柄，如果没有指定路径则返回设备路径
说明：获取叠加类句柄，可以通过该句柄叠加文字图片信息
26、函数：getOverlayBitmapPathPosition
原型：DWORD getOverlayBitmapPathPosition() const;
参数：无
返回值：返回当前叠加类的路径
说明：获取当前叠加类的路径
27、函数：getPauseLive
原型：bool getPauseLive() const;
参数：无
返回值：暂停返回true，否则返回false
说明：判断视频是否处于暂停状态
28、函数：getProperty
原型：long getProperty( tCameraPropertyEnum CameraPropType ) const;
long getProperty( tVideoPropertyEnum VideoPropType ) const;
参数：CameraPropType 曝光时间等参数
VideoPropType 亮度、对比度等参数
返回值：返回指定参数的当前值
说明：获取指定参数的当前值
29、函数：getPropertyDefault
原型：long getPropertyDefault ( tCameraPropertyEnum CameraPropType )const;
long getPropertyDefault ( tVideoPropertyEnum VideoPropType ) const;
参数：CameraPropType 曝光时间等参数
亮度、对比度等参数
VideoPropType
返回值：返回指定参数的默认值
说明：获取指定参数的默认值
30、函数：getPropertyRange
原型：tsPropertyRange getPropertyRange ( tCameraPropertyEnum CameraPropType ) const;
tsPropertyRange getPropertyRange ( tVideoPropertyEnum VideoPropType ) const;
参数：CameraPropType 曝光时间等参数
亮度、对比度等参数
VideoPropType
返回值：返回指定参数的取值范围
说明：获取指定参数的取值范围
31、函数：getSinkType
原型：const GrabberSinkType& getSinkType() const;
参数：无
返回值：返回当前选择SINK类的类型
说明：获取当前选择SINK类的类型
32、函数：getSinkTypePtr
原型：smart_ptr
参数：无
返回值：返回当前选择SINK类的指针
说明：获取当前选择SINK类的指针
33、函数：getVideoFormat
原型：VideoFormatItem getVideoFormat() const;
参数：无
返回值：返回当前选择的视频数据格式
说明：获取当前选择的视频数据格式
34、函数：getWindowPosition
原型：bool getWindowPosition( long& posx, long& posy, long& width, long& height); 参数：posx 水平位置
垂直位置
posy
width 宽度
height 高度
返回值：成功返回true，否则返回false
说明：获取当前显示窗口的位置和大小
35、函数：hasExternalTrigger
原型：bool hasExternalTrigger() const;;
参数：无
返回值：采集设备带外触发返回true，否则返回false
说明：判断采集设备是否带外触发功能
36、函数：isDevOpen
原型：bool isDevOpen() const;
参数：无
返回值：设备打开返回true，否则返回false
说明：判断设备是否打开
37、函数：isDevValid
原型：bool isDevValid() const;
参数：无
返回值：设备有效返回true，否则返回false
说明：判断设备是否有效
38、函数：isFrameRateListAvailable
原型：bool isFrameRateListAvailable() const;
bool isFrameRateListAvailable( const VideoFormatItem& op ) const; 参数：VideoFormatItem 数据格式
返回值：支持返回true，否则返回false
说明：判断指定数据格式是否支持不同帧率
39、函数：isListenerRegistered
原型：bool isListenerRegistered( GrabberListener* pListener, DWORD callback = -1 );
参数：pListener 数据流回调类指针
callback 回调的事件类型
返回值：制动数据回调事件至少一个注册返回true，否则返回false
说明：判断指定数据数据回调事件是否注册
例：参看addListener
40、函数：isLive
原型：bool isLive() const;
参数：无
返回值：视频实时显示返回true，否则返回false
说明：判断视频是否实时显示
41、函数：isLivePrepared
原型：bool isLivePrepared() const;
参数：无
返回值：判断视频流处于等待状态返回true，否则返回false
说明：判断视频流是否处于等待状态
42、函数：isPropertyAutomationAvailableWithCurDev
原型：
bool isPropertyAutomationAvailableWithCurDev(tCameraPropertyEnum CameraPropType) const;
bool isPropertyAutomationAvailableWithCurDev(VideoPropertyEnum VideoPropType) cons t;
参数：CameraPropType 曝光时间等参数
亮度、对比度等参数
VideoPropType
返回值：参数可以设为自动返回true，否则返回false
说明：判断当前设备的指定参数是否可以设为自动