HighGUI參考手冊

HighGUI概述

簡單圖形界面

cvNamedWindow

創建窗口

int cvNamedWindow( const char* name, int flags );

name: 窗口的名字，它被用來區分不同的窗口，並被顯示爲窗口標題。
flags: 窗口屬性標誌。目前唯一支持的標誌是CV_WINDOW_AUTOSIZE。當這個標誌被設置後，如果用戶不能手動改變窗口大小，窗口大小會自動調整以適合被顯示圖像（參考cvShowImage）。

函數cvNamedWindow創建一個可以放置圖像和trackbar的窗口。被創建的窗口可以通過它們的名字被引用。

如果已經存在這個名字的窗口，這個函數將不做任何事情。

cvDestroyWindow

銷燬一個窗口

void cvDestroyWindow( const char* name );

name: 要被銷燬的窗口的名字。

函數cvDestroyWindow銷燬指定名字的窗口。

cvDestroyAllWindows

銷燬所有HighGUI窗口

void cvDestroyAllWindows(void);

函數cvDestroyAllWindows銷燬所有已經打開的HighGUI窗口。

cvResizeWindow

設定窗口大小

void cvResizeWindow( const char* name, int width, int height );

name: 將被設置窗口的名字。
width: 新的窗口寬度。
height: 新的窗口高度。

函數cvResizeWindow改變窗口的大小。

cvMoveWindow

設定窗口的位置

void cvMoveWindow( const char* name, int x, int y );

name: 將被設置的窗口的名字。
x: 窗口左上角的x座標。
y: 窗口左上角的y座標。

函數cvMoveWindow改變窗口的位置。

cvGetWindowHandle

通過名字獲取窗口句柄

void* cvGetWindowHandle( const char* name );

name: 窗口名字。

函數cvGetWindowHandle返回原始的窗口句柄（在Win32情況下返回HWND，GTK+情況下返回GtkWidget）

cvGetWindowName

通過句柄獲取窗口的名字

const char* cvGetWindowName( void* window_handle );

window_handle: 窗口句柄。

給定函數cvGetWindowName一個窗口的句柄（在Win32情況下是HWND，GTK+情況下是GtkWidget），函數返回窗口的名字。

cvShowImage

在指定窗口中顯示圖像

void cvShowImage( const char* name, const CvArr* image );

name: 窗口的名字。
image: 被顯示的圖像。

函數cvShowImage 在指定窗口中顯示圖像。如果窗口創建的時候被設定標誌CV_WINDOW_AUTOSIZE，那麼圖像將以原始尺寸顯示；否則，圖像將被伸縮以適合窗口大小。

cvCreateTrackbar

創建trackbar並將它添加到指定的窗口。

CV_EXTERN_C_FUNCPTR( void (*CvTrackbarCallback)(int pos) );

int cvCreateTrackbar( const char* trackbar_name, const char* window_name,
                      int* value, int count, CvTrackbarCallback on_change );

trackbar_name: 被創建的trackbar名字。
window_name: 窗口名字，這個窗口將爲被創建trackbar的父對象。
value: 整數指針，它的值將反映滑塊的位置。這個變量指定創建時的滑塊位置。
count: 滑塊位置的最大值。最小值一直是0。
on_change: 每次滑塊位置被改變的時候，被調用函數的指針。這個函數應該被聲明爲void Foo(int); 如果沒有回調函數，這個值可以設爲NULL。

函數cvCreateTrackbar用指定的名字和範圍來創建trackbar（滑塊或者範圍控制），指定與trackbar位置同步的變量，並且指定當trackbar位置被改變的時候調用的回調函數。被創建的trackbar顯示在指定窗口的頂端。

cvGetTrackbarPos

獲取trackbar的位置

int cvGetTrackbarPos( const char* trackbar_name, const char* window_name );

trackbar_name: trackbar的名字。
window_name: trackbar父窗口的名字。

函數cvGetTrackbarPos返回指定trackbar的當前位置。

cvSetTrackbarPos

設置trackbar位置

