opencv_webcam/README.en.md

[中文简体](./README.md)|English
<p align="center">
<a href="https://gitee.com/CV_Lab/opencv_webcam">
<img src="https://pic.imgdb.cn/item/61f116412ab3f51d918b7bb1.png" alt="Simple Icons" >
</a>
<p align="center">
    Webcam program based on OpenCV, suitable for real-time video frame acquisition, computer vision data collection, etc.
</p>
<p align="center">
    It has the characteristics of convenient installation, simple operation and cross-platform.
</p>
</p>
<p align="center">
<a href="https://gitee.com/CV_Lab/opencv_webcam/blob/master/codeCheck.md"><img src="https://img.shields.io/badge/CodeCheck-passing-success" alt="code check" /></a>
<a href="https://pypi.org/project/opencv-webcam-script/0.4.0/"><img src="https://img.shields.io/badge/PyPi-v0.4.0-brightgreen?logo=pypi" alt="PyPi" /></a>
<a href="https://gitee.com/CV_Lab/opencv_webcam/releases/v0.4"><img src="https://img.shields.io/badge/Releases-v0.4-green" alt="Releases Version" /></a>
<a href="https://hub.docker.com/r/zengdockerdocker/opencv-webcam-script"><img src="https://img.shields.io/badge/docker-v0.4-blue?logo=docker" alt="Docker" /></a>
<a href="https://gitee.com/CV_Lab/opencv_webcam/blob/master/tutorial/ows_jupyter.ipynb"><img src="https://img.shields.io/badge/Jupyter-v0.4-orange?logo=jupyter" alt="Jupyter" /></a>
<a href="https://gitee.com/CV_Lab/opencv_webcam/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-GPL--3.0-blue" alt="License" /></a>
</p>




<h2 align="center">🚀Update Trend</h2>

