Image類（Leap::Image）和ImageList類（Leap::ImageList）

Image類（Leap::Image）

這個類描述了其中一個Leap Motion相機的單獨的圖檔。除了圖檔資料之外，Image對象還提供了一個畸變圖譜用來修正透鏡畸變。Image對象也可以是無效的，可以通過Image::isValid()函數來測試有效性。

int bytesPerPixel(): 表示每個像素中的位元組數目。用這個值，結合函數Image::width()和Image::height()來計算資料緩沖區的大小。

用法：int bufferSize=image. bytesPerPixel()*image::width()*image::height();

const unsigned char *data(): 表示圖檔資料。這個圖檔資料是個8位整型值的集合。緩沖區的長度為Image. bytesPerPixel()*Image::width()*Image::height()個位元組。傳回的是包含傳感器亮度值的無符号字元型數組。

const float * distortion(): 表示這幅圖檔的畸變标定圖譜。這個校正圖譜是64×64的網格點，每個點被定義為一對32位的浮點型值。圖譜中的每個點代表投射到相機中的一條射線。網格點的值定義了圖檔資料中的像素，包含了由進入的光和相應的射線産生的亮度值。通過網格資料點之間的插值，可以得到任何一條投射進來的射線的亮度值。落在0到1範圍之外的網格值在圖檔資料中并沒有對應的亮度值，應該忽略這些點。

标定圖譜可以用來呈現一個無畸變的圖檔，還可以用來得到從相機到原始圖檔中的一個特征的角度。這個畸變圖譜本身是設計來和GLSL着色器程式一起使用的。在非實時環境中，用Image::rectify()和Image::warp()函數更友善。如果無法用着色器，可以直接用畸變圖譜。如果很好的優化的話，這要比用warp()函數要快。

畸變是由透鏡幾何和透鏡與傳感器視窗中的瑕疵造成的。這個标定圖譜是由工廠每個裝置執行标定過程中建立的。在以後的release中每幅圖檔可能會有兩個畸變圖譜，一個包含了水準值另一個包含了垂直值。

用法：const float * distortion_buffer=image. distortion();

int distortionHeight(): 表示畸變圖譜的高，通常固定為64.

用法：int correctionGridHeight=image. distortionHeight();

int distortionWidth(): 表示畸變圖譜的寬。因為在64×64元素的畸變圖譜中的每個點在緩沖中都有兩個值。步幅是網格大小的2倍。（步幅通常固定為2*64=128）

用法：int correctionGridWidth=image. distortionWidth();

FormatType format(): 表示圖檔的格式。

用法：if (image.format() == Leap::Image::INFRARED){

std::string openGL_format = “GL_RED”;

std::string openGL_type = “GL_UNSIGNED_BYTE”;

}

int height(): 表示圖檔的高。

用法：int height=image.height();

int width(): 表示圖檔的寬。

用法：int width=image. width();

int32_t id(): 表示圖檔的ID值。帶有ID值為0的圖檔來自左相機，帶有ID值為1的圖檔來自右相機（當綠色的小燈朝向操作者，裝置處于标準的操作位置）。

Image(): 構造一個無效的Image對象。沒有初始化的對象被認為是無效的。從ImageList對象中得到有效的Image對象，而ImageList對象則是從Frame::images()中得到。

bool isValid(): 判斷這個Image執行個體中是否包含有效的資料。當且僅當圖檔有效時傳回True。

bool operator!=(const Image &): 比較Image對象是否不相等。如果兩個對象都是有效的，在同一幀中有且僅有這兩個對象表示同樣的實體，則這兩個對象相等。

bool operator==(const Image &): 比較Image對象是否相等。如果兩個對象都是有效的，在同一幀中有且僅有這兩個對象表示同樣的實體，則這兩個對象相等。

float rayOffsetX(): 表示水準射線補償。用來在處于0到1範圍内的歸一化坐标和處于-4到4範圍内的光束角之間的轉化。

說明：Leap::Vector raySlopes(-3.28, 1.76, 0);

Leap::Vector normRay =

Leap::Vector(raySlopes.x * image.rayScaleX() + image.rayOffsetX(),

raySlopes.y * image.rayScaleY() + image.rayOffsetY(), 0);

float rayOffsetY(): 表示垂直射線補償。用來在處于0到1範圍内的歸一化坐标和處于-4到4範圍内的光束角之間的轉化。