void cvSetTrackbarPos( const char* trackbar_name, const char* window_name, int pos );

trackbar_name: trackbar的名字。
window_name: trackbar父窗口的名字。
pos: 新的位置。

函數cvSetTrackbarPos設置指定trackbar的位置。

cvSetMouseCallback

設置鼠標事件的回調函數

#define CV_EVENT_MOUSEMOVE      0
#define CV_EVENT_LBUTTONDOWN    1
#define CV_EVENT_RBUTTONDOWN    2
#define CV_EVENT_MBUTTONDOWN    3
#define CV_EVENT_LBUTTONUP      4
#define CV_EVENT_RBUTTONUP      5
#define CV_EVENT_MBUTTONUP      6
#define CV_EVENT_LBUTTONDBLCLK  7
#define CV_EVENT_RBUTTONDBLCLK  8
#define CV_EVENT_MBUTTONDBLCLK  9

#define CV_EVENT_FLAG_LBUTTON   1
#define CV_EVENT_FLAG_RBUTTON   2
#define CV_EVENT_FLAG_MBUTTON   4
#define CV_EVENT_FLAG_CTRLKEY   8
#define CV_EVENT_FLAG_SHIFTKEY  16
#define CV_EVENT_FLAG_ALTKEY    32

CV_EXTERN_C_FUNCPTR( void (*CvMouseCallback )(int event, int x, int y, int flags, void* param) );

void cvSetMouseCallback( const char* window_name, CvMouseCallback on_mouse, void* param=NULL );

window_name

窗口的名字。

on_mouse

指定窗口裏每次鼠標時間發生的時候，被調用的函數指針。這個函數的原型應該爲

void Foo(int event, int x, int y, int flags, void* param);

其中event是 CV_EVENT_*變量之一， x和y是鼠標指針在圖像座標系的座標（不是窗口座標系）， flags是CV_EVENT_FLAG的組合， param是用戶定義的傳遞到cvSetMouseCallback函數調用的參數。

param

用戶定義的傳遞到回調函數的參數。

函數cvSetMouseCallback設定指定窗口鼠標事件發生時的回調函數。詳細使用方法，請參考opencv/samples/c/ffilldemo.c demo。

cvWaitKey

等待按鍵事件

int cvWaitKey( int delay=0 );

delay: 延遲的毫秒數。

函數cvWaitKey無限制的等待按鍵事件（delay<=0時）；或者延遲"delay"毫秒。返回值爲被按鍵的值，如果超過指定時間則返回-1。

註釋：這個函數是HighGUI中唯一能夠獲取和操作事件的函數，所以在一般的事件處理中，它需要週期地被調用，除非HighGUI被用在某些能夠處理事件的環境中。

讀取與保存圖像

cvLoadImage

從文件中讀取圖像

IplImage* cvLoadImage( const char* filename, int iscolor=1 );

filename: 要被讀入的文件的文件名。
iscolor: 指定讀入圖像的顏色：
如果 >0，讀入的圖像將被強制轉換爲3通道彩色圖像；
如果爲 0, 讀入的圖像將被強制轉換爲灰度圖像；
如果 <0, 讀入的圖像將與它本來顏色信息一樣（顏色通道數目由圖像文件決定）。

函數cvLoadImage從指定文件讀入圖像，返回讀入圖像的指針。目前支持如下文件格式：

Windows位圖文件 - BMP, DIB；
JPEG文件 - JPEG, JPG, JPE；
便攜式網絡圖片 - PNG；
便攜式圖像格式 - PBM，PGM，PPM；
Sun rasters - SR，RAS；
TIFF文件 - TIFF，TIF。

cvSaveImage

保存圖像到文件

int cvSaveImage( const char* filename, const CvArr* image );

filename: 文件名。
image: 要保存的圖像。

函數cvSaveImage保存圖像到指定文件。圖像格式的的選擇依賴於filename的擴展名，請參考cvLoadImage。只有8位單通道或者3通道（通道順序爲'BGR' ）可以使用這個函數保存。如果格式，深度或者通道不符合要求，請先用cvCvtScale 和cvCvtColor轉換；或者使用通用的cvSave保存圖像爲XML或者YAML格式。

