🔒 锁定依赖

henryzhuhr · Jun 7, 2024 · 3dea50d · 3dea50d
1 parent c57b966
commit 3dea50d
Show file tree

Hide file tree

Showing 9 changed files with 254 additions and 99 deletions.
diff --git a/dataset-process.py b/dataset-process.py
@@ -8,22 +8,26 @@
 
 
 class DatasetProcessArgs:
+    @staticmethod
+    def get_args():
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            "-d", "--datadir", type=str, default="~/data/drink/"
+        )
+        return parser.parse_args()
+
     def __init__(self) -> None:
         args = self.get_args()
         self.datadir: str = os.path.expandvars(os.path.expanduser(args.datadir))
+        if self.datadir[-1] == "/" or self.datadir[-1] == "\\":
+            self.datadir = self.datadir[:-1]
 
         # check if the directory exists
         if not os.path.exists(self.datadir):
             raise FileNotFoundError(
                 f"Directory '{self.datadir}' not found, check '--datadir {args.datadir}'"
             )
 
-    @staticmethod
-    def get_args():
-        parser = argparse.ArgumentParser()
-        parser.add_argument("-d","--datadir", type=str, default="~/data/drink")
-        return parser.parse_args()
-
 
 def main():
     args = DatasetProcessArgs()
@@ -41,7 +45,6 @@ def main():
             f"\033[00;33m To avoid overwriting, please manually delete by\033[0m"
             f"\033[00;32m 'rm -rf {organized_datadir}'\033[0m"
             f"\033[00;33m and run this script again.\033[0m"
-
         )
 
     images_dir = os.path.join(organized_datadir, "images")

diff --git a/docs/dataset.md b/docs/dataset.md
@@ -7,6 +7,13 @@ outline: deep
 
 # 目标检测数据集制作
 
