(Open for checking code) New docs site for ARFlow's Unity Client

.github/workflows/website.yml

@@ -10,6 +10,7 @@ on:
       - 'python/**'
       - '.github/workflows/website.yml'
       - 'website/**'
+      - 'unity/**'
 
     # Alternative: only build for tags.
     # tags:
@@ -23,7 +24,30 @@ permissions:
   contents: read
 
 jobs:
-  build-docs:
+  build-client-docs-as-artifact:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install docfx
+        run: dotnet tool install -g docfx
+
+      - name: Run script to build the documentation
+        working-directory: ./unity/Documentation
+        run: ./scripts/build.cmd
+
+      # - name: Move docs to website directory
+      #   run: |
+      #     mkdir -p ./website/docs/client/
+      #     cp -r ./unity/Documentation/clientHTMLOutput/* ./website/docs/client/
+      # Upload the website directory as an artifact
+      - uses: actions/upload-artifact@v4
+        with:
+          name: client-docs
+          path: ./unity/Documentation/clientHTMLOutput
+
+  build-server-docs:
+    needs: build-client-docs-as-artifact
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -63,13 +87,28 @@ jobs:
           mkdir -p ./website/docs/server/
           cp -r ./python/docs/* ./website/docs/server/
 
+      # Get client docs to use as part of pages artifact
+      - uses: actions/download-artifact@v4
+        with:
+          name: client-docs
+          path: ./website/docs/client
+
+      # # cleanup client docs artifacts
+      # - name: Delete client docs artifact
+      #   run: |
+      #     github.rest.actions.deleteArtifact({
+      #       owner: context.repo.owner,
+      #       repo: context.repo.repo,
+      #       artifact_id: ${{ steps.artifact-download.outputs.artifact-id }}
+      #     });
+
       - uses: actions/upload-pages-artifact@v3
         with:
           path: ./website
 
   # Single deploy job since we're just deploying
   deploy:
-    needs: build-docs
+    needs: build-server-docs
     runs-on: ubuntu-latest
     permissions:
       pages: write

.gitignore

@@ -242,6 +242,7 @@ ExportedObj/
 .consulo/
 *.csproj
 *.unityproj
+# add .sln files to build documentation
 *.sln
 *.suo
 *.tmp

README.md

@@ -48,6 +48,13 @@ series = {HOTMOBILE '24}
                     <sub><b>Yiqin Zhao</b></sub>
                 </a>
             </td>
+            <td align="center">
+                <a href="https://github.com/legoeruro">
+                    <img src="https://avatars.githubusercontent.com/u/68761938?v=4" width="100;" alt="legoeruro"/>
+                    <br />
+                    <sub><b>Khang Luu</b></sub>
+                </a>
+            </td>
             <td align="center">
                 <a href="https://github.com/FelixNgFender">
                     <img src="https://avatars.githubusercontent.com/u/75899581?v=4" width="100;" alt="FelixNgFender"/>

unity/.gitignore

@@ -34,6 +34,7 @@ ExportedObj/
 .consulo/
 *.csproj
 *.unityproj
+# solution file is uploaded for doc building
 *.sln
 *.suo
 *.tmp

unity/Assets/Scripts/ARFlow/ARFlowClient.cs

@@ -5,12 +5,20 @@
 
 namespace ARFlow
 {
+    /// <summary>
+    /// This class represent the implementation for the client, using the gRPC protocol generated by Protobuf.
+    /// The client of ARFlow allows registering to the server and sending data frames to the server.
+    /// </summary>
     public class ARFlowClient
     {
         private readonly GrpcChannel _channel;
         private readonly ARFlowService.ARFlowServiceClient _client;
         private string _sessionId;
 
+        /// <summary>
+        /// Initialize the client
+        /// </summary>
+        /// <param name="address">The address (AKA server URL) to connect to</param>
         public ARFlowClient(string address)
         {
             var handler = new YetAnotherHttpHandler() { Http2Only = true };
@@ -27,6 +35,10 @@ public ARFlowClient(string address)
             _channel.Dispose();
         }
 
+        /// <summary>
+        /// Connect to the server with a request that contain register data of about the camera.
+        /// </summary>
+        /// <param name="requestData">Register data (AKA metadata) of the camera. The typing of this is generated by Protobuf.</param>
         public void Connect(RegisterRequest requestData)
         {
             try
@@ -44,6 +56,10 @@ public void Connect(RegisterRequest requestData)
             }
         }
 
+        /// <summary>
+        /// Send a data of a frame to the server.
+        /// </summary>
+        /// <param name="frameData">Data of the frame. The typing of this is generated by Protobuf.</param>
         public void SendFrame(DataFrameRequest frameData)
         {
             frameData.Uid = _sessionId;

unity/Assets/Scripts/ARFlow/XRCpuImageExt.cs

@@ -5,20 +5,33 @@
 
 namespace ARFlow
 {
+    /// <summary>
+    /// Interface for encoding CPU image
+    /// </summary>
     internal interface IXRCpuImageEncodable
     {
         public byte[] Encode();
     }
 
+    /// <summary>
+    /// Depth image information. 
+    /// </summary>
     internal struct XRDepthImage : IXRCpuImageEncodable
     {
         private XRCpuImage _image;
 
+        /// <summary>
+        /// Get Depth image from AROcclusionManager. 
+        /// </summary>
         public XRDepthImage(AROcclusionManager occlusionManager)
         {
             occlusionManager.TryAcquireEnvironmentDepthCpuImage(out _image);
         }
 
+        /// <summary>
+        /// Encode depth image
+        /// </summary>
+        /// <returns>Depth image in bytes</returns>
         public byte[] Encode()
         {
             return _image.GetPlane(0).data.ToArray();
@@ -30,6 +43,9 @@ public void Dispose()
         }
     }
 
+    /// <summary>
+    /// Depth image information with confidence
+    /// </summary>
     internal struct XRConfidenceFilteredDepthImage : IXRCpuImageEncodable
     {
         private XRCpuImage _depthImage;
@@ -41,6 +57,11 @@ public Vector2Int Size()
             return _depthImage.dimensions;
         }
 
+        /// <summary>
+        /// Get depth and depth confidence from AROcclusionManager.
+        /// </summary>
+        /// <param name="occlusionManager"></param>
+        /// <param name="minConfidence">Min confidence for filtering</param>
         public XRConfidenceFilteredDepthImage(AROcclusionManager occlusionManager, int minConfidence = 1)
         {
             // occlusionManager.TryAcquireEnvironmentDepthCpuImage(out _depthImage);
@@ -49,6 +70,12 @@ public XRConfidenceFilteredDepthImage(AROcclusionManager occlusionManager, int m
             _minConfidence = minConfidence;
         }
 
+        /// <summary>
+        /// For each depth value, if confidence is lower than minConfidence, it will be ignored (replaced with 0s). 
+        /// The rest is encoded to bytes.
+        /// 
+        /// </summary>
+        /// <returns>Encoded bytes</returns>
         public byte[] Encode()
         {
             var depthValues = _depthImage.GetPlane(0).data.ToArray();
@@ -83,6 +110,9 @@ public void Dispose()
         }
     }
 
+    /// <summary>
+    /// Color image information
+    /// </summary>
     internal struct XRYCbCrColorImage : IXRCpuImageEncodable
     {
         private XRCpuImage _image;
@@ -91,7 +121,11 @@ internal struct XRYCbCrColorImage : IXRCpuImageEncodable
         private readonly Vector2Int _nativeSize;
         private readonly Vector2Int _sampleSize;
 
-
+        /// <summary>
+        /// Get image from ARCameraManager, and set scale to relative of sample (depth) size.
+        /// </summary>
+        /// <param name="cameraManager"></param>
+        /// <param name="sampleSize"></param>
         public XRYCbCrColorImage(ARCameraManager cameraManager, Vector2Int sampleSize)
         {
             cameraManager.TryAcquireLatestCpuImage(out _image);
@@ -101,6 +135,10 @@ public XRYCbCrColorImage(ARCameraManager cameraManager, Vector2Int sampleSize)
             _scale = _sampleSize.x / (float)_nativeSize.x;
         }
 
+        /// <summary>
+        /// Resample color image to right size and convert to bytes.
+        /// </summary>
+        /// <returns>Encoded bytes</returns>
         public byte[] Encode()
         {
             var size = _sampleSize.x * _sampleSize.y + 2 * (_sampleSize.x / 2 * _sampleSize.y / 2);

unity/Assets/Scripts/ARFlowDeviceSample.cs

@@ -8,7 +8,13 @@
 
 public class ARFlowDeviceSample : MonoBehaviour
 {
+    /// <summary>
+    /// Camera image data's manager from the device camera
+    /// </summary>
     public ARCameraManager cameraManager;
+    /// <summary>
+    /// Depth data's manager from the device camera
+    /// </summary>
     public AROcclusionManager occlusionManager;
 
     public Button connectButton;
@@ -37,7 +43,10 @@ void Start()
         // Application.targetFrameRate = 30;
     }
 
-
+    /// <summary>
+    /// Get register request data from camera and send to server.
+    /// Image and depth info is acquired once to get information for the request, and is disposed afterwards.
+    /// </summary>
     private void OnConnectButtonClick()
     {
         try
@@ -98,6 +107,10 @@ private void OnConnectButtonClick()
         }
     }
 
+    /// <summary>
+    /// On pause, pressing the button changes the _enabled flag to true  (and text display) and data starts sending in Update()
+    /// On start, pressing the button changes the _enabled flag to false and data stops sending
+    /// </summary>
     private void OnStartPauseButtonClick()
     {
         Debug.Log($"Current framerate: {Application.targetFrameRate}");
@@ -113,6 +126,10 @@ void Update()
         UploadFrame();
     }
 
+    /// <summary>
+    /// Get color image and depth information, and copy camera's transform from float to bytes. 
+    /// This data is sent over the server.
+    /// </summary>
     private void UploadFrame()
     {
         var colorImage = new XRYCbCrColorImage(cameraManager, _sampleSize);