From aca2ae7fa36737c2c84eaa83efc78c8d27577f56 Mon Sep 17 00:00:00 2001 From: "Chanwut (Mick) Kittivorawong" <30903997+chanwutk@users.noreply.github.com> Date: Sat, 27 Jul 2024 23:21:49 -0700 Subject: [PATCH] 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 --- .github/workflows/gh-pages.yml | 80 ++++++++++++++----- .gitignore | 2 + README.md | 7 +- .../stages/detection_3d/__init__.py | 40 +++++----- .../detection_estimation.py | 9 ++- .../detection_estimation/segment_mapping.py | 16 ++-- spatialyze/video_processor/stream/__init__.py | 0 .../stream/from_detection_2d_and_road.py | 7 +- .../video_processor/utils/depths_to_3d.py | 9 +-- 9 files changed, 108 insertions(+), 62 deletions(-) create mode 100644 spatialyze/video_processor/stream/__init__.py diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 5b334d7..f8f6965 100644 --- 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 index e109f4d..561acb7 100644 --- 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 \ No newline at end of file diff --git a/README.md b/README.md index 34b7a1e..69ddaf1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
-

+

A Geospatial Video Analytic System with Spatial-Aware Optimizations

@@ -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 - + diff --git a/spatialyze/video_processor/stages/detection_3d/__init__.py b/spatialyze/video_processor/stages/detection_3d/__init__.py index 0c356e3..0cea2d8 100644 --- 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 index c58449d..3c45446 100644 --- 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 index bb965a8..5255d79 100644 --- 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 new file mode 100644 index 0000000..e69de29 diff --git a/spatialyze/video_processor/stream/from_detection_2d_and_road.py b/spatialyze/video_processor/stream/from_detection_2d_and_road.py index 39371e3..8afb154 100644 --- 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 index 7608357..919a1e5 100644 --- 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