# 智動擬真標記式AR引擎 技術文件 Document
###### tags: `畢業專題`

程式庫：https://github.com/54bp6cl6/SmartAutoAR
使用教學 Tutorial：https://hackmd.io/MzwI6hvPRUKN1vdY6TrseA
技術文件 Document：https://hackmd.io/8NsHfsW2QfqYN-4aqOfTlg

撰文：鄭人豪 - 2020 / 11 / 8

## 目錄

* [ArWorkflow 類別](#ArWorkflow類別)
* [ColorCalculation 類別](#ColorCalculation類別)
* [ColorHarmonization 類別](#ColorHarmonization類別)
* [LightSourceTracker 類別](#LightSourceTracker類別)
* Marker 類別
* MarkerDetector 類別
* MarkerTrackingInfo 類別
* Scene 類別
* [InputSource 命名空間](#InputSource命名空間)
* [IInputSource 介面](#IInputSource介面)
* [ImageSource 類別](#ImageSource類別)
* [VideoSource 類別](#VideoSource類別)
* [StreamSource 類別](#StreamSource類別)
* V[irtualObject 命名空間](#VirtualObject命名空間)
* [Model 類別](#Model類別)
* Background 類別
* Base 命名空間
* Material 類別
* Mesh 類別
* Shader 類別
* Texture 類別
* Vertex 類別
* Cameras 命名空間
* ICamera 介面
* ArCamera 類別
* [Lights 命名空間](#VirtualObject.Lights命名空間)
* [ILight 介面](#ILight介面)
* [AmbientLight 類別](#AmbientLight類別)
* [PointLight 類別](#PointLight類別)
* [DirectionalLight 類別](#DirectionalLight類別)

-------------------------------------------------------
## SmartAutoAR命名空間

### ArWorkflow類別
整合各種功能，能夠快速製作AR的類別。
| 名稱 | 型別 | 說明 |
| - | - | - |
| InputSource | IInputSource | 取得輸入影像的來源 |
| MarkerPairs | Dictionary<Bitmap, Scene> | 紀錄 Marker 與虛擬場景的對應關係 |
| EnableLightTracking | bool | 是否啟用光源追蹤 |
| EnableColorHarmonizing | bool | 是否啟用色彩調和 |
| WindowAspectRatio | float | 取得輸出影像的長寬比 |
| ArWorkflow(IInputSource) | Constructor | 以指定的影像輸入物件初始化物件 |
| ClearState() | void | 清除用於優化下一幀的暫存資料，於重播影片、切換輸入來源前使用|
| TrainMarkers() | void | 使 MarkerPairs 的設定生效 |
| Show() | void | 於目前綁定的 OpenGL Context 上渲染 AR 畫面 |

### ColorCalculation類別
提供影像色彩處理功能的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| GetLabChennel(Mat) | Mat[] | 將 RGB 影像轉為 L、a、b 三個頻道(Chennel) |

### ColorHarmonization類別
透過深度學習，提供對影像做色彩調合的功能。
| 名稱 | 型別 | 說明 |
| - | - | - |
| IsDisposed | bool | 指出神經網路資源是否已經釋放 |
| FirstForward(string) | void | 使用指定路徑的圖片，預先使模型進行第一次運算，以加速未來的運算速度 |
| InputImgProcess(Mat) | Mat | 將指定的影像資料轉為適合模型的輸入 |
| MaskImgProcess(Mat) | Mat | 將虛擬物體遮罩處理為適合模型輸入的格式 |
| NetForwardProcess(Mat, Mat) | Mat | 進行模型前向傳播 |
| OutputImgProcess(Mat, int, int) | Mat | 將模型的輸出處理為影像資料 |
| Dispose | void | 釋放物件相關之記憶體 |

### LightSourceTracker類別
提供光源追蹤功能的類別。
| 名稱 | 型別 | 說明 |
| - | - | - |
| PredictLightSource(Mat, MarkerTrackingInfo) | ILight[] | 根據 MarkerTrackingInfo 中的 Marker 偵測結果，計算與真實環境類似的模擬光源 |

-------------------------------------------------------
## InputSource命名空間

### IInputSource介面
描述影像來源的統一行為與屬性。

| 名稱 | 型別 | 說明 |
| - | - | - |
| LastFrame | Bitmap | 取得的最後一張影像 |
| OutputWidth | int | 目前影像的寬度 |
| OutputHeight | int | 目前影像的高度 |
| AspectRatio | float | 目前影像的長寬比 |
| GetNextFrame() | Bitmap | 呼叫物件取得新影像 |

### ImageSource類別
實作 [IInputSource](#IInputSource介面) 介面，用於取得圖片輸入的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| ImageSource(Bitmap) | Constructor | 將指定的Bitmap作為影像輸入來源 |
| ImageSource(string) | Constructor | 將指定路徑的圖片檔案作為影像輸入來源 |

### VideoSource類別
實作 [IInputSource](#IInputSource介面) 介面，用於取得影片輸入的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| EndOfVideo | bool | 指出影片是否已撥放至結尾 |
| VideoSource(string) | Constructor | 將指定路徑的影片檔案作為影像輸入來源 |
| Replay() | void | 重新讀取影片，下一次呼叫 GetNextFrame() 時將返回第一幀影像|

### StreamSource類別
實作 [IInputSource](#IInputSource介面) 介面，用於取得鏡頭串流的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| StreamSource(int) | Constructor | 接收指定鏡頭編號的串流影像作為輸入來源 |

-------------------------------------------------------
## VirtualObject命名空間

### Model類別
儲存模型的各項資料，並提供匯入、縮放、移動、旋轉、渲染等功能。

| 名稱 | 型別 | 說明 |
| - | - | - |
| Meshes | List\<Mesh\> | 儲存模型各個部位的資料 |
| ModelMatrix | Matrix4 | 模型的 Model Matrix，在渲染時描述模型額外的旋轉與位移 |
| Rotation(float, float, float) | void | 分別以 x, y, z 軸使模型旋轉 (0~360) 度 |
| Move(float, float, float) | void | 使模型沿 x, y, z 軸位移 |
| Resize(float) | void | 依倍率縮放模型大小 |
| Render(Shader) | void | 使用指定的著色器渲染模型 |
| LoadModel(string) | Model | 從指定的路徑匯入模型 |
| Dispose() | void | 釋放資源 |

-------------------------------------------------------
## VirtualObject.Lights命名空間

### ILight介面
描述虛擬光源的統一行為與屬性。

| 名稱 | 型別 | 說明 |
| - | - | - |
| SetShader(Shader, int) | void | 將光照屬性綁定至指定著色器中相對應燈光陣列的index |

### AmbientLight類別
實作 [ILight](#ILight介面) 介面，作為環境光為虛擬場景提高整體亮度的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| Color | Color4 | 描述光的顏色 |
| Main_strength | float | 描述光的強度(0~1) |
| AmbientLight(Color4, float) | Constructor | |

### PointLight類別
實作 [ILight](#ILight介面) 介面，作為點光源使虛擬物件產生光影變化的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| Color | Color4 | 描述光的顏色 |
| Position | Vector3 | 描述光源的位置 |
| Main_strength | float | 描述光的強度(0~1) |
| Specular_strength | float | 描述鏡面反射的強度(0~1) |
| PointLight(Color4, Vector3, float, float) | Constructor | |

### DirectionalLight類別
實作 [ILight](#ILight介面) 介面，作為平行光使虛擬物件產生光影變化的類別。

| 名稱 | 型別 | 說明 |
| - | - | - |
| Color | Color4 | 描述光的顏色 |
| Direction | Vector3 | 描述光相對於原點的方向 |
| Main_strength | float | 描述光的強度(0~1) |
| Specular_strength | float | 描述鏡面反射的強度(0~1) |
| PointLight(Color4, Vector3, float, float) | Constructor | 以指定的位置計算相對於原點的方向 |