feat(examples): add supervision-service web app with FastAPI and Vue - #2392
Closed
CWJ-CCode wants to merge 3 commits into
Closed
feat(examples): add supervision-service web app with FastAPI and Vue#2392CWJ-CCode wants to merge 3 commits into
CWJ-CCode wants to merge 3 commits into
Conversation
Add a full-stack example for video tracking and speed estimation, including async job processing, SQLite history, and a Vue 3 dashboard. Co-authored-by: Cursor <cursoragent@cursor.com>
|
|
Member
^^ Please, pay attention to this; we can land anything without SLA... |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new end-to-end example application under examples/supervision-service that combines a FastAPI backend with a Vue 3 (Vite) frontend to upload videos, run tracking / speed-estimation workflows asynchronously, and browse persisted processing history (SQLite). It also updates the Python lockfile and adds additional documentation/scripts alongside the example.
Changes:
- Add
examples/supervision-service: FastAPI API (background jobs + SQLite records) and a Vue 3 web UI for upload/processing/history. - Add backend processing utilities for tracking, speed estimation, and browser-playable (H.264) transcoding.
- Update dependencies (notably
pydeprecate) and add supplemental docs/scripts.
Reviewed changes
Copilot reviewed 69 out of 75 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| uv.lock | Updates locked dependencies (e.g., pydeprecate) and wheel metadata. |
| HIGHWAY_VISION_DEV_GUIDE.md | Adds a large highway-vision development guide document. |
| examples/README.md | Updates the examples index to reference the new example. |
| .gitignore | Adds ignore rules for video/model artefacts. |
| examples/speed_estimation/calibrate_source.py | Adds an interactive tool to pick calibration SOURCE points from a video. |
| examples/supervision-service/README.md | Documents how to run the FastAPI + Vue example in dev/prod modes. |
| examples/supervision-service/pyproject.toml | Defines the example backend as an installable Python project (hatchling). |
| examples/supervision-service/.gitignore | Ignores runtime artefacts for the example (uploads/outputs/models/db, etc.). |
| examples/supervision-service/app/init.py | Declares the backend package/module. |
| examples/supervision-service/app/config.py | Centralizes example app paths, defaults, and creates required directories. |
| examples/supervision-service/app/main.py | FastAPI app wiring: routers, CORS, DB init, and optional static webapp mounting. |
| examples/supervision-service/app/routers/init.py | Router package marker. |
| examples/supervision-service/app/routers/health.py | Adds /health endpoint. |
| examples/supervision-service/app/routers/videos.py | Adds async tracking job submission endpoint. |
| examples/supervision-service/app/routers/speed.py | Adds async speed-estimation job submission with calibration payload parsing. |
| examples/supervision-service/app/routers/records.py | Adds record listing + file download endpoints for uploads and job results. |
| examples/supervision-service/app/schemas/init.py | Exposes common schemas for the example API. |
| examples/supervision-service/app/schemas/common.py | Defines health/info response models. |
| examples/supervision-service/app/schemas/records.py | Defines upload/job record response models and list payloads. |
| examples/supervision-service/app/db/init.py | DB package marker. |
| examples/supervision-service/app/db/database.py | SQLite init + simple migrations and connection helper. |
| examples/supervision-service/app/db/repository.py | DB repository layer for uploads/jobs and progress updates. |
| examples/supervision-service/app/services/init.py | Exposes selected service functions. |
| examples/supervision-service/app/services/upload_service.py | Persists uploads to disk and stores metadata in SQLite. |
| examples/supervision-service/app/services/video_processor.py | Implements YOLO + ByteTrack tracking pipeline and output path helper. |
| examples/supervision-service/app/services/speed_processor.py | Implements calibration-based speed estimation and output path helper. |
| examples/supervision-service/app/services/job_runner.py | Runs background jobs and updates SQLite progress/status. |
| examples/supervision-service/app/services/video_encoding.py | Transcodes outputs to browser-playable H.264 using ffmpeg. |
| examples/supervision-service/webapp/package.json | Adds Vue/Vite frontend project config, scripts, and dependencies. |
| examples/supervision-service/webapp/README.md | Contains default scaffold README content for the webapp. |
| examples/supervision-service/webapp/index.html | Defines the webapp HTML shell and fonts. |
| examples/supervision-service/webapp/vite.config.ts | Configures Vue plugin and dev proxies to the FastAPI backend. |
| examples/supervision-service/webapp/tsconfig.json | TS project references for app/node configs. |
| examples/supervision-service/webapp/tsconfig.app.json | TS config for the browser app (paths, stricter indexed access). |
| examples/supervision-service/webapp/tsconfig.node.json | TS config for node-run configs (vite/eslint/etc). |
| examples/supervision-service/webapp/env.d.ts | Vite client typings reference. |
| examples/supervision-service/webapp/eslint.config.ts | ESLint flat config for Vue + TS + oxlint + prettier. |
| examples/supervision-service/webapp/.prettierrc.json | Prettier configuration (single quotes, no semicolons, width 100). |
| examples/supervision-service/webapp/.oxlintrc.json | Oxlint configuration. |
| examples/supervision-service/webapp/.editorconfig | EditorConfig rules for consistent formatting. |
| examples/supervision-service/webapp/.gitattributes | Sets text normalization and LF endings. |
| examples/supervision-service/webapp/.gitignore | Ignores typical frontend artefacts (node_modules/dist/cache/etc). |
| examples/supervision-service/webapp/src/main.ts | Vue app bootstrap + router mounting. |
| examples/supervision-service/webapp/src/App.vue | Root component rendering router view. |
| examples/supervision-service/webapp/src/router/index.ts | Defines SPA routes (dashboard/track/speed/history). |
| examples/supervision-service/webapp/src/layouts/AppLayout.vue | App shell layout with sidebar navigation and API status badge. |
| examples/supervision-service/webapp/src/views/DashboardView.vue | Dashboard landing page with links to modules. |
| examples/supervision-service/webapp/src/views/TrackView.vue | Track workflow UI: upload video, run job, show progress/result. |
| examples/supervision-service/webapp/src/views/SpeedView.vue | Speed workflow UI: capture first frame, calibrate, run job, show result. |
| examples/supervision-service/webapp/src/views/HistoryView.vue | Records UI: lists uploads/jobs and supports preview/download. |
| examples/supervision-service/webapp/src/api/video.ts | Frontend API client for health check and tracking job submission/polling. |
| examples/supervision-service/webapp/src/api/speed.ts | Frontend API client for speed-estimation job submission/polling. |
| examples/supervision-service/webapp/src/api/jobs.ts | Job polling utilities and job record fetcher. |
| examples/supervision-service/webapp/src/api/records.ts | Record-listing and file URL helpers for uploads/jobs. |
| examples/supervision-service/webapp/src/composables/useApiHealth.ts | Polling composable to reflect backend online/offline status. |
| examples/supervision-service/webapp/src/composables/useVideoFile.ts | Upload/preview composable for selected video files. |
| examples/supervision-service/webapp/src/components/ApiStatusBadge.vue | Small UI component for API status display. |
| examples/supervision-service/webapp/src/components/VideoDropzone.vue | Drag/drop + file picker component for video selection. |
| examples/supervision-service/webapp/src/components/ProcessingState.vue | UI component for progress bar + frame counters. |
| examples/supervision-service/webapp/src/components/ResultPanel.vue | UI component to preview/download processed video output. |
| examples/supervision-service/webapp/src/components/CalibrationCanvas.vue | Canvas-based calibration point selection/visualization. |
| examples/supervision-service/webapp/src/components/WelcomeItem.vue | Scaffold component used by default Vue template. |
| examples/supervision-service/webapp/src/components/TheWelcome.vue | Default Vue scaffold content (not used by the new layout flow). |
| examples/supervision-service/webapp/src/components/HelloWorld.vue | Default Vue scaffold component. |
| examples/supervision-service/webapp/src/components/icons/IconDocumentation.vue | Icon asset component. |
| examples/supervision-service/webapp/src/components/icons/IconTooling.vue | Icon asset component (includes upstream license note). |
| examples/supervision-service/webapp/src/components/icons/IconEcosystem.vue | Icon asset component. |
| examples/supervision-service/webapp/src/components/icons/IconCommunity.vue | Icon asset component. |
| examples/supervision-service/webapp/src/components/icons/IconSupport.vue | Icon asset component. |
| examples/supervision-service/webapp/src/assets/global.css | App-wide styling and CSS variables for the UI theme. |
| examples/supervision-service/webapp/src/assets/base.css | Vue scaffold base stylesheet. |
| examples/supervision-service/webapp/src/assets/main.css | Vue scaffold main stylesheet. |
| examples/supervision-service/webapp/src/assets/logo.svg | Vue logo asset. |
| - [speed estimation](./speed_estimation) by [@SkalskiP](https://github.com/SkalskiP) | ||
| - [time in zone](./time_in_zone) by [@SkalskiP](https://github.com/SkalskiP) | ||
| - [heatmap and track](./heatmap_and_track/) by [@HinePo](https://github.com/HinePo) | ||
| - [App](./App) — FastAPI video analysis API |
Comment on lines
+12
to
+14
| - **上游仓库**: https://github.com/roboflow/supervision | ||
| - **Fork 仓库**: https://github.com/DavidWangW/supervision | ||
| - **官方文档**: https://supervision.roboflow.com/latest/ |
| ### 1.3 项目结构 | ||
|
|
||
| ``` | ||
| d:\MyGithubRepo\supervision\ |
Comment on lines
+25
to
+32
| content = file.file.read() | ||
| if not content: | ||
| raise ValueError("Uploaded file is empty.") | ||
|
|
||
| suffix = Path(file.filename).suffix or ".mp4" | ||
| stored_filename = f"{uuid4().hex}{suffix}" | ||
| upload_path = UPLOAD_DIR / stored_filename | ||
| upload_path.write_bytes(content) |
| iou_threshold=iou_threshold, | ||
| on_progress=_make_progress_callback(job_id), | ||
| ) | ||
| update_job_progress(job_id, progress=99, current_frame=0, total_frames=0) |
| iou_threshold=iou_threshold, | ||
| on_progress=_make_progress_callback(job_id), | ||
| ) | ||
| update_job_progress(job_id, progress=99, current_frame=0, total_frames=0) |
Comment on lines
+23
to
+29
| model = YOLO(str(weights_path)) | ||
| tracker = sv.ByteTrack() | ||
| box_annotator = sv.BoxAnnotator() | ||
| label_annotator = sv.LabelAnnotator() | ||
|
|
||
| video_info = sv.VideoInfo.from_video_path(str(source_video_path)) | ||
| frame_generator = sv.get_video_frames_generator(str(source_video_path)) |
Comment on lines
+48
to
+49
| width = max(target_width, 1.0) | ||
| height = max(target_height, 1.0) |
Comment on lines
+26
to
+43
| subprocess.run( | ||
| [ | ||
| ffmpeg, | ||
| "-y", | ||
| "-i", | ||
| str(video_path), | ||
| "-c:v", | ||
| "libx264", | ||
| "-pix_fmt", | ||
| "yuv420p", | ||
| "-movflags", | ||
| "+faststart", | ||
| "-an", | ||
| str(temp_path), | ||
| ], | ||
| check=True, | ||
| capture_output=True, | ||
| ) |
Comment on lines
+40
to
+49
| video.preload = 'metadata' | ||
| video.src = url | ||
| video.muted = true | ||
| video.playsInline = true | ||
|
|
||
| video.onloadeddata = () => { | ||
| videoWidth.value = video.videoWidth | ||
| videoHeight.value = video.videoHeight | ||
| video.currentTime = 0 | ||
| } |
Collaborator
|
Thanks for putting this together and for the amount of work behind it. After reviewing the PR, I don't think we should merge it into Supervision. The examples directory is meant for focused, self-contained examples showing how to solve a specific computer vision problem with Supervision. This PR introduces a separate application stack: FastAPI, SQLite persistence, background jobs, file storage, video transcoding, a Vue frontend, a Node toolchain, and deployment setup. Merging it would make the Supervision maintainers responsible for the long-term maintenance of a full web application, including its frontend, backend, upload handling, persistence, dependencies, and deployment. This falls outside the scope we want the repository to own. The core tracking and speed-estimation workflows are also already covered by smaller examples in the repository. I think this project belongs in a standalone repository built on top of Supervision, where it could evolve independently without expanding the maintenance surface of the library. For this reason, I'm going to close the PR rather than ask for another revision. Thanks again for sharing the project and contributing your work. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
pm run dev\ in examples/supervision-service/webapp
pm run build\ and serve via FastAPI static files
Made with Cursor