+## 概要
+
+数据集的构建，应该使用“**少量标注+半自动标注**”的方式，即先标注少量数据，然后通过「[半自动标注](#半自动标注)」的方式，快速标注其他数据，最后通过标注工具进行精细化调整。这样可以大大减少标注的工作量
+
+因此建议先阅读完整个文档，再构建自己的数据集
+
+
 ## 数据集采集和归档
 
 ::: tip
@@ -41,12 +48,21 @@ ln -s ~/data resource/data
 DATASET_DIR=~/data/drink
 ```
 
-参考该目录构建自己的数据集，并且完成标注
+考虑到单张图像中可能出现不同类别的目标，因此数据集不一定需要按照类别进行划分，可以自定义划分，按照项目的需求任意归档数据集，但是请确保，每一张图像同级目录下有同名的**标签文件**。可以参考如下的几种目录结构构建自己的数据集：
 
-考虑到单张图像中可能出现不同类别的目标，因此数据集不一定需要按照类别进行划分，可以自定义划分，按照项目的需求任意归档数据集，但是请确保，每一张图像同级目录下有同名的**标签文件**
+::: code-group
 
-按照类别划分的目录结构参考
-```shell
+```shell [不划分子目录]
+# 这种目录结构适用于数据集不划分类别，直接存放在同一目录下
+·
+└── /path/to/dataset    
+    ├─ file_1.jpg
+    ├─ file_1.xml
+    └─ ...
+```
+
+```shell [按照类别划分的目录]
+# 这种目录结构适用于数据集按照类别划分，每个类别一个目录
 ·
 └── /path/to/dataset
     ├── class_A         
@@ -59,15 +75,22 @@ DATASET_DIR=~/data/drink
         └─ ...
 ```
 
-不进行类别划分的目录结构参考
-```shell
+
+
+```shell [自定义划分的目录结构]
+# 这种目录结构可以根据项目的需求自定义划分，例如按照视频分割帧构建的数据集
 ·
-└── /path/to/dataset    
-    ├─ file_1.jpg
-    ├─ file_1.xml
-    └─ ...
+└── /path/to/dataset
+    ├── video_A
+    │   ├─ file_A1.jpg
+    │   ├─ file_A1.xml
+    │   └─ ...
+    └── video_B
+        ├─ file_B1.jpg
+        ├─ file_B1.xml
+        └─ ...
 ```
-
+:::
 
 ## 启动标注工具
 
@@ -114,8 +137,9 @@ labelImg
 
 运行脚本，生成同名目录，但是会带 `-organized` 后缀，例如
 ```shell
-python dataset-process.py --datadir ~/data/drink
+python dataset-process.py -d ~/data/drink # -d / --datadir
 ```
+> 建议路径不要有最后的 `/` 或者 `\`，否则可能会出现路径错误
 
 该脚本会自动递归地扫描目录 `~/data/drink` 下的所有 `.xml` 文件，并查看是否存在对应的 `.jpg` 文件
 

diff --git a/docs/install.legacy.md b/docs/install.legacy.md
@@ -0,0 +1,179 @@
+---
+lastUpdated: true
+editLink: true
+footer: true
+outline: deep
+---
+
+# 安装环境
+
+
+## 获取代码
+
+::: code-group
+
+```shell [SSH(Recommend)]
+# 需要配置 github 上的 SSH key
+git clone --recursive [email protected]:HenryZhuHR/deep-object-detect-track.git
+```
+
+```shell [HTTP]
+git clone --recursive https://github.com/HenryZhuHR/deep-object-detect-track.git
+```
+
+:::
+
+进入项目目录
+
+```shell
+cd deep-object-detect-track
+```
+
+> 后续的脚本基于 `deep-object-detect-track` 目录下执行
+
+如果未能获取子模块，可以手动获取，如果 `git submodule` 无法获取，可以使用 `git clone` 获取
+
+::: code-group
+
+```shell [git submodule]
+# in deep-object-detect-track directory
+git submodule init
+git submodule update
+```
+
+```shell [git clone]
+git clone https://github.com/ultralytics/yolov5.git projects/yolov5
+```
+
+:::
+
+
+## 系统要求
+
+### 操作系统
+
+
+项目在 Linux(Ubuntu) 和 MacOS 系统并经过测试 ，经过测试的系统：
+- ✅ Ubuntu 22.04 jammy (CPU & GPU)
+- ✅ MacOS (CPU)
+
+::: warning
+项目不支持 Windows 系统 ❌ ，如果需要在 Windows 系统上运行，可以使用 WSL2 或者根据提供的脚本手动执行；虽然已经测试通过，但是不保证所有功能都能正常运行，因此不接受 Windows 系统的问题反馈
+:::
+
+### GPU
+
+如果需要使用 GPU 训练模型，需要安装 CUDA Toolkit，可以参考 [CUDA Toolkit Archive](https://developer.nvidia.com/cuda-toolkit-archive) 下载对应版本的 CUDA Toolkit，具体下载的版本需要参考 [*INSTALL PYTORCH*](https://pytorch.org/get-started/locally/)
+
+例如 Pytorch 2.3.0 支持 CUDA 11.8/12.1，因此安装 CUDA 11.8/12.1 即可，而不需要过高的 CUDA 版本，安装后需要配置环境变量
+
+```shell
+# ~/.bashrc
+export CUDA_VERSION=12.1
+export CUDA_HOME="/usr/local/cuda-${CUDA_VERSION}"
+export PATH="$CUDA_HOME/bin:$PATH"
+export LD_LIBRARY_PATH="$CUDA_HOME/lib64:$LD_LIBRARY_PATH"
+```
+
+> 事实上，Pytorch 1.8 开始就会在安装的时候自动安装对应的 CUDA Toolkit，因此不需要手动安装 CUDA Toolkit，因此可以跳过这一步
+
+MacOS 系统不支持 CUDA Toolkit，可以使用 CPU 训练模型 (Yolov5 项目暂不支持 MPS 训练)，但是推理过程可以使用 Metal ，参考 [*Introducing Accelerated PyTorch Training on Mac*](https://pytorch.org/blog/introducing-accelerated-pytorch-training-on-mac/#getting-started) 和 [*MPS backend*](https://pytorch.org/docs/stable/notes/mps.html#mps-backend)
+
+
+## 安装环境
+
+这里安装的环境指的是需要训练的环境，如果不需要训练而是直接部署，请转至 「[模型部署](./deploy)」 文档
+
+提供两种方式安装， venv 或 conda
+
+- **venv** : 嵌入式设备的部署建议使用这种方案，以确保链接到系统的库，如果没有安装，请安装
+
+::: code-group
+
+```shell [Linux]
+sudo apt install -y python3-venv python3-pip
+```
+
+```shell [MacOS]
+# Mac 貌似自带了 python3-venv
+# brew install python3-venv python3-pip
+```
+
+:::
+
+- **conda** : 如果没有安装，请从 [Miniconda](https://docs.anaconda.com/free/miniconda/index.html) 下载，或者快速安装
+
+::: code-group
+
+```shell [linux x64]
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
+bash Miniconda3-latest-Linux-x86_64.sh
+```
+
+```shell [MacOS arm64]
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
+zsh Miniconda3-latest-MacOSX-arm64.sh
+```
+
+::: 
+
+### 方法一：手动安装
+
+创建虚拟环境
+
+::: code-group
+
+```shell [在项目内安装环境(推荐)]
+conda create -p .env/deep-object-detect-track python=3.10 -y
+conda activate ./.env/deep-object-detect-track
+```
+
+```shell [全局安装环境]
+conda create -n deep-object-detect-track python=3.10 -y
+conda activate deep-object-detect-track
+```
+
+:::
+
+> Python 版本选择 3.10 是因为 Ubuntu 22.04 默认安装的 Python 版本是 3.10
+
+
+- 如果电脑有 NVIDIA GPU，可以直接安装 [PyTorch](https://pytorch.org/get-started/locally/) 和其他依赖
+```shell
+pip install -r requirements.txt
+```
+
+- 如果电脑没有 NVIDIA GPU，可以安装 CPU 版本的 PyTorch
+```shell
+pip install -r requirements/requirements-cpu.txt
+```
+
+
+### 方法二：使用提供的脚本
+
+提供的安装脚本依赖于基本环境变量 `scripts/variables.sh` ，可以复制一份到项目目录下进行自定义修改（推荐），如果不需要修改，可以直接执行
+
+```shell
+cp scripts/variables.sh scripts/variables.custom.sh
+```
+- `CACHE_DIR`: 用于存放一些缓存文件，例如 `yolov5/requirements.txt`，默认为项目目录下的 `.cache`
+- 安装过程会自动检测 `CUDA_VERSION` 以安装对应的 PyTorch 版本，否则默认安装 CPU 版本的 PyTorch；如果电脑有 NVIDIA GPU 但是不想安装 CUDA Toolkit 到全局系统（需要 sudo）可以取消注释 `export CUDA_VERSION=12.1` 以安装对应的 PyTorch 版本
+
+运行会自动检测是否存在用户自定义的环境变量 `scripts/variables.custom.sh` ，如果存在则使用自定义的环境变量，否则使用默认的环境变量 `scripts/variables.sh` 
+
+执行命令自动创建并且激活虚拟环境，默认使用 `venv`，**可以重复执行该脚本获取激活环境的提示信息或者安装依赖**
+
+::: code-group
+
+```shell [使用 venv 创建虚拟环境]
+bash scripts/create-python-env.sh -i # -i 自动安装依赖
+#zsh scripts/create-python-env.sh -i # zsh
+```
+
+```shell [使用 conda 创建虚拟环境]
+bash scripts/create-python-env.sh -e conda -i # -i 自动安装依赖
+#zsh scripts/create-python-env.sh -e conda -i # zsh
+```
+
+:::
+
diff --git a/docs/install.md b/docs/install.md
@@ -84,7 +84,7 @@ MacOS 系统不支持 CUDA Toolkit，可以使用 CPU 训练模型 (Yolov5 项
 
 这里安装的环境指的是需要训练的环境，如果不需要训练而是直接部署，请转至 「[模型部署](./deploy)」 文档
 
-提供两种方式安装， venv 或 conda
+可以使用 venv 或 conda 创建虚拟环境
 
 - **venv** : 嵌入式设备的部署建议使用这种方案，以确保链接到系统的库，如果没有安装，请安装
 
@@ -117,18 +117,22 @@ zsh Miniconda3-latest-MacOSX-arm64.sh
 
 ::: 
 
-### 方法一：手动安装
 
 创建虚拟环境
 
 ::: code-group
 
-```shell [在项目内安装环境(推荐)]
+```shell [venv (推荐)]
+python -m venv .env/deep-object-detect-track
+source .env/deep-object-detect-track/bin/activate
+```
+
+```shell [项目内 conda (推荐)]
 conda create -p .env/deep-object-detect-track python=3.10 -y
 conda activate ./.env/deep-object-detect-track
 ```
 
-```shell [全局安装环境]
+```shell [全局 conda]
 conda create -n deep-object-detect-track python=3.10 -y
 conda activate deep-object-detect-track
 ```
@@ -137,43 +141,7 @@ conda activate deep-object-detect-track
 
 > Python 版本选择 3.10 是因为 Ubuntu 22.04 默认安装的 Python 版本是 3.10
 
-
-- 如果电脑有 NVIDIA GPU，可以直接安装 [PyTorch](https://pytorch.org/get-started/locally/) 和其他依赖
+安装依赖，其中包含了 [PyTorch](https://pytorch.org/get-started/locally/) 以及 yolov5 项目依赖
 ```shell
 pip install -r requirements.txt
 ```
-
-- 如果电脑没有 NVIDIA GPU，可以安装 CPU 版本的 PyTorch
-```shell
-pip install -r requirements/requirements-cpu.txt
-```
-
-
-### 方法二：使用提供的脚本
-
-提供的安装脚本依赖于基本环境变量 `scripts/variables.sh` ，可以复制一份到项目目录下进行自定义修改（推荐），如果不需要修改，可以直接执行
-
-```shell
-cp scripts/variables.sh scripts/variables.custom.sh
-```
-- `CACHE_DIR`: 用于存放一些缓存文件，例如 `yolov5/requirements.txt`，默认为项目目录下的 `.cache`
-- 安装过程会自动检测 `CUDA_VERSION` 以安装对应的 PyTorch 版本，否则默认安装 CPU 版本的 PyTorch；如果电脑有 NVIDIA GPU 但是不想安装 CUDA Toolkit 到全局系统（需要 sudo）可以取消注释 `export CUDA_VERSION=12.1` 以安装对应的 PyTorch 版本
-
-运行会自动检测是否存在用户自定义的环境变量 `scripts/variables.custom.sh` ，如果存在则使用自定义的环境变量，否则使用默认的环境变量 `scripts/variables.sh` 
-
-执行命令自动创建并且激活虚拟环境，默认使用 `venv`，**可以重复执行该脚本获取激活环境的提示信息或者安装依赖**
-
-::: code-group
-
-```shell [使用 venv 创建虚拟环境]
-bash scripts/create-python-env.sh -i # -i 自动安装依赖
-#zsh scripts/create-python-env.sh -i # zsh
-```
-
-```shell [使用 conda 创建虚拟环境]
-bash scripts/create-python-env.sh -e conda -i # -i 自动安装依赖
-#zsh scripts/create-python-env.sh -e conda -i # zsh
-```
-
-:::
-