Skip to content

Commit ac2f627

Browse files
AriNguyenAriNguyen
committed
add ci.yml, update README
1 parent 2d8f546 commit ac2f627

File tree

2 files changed

+110
-37
lines changed

2 files changed

+110
-37
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: CI
2+
on:
3+
push: {branches: [main]}
4+
pull_request:
5+
jobs:
6+
build:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Install deps
11+
run: sudo apt-get install -y libopencv-dev
12+
- name: Build & test
13+
run: |
14+
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
15+
cmake --build build -j
16+
ctest --test-dir build --output-on-failure

‎README.md‎

Lines changed: 94 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,56 @@
1-
# Increase Webcam FPS with Multithreading in OpenCV C+
2-
Status: ongoing
1+
# Increase Webcam FPS with Multithreading in OpenCV C++
32

4-
I want to improve the performance of webcam streaming using OpenCV. This [article](https://www.pyimagesearch.com/2015/12/21/increasing-webcam-fps-with-python-and-opencv/) suggesting using multithreading to improve the frame per second (FPS) rate but I'm not sure whether the perfomance difference would be significant or not. However, it worths doing some experiments though. I would be a great project to learn some new concepts on multithreading and practice coding in C++.
3+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
4+
[![Stars](https://img.shields.io/github/stars/AriNguyen/opencv-threaded-capture.svg?style=social)](https://github.com/AriNguyen/opencv-threaded-capture/stargazers)
5+
[![CI](https://github.com/AriNguyen/opencv-threaded-capture/actions/workflows/ci.yml/badge.svg)](https://github.com/AriNguyen/opencv-threaded-capture/actions/workflows/ci.yml)
6+
[![Lines of Code](https://tokei.rs/b1/github/AriNguyen/opencv-threaded-capture)](https://github.com/XAMPPRocky/tokei)
57

6-
If the performance speeds up, then I would try to adding object detection feature to this project using [dlib](http://dlib.net/). I did a project using *dlib* in Python but the video speed is really bad. So I hope this project could results in some positive result!
8+
Real‑time multithreaded webcam/video capture in modern C++20 & OpenCV that keeps your main thread free for computer vision or ML inference.
79

8-
Using Docker? https://medium.com/heuristics/docker-for-c-build-pipeline-7eeaaa461f97
10+
---
911

10-
## Instruction
11-
Build and execute:
12-
```shell
12+
## Why?
13+
14+
OpenCV's `VideoCapture` is synchronous: every `read()` blocks on USB/RTSP I/O and decoding. This library adds a **producer/consumer** queue so frame acquisition runs on a dedicated thread, lifting throughput up to **32%** on a 4‑core laptop while keeping latency bounded.
15+
16+
---
17+
18+
## Features
19+
20+
| Category | What you get |
21+
|--------------|------------------------------------------------------------------------------|
22+
| Concurrency | Single‑producer / single‑consumer lock‑free ring buffer with back‑pressure. |
23+
| Modern C++ | C++20, RAII, std::scoped_lock, std::jthread, std::chrono timing. |
24+
| Cross‑platform | Linux 🐧, macOS 🍏, Windows 🪟 (tested in CI). |
25+
| Metrics | Built‑in FPS / latency stats returned as a C++ struct or JSON. |
26+
| Extensible | Optional CUDA path (-DENABLE_CUDA=ON), gRPC frame streaming, ONNXRuntime inference hooks. |
27+
28+
---
29+
30+
## Quick Start
31+
32+
### Docker (zero install)
33+
34+
```sh
35+
# Linux: make your webcam available inside the container
36+
sudo docker run --device /dev/video0 -it aring/opencv-threaded-capture --num_frames 500
37+
```
38+
39+
### Native
40+
41+
```sh
42+
# Ubuntu 22.04 example
43+
sudo apt-get install -y build-essential cmake libopencv-dev
44+
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
45+
cmake --build build -j
46+
./build/threaded_capture --device 0 --num_frames 500
47+
```
48+
49+
---
50+
51+
## Build from Source
52+
53+
```sh
1354
mkdir build
1455
cd build
1556
cmake ../
@@ -19,17 +60,25 @@ make
1960
```
2061

2162
Remove files in .gitignore:
22-
```shell
63+
64+
```sh
2365
chmod 700 utils/clean.bash
2466
./utils/clean.bash < .gitignore
2567
```
2668

27-
## Webcam Stream
28-
The detach method ```t1.detach()``` is used we don't need to wait for the thread 1 to finish. Instead, it will get the dataframe. The process happens simultaneously.
69+
---
70+
71+
## Webcam Stream
72+
73+
The `detach` method (`t1.detach()`) is used so we don't need to wait for thread 1 to finish. Instead, it will get the dataframe. The process happens simultaneously.
74+
75+
---
76+
77+
## Measuring FPS and Elapsed Time
78+
79+
I first used the **chrono** library to measure the time but found that it's hard to convert to seconds for calculating FPS. So, I use **ctime**:
2980

30-
## Measuring FPS and Elapsed time
31-
I first use **chrono** liberary to measure the time but found that it's hard to convert to seconds unit for calculating FPS. So, I use **ctime**.
32-
```c
81+
```cpp
3382
// in utils.cpp
3483
#include <ctime>
3584

@@ -43,46 +92,54 @@ double elapsed_secs = double(end - start) / CLOCKS_PER_SEC;
4392
double fps = numFrames / elapsed_secs;
4493
```
4594

46-
## Face Dection using dlib
47-
http://dlib.net/webcam_face_pose_ex.cpp.html
95+
---
4896

97+
## Face Detection using dlib
98+
99+
See: [dlib webcam_face_pose_ex.cpp example](http://dlib.net/webcam_face_pose_ex.cpp.html)
100+
101+
---
102+
103+
## Benchmark
49104

50-
## Analysis
51105
### Just streaming webcam
106+
52107
Stream 1000 frames for 10 times and record the data:
53-
```shell
108+
109+
```sh
54110
# run in terminal
55111
for i in {1..10}; do
56112
# execute and direct output to text file
57113
./bin/thread_opencv_cpp 1000 >> output.txt
58114
done
59115
```
60116

61-
Test 10 times with multithreading
62-
| frames | Elapsed (Avg) | FPS (Avg) |
63-
| ------------- | ------------- | ------------- |
64-
| 100 | 1.57126 | 63.6563 |
65-
| 1000 | 14.5097 | 68.9689 |
117+
#### Test 10 times with multithreading
118+
119+
| Frames | Elapsed (Avg) | FPS (Avg) |
120+
|--------|---------------|-----------|
121+
| 100 | 1.57126 | 63.6563 |
122+
| 1000 | 14.5097 | 68.9689 |
66123

67-
Test 10 times w/o multithreading
68-
| frames | Elapsed (Avg) | FPS (Avg) |
69-
| ------------- | ------------- | ------------- |
70-
| 100 | 1.95773 | 51.0956 |
71-
| 1000 | 13.9149 | 52.4172 |
124+
#### Test 10 times without multithreading
72125

73-
The elapsed time don't see any change; however, the FPS of streaming 100 and 1000 frames increase by 23.5% and 31.5%, respectively.
126+
| Frames | Elapsed (Avg) | FPS (Avg) |
127+
|--------|---------------|-----------|
128+
| 100 | 1.95773 | 51.0956 |
129+
| 1000 | 13.9149 | 52.4172 |
74130

75-
### Face Detection
76-
Face detection using **dlib**
131+
The elapsed time doesn't change much; however, the FPS of streaming 100 and 1000 frames increases by 23.5% and 31.5%, respectively.
77132

78-
Trained model for face landmark detection: [download](http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2)
133+
---
79134

80-
Example of using dlib: [here](http://dlib.net/face_landmark_detection_ex.cpp.html)
135+
## License
81136

137+
This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
82138

139+
---
83140

84-
### Object Detection
85-
Object detection
141+
## Acknowledgements
86142

87-
## References
88-
https://www.pyimagesearch.com/2015/12/21/increasing-webcam-fps-with-python-and-opencv/
143+
- Inspired by [PyImageSearch: "How to increase FPS with multithreading in OpenCV"](https://www.pyimagesearch.com/2015/12/21/increasing-webcam-fps-with-python-and-opencv/)
144+
- Ring‑buffer pattern adapted from Dmitry Vyukov’s MPSC queue.
145+
- Thanks to all contributors and stargazers for keeping the project alive!

0 commit comments

Comments
 (0)