If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Ewenwan/MVision shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Ewenwan/MVision repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Ewenwan/MVision.

What it runs against: a local clone of Ewenwan/MVision — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Ewenwan/MVision | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | Last commit ≤ 699 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Ewenwan/MVision. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Ewenwan/MVision.git
#   cd MVision
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Ewenwan/MVision and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Ewenwan/MVision(\\.git)?\\b" \\
  && ok "origin remote is Ewenwan/MVision" \\
  || miss "origin remote is not Ewenwan/MVision (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 699 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~669d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Ewenwan/MVision"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MVision is a comprehensive machine vision framework implementing SLAM (ORB-SLAM2), 3D object detection, tracking, action recognition, and autonomous driving pipelines. It integrates OpenCV, PCL, CUDA, and deep learning (YOLOv3) to enable robotic vision systems with dense tracking, multi-object tracking, optical flow, and real-time visual perception for mobile robots and self-driving applications. Monorepo organized by computer vision domain: CNN/ contains action recognition (C3D, IDT, DTPP), 3D_Object_Detection/ has tracking (multitracker.cpp, single_tracker.cpp, optical flow), supporting papers/PDFs in pdf/ folders, and MATLAB reference implementations in pf_socker/. No clear separation of concerns—each subsystem is mostly independent with its own CMakeLists.txt rather than a unified build system.

Roboticists, autonomous vehicle engineers, and computer vision researchers implementing production vision pipelines who need integrated SLAM, 3D tracking, and real-time detection without building from scattered papers—particularly those targeting embedded systems and mobile robots.

Actively developed but showing signs of age (large commit history with 4.8MB C++ code suggests >5 years of work), with well-structured examples in CNN/Action_Recognition/ and 3D_Object_Detection/ directories. No visible CI/CD setup (no .github/workflows, no recent test infrastructure mentioned) and no package.json or setup.py versioning suggest research-grade maturity rather than production-hardened. Likely stable for reference implementations but not actively maintained for modern dependency versions.

Standard open source risks apply.

Cannot determine from provided file list—no git log, PR list, or recent commits visible. The extensive organizational structure and documentation suggest core modules are feature-complete, but the presence of 'readme.md' files throughout suggests ongoing documentation efforts rather than active feature development.

git clone https://github.com/Ewenwan/MVision.git
cd MVision
# For C++ modules:
cd 3D_Object_Detection/Object_Tracking/src
cmake . && make
# For Python-based detection:
python3 -m pip install opencv-python numpy  # Infer from .py usage
# For MATLAB particle filtering:
matlab -r "run soccerboxesusage.m"

Daily commands: Inferred from structure (no single entry point visible): per-subsystem: cd 3D_Object_Detection/Object_Tracking/src && cmake . && make && ./multitracker or ./single_tracker. Python detection likely: python3 yolov3_detector.py --input video.mp4 (exact script not in file list).

• 3D_Object_Detection/Object_Tracking/src/multitracker.cpp: Core multi-object tracking using data association (Hungarian algorithm implied by MHT references), manages track lifecycle and state fusion
• 3D_Object_Detection/Object_Tracking/src/opticalFlow.cpp: Dense optical flow computation for motion estimation; feeds into tracking and action recognition pipelines
• 3D_Object_Detection/Object_Tracking/pf_socker/samplePFcode.m: Reference particle filter implementation for socket-based soccer tracking; demonstrates probabilistic filtering model used in C++ tracking
• CNN/Action_Recognition/IDT/IDT/src/DenseTrackStab.cpp: Dense trajectory extraction for action recognition; bridges optical flow output to spatio-temporal feature learning
• 3D_Object_Detection/readme.md: Documents 3D detection pipeline architecture, depth completion methods (referenced in 深度图补全.md), and fusion with SLAM

For tracking improvements: edit 3D_Object_Detection/Object_Tracking/src/multitracker.cpp (multi-object state management) or single_tracker.cpp (Kalman filter/particle filter logic). For detection tuning: modify CNN/ subsystem's model configs (C3D for temporal, YOLOv3 weights). For SLAM: extend ORB-SLAM2 reference (papers in pdf/ but no src visible). For action recognition: augment IDT/FV pipeline in CNN/Action_Recognition/IDT/. Start with readme.md files in each subsystem for context.

No package manager versioning: C++ dependencies (OpenCV, PCL, CUDA) must be pre-installed system-wide; CMakeLists.txt likely has hardcoded paths or assumes standard Ubuntu /usr/local/ layout. Mixed language build: MATLAB code in pf_socker/ will not compile in pure C++; requires separate MATLAB runtime or MCR. CUDA hard-dependency: GPU acceleration assumed; CPU-only builds untested based on visible structure. No data included: tracking/detection modules reference 'soccer' dataset (soccerboxesusage.m) but dataset not in repo. CMake per-subdirectory: each subsystem has independent CMakeLists.txt; no unified top-level build—incremental rebuilds risk inconsistency.