- `2022-01-24` **⚡ [opencv-webcam-script v0.4 release](https://gitee.com/CV_Lab/opencv_webcam/releases/v0.4) officially launched**
- `2022-01-24` **⚡ [opencv-webcam-script v0.4 docker version](https://hub.docker.com/r/zengdockerdocker/opencv-webcam-script) officially launched**
- `2022-01-24` **⚡ [opencv-webcam-script v0.4.0 PyPi version](https://pypi.org/project/opencv-webcam-script/0.4.0/)officially launched**
- `2022-01-24` **⚡ [opencv-webcam-script v0.4 Jupyter version](https://gitee.com/CV_Lab/opencv_webcam/blob/master/tutorial/ows_jupyter.ipynb)officially launched**
- ⚡ [opencv-webcam-script v0.3](./v_change/v03_change.md)
- ⚡ [opencv-webcam-script v0.2](./v_change/v02_change.md)
- ⚡ [opencv-webcam-script v0.1](./v_change/v01_change.md)



<h2 align="center">💡Project Structure</h2>

```
.
├── opencv_webcam							# 项目名称
│   ├── utils								# 工具包
│   │   ├── args_yaml.py					# 指令管理
│   │   ├── compress.py						# 压缩管理
│   │   ├── frame_opt.py					# 帧保存管理
│   │   ├── hotkey.py						# 热键管理
│   │   ├── __init__.py						# 工具包初始化
│   │   ├── log.py							# 日志管理
│   │   ├── ows_path.py						# 保存路径管理
│   │   └── time_format.py					# 时间格式化
│   ├── v_change							# 版本变更
│   │   ├── v01_change.md					# v0.1版本变更
│   │   ├── v02_change.md					# v0.2版本变更
│   │   └── v03_change.md					# v0.3版本变更
│   ├── tutorial							# ows教程
│   │   ├── ows_pypi.md						# ows pypi版教程
│   │   ├── ows_docker.md					# ows docker版教程
│   │   └── ows_jupyter.md					# ows Jupyter版教程
│   ├── codeCheck.md						# 代码检查
│   ├── Dockerfile							# docker构建文件
│   ├── __init__.py							# 项目初始化
│   ├── LICENSE								# 项目许可
│   ├── opencv_webcam.py					# 脚本主运行文件
│   ├── README.md							# 项目说明
│   └── requirements.txt					# 脚本依赖包
```



<h2 align="center">🔥Installation Tutorial</h2>

### ✅ Method 1: Linux Shell Installation (Development Edition)

- Step 1: Clone the project

```shell
git clone https://gitee.com/CV_Lab/opencv_webcam.git # clone project
```

- Step 2: Create a virtual environment

```shell
# Create a conda virtual environment, taking python 3.8 as an example
conda create -n ows python==3.8 # The virtual environment name is ows
conda activate ows # Activate the virtual environment
```

- Step 3: Install the script

```shell
pip install -r ./requirements.txt -U # Install OpenCV Webcam Script
```

- Steps 2 and 3 can also be performed via `setup.sh`

```shell
bash ./setup.sh
```



### ✅ Method 2: pip quick installation (PyPi version)

#### 🔥 [opencv-webcam-script PyPi version detailed tutorial](./tutorial/ows_pypi.md)

#### 🔑 Easy Tutorial

- Step 1: Create an ows virtual environment, see Method 1
- Step 2: Execute the pip command

```shell 
pip install opencv-webcam-script==0.4.0
```

- Step 3: Write a python program

```python
from opencv_webcam.opencv_webcam import webcam_opencv
# Example of a few functions
webcam_opencv() # regular call
webcam_opencv(is_autoSaveFrame=True) # Auto save frames
webcam_opencv(is_autoSaveFrame=True, is_compress=True) # compressed frame
```



### ✅ Method 3: docker image installation (docker version)

#### 🔥 [opencv-webcam-script docker version detailed tutorial](./tutorial/ows_docker.md)

#### 🔑 Easy Tutorial

- Step 1: Download the mirror

```shell
sudo docker pull zengdockerdocker/opencv-webcam-script:v0.4 # Mirror pull
```

- Step 2: Create the container

```shell
xhost +local:root # Allow root user access to running X server (important)
sudo docker run --name=ows --ipc=host -it -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=unix$DISPLAY --device=/dev/video0:/dev/video0 zengdockerdocker/opencv-webcam-script:v0.4 # Create a container named ows
```

- Step 3: Run the program

```shell
python3 opencv_webcam.py # run script
python3 opencv_webcam.py -isasf # Auto save frames

# Get docker frame data to this machine
sudo docker cp Container name: container directory local host directory
sudo docker cp ows:/usr/src/app/WebcamFrame /home/username # Example
```

### ✅ Method 4: Jupyter installation (Jupyter version)

#### 🔥 [opencv-webcam-script Jupyter version detailed tutorial](./tutorial/ows_jupyter.ipynb)

#### 🔑 Easy Tutorial

- Step 1: Installation

```shell
# First create a virtual environment manually
# conda create -n ows python==3.8 # The virtual environment name is ows
# conda activate ows # Activate the virtual environment
!git clone https://gitee.com/CV_Lab/opencv_webcam.git # clone
%cd opencv_webcam
%pip install -qr requirements.txt -U # install
```

- Step 2: Run

```shell
!python opencv_webcam.py # Press the q key to exit by default
!python opencv_webcam.py -isasf # Automatically save video frames
```

**Note: Jupyter version of ows program can run unit instructions through `Ctrl+Enter`**



<h2 align="center">⚡Usage</h2>

####  💡 regular call

```shell
# Press the q key to exit by default
python opencv_webcam.py
```



####  💡 Device Selection

```shell
# 多摄像头切换示例，默认为0
python opencv_webcam.py -dev 0
python opencv_webcam.py -dev 1
python opencv_webcam.py -dev 2
# RTSP
python opencv_webcam.py -dev rtsp://username:password@xxx.xxx.xxx
```



####  💡 set escape key

```shell
# 默认按q键退出
python opencv_webcam.py -q z # 设置z键退出
python opencv_webcam.py -q k # 设置k键退出
```



####  💡 Auto save frames

```shell
python opencv_webcam.py -isasf
```



#### 💡 Save frames every n frames

```shell
# 每隔10帧保存一次帧
python opencv_webcam.py -isasf -fns 10
```



#### 💡 Save frames manually

```shell
# 默认按a键捕获一帧
python opencv_webcam.py -ishsf
```



#### 💡 custom capture key

```shell
# 设置z键为捕获键，默认为a键
python opencv_webcam.py -ishsf -fck z
```



#### 💡 Reshape frame size (custom width and height)

```shell
# 重塑宽度300 高度200
python opencv_webcam.py -isasf -isrf -rf 300 200 # 自动版
python opencv_webcam.py -ishsf -isrf -rf 300 200 # 手动版
```



#### 💡 Reshape frame size (custom aspect scaling)

```shell
# 宽高缩放比为0.5
python opencv_webcam.py -isasf -isrf -rrf 0.5 # 自动版
python opencv_webcam.py -ishsf -isrf -rrf 0.5 # 手动版
```



#### 💡 Custom save path

```shell
# 设置保存路径，默认保存路径为./WebcamFrame
python opencv_webcam.py -fsd custom_dir -isasf # 以自动版为例
```



####  💡 custom frame directory name

```shell
# 设置帧目录名称，默认保存路径为frames
python opencv_webcam.py -fdn frames_custom -isasf # 以自动版为例
```




####  💡 Custom frame name prefix

```shell
# 设置帧图片的前缀名称
python opencv_webcam.py -isasf -fnp webcam
```



#### 💡 Set the frame save format

```shell
# 设置JPG质量为100，默认为95
python opencv_webcam.py -isasf -fss jpg -jq 100
# 设置PNG质量为5，默认为3
python opencv_webcam.py -isasf -fss png -jq 5
```



#### 💡 set pause button

```shell
# 设置w键为暂停键，默认为p键
python opencv_webcam.py -p w # 按任意键继续
```



#### 💡 Set the number of frames to save

```shell
# 设置保存100帧
python opencv_webcam.py -isasf -afn 100
```



#### 💡 log settings

```shell
# 日志文件默认保存在项目根目录，ows.log
python opencv_webcam.py
# 设置日志文件名称及类型，类型包括.log、.txt、.data
python opencv_webcam.py -ln ows02.txt
# 设置日志保存方式，，默认为追加模式
python opencv_webcam.py -lm w # 设置为覆盖模式
```

 

#### 💡 video frame compression

```shell
# 常规压缩，默认ows.zip（以自动版为例）
python opencv_webcam.py -isasf -isc
# 自定义压缩文件名称
python opencv_webcam.py -isasf -isc -cn ows02
# 自动命名压缩文件
python opencv_webcam.py -isasf -isc -isacn
# 自定义压缩模式，默认为写覆盖
python opencv_webcam.py -isasf -isc -cm a # 追加模式(a模式仅限zip) 注：该指令仅限v0.4
python opencv_webcam.py -isasf -isc -cs tar -cm w:gz # tar压缩
```



#### 💡 Instruction query

```shell
# 查询脚本参数
python opencv_webcam.py --help
```

<details open>
<summary>指令查询结果</summary>

```shell
usage: opencv_webcam.py [-h] [--device DEVICE] [--quit QUIT] [--is_autoSaveFrame] [--is_handSaveFrame] [--is_resizeFrame] [--frame_saveDir FRAME_SAVEDIR] [--frame_dirName FRAME_DIRNAME]
                        [--frame_nSave FRAME_NSAVE] [--frame_capKey FRAME_CAPKEY] [--resize_frame RESIZE_FRAME [RESIZE_FRAME ...]] [--resizeRatio_frame RESIZERATIO_FRAME]
                        [--frame_namePrefix FRAME_NAMEPREFIX] [--frame_saveStyle FRAME_SAVESTYLE] [--jpg_quality JPG_QUALITY] [--png_quality PNG_QUALITY] [--pause PAUSE]
                        [--auto_frameNum AUTO_FRAMENUM] [--logName LOGNAME] [--logMode LOGMODE] [--is_compress] [--compressStyle COMPRESSSTYLE] [--is_autoCompressName]
                        [--compressName COMPRESSNAME] [--compressMode COMPRESSMODE]

OpenCV Webcam Script v0.4

optional arguments:
  -h, --help            show this help message and exit
  --device DEVICE, -dev DEVICE
                        device index for webcam, 0 or rtsp
  --quit QUIT, -q QUIT  quit key for webcam
  --is_autoSaveFrame, -isasf
                        is auto save frame
  --is_handSaveFrame, -ishsf
                        is hand save frame
  --is_resizeFrame, -isrf
                        is resize frame
  --frame_saveDir FRAME_SAVEDIR, -fsd FRAME_SAVEDIR
                        save frame dir
  --frame_dirName FRAME_DIRNAME, -fdn FRAME_DIRNAME
                        save frame dir name
  --frame_nSave FRAME_NSAVE, -fns FRAME_NSAVE
                        n frames save a frame (auto save frame)
  --frame_capKey FRAME_CAPKEY, -fck FRAME_CAPKEY
                        frame capture key (hand save frame)
  --resize_frame RESIZE_FRAME [RESIZE_FRAME ...], -rf RESIZE_FRAME [RESIZE_FRAME ...]
                        resize frame save
  --resizeRatio_frame RESIZERATIO_FRAME, -rrf RESIZERATIO_FRAME
                        resize ratio frame save
  --frame_namePrefix FRAME_NAMEPREFIX, -fnp FRAME_NAMEPREFIX
                        frame name prefix
  --frame_saveStyle FRAME_SAVESTYLE, -fss FRAME_SAVESTYLE
                        frame save style
  --jpg_quality JPG_QUALITY, -jq JPG_QUALITY
                        frame save jpg quality (0-100) default 95
  --png_quality PNG_QUALITY, -pq PNG_QUALITY
                        frame save jpg quality (0-9) default 3
  --pause PAUSE, -p PAUSE
                        webcam pause
  --auto_frameNum AUTO_FRAMENUM, -afn AUTO_FRAMENUM
                        auto save number of frames
  --logName LOGNAME, -ln LOGNAME
                        log save name
  --logMode LOGMODE, -lm LOGMODE
                        log write mode
  --is_compress, -isc   is compress file
  --compressStyle COMPRESSSTYLE, -cs COMPRESSSTYLE
                        compress style
  --is_autoCompressName, -isacn
                        is auto compress name
  --compressName COMPRESSNAME, -cn COMPRESSNAME
                        compress save name
  --compressMode COMPRESSMODE, -cm COMPRESSMODE
                        compress save mode, tar w:gz
```

</details>