說明：Leap::Vector normSlopes(.09, .72, 0);

Leap::Vector slope((normSlopes.x - image.rayOffsetX()) / image.rayScaleX(),

(normSlopes.y - image.rayOffsetY()) / image.rayScaleY(), 0);

float rayScaleX(): 表示水準射線縮放因子。用來在處于0到1範圍内的歸一化坐标和處于-4到4範圍内的光束角之間的轉化。

說明：Leap::Vector raySlopes(-3.28, 1.76, 0);

Leap::Vector normRay =

Leap::Vector(raySlopes.x * image.rayScaleX() + image.rayOffsetX(),

raySlopes.y * image.rayScaleY() + image.rayOffsetY(), 0);

float rayScaleY(): 表示垂直射線縮放因子。用來在處于0到1範圍内的歸一化坐标和處于-4到4範圍内的光束角之間的轉化。

說明：Leap::Vector normSlopes(.09, .72, 0);

Leap::Vector slope((normSlopes.x - image.rayOffsetX()) / image.rayScaleX(),

(normSlopes.y - image.rayOffsetY()) / image.rayScaleY(), 0);

Vector rectify(const Vector & uv): 提供糾正的相機射線（截獲了圖檔中的指定點）。給定一個圖檔上的點，這個函數可以糾正相機畸變，傳回從相機到Leap Motion視線内圖檔點來源的正确方向。

對于方向向量[x,y,0]，用的是二維的相機坐标系，x軸平行于較長的尺寸（通常是水準的），y軸平行于較短的尺寸。相機的坐标系與三維的Leap Motion坐标系并不相關。

該函數中的參數uv是包含了圖檔中一個像素位置的向量，傳回的是包含了射線方向的向量，其中向量的z元素總是0.

用法：Leap::Vector feature(127, 68, 0);

Leap::Vector slopes = image.rectify(feature);

int64_t sequenceld(): 表示圖檔序列的ID值。

int64_t timestamp(): 傳回的是這一幀開始被裝置捕獲的時間标記。

std::string toString(): 一個包含簡略描述該Image對象的字元串。

Vector warp(const Vector & xy): 提供了與投影到相機上的射線相對應的點。給定一個以一個指定的方向投影到相機上的射線，該函數可以修正相機畸變，傳回圖檔上對應的像素坐标。射線的方向是基于對相機的考慮來指定的第一個元素關聯于水準視角，第二個元素關聯于垂直視角。

如果向一個沒有記錄資料的點投影射線，則該函數将傳回圖檔邊界以外的像素坐标。這個函數速度不快，沒法實作實時畸變校正。為了更好的效果，需要用到GPU上的着色器。

用法：參數xy是包含射線方向的向量。

float horizontal_slope = tan(65 * Leap::PI / 180);

float vertical_slope = tan(15 * Leap::PI / 180);

Leap::Vector pixel = image.warp(Leap::Vector(horizontal_slope, vertical_slope, 0));

if (pixel.x >= 0 && pixel.y >= 0 && pixel.x <= image.width() && pixel.y <= image.height()){

int data_index = floor(pixel.y) * image.width() + floor(pixel.x);

unsigned char brightness = image.data()[data_index];

}

const Image & invalid(): 傳回一個無效Image對象。也可以用Imge::isValid()函數。

ImageList類（Leap::ImageList）

這個類代表了Image對象的清單。通過調用Frame::images()可以得到一個與跟蹤資料的Frame相關的ImageList對象。通過調用Controller::images()函數得到最近的圖檔集，這要比建立目前幀所用到的圖檔要新。

ImageList & append(const ImageList & other): 表示把指定的一個ImageList的成員添加到這個ImageList對象中。參數other表示一個ImageList對象，其中包含Image對象，将要添加到這個ImageList對象末端。

const_iterator begin(): 表示C++的疊代器，設定在這個ImageList對象的開始。

int count(): 表示這個清單中圖檔的數目。

const_iterator end(): 表示C++的疊代器，設定在這個ImageList對象的結束。

ImageList(): 表示構造一個沒有實體的空清單。

bool isEmpty(): 判斷這個清單是否為空。如果沒有成員，傳回True。

Image operator[](int index): 表示對清單中一個成員位置的通路。傳回的是指定索引下的Image對象。

譯自：https://developer.leapmotion.com/documentation/cpp/api/Leap.Image.html

https://developer.leapmotion.com/documentation/cpp/api/Leap.ImageList.html