• Dense Optical Flow (Horn-Schunck / Lucas-Kanade) — Foundation for motion estimation in opticalFlow.cpp, used to compute frame-to-frame displacements feeding action recognition and tracking initialization
• Multi-Hypothesis Tracking (MHT) — Probabilistic framework referenced in multitracker.cpp comments; handles one-to-many and many-to-one data associations in crowded scenes
• Particle Filter (Sequential Monte Carlo) — Core inference method in pf_socker/ MATLAB reference; provides non-parametric Bayesian filtering for non-linear motion models in single_tracker.cpp
• ORB-SLAM (Oriented FAST and Rotated BRIEF) — Real-time monocular/stereo SLAM engine; provides camera localization and sparse 3D map used to ground object tracking in world coordinates
• Two-Stream CNN (Spatial-Temporal Fusion) — Architecture underlying CNN/Action_Recognition/ and C3D; fuses RGB (spatial) and optical flow (temporal) streams for action classification
• Improved Dense Trajectories (IDT) — Hand-crafted feature extractor in CNN/Action_Recognition/IDT/; predecessor to C3D, demonstrates spatio-temporal interest point detection for human action understanding
• Hungarian Algorithm (Bipartite Matching) — Implicit in multitracker data association logic; solves optimal assignment of detections to existing tracks minimizing cost (Euclidean/Mahalanobis distance)

• raulmur/ORB_SLAM2 — Canonical ORB-SLAM2 implementation referenced in MVision docs; this repo extends it with tracking and detection layers
• pjreddie/darknet — Original YOLOv3 framework; MVision uses YOLOv3 for real-time object detection feeding into 3D tracking
• PointCloudLibrary/pcl — Point Cloud Library providing 3D geometric algorithms; MVision depends on PCL for 3D object representation and alignment in tracking
• opencv/opencv — OpenCV core; MVision extensively uses optical flow, image features, and matrix ops from cv::DenseOpticalFlow and cv::KeyPoint
• facebookresearch/fvision — Facebook's dense trajectory and action recognition framework; conceptually related to MVision's CNN/Action_Recognition/ and IDT pipeline

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive README and build documentation for Object_Tracking module

The 3D_Object_Detection/Object_Tracking directory contains multiple tracking implementations (single_tracker.cpp, multitracker.cpp, particle filter code) but lacks integration documentation. The src/readme.md and pf_socker/readme.md files are placeholders. This creates a high barrier for contributors trying to understand the tracking pipeline, test different algorithms, or extend them.

• [ ] Document the CMakeLists.txt build process in 3D_Object_Detection/Object_Tracking/src/readme.md with dependency requirements and compilation steps
• [ ] Create algorithm comparison guide in 3D_Object_Detection/Object_Tracking/readme.md explaining single_tracker.cpp vs multitracker.cpp vs particle filter approaches with use cases
• [ ] Add usage examples for pf_socker MATLAB code in 3D_Object_Detection/Object_Tracking/pf_socker/readme.md with sample input/output and integration with C++ modules
• [ ] Document the optical flow implementation and how it integrates with tracking in src/opticalFlow.cpp

Create unified build and test infrastructure for CNN/Action_Recognition subdirectories

The CNN/Action_Recognition directory contains 7+ different action recognition methods (C3D, TSN, ST-GCN, IDT, etc.) with inconsistent structure. IDT has source code and a Makefile, while others only have readme.md placeholders. This fragmentation makes it difficult to benchmark algorithms, run comparative tests, or create a unified training pipeline. A contributor could significantly improve usability.

• [ ] Create CNN/Action_Recognition/CMakeLists.txt (or similar) as root build configuration that detects and builds all subdirectories with optional components
• [ ] Standardize each method directory (C3D, TSN, R-C3D, ST-GCN, etc.) with: 1) build instructions, 2) dataset preparation scripts, 3) inference examples
• [ ] Add CNN/Action_Recognition/tests/ directory with sample video files and expected output for each algorithm to enable regression testing
• [ ] Document in CNN/Action_Recognition/readme.md a performance comparison table (accuracy, speed, memory) for different methods on standard benchmarks

Implement CI/CD pipeline with GitHub Actions for multi-language builds

The repo contains C++ (CMake), MATLAB, Python, and shell scripts across multiple modules, but has no visible CI workflow. Given the complexity of building 3D detection, tracking, and action recognition modules with various dependencies (OpenCV, PCL, MATLAB toolboxes), automated testing would catch breakages early and guide contributors on correct build practices.