視頻讀寫函數

CvCapture

視頻獲取結構

typedef struct CvCapture CvCapture;

結構CvCapture 沒有公共接口，它只能被用來作爲視頻獲取函數的一個參數。

cvCaptureFromFile

初始化從文件中獲取視頻

CvCapture* cvCaptureFromFile( const char* filename );

filename: 視頻文件名。

函數cvCaptureFromFile給指定文件中的視頻流分配和初始化CvCapture結構。

當分配的結構不再使用的時候，它應該使用cvReleaseCapture函數釋放掉。

cvCaptureFromCAM

初始化從攝像頭中獲取視頻

CvCapture* cvCaptureFromCAM( int index );

index: 要使用的攝像頭索引。如果只有一個攝像頭或者用哪個攝像頭也無所謂，那使用參數-1應該便可以。

函數cvCaptureFromCAM給從攝像頭的視頻流分配和初始化CvCapture結構。目前在Windows下可使用兩種接口：Video for Windows（VFW）和Matrox Imaging Library（MIL）； Linux下也有兩種接口：V4L和FireWire（IEEE1394）。

釋放這個結構，使用函數cvReleaseCapture。

cvReleaseCapture

釋放CvCapture結構

void cvReleaseCapture( CvCapture** capture );

capture: 視頻獲取結構指針。

函數cvReleaseCapture釋放由cvCaptureFromFile 或者cvCaptureFromCAM申請的CvCapture結構。

cvGrabFrame

從攝像頭或者視頻文件中抓取幀

int cvGrabFrame( CvCapture* capture );

capture: 視頻獲取結構指針。

函數cvGrabFrame從攝像頭或者文件中抓取幀。被抓取的幀在內部被存儲。這個函數的目的是快速的抓取幀，這一點對同時從幾個攝像頭讀取數據的同步是很重要的。被抓取的幀可能是壓縮的格式（由攝像頭／驅動定義），所以沒有被公開出來。如果要取回獲取的幀，請使用cvRetrieveFrame。

cvRetrieveFrame

取回由函數cvGrabFrame抓取的圖像

IplImage* cvRetrieveFrame( CvCapture* capture );

capture: 視頻獲取結構。

函數cvRetrieveFrame返回由函數cvGrabFrame 抓取的圖像的指針。返回的圖像不可以被用戶釋放或者修改。

cvQueryFrame

從攝像頭或者文件中抓取並返回一幀

IplImage* cvQueryFrame( CvCapture* capture );

capture: 視頻獲取結構。

函數cvQueryFrame從攝像頭或者文件中抓取一幀，然後解壓並返回這一幀。這個函數僅僅是函數cvGrabFrame和函數cvRetrieveFrame在一起調用的組合。返回的圖像不可以被用戶釋放或者修改。

cvGetCaptureProperty

獲得視頻獲取結構的屬性

double cvGetCaptureProperty( CvCapture* capture, int property_id );

capture: 視頻獲取結構。
property_id: 屬性標識。可以是下面之一：
CV_CAP_PROP_POS_MSEC - 影片目前位置，爲毫秒數或者視頻獲取時間戳
CV_CAP_PROP_POS_FRAMES - 將被下一步解壓／獲取的幀索引，以0爲起點
CV_CAP_PROP_POS_AVI_RATIO - 視頻文件的相對位置（0 - 影片的開始，1 - 影片的結尾)
CV_CAP_PROP_FRAME_WIDTH - 視頻流中的幀寬度
CV_CAP_PROP_FRAME_HEIGHT - 視頻流中的幀高度
CV_CAP_PROP_FPS - 幀率
CV_CAP_PROP_FOURCC - 表示codec的四個字符 CV_CAP_PROP_FRAME_COUNT - 視頻文件中幀的總數

函數cvGetCaptureProperty獲得攝像頭或者視頻文件的指定屬性。

譯者注：有時候這個函數在cvQueryFrame被調用一次後，再調用cvGetCaptureProperty纔會返回正確的數值。

