Guidance SDK文件
目錄
概述：通過授予對Guidance的完全控制權，Guidance SDK使您能夠輕鬆地開發各種基於視覺的應用程式，您可以輕鬆地從所有主流系統的指南中訪問所有輸出資料。
支援平臺：Windows、Linux、Embeded systems
特徵：
1、機身狀態：輸出機身的三維速度與位置（世界座標系？）、輸出到最近障礙物的距離（影象和超聲波資料）
2、感測器資料：輸出機身IMU資料（三軸加速度計和陀螺儀（機體座標系））、輸出到最近障礙物的距離
3、影象：輸出固定解析度為3x240的8或16位灰度影象、
4、相機配置：有權獲取雙目相機標定引數、有權訪問和修改相機曝光模式和引數
硬體介面：
- USB：以高資料速率傳輸所有資料並精確控制相機引數
- UART：傳輸除影象以外的所有資料，適用於所有具有序列通訊的系統
1.1啟動
官方Guidance SDK包，用於通過USB和UART訪問指南的豐富類別的輸出資料，並根據需要配置Guidance。
1.1.1檔案
A、開發者指南
B、執行例程
C、建立視覺跟蹤專案
D、Guidance SDK參考
1.1.2結構
A、demo：使用Guidance SDK的演示應用程式
B、doc：檔案
C、examples：USB和UART的例程
D、include：Guidance SDK的標頭檔案
E、lib：Windows的庫檔案
2010/X64：使用Visual Studio 2010 64位生成
2010/X86：使用Visual Studio 2010 32位生成
2013/X64：使用Visual Studio 2013 64位生成
2013/X86：使用Visual Studio 2013 32位生成
F、so：Linux的庫檔案
X64：用g++在64位Linux系統上構建
X86：用g++在32位Linux系統上構建
XU3：用g++在XU3系統上構建
arm：在嵌入式ARM系統上，用最新的arm-linux-gnueabi-g++構建，通過下面語句安裝交叉編譯工具鏈：sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
還要注意，為了使ROS使用者能夠快速下載，我們有一個單獨的ROS報告，其規模要小得多：Guidance-SDK-ROS.
1.1.3用法
A、Windows
USB和UART的例子在examples/usb_example、examples/uart_example，包括待編譯的Makefile檔案。請記住將相應的DjiGuang.dLL檔案複製到輸出二進位制位置所在的相同目錄。
B、Linux
USB和UART的例子在examples/usb_example、examples/uart_example，包括待編譯的Makefile檔案。請記住將相應的DjiGuang.dLL檔案複製到輸出二進位制位置所在的相同目錄。
請注意，Linux中讀寫USB埠需要root許可權，為了解決每次執行SDK應用程式時鍵入sudo的麻煩，建議將一個規則新增到/etc/udev/rules.d目錄中，這可以在doc/51-guidance.rules中找到。或從終端輸入以下行:
sudo sh -c 'echo "SUBSYSTEM==\"usb\", ATTR{idVendor}==\"fff0\", ATTR{idProduct}==\"d009\", MODE=\"0666\"" > /etc/udev/rules.d/51-guidance.rules'
1.2 執行例程
Guidance SDK提供了從Guidance系統獲得資料的例子。本節將指導您如何執行這些示例。我們使用OpenCV來檢視從Guidance傳輸的影象，因此建議在系統上安裝OpenCV。但是，如果沒有OpenCV，也可以獲得除影象以外的所有資料。
我們提供Linux和Windows系統的CMAKLIST.TXT，它自動檢測是否安裝了OpenCV。
1.2.1用CMake編譯USB例項
注：CMake是必需的。在Windows上，也需要VisualStudio（2010或2013）。
A、cd Guidance-SDK\examples\usb_example\DJI_guidance_example
B、mkdir build
C、cd build
D、cmake ..
E、build：
a、Linux系統：make
b、Windows系統：您將看到生成一個解決方案檔案。開啟它並建立專案dji_guidance_usb
A、設定環境
Guidance SDK使用libusb-1.0.9庫從Guidance系統讀取資料。請參考 編譯並安裝原始碼的LUBSB-1.0.9庫。
B、複製相關檔案
提供Makefile且已測試過。 使用者無需更改任何內容即可執行示例程式碼。要在自己的專案中使用Guidance，使用者可以按照以下說明操作：
- 複製libDJI_guidance.so到自己專案的庫檔案路徑
- 複製DJI_guidance.h到標頭檔案路徑
- 在專案的Makefile中新增庫，如下所示：
LDFLAGS = -Wl,-rpath,./ -lpthread -lrt -L./ -L/usr/local/lib/ -l **DJI\_guidance** -lusb-1.0
C、編譯例程
進入專案目錄並輸入：Make -f Makefile_noOpenCV
注意：這裡我們假設您沒有安裝OpenCV並使用Makefile_noOpenCV。 您可以根據自己的情況在make期間指定makefile。 例如，如果安裝了OpenCV，請使用其他makefile：make –f Makefile
D、通過USB連線Guidance並執行
如果尚未按照開發人員指南中的說明將51-guidance.rules檔案新增到/etc/udev/rules.d/目錄，則需要root許可權才能執行此示例。
sudo ./guidance_example
執行結果如下所示：
A、配置環境
Guidance SDK使用libusb庫從Guidance系統讀取資料。 請確保正確安裝Guidance Assistant軟體，其中包括用於指導的DJI USB驅動程式。
B、安裝Visual studio
提供並測試了不同版本的Visual Studio的解決方案。 使用者無需更改任何內容即可執行示例程式碼。
要在自己的專案中使用Guidance，建議使用examples \ usb_example資料夾中提供的屬性表文件。 使用者只需要更改屬性表文件中的標頭檔案和庫檔案的目錄。
或者，使用者可以直接複製檔案並按如下方式配置Visual Studio：
- 複製DJI_guidance.dll 、DJI_guidance.lib到自己專案的庫檔案路徑
- 複製DJI_guidance.h到標頭檔案路徑
- 將DJI_guidance.lib新增到Visual Studio專案的其他依賴項中
C、編譯
使用Microsoft Visual Studio編譯示例專案。
如果安裝了OpenCV，還可以通過在原始檔main.cpp中或在Visual Studio的預處理設定中定義HAVE_OPENCV來將Visual Studio配置為使用OpenCV。
D、連線Guidance系統並進行測試
結果如下所示
A、訂閱UART資料
參考2.1.2啟用UART
B、編譯
進入uart_example目錄並make：
C、連線Guidance系統並進行測試
A、訂閱UART資料
參考2.1.2啟用UART
B、編譯
使用VS編譯
- 連線Guidance系統並測試
2、介紹（Guidance SDK reference）
2.1 背景
此文件提供了關於SDK的結構和API函式的詳細解釋。我們假設你有：
1、一個Guidance系統，
2、一臺安裝了OpenCV的計算機
並且你：
1、熟悉Linux程式設計，
2、或者熟悉Windows程式設計和Microsoft Visual Studio使用。
2.2 簡介
本節介紹指導SDK的結構。該SDK分為三個層次:
應用: 該層處理由HAL層傳來的資料，由開發者編寫。
HAL: 硬體抽象層。該層打包/解析從驅動層傳來的資料，由示例程式碼實現（串列埠）SDK庫（用於USB）實現，例如libDJI_guidance.so。
驅動: 該層通過USB或者串列埠從Guidance接收資料，由作業系統或第三方庫（如_libusb_）實現。
介面：
Guidance SDK支援兩種通訊協議:USB和串列埠。
1. USB
支援的資料型別包括速度資料，障礙物距離資料，IMU資料，超聲波資料，灰度影象和深度影象。有兩種方法可以通過USB訂閱資料。
I、Guidance Assist軟體
使用者可以使用Guidance Assist軟體中的“DIY-> API - > USB”選項卡來訂閱資料。
A、使用USB線連線Guidance和PC，將Guidance上電
B、選擇“啟用”複選框
C、根據您的需求選擇資料
注: 可用頻寬是受制於選擇的影象資料和輸出頻率。訂閱影象資料和輸出頻率的選擇將被儲存在Guidance系統上，並在Guidance下一次啟動時生效。
II、Guidance API
使用者可以通過Guidance API訂閱資料，這些API函式的名字都以"select"開頭。
注: 如果使用者通過Guidance API函式來訂閱影象資料和輸出頻率，它只會在Guidance上電期間臨時生效，Guidance斷電後將恢復到Guidance Assist設定的狀態。
2、串列埠
串列埠的輸出資料型別包括速度資料，障礙物距離資料，IMU資料和超聲波資料。由於頻寬限制，影象資料不通過UART輸出。
注: Guidance串列埠目前只支援115200波特率。
A、訂閱資料
您只能使用Guidance Assist軟體訂閱UART資料。從“DIY-> API - > UART”頁面啟用串列埠。與USB相同，該配置將被儲存在Guidance系統上，除非你在“UART”選項卡中取消選擇“啟用”選項。
B、協議說明
協議幀格式:
SOF LEN VER RES SEQ CRC16 DATA CRC32
協議幀解釋:
|
名稱 |
位元組索引 |
大小（位） |
說明 |
|
SOF |
0 |
8 |
幀起始編號，固定為0xAA |
|
LEN |
1 |
10 |
幀長，最大長度為1023位元組 |
|
VER |
1 |
6 |
協議版本 |
|
RES |
5 |
40 |
保留位，固定為0 |
|
SEQ |
8 |
16 |
幀序列號 |
|
CRC16 |
10 |
16 |
幀頭CRC16校驗和 |
|
DATA |
12 |
註釋1 |
幀資料，最大長度為1007位元組 |
|
CRC32 |
註釋2 |
32 |
幀CRC32校驗和 |
註釋1：幀資料大小是可變的，最大為1007位元組。
註釋2：該域的索引取決於資料域的長度。
資料域格式:
COMMAND SET COMMAND ID COMMAND DATA
|
資料域 |
位元組索引 |
大小（位） |
說明 |
|
COMMAND SET |
0 |
1 |
恆為0X00 |
|
COMMAND ID |
1 |
1 |
e_image： 0x00;；e_imu： 0x01; e_ultrasonic：0x02；e_velocity：0x03; e_obstacle_distance:：0x04 |
|
COMMAND DATA |
2 |
-- |
資料體 |
資料型別：
支援的資料型別描述如下。
錯誤碼: 列舉可能的錯誤程式碼。當錯誤發生時，通常會返回一個錯誤碼，而開發者可以參考此列舉來檢查錯誤型別。
速度資料: 機體座標下的速度。單位是毫米每秒，頻率是10 Hz.
障礙物距離資料: 從五個Guidance感測器模組讀取的障礙物距離資料。單位是釐米，頻率是20 Hz.
IMU資料: IMU資料，包括加速度計（單位為重力加速度g）和陀螺儀（四元數格式）資料。頻率為20 Hz.
超聲波資料: 輸出從五個Guidance感測器讀取的超聲波資料，包括障礙物距離（單位為米）和資料的可靠性。頻率為20 Hz.
灰度影象: 輸出五個方向的8位元灰度影象。每張影象解析度為320*240. 預設頻率為20Hz，可以通過API函式降頻。
深度影象: 輸出五個方向的16位元深度影象。每張影象解析度為320*240. 預設頻率為20Hz，可以通過API函式降頻。
視差影象: 輸出五個方向的16位元視差影象。這個資料在開發者想要進一步優化視差圖時是有用的，比如用speckle filter等函式優化。每張影象解析度為320*240. 預設頻率為20Hz，可以通過API函式降頻。
2.3 資料結構
I、e_sdk_err_code
描述: 定義SDK的錯誤程式碼。
enum e_sdk_err_code
{
e_timeout = -7, // USB傳輸超時
e_libusb_io_err = -1, // libusb庫IO錯誤
e_sdk_no_err = 0, // 成功，沒有錯誤
e_load_libusb_err=1, // 載入的libusb庫錯誤
e_sdk_not_inited=2, // SDK軟體還沒有準備好
e_hardware_not_ready=3, // Guidance硬體還沒有準備好
e_disparity_not_allowed=4, // 視差圖或深度圖不允許被選擇
e_image_frequency_not_allowed=5, // 影象頻率必須是列舉型別e_image_data_frequecy之一
e_config_not_ready=6, // 配置沒有準備好
e_online_flag_not_ready=7, // 線上標誌沒有準備好
e_stereo_cali_not_ready = 8, // 攝像頭標定引數沒有準備好
e_max_sdk_err = 100 // 錯誤最大數量
};
解釋:
- e_timeout: USB傳輸超時。
- e_libusb_io_err: libusb庫IO錯誤。這可能由USB的連線錯誤引起。
- e_OK: 成功，沒有錯誤。
- e_load_libusb_err: 載入的libusb庫錯誤。這是由於使用了不正確的libusb庫。
- e_sdk_not_inited: SDK軟體還沒有準備好。
- e_hardware_not_ready: Guidance硬體還沒有準備好。
- e_disparity_not_allowed: 如果您的Guidance工作在標準模式下，且激活了障礙物感知功能，那麼視差圖和深度圖是不允許被選擇的。因為障礙物感知有自己的選擇視差圖的方法。
- e_image_frequency_not_allowed: 影象頻率必須是列舉型別e_image_data_frequecy之一。目前只支援3種傳輸頻率:5Hz, 10Hz, 20Hz.
- e_config_not_ready: 配置資料沒有準備好。Guidance上電時，需要花幾秒鐘時間（有時更長）來進行初始化，包括載入配置資料到記憶體，並將資料傳送至應用層（即SDK軟體）。如果使用者在配置資料準備好之前啟動了SDK程式，這個錯誤就會被丟擲。配置資料包括:Guidance的工作模式，Guidance感測模組的線上狀態，標定引數，等待。
- e_online_flag_not_ready: 線上標誌沒有準備好。Guidance系統允許使用者使用任意數目的感測模組，從1到5. 我們使用一個線上狀態陣列來標識哪些感測模組是線上的。如果使用者從不線上的感測模組訂閱了資料，那麼不會有資料傳輸過來。
- e_stereo_cali_not_ready: 攝像頭標定引數沒有準備好。這個引數對三維應用是有用的。因為影象已經是校正過的影象，我們沒有提供畸變係數，只提供了:主點座標cu, cv，焦距focal，和基線長度baseline.
II、e_vbus_index
描述: 定義VBUS的邏輯方向，即Guidance感測模組的方向。注意它們只取決於Guidance處理模組上的VBUS介面，而不是Guidance感測模組。
每個列舉值的註釋說明了當Guidance以預設方式安裝在Matrice 100上時該列舉值代表的方向。但開發者可以任意方式安裝Guidance在任意的裝置上，因此
enum e_vbus_index
{
e_vbus1 = 1, // M100上為前視
e_vbus2 = 2, // M100上為右視
e_vbus3 = 3, // M100上為後視
e_vbus4 = 4, // M100上為左視
e_vbus5 = 0 // M100上為下視
};
III、e_image_data_frequecy
描述: 定義影象資料的頻率。可選的頻率有:5Hz, 10Hz, 20Hz. 訂閱的影象越多，傳輸的頻率就越低
enum e_image_data_frequecy
{
e_frequecy_5 = 0, // frequecy of image data: 5Hz
e_frequecy_10 = 1, // frequecy of image data: 10Hz
e_frequecy_20 = 2 // frequecy of image data: 20Hz
};
IV、e_guidance_event
描述: 定義回撥的事件型別。
enum e_guidance_event
{
e_image = 0, // called back when image comes
e_imu, // called back when imu comes
e_ultrasonic, // called back when ultrasonic comes
e_velocity, // called back when velocity data comes
e_obstacle_distance, // called back when obstacle data comes
e_motion, // called back when global position comes
e_event_num
};
V、image_data
描述: 定義影象的資料結構。每個方向的深度圖與雙目灰度圖中的左圖對齊。
typedef struct _image_data
{
unsigned int frame_index; // frame index
unsigned int time_stamp; // time stamp of image captured in ms
char *m_greyscale_image_left[CAMERA_PAIR_NUM];// greyscale image of left camera
char *m_greyscale_image_right[CAMERA_PAIR_NUM]; // greyscale image of right camera
char *m_depth_image[CAMERA_PAIR_NUM]; // depth image in *128 meters
char *m_disparity_image[CAMERA_PAIR_NUM]; // disparity image in *16 pixels
}image_data;
解釋:
1、m_greyscale_image_left和m_greyscale_image_right都是寬320，高240的8位元灰度圖。
2、m_depth_image是寬320，高240的16位元深度圖，每兩個位元組描述一個點的深度，低7位為小數位，高9位為整數位。
3、m_disparity_image是寬320，高240的16位元視差圖，每兩個位元組描述一個點的深度，低4位為小數位，高12位為整數位。
VI、ultrasonic_data
描述: 定義超聲波的資料結構。ultrasonic是超聲波感測器檢測到的最近物體的距離，單位是mm。reliability是該距離測量的可信度，1為可信，0為不可信。由於觀測資料存在噪聲，建議對資料進行濾波後再使用。
typedef struct _ultrasonic_data
{
unsigned int frame_index; // corresponse frame index
unsigned int time_stamp; // time stamp of corresponse image captured in ms
short ultrasonic[CAMERA_PAIR_NUM]; // distance in mm. -1 means invalid measurement.
unsigned short reliability[CAMERA_PAIR_NUM]; // reliability of the distance data
}ultrasonic_data;
VII、velocity
描述: 定義體座標系下的速度。單位是mm/s。
typedef struct _velocity
{
unsigned int frame_index; // corresponse frame index
unsigned int time_stamp; // time stamp of corresponse image captured in ms
short vx; // velocity of x in mm/s
short vy; // velocity of y in mm/s
short vz; // velocity of z in mm/s
}velocity;
VIII、obstacle_distance
描述: 定義由視覺和超聲波融合得到的障礙物距離。單位是cm。
typedef struct _obstacle_distance
{
unsigned int frame_index; // corresponse frame index
unsigned int time_stamp; // time stamp of corresponse image captured in ms
unsigned short distance[CAMERA_PAIR_NUM]; // distance of obstacle in cm
}obstacle_distance;
IX、imu
描述: 定義IMU資料結構。加速度單位為m/s^2
typedef struct _imu
{
unsigned int frame_index; //相應的幀索引
unsigned int time_stamp; //以ms為單位捕獲的對應影象的時間戳
float acc_x; // acceleration of x in unit of m/s^2
float acc_y; // acceleration of y in unit of m/s^2
float acc_z; // acceleration of z in unit of m/s^2
float q[4]; // quaternion: [w,x,y,z]
}imu;
X、stereo_cali
描述: 攝像頭的標定引數。如果某個方向的感測器不線上，則所有值為0.
typedef struct _stereo_cali
{
float cu; // 焦點中心的x位置，以畫素為單位
float cv; // 焦點中心的y位置，以畫素為單位
float focal; // 焦距以畫素為單位
float baseline; // 以米為單位的立體相機基線
_stereo_cali() { }
_stereo_cali(float _cu, float _cv, float _focal, float _baseline)
{
cu = _cu, cv = _cv;
focal = _focal, baseline = _baseline;
}
}stereo_cali;
XI、exposure_param
描述: 攝像頭的曝光引數。當m_expo_time = m_expected_brightness=0時，變成預設的自動曝光控制
typedef struct _exposure_param
{
float m_step; // 自動曝光控制（AEC）的調整步驟。 預設值為10。
float m_exposure_time;// 持續曝光時間以微秒為單位。 範圍是0.1~20。 預設值為7.25。
unsigned int m_expected_brightness; // AEC的恆定預期亮度。 範圍是50~200。 預設值為85。
unsigned int m_is_auto_exposure; // 1：自動曝光; 0：持續曝光
int m_camera_pair_index; // index of Guidance Sensor
_exposure_param(){
m_step = 10;
m_exposure_time = 7.68;
m_expected_brightness = 85;
m_is_auto_exposure = 1;
m_camera_pair_index = 1;
}
}exposure_param;
XII、motion
描述: 定義全域性位置資料結構。位置單位為m，速度單位為m/s.
typedef struct _motion
{
unsigned int frame_index;
unsigned int time_stamp;
int corresponding_imu_index;
float q0;
float q1;
float q2;
float q3;
int attitude_status; // 0:invalid; 1:valid
float position_in_global_x; // position in global frame: x
float position_in_global_y; // position in global frame: y
float position_in_global_z; // position in global frame: z
int position_status; // lower 3 bits are confidence. 0:invalid; 1:valid
float velocity_in_global_x; // velocity in global frame: x
float velocity_in_global_y; // velocity in global frame: y
float velocity_in_global_z; // velocity in global frame: z
int velocity_status; // lower 3 bits are confidence. 0:invalid; 1:valid
float reserve_float[8];
int reserve_int[4];
float uncertainty_location[3];// uncertainty of position
float uncertainty_velocity[3];// uncertainty of velocity
} motion;
2.4.1 概述
對USB介面，Guidance API提供了配置和控制Guidance的C介面。下面是該API提供的關鍵方法的概覽。
當使用UART傳輸時請參考第2.1.2節的協議，以及uart_example示例程式碼。
I、初始化
reset_config
init_transfer
II、訂閱資料
select_imu
select_ultrasonic
select_velocity
select_obstacle_distance
set_image_frequecy
select_depth_image
select_disparity_image
select_greyscale_image
select_motion
III、設定回撥函式和曝光
set_sdk_event_handler
set_exposure_param
IV、獲取資料
get_online_status
get_stereo_cali
get_device_type
get_image_size
V、傳輸控制
start_transfer
stop_transfer
release_transfer
wait_for_board_ready
2.4.2 方法
I、user_callback
描述: 回撥函式的原型。 開發者的回撥函式必須按照該原型編寫。為了達到最佳效能，建議在回撥函式中不執行任何耗時的處理，只複製資料。否則，傳輸頻率可能會有所降低。
引數: event_type使用它來識別資料型別:影象，IMU，超聲波，速度或障礙物距離;data_len輸入資料的長度; data從Guidance輸入的資料。
返回: 錯誤碼。如果發生錯誤為非零。
typedef int (*user_call_back)( int event_type, int data_len, char *data );
II、reset_config
描述: 清除訂閱的配置，如果你想訂閱跟上次不同的資料。
引數: 空
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int reset_config ( void );
III、init_transfer
描述: 初始化Guidance，建立資料傳輸執行緒。
引數: 空
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int init_transfer ( void );
IV、select_imu
描述: 訂閱IMU資料。在標準模式下，必須連線DJI N1飛控才能輸出IMU資料。在自定義模式下則不需要連線飛控就可以輸出。
引數: 空
返回: 空
SDK_API void select_imu ( void );
V、select_ultrasonic
描述: 訂閱超聲波資料。
引數: 空
返回: 空
SDK_API void select_ultrasonic ( void );
VI、select_velocity
描述: 訂閱速度資料。注意該速度是體座標系下的速度。
引數: 空
返回: 空
SDK_API void select_velocity ( void );
VII、select_obstacle_distance
描述: 訂閱障礙物距離資料。
引數: 空
返回: 空
SDK_API void select_obstacle_distance ( void );
VIII、set_image_frequecy
描述: 設定影象傳輸的頻率。 注意: 由於USB的頻寬限制，如果訂閱太多的影象（灰度影象或深度影象），應設定較小的頻率，否則在SDK不能保證影象傳輸的連續性。
引數: frequency 影象傳輸的頻率。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int set_image_frequecy ( e_image_data_frequecy frequecy );
IX、select_depth_image
描述: 訂閱深度影象資料。
引數: camera_pair_index 選定雙目相機對的索引。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int select_depth_image ( e_vbus_index camera_pair_index );
示例：
#include "DJI_guidance.h"
#include "DJI_utility.h"
#include "opencv2/opencv.hpp"
#include <stdio.h>
#include <string>
e_vbus_index sensor_id = e_vbus1;
Mat g_depth;
int my_callback(int data_type, int data_len, char *content)
{
g_lock.enter();
if (e_image == data_type && NULL != content)
{
image_data* data = (image_data* )content;
if ( data->m_depth_image[sensor_id] ){
g_depth = Mat::zeros(HEIGHT,WIDTH,CV_16SC1);
memcpy( g_depth.data, data->m_depth_image[sensor_id], IMAGE_SIZE * 2 );
}
}
g_lock.leave();
g_event.set_event();
return 0;
}
int main(int argc, const char** argv)
{
reset_config(); // clear all data subscription
int err_code = init_transfer(); //wait for board ready and init transfer thread
err_code = select_depth_image( sensor_id );
err_code = set_sdk_event_handler( my_callback );
err_code = start_transfer();
while(1)
{
g_event.wait_event();
if(!g_depth.empty()){
Mat depth8(HEIGHT,WIDTH,CV_8UC1);
g_depth.convertTo(depth8, CV_8UC1);
imshow(string("depth_")+char('0'+sensor_id), depth8);
printf("Depth at point (%d,%d) is %f meters!\n", HEIGHT/2, WIDTH/2, float(g_depth.at<short>( HEIGHT/2,WIDTH/2))/128);
}
}
err_code = stop_transfer();
//make sure the ack packet from GUIDANCE is received
sleep( 1000000 );
err_code = release_transfer();
}
X、select_disparity_image
描述: 訂閱視差影象資料。視差影象可以用filterSpeckles等函式進行濾波處理。
引數: camera_pair_index 選定雙目相機對的索引。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int select_disparity_image ( e_vbus_index camera_pair_index );
示例：
#include "DJI_guidance.h"
#include "DJI_utility.h"
#include "opencv2/opencv.hpp"
#include <stdio.h>
#include <string>
e_vbus_index sensor_id = e_vbus1;
Mat g_disparity;
int my_callback(int data_type, int data_len, char *content)
{
g_lock.enter();
if (e_image == data_type && NULL != content)
{
image_data* data = (image_data* )content;
if ( data->m_disparity_image[sensor_id] ){
g_disparity = Mat::zeros(HEIGHT,WIDTH,CV_16SC1);
memcpy( g_disparity.data, data->m_disparity_image[sensor_id], IMAGE_SIZE * 2 );
}
}
g_lock.leave();
g_event.set_event();
return 0;
}
int main(int argc, const char** argv)
{
reset_config(); // clear all data subscription
int err_code = init_transfer(); //wait for board ready and init transfer thread
err_code = select_disparity_image( sensor_id );
err_code = set_sdk_event_handler( my_callback );
err_code = start_transfer();
while(1)
{
g_event.wait_event();
if(!g_disparity.empty()){
Mat disp8(HEIGHT,WIDTH,CV_8UC1);
g_disparity.convertTo(disp8, CV_8UC1);
imshow(string("disparity_")+char('0'+sensor_id), disp8);
printf("Disparity at point (%d,%d) is %f pixels!\n", HEIGHT/2, WIDTH/2, float(g_disparity.at<short>( HEIGHT/2,WIDTH/2))/16);
}
}
err_code = stop_transfer();
//make sure the ack packet from GUIDANCE is received
sleep( 1000000 );
err_code = release_transfer();
}
XI、select_greyscale_image
描述: 訂閱糾正灰度影象資料。
引數: camera_pair_index 選擇的攝像機對索引; is_left是否選擇左邊的影象:為true時選擇左圖，為false時選擇右圖。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int select_greyscale_image ( e_vbus_index camera_pair_index, bool is_left );
XII、select_motion
描述: 訂閱全域性運動資訊，即全域性座標系下Guidance的速度和位置。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API void select_motion( void );
XIII、set_sdk_event_handler
描述: 設定回撥函式指標。當有資料從Guidance傳過來時，回撥函式將被傳輸執行緒呼叫。
引數: handler 回撥函式指標。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int set_sdk_event_handler ( user_call_back handler );
XIV、start_transfer
描述: 通知Guidance開始傳輸資料。
引數: 空。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int start_transfer ( void );
XV、stop_transfer
描述: 通知Guidance停止資料傳輸。
引數: 空。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int stop_transfer ( void );
XVI、release_transfer
描述: 釋放資料傳輸執行緒。
引數: 空。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int release_transfer ( void );
XVII、get_online_status
描述: 獲取Guidance感測模組的線上狀態。
引數: online_status[CAMERA_PAIR_NUM] Guidance感測模組的線上狀態的陣列。
返回: 錯誤碼。如果發生錯誤則非零。
XVIII、get_device_type
描述: 獲取裝置型別。目前只支援Guidance一種裝置。
引數: device_type 裝置型別。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int get_device_type(e_device_type* device_type);
XIX、get_image_size
描述: 獲取影象大小。
引數: width 影象寬度。
引數: height 影象高度。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int get_image_size(int* width, int* height);
XX、wait_for_board_ready
描述: 等待Guidance處理模組的準備訊號。該函式最多會等待20秒，如果20秒內沒有收到準備好訊號，則返回一個超時錯誤。開發者一般不需要使用這個函式，因為它已經在init_transfer中被呼叫。
引數: 空。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int wait_for_board_ready();
XXI、set_exposure_param
描述: 設定曝光模式及引數。
引數: param 曝光引數結構體的指標。
返回: 錯誤碼。如果發生錯誤則非零。
SDK_API int set_exposure_param( exposure_param *param );
3、Guidance SDK開發者指南
Guidance SDK軟體包在GitHub上更新和維護。
：完整包。包括標頭檔案、所有平臺的庫檔案、所有文件。
：ROS包。包括標頭檔案、Ubuntu及Odroid XU3的庫檔案。
3.2 環境配置
I、安裝Guidance Assistant軟體
首先，在Windows平臺下安裝Guidance Assistant軟體。軟體在安裝過程中會自動安裝Guidance所需的USB驅動，在軟體安裝引導結束後需重啟系統使之生效。系統重新啟動後，將Guidance通過USB連至電腦並上電，進入計算機管理-裝置管理器中檢視，如果在裝置列表中出現“DJI, Inc. - Guidance”，意味著軟體安裝成功。
II、安裝UART驅動
如果要通過UART使用Guidance SDK，需要安裝USB轉RS232的驅動。使用過程中請注意，Guidance SDK中examples預設讀取的串列埠號為COM5。如果您的計算機上的串列埠號與之不同，請修改程式碼中的設定或更改裝置串列埠號。
III、通過Guidance Assistant軟體啟用並訂閱資料
假設使用者已經在Windows上正確安裝了Guidance Assistant軟體。
A、首先，將Guidance連線至電腦並上電啟動；接著等待Guidance上的綠燈開始閃爍後，開啟Guidance Assistant軟體，可以看到軟體檢視頁面的左下角綠燈亮起，說明連線正常；此時將工作模式設定為自定義模式。
B、然後轉到“自定義”頁面，在“介面引數”選項卡中根據需要啟用USB與UART，並通過勾選相應的選項來訂閱影象資料及影象輸出頻率；影象資料及頻率設定也可通過Guidance SDK中相應的API進行設定。
C、關閉Guidance Assistant軟體並重啟Guidance使配置生效。
IV、推薦使用Visual Studio
Guidance SDK中提供了Demo與examples供參考使用,其中包含了Visual Studio 2010的完整配置檔案與Visual studio 2013的部分配置檔案。分別是Windows7系統下測試通過的32位與64位、debug與release相關的opencv與SDK配置檔案，形如use_Guidance_*.prop,use_opencv_*.prop，使用者可以根據需要將它們複製並新增到自己的工程中，省去配置的麻煩。
V、安裝OpenCV
Guidance SDK分別在Opencv2.4.8、OpenCV2.4.9及OpenCV2.4.11上進行了測試，Demo及examples中的例程預設使用的是OpenCV2.4.11版本。使用者可以從OpenCV官方網站 上下載合適版本的OpenCV並安裝到電腦上。使用時請注意，在Demo及examples的配置檔案中，由於使用了 OPENCVROOT 的環境變數，因此使用者在配置OpenCV環境的過程中需要新建一個名為OPENCVROOT 的系統環境變數，其值為OpenCV的安裝目錄。
假設使用者已經成功在電腦上安裝了OpenCV2.4.11
A、安裝目錄為D:/OPENCV/opencv2411/build[sources]，如下圖所示，進入高階系統設定-環境變數-系統變數，新建一個變數，變數名為OPENCVROOT，值為 D:\OPENCV\opencv2411\
B、接著在系統變數的PATH變數尾部新增OpenCV的庫目錄，注意不同目錄間用分號隔開:
D:/OPENCV/opencv2411/build/x64/vc10/bin; D:/OPENCV/opencv2411/build/x86/vc10/bin;
C、如果使用者使用Visual Studio作為開發環境，接下來就只需將相應的 use_Guidance_*.prop 與 use_opencv_*.prop 配置檔案新增到工程中去即可；或者也可直接複製例程，在例程的基礎上進行開發。
VI、正確放置DJI_guidance.dll
務必記得將DJI_guidance.dll拷貝至exe所在的目錄，否則會顯示無法找到DJI_guidance.dll的錯誤。
I、安裝libusb驅動
從下載並解壓libusb-1.0.9.tar.bz2，並按照指導正確安裝libusb驅動；不推薦通過apt-get install 安裝libusb驅動；
例如: 解壓libusb-1.0.9.tar.bz2並利用cd命令跳轉到解壓目錄下；接著執行以下指令:
>> ./configure
>> make
>> make install
II、安裝UART驅動
Linux預設包含了UART驅動，不需要另外安裝。
III、通過Guidance Assistant軟體啟用並訂閱資料
<