• [ ] Create .github/workflows/cpp-build.yml to compile 3D_Object_Detection/Object_Tracking/src with CMake on Linux/macOS, testing against OpenCV and PCL versions
• [ ] Create .github/workflows/python-lint.yml to run pylint/flake8 on any Python scripts and validate requirements.txt for CNN modules
• [ ] Add .github/workflows/matlab-syntax.yml using MATLAB's mlint or equivalent to validate MATLAB code in pf_socker/ and IDT/svm/
• [ ] Create a CONTRIBUTING.md documenting the build process for each module type and referencing the CI checks new PRs must pass

• Document SLAM integration: The pdf/ folder references KinectFusion and ElasticFusion but no corresponding C++ src/ exists in 3D_Object_Detection/—add a integration guide explaining how ORB-SLAM2 output feeds into the tracking pipeline, or point to external ORB-SLAM2 fork used.
• Add unit tests for opticalFlow.cpp: Core motion estimation has no visible test suite (no gtest or catch2 usage); write synthetic video tests validating optical flow magnitude/direction on known motion patterns.
• Create Python binding examples: Heavy C++ codebase (multitracker, opticalFlow) lacks Python ctypes/pybind11 wrappers; add example Python scripts calling compiled tracker binaries via subprocess, enabling faster prototyping for action recognition pipeline.

This is a research/educational machine vision repository with moderate security posture. The codebase consists primarily of computer vision algorithms, MATLAB scripts, and C++ implementations focused on object tracking and 3D detection rather than web services or user-facing applications. Main concerns include: (1) Potential use of outdated dependent libraries (OpenCV), (2) Lack of input validation in processing external video/sensor data, (3) Missing security documentation and vulnerability disclosure policy, (4) MATLAB code lacking security review. The repository is relatively low-risk for deployment in controlled research environments but would require significant security hardening before production use in autonomous systems or robots. No hardcoded credentials, injection vulnerabilities, or exposed infrastructure issues were identified in the provided file structure.

• Medium · Potential Use of Outdated OpenCV Libraries — 3D_Object_Detection/Object_Tracking/src/. The repository contains object tracking and computer vision code that likely depends on OpenCV. Based on the file structure showing C++ implementations (multitracker.cpp, opticalFlow.cpp, single_tracker.cpp), there is a risk of using outdated versions of OpenCV which may contain known security vulnerabilities in image processing functions. Fix: Ensure CMakeLists.txt specifies minimum secure OpenCV versions (4.5.0+), and regularly update dependencies. Use dependency scanning tools like OWASP Dependency-Check.
• Medium · Lack of Input Validation in Tracking Algorithms — 3D_Object_Detection/Object_Tracking/src/multitracker.cpp, 3D_Object_Detection/Object_Tracking/src/single_tracker.cpp. The object tracking implementations (multitracker.cpp, single_tracker.cpp) process external data from video feeds and sensor inputs without visible input validation mechanisms. This could lead to buffer overflows or processing of malformed data. Fix: Implement strict input validation for video frames, coordinate data, and detector outputs. Add bounds checking and sanitization before processing.
• Low · MATLAB Code Security Review Missing — 3D_Object_Detection/Object_Tracking/pf_socker/. MATLAB scripts in the particle filter implementation (pf_socker directory) lack documented security review. These files execute dynamic code that could be vulnerable if datasets are untrusted. Fix: Review MATLAB scripts for unsafe functions (eval, feval, system calls). Validate all input data sources and consider migrating to compiled implementations.
• Low · Missing Security Documentation — Repository root. No security policy, vulnerability disclosure procedures, or security guidelines are documented in the repository. The README contains educational links but no security warnings for production use. Fix: Add SECURITY.md with vulnerability disclosure policy. Document known security limitations of SLAM, object detection, and tracking implementations.
• Low · Potential Race Conditions in Multi-threaded Tracking — 3D_Object_Detection/Object_Tracking/src/multitracker.cpp. The 'multitracker.cpp' implementation suggests concurrent tracking of multiple objects, which could contain race conditions or synchronization issues if not properly implemented. Fix: Review thread safety of shared data structures. Use thread-safe containers and proper mutex protection. Add thread sanitizer testing.
• Low · Unvalidated PDF Dependencies — 3D_Object_Detection/pdf/. Repository contains PDF files that may have been downloaded from external sources without verification. These could potentially contain malicious content or embedded exploits. Fix: Verify integrity of PDF files using checksums. Consider hosting educational materials on trusted platforms rather than in the repository.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.