cvSetCaptureProperty

設置視頻獲取屬性

int cvSetCaptureProperty( CvCapture* capture, int property_id, double value );

capture: 視頻獲取結構。
property_id: 屬性標識符。可以是下面之一：
CV_CAP_PROP_POS_MSEC - 從文件開始的位置，單位爲毫秒
CV_CAP_PROP_POS_FRAMES - 單位爲幀數的位置（只對視頻文件有效）
CV_CAP_PROP_POS_AVI_RATIO - 視頻文件的相對位置（0 - 影片的開始，1 - 影片的結尾)
CV_CAP_PROP_FRAME_WIDTH - 視頻流的幀寬度（只對攝像頭有效）
CV_CAP_PROP_FRAME_HEIGHT - 視頻流的幀高度（只對攝像頭有效）
CV_CAP_PROP_FPS - 幀率（只對攝像頭有效）
CV_CAP_PROP_FOURCC - 表示codec的四個字符（只對攝像頭有效）
value: 屬性的值。

函數cvSetCaptureProperty設置指定視頻獲取的屬性。目前這個函數對視頻文件只支持： CV_CAP_PROP_POS_MSEC, CV_CAP_PROP_POS_FRAMES, CV_CAP_PROP_POS_AVI_RATIO

cvCreateVideoWriter

創建視頻文件寫入器

typedef struct CvVideoWriter CvVideoWriter;
CvVideoWriter* cvCreateVideoWriter( const char* filename, int fourcc, double fps, CvSize frame_size, int is_color=1 );

filename: 輸出視頻文件名。
fourcc: 四個字符用來表示壓縮幀的codec 例如，CV_FOURCC('P','I','M','1')是MPEG-1 codec， CV_FOURCC('M','J','P','G')是motion-jpeg codec等。在Win32下，如果傳入參數-1，可以從一個對話框中選擇壓縮方法和壓縮參數。
fps: 被創建視頻流的幀率。
frame_size: 視頻流的大小。
is_color: 如果非零，編碼器將希望得到彩色幀並進行編碼；否則，是灰度幀（只有在Windows下支持這個標誌）。

函數cvCreateVideoWriter創建視頻寫入器結構。

cvReleaseVideoWriter

釋放視頻寫入器

void cvReleaseVideoWriter( CvVideoWriter** writer );

writer: 指向視頻寫入器的指針。

函數cvReleaseVideoWriter結束視頻文件的寫入並且釋放這個結構。

cvWriteFrame

寫入一幀到一個視頻文件中

int cvWriteFrame( CvVideoWriter* writer, const IplImage* image );

writer: 視頻寫入器結構。
image: 被寫入的幀。

函數cvWriteFrame寫入／附加到視頻文件一幀。

實用函數與系統函數

cvInitSystem

初始化HighGUI

int cvInitSystem( int argc, char** argv );

argc: 命令行參數個數。
argv: 命令行參數數組。

函數cvInitSystem初始化HighGUI。如果在第一個窗口被創建前這個函數不能被用戶顯式地調用，這個函數將以參數argc=0，argv=NULL隱式地被調用。在Win32下，沒有必要顯式調用這個函數。在X Window下，參數也許被用來自定義一個HighGUI窗口和控件的外觀。

cvConvertImage

Converts one image to another with optional vertical flip

void cvConvertImage( const CvArr* src, CvArr* dst, int flags=0 );

src: 輸入圖像。
dst: 目標圖像。必須爲單通道或者3通道8位圖像。
flags: 操作標誌：
CV_CVTIMG_FLIP - 垂直翻轉圖像。 CV_CVTIMG_SWAP_RB - 交換紅藍通道。在OpenCV中，彩色圖像的通道順序是 BGR 然而在一些系統中，在顯式圖像之前通道順序應該被翻轉爲（cvShowImage能夠自動轉換）。

函數cvConvertImage轉換一幅圖像到另一幅圖像，如果需要的話可以垂直翻轉圖像。這個函數被cvShowImage使用。