Add Documentations (#60)

* add documentation * install dependencies * update docs * style: [CI] format * update data assets * images in readme * update readme * do not import * dont install all dependencies * add references * just api * remove ignored modules * . * dont remove * . * clean up --------- Co-authored-by: Github Actions Bot <spatialyze-actions-bot@users.noreply.github.com>
apperception-db · Jul 28, 2024 · aca2ae7 · aca2ae7
1 parent 889a085
commit aca2ae7
Show file tree

Hide file tree

Showing 9 changed files with 108 additions and 62 deletions.
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -1,31 +1,69 @@
-name: Publish GitHub Pages
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
 
 on:
   push:
-    branches: [ main ]
+    branches: ["main", "doc"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
 
 jobs:
-  publish:
-    name: Publish GitHub Pages
+  # Build job
+  build:
     runs-on: ubuntu-latest
-
     steps:
-    - name: Set up Git repository
-      uses: actions/checkout@v3
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: API Doc
+        run: |
+          pip install pydoctor
+          pydoctor --project-name=Spatialyze \
+                   --project-version=0.1.0 \
+                   --project-url=https://apperception-db.github.io/spatialyze \
+                   --html-viewsource-base=https://github.com/apperception-db/spatialyze/tree/main \
+                   --make-html \
+                   --html-output=_site \
+                   --project-base-dir="." \
+                   --docformat=epytext \
+                   --intersphinx=https://docs.python.org/3/objects.inv \
+                   --privacy="HIDDEN:spatialyze.video_processor.modules" \
+                   --privacy="HIDDEN:spatialyze.video_processor.stages" \
+                   ./spatialyze
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v3
 
-    - name: Setup GitHub Pages Folder
-      run: |
-        rm -rf ./build
-        mkdir ./build
-        cp ./README.md ./build/
-        mkdir -p ./build/data/assets
-        cp ./data/assets/* ./build/data/assets/
-
-    # - name: Publish Website
-    #   uses: JamesIves/github-pages-deploy-action@v4
-    #   with:
-    #     folder: 'build'
-    #     single-commit: true
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -35,3 +35,5 @@ evaluation/eva/evadb_data
 evaluation/eva/eva-times.txt
 evaluation/nuscenes/devkit/*.txt
 data/skyquery/car-model/yolov3.best
+
+_site
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <br/>
-<p align="center"><img width=60% src="./data/assets/spatialyze.png"></p>
+<p align="center"><img width="60%" src="./data/assets/spatialyze.png" /></p>
 
 <h2 align="center">A Geospatial Video Analytic System with Spatial-Aware Optimizations</h2>
 <p align="center">
@@ -113,6 +113,9 @@ To run PostGIS every system restart
 docker update --restart unless-stopped spatialyze-gsstore
 ```
 
+## API References
+Please visit https://apperception-db.github.io/spatialyze for API References.
+
 ### Try the demo (WIP 🚧)
 In spatialyze repo:
 ```sh
@@ -143,4 +146,4 @@ This paper will be presented at [VLDB](https://vldb.org/2024/).
 ```
 
 ## Codecov
-<img width=100% src="https://codecov.io/gh/apperception-db/spatialyze/graphs/icicle.svg?token=A4FHKVI1Ua">
+<img width="100%" src="https://codecov.io/gh/apperception-db/spatialyze/graphs/icicle.svg?token=A4FHKVI1Ua" />
diff --git a/spatialyze/video_processor/stages/detection_3d/__init__.py b/spatialyze/video_processor/stages/detection_3d/__init__.py
@@ -9,36 +9,36 @@
 class Metadatum(NamedTuple):
     """
     detections:
-    -----------
+    ===========
     A torch.Tensor with size N x 18, representing N objects detected from a single frame.
     Each including 3d information.
 
     Each column represents:
-    - bbox_left
-    - bbox_top
-    - bbox_w
-    - bbox_h
-    - conf
-    - class
+        - bbox_left
+        - bbox_top
+        - bbox_w
+        - bbox_h
+        - conf
+        - class
 
-    - bbox3d_left_x
-    - bbox3d_left_y
-    - bbox3d_left_z
+        - bbox3d_left_x
+        - bbox3d_left_y
+        - bbox3d_left_z
 
-    - bbox3d_right_x
-    - bbox3d_right_y
-    - bbox3d_right_z
+        - bbox3d_right_x
+        - bbox3d_right_y
+        - bbox3d_right_z
 
-    - bbox3d_from_camera_left_x
-    - bbox3d_from_camera_left_y
-    - bbox3d_from_camera_left_z
+        - bbox3d_from_camera_left_x
+        - bbox3d_from_camera_left_y
+        - bbox3d_from_camera_left_z
 
-    - bbox3d_from_camera_right_x
-    - bbox3d_from_camera_right_y
-    - bbox3d_from_camera_right_z
+        - bbox3d_from_camera_right_x
+        - bbox3d_from_camera_right_y
+        - bbox3d_from_camera_right_z
 
     class_map:
-    ----------
+    ==========
     A mapping from an object class number (in detections[:, 5]) to a class string name
     """
 

diff --git a/spatialyze/video_processor/stages/detection_estimation/detection_estimation.py b/spatialyze/video_processor/stages/detection_estimation/detection_estimation.py
@@ -1,12 +1,15 @@
-"""Detection Estimation Module
+"""
+Detection Estimation Module
+===========================
 
 This module is responsible for estimating the object detection throughout the whole video.
 The sampling algorithm skips frames based on the current frame geo information.
 We estimate objects' metadata only based on the sampled frames.
 
 Usage example:
-    from detection_estimation import detection_estimation
-    detection_estimation(sorted_ego_config, video, start_frame_num, view_distance=50, img_base_dir='')
+==============
+from detection_estimation import detection_estimation
+detection_estimation(sorted_ego_config, video, start_frame_num, view_distance=50, img_base_dir='')
 
 TODO:
     1. incoporate yolo detection, either merge this module to the tracking pipeline

diff --git a/spatialyze/video_processor/stages/detection_estimation/segment_mapping.py b/spatialyze/video_processor/stages/detection_estimation/segment_mapping.py
@@ -1,13 +1,15 @@
-""" Goal to map the road segment to the frame segment
-    Now only get the segment of type lane and intersection
-    except for the segment that contains the ego camera
+"""
+Goal to map the road segment to the frame segment
+Now only get the segment of type lane and intersection
+except for the segment that contains the ego camera
 
 Usage example:
-    from optimization_playground.segment_mapping import map_imgsegment_roadsegment
-    from spatialyze.utils import fetch_camera_config
+==============
+from optimization_playground.segment_mapping import map_imgsegment_roadsegment
+from spatialyze.utils import fetch_camera_config
 
-    test_config = fetch_camera_config(test_img, database)
-    mapping = map_imgsegment_roadsegment(test_config)
+test_config = fetch_camera_config(test_img, database)
+mapping = map_imgsegment_roadsegment(test_config)
 """
 
 import array

diff --git a/spatialyze/video_processor/stream/__init__.py b/spatialyze/video_processor/stream/__init__.py
diff --git a/spatialyze/video_processor/stream/from_detection_2d_and_road.py b/spatialyze/video_processor/stream/from_detection_2d_and_road.py
@@ -108,11 +108,10 @@ def _stream(self, video: Video):
 def rotate(vectors: npt.NDArray, rotation: Quaternion) -> npt.NDArray:
     """Rotate 3D Vector by rotation quaternion.
     Params:
-        vectors: (3 x N) 3-vectors each specified as any ordered
-            sequence of 3 real numbers corresponding to x, y, and z values.
-        rotation: A rotation quaternion.
+    vectors: (3 x N) 3-vectors each specified as any ordered sequence of 3 real numbers corresponding to x, y, and z values.
+    rotation: A rotation quaternion.
 
     Returns:
-        The rotated vectors (3 x N).
+    The rotated vectors (3 x N).
     """
     return rotation.unit.rotation_matrix @ vectors
diff --git a/spatialyze/video_processor/utils/depths_to_3d.py b/spatialyze/video_processor/utils/depths_to_3d.py
@@ -27,13 +27,12 @@ def depths_to_3ds(
 ) -> npt.NDArray:
     """
     Parameters:
-        depths: (N x X x Y) depth maps
-        intrinsic: (3 x 3) camera intrinsic
-        true_depth: True if depths is the z-axis distance from the camera.
-            False if depths is the distance from the camera.
+    depths: (N x X x Y) depth maps
+    intrinsic: (3 x 3) camera intrinsic
+    true_depth: True if depths is the z-axis distance from the camera. False if depths is the distance from the camera.
 
     Returns:
-        d3 location of each pixel (N x X x Y x 3)
+    d3 location of each pixel (N x X x Y x 3)
     """
     n, lenx, leny = depths.shape