📚 课程目录第2章标注工具与环境搭建

2. 标注工具与环境搭建：LabelImg、CVAT等工具安装与配置、Python环境准备、依赖库安装（OpenCV、Pillow）

工欲善其事，必先利其器。做光学玻璃缺陷标注，工具选不对，后面全是坑。我见过不少新手，上来就用盗版软件或者随便找个在线工具，结果标注到一半软件崩溃，数据全丢——那种感觉，比玻璃上划了一道还难受。

这一章，咱们就把环境彻底搭好。说白了，就是给你的电脑装上“眼睛”和“手”，让它能看图、能画框、能存数据。我个人习惯把环境分成三层：Python 基础层 → 图像处理层 → 标注工具层。一层一层来，稳得很。

  本章核心目标： 完成从零到可标注的完整环境搭建，确保 OpenCV 能读图、Pillow 能存图、LabelImg/CVAT 能正常启动并保存标注结果。

2.1 Python 环境准备

Python 版本别太新也别太旧。我踩过坑——Python 3.12 刚出的时候，有些标注工具的依赖库还没适配，装到一半报错，查了半天才发现是版本问题。所以，推荐用 Python 3.8 ~ 3.10，稳定，兼容性好。

2.1.1 安装 Python

下载：去 Python 官网（python.org）下载对应系统版本。Windows 选 64-bit 安装包。
安装：记得勾选 Add Python to PATH。这一步很多人忘，导致后面命令行找不到 python 命令。
验证：打开终端（cmd 或 PowerShell），输入：

python --version
pip --version

能看到版本号，说明装好了。如果提示“不是内部或外部命令”，那就是 PATH 没加，重装一遍勾上就行。

2.1.2 创建虚拟环境

为什么要用虚拟环境？说白了，就是给每个项目一个“独立的小房间”。你想想看，不同项目可能依赖不同版本的库，全装在一起迟早打架。我曾经在一个服务器上同时跑三个标注项目，结果因为 OpenCV 版本冲突，一个项目能读图，另一个直接崩溃——从那以后，我每个项目都建独立环境。

# 创建虚拟环境（在项目目录下执行）
python -m venv glass_defect_env

# 激活环境
# Windows:
glass_defect_env\Scripts\activate

# macOS/Linux:
source glass_defect_env/bin/activate

# 激活后，终端前面会出现 (glass_defect_env) 字样

小技巧： 我习惯在项目根目录建一个 requirements.txt 文件，把所有依赖写进去。这样换电脑或者给同事部署时，一行命令就能装完所有库。

2.2 依赖库安装

环境激活后，开始装图像处理的核心库。这两个库是标注工作的“眼睛”——OpenCV 负责读图和处理，Pillow 负责格式转换和保存。

2.2.1 安装 OpenCV

pip install opencv-python
pip install opencv-contrib-python  # 包含额外模块，可选

验证是否装成功：

python -c "import cv2; print(cv2.__version__)"

能打印出版本号，比如 4.8.1，就对了。如果报错 ModuleNotFoundError，检查一下虚拟环境是否激活，或者 pip 是否指向了正确的 Python。

注意： OpenCV 的安装包比较大（约 30-50MB），如果下载慢，可以换国内镜像源：

pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple

2.2.2 安装 Pillow

pip install Pillow

验证：

python -c "from PIL import Image; print(Image.__version__)"

Pillow 是 Python 图像库 PIL 的现代分支。我遇到过有人装成了 PIL（老版本），结果很多新格式不支持。记住，装 Pillow，不是 PIL。

2.2.3 其他辅助库

库名	用途	安装命令
NumPy	数组运算，OpenCV 图像本质是 NumPy 数组	`pip install numpy`
Matplotlib	可视化图像和标注结果	`pip install matplotlib`
lxml	XML 解析（LabelImg 标注文件格式）	`pip install lxml`

一次性装完所有依赖，可以写个 requirements.txt：

opencv-python==4.8.1
Pillow==10.1.0
numpy==1.24.3
matplotlib==3.7.2
lxml==4.9.3

然后执行：

pip install -r requirements.txt

2.3 标注工具安装与配置

工具选哪个？看场景。我个人的经验是：小项目、单机操作 → LabelImg；团队协作、大项目 → CVAT。下面两个都讲，你自己选。

2.3.1 LabelImg（本地桌面端）

LabelImg 是纯 Python 写的，轻量，启动快。适合一个人对着屏幕慢慢标。

安装步骤：

确保虚拟环境已激活，且已安装 lxml 和 PyQt5：

pip install PyQt5
pip install lxml

从 GitHub 克隆或下载 LabelImg 源码：

git clone https://github.com/HumanSignal/labelImg.git
cd labelImg

启动工具：

python labelImg.py

看到图形界面弹出来，就成功了。界面很简单——左边是图像区，右边是标注列表和工具按钮。

配置建议： 启动前，先创建一个 classes.txt 文件，把缺陷类别写进去，比如：

划痕
气泡
杂质
裂纹
麻点

然后在 LabelImg 中加载这个文件，标注时就能直接选类别，不用手打。

2.3.2 CVAT（Web 服务端）

CVAT 是 Intel 开源的 Web 标注工具。功能比 LabelImg 强很多——支持视频标注、自动标注、多人协作。但部署也复杂一些。

安装方式（Docker 部署，推荐）：

# 安装 Docker 和 Docker Compose（略，请自行安装）

# 克隆 CVAT 仓库
git clone https://github.com/opencv/cvat.git
cd cvat

# 启动服务
docker compose up -d

启动后，浏览器访问 http://localhost:8080，默认账号 admin，密码 admin。进去后可以创建项目、上传图片、分配标注任务。

注意： CVAT 对内存要求较高，建议至少 8GB 可用内存。我第一次在 4GB 的笔记本上跑，直接卡死。后来加了虚拟内存才勉强能用——但体验很差。如果是团队用，建议部署在服务器上。

2.4 环境验证：跑一个简单的标注测试

环境搭好了，到底能不能用？写个脚本验证一下。这个脚本会读取一张图片，显示出来，然后打印图像信息。如果不出错，说明 OpenCV 和 Pillow 都正常工作。

import cv2
from PIL import Image
import numpy as np

# 1. 用 OpenCV 读取图片
img_cv = cv2.imread('test_glass.jpg')
if img_cv is None:
    print("❌ OpenCV 无法读取图片，请检查路径或图片格式")
else:
    print(f"✅ OpenCV 读取成功：{img_cv.shape}")  # (高, 宽, 通道)

# 2. 用 Pillow 读取同一张图片
img_pil = Image.open('test_glass.jpg')
print(f"✅ Pillow 读取成功：{img_pil.size}")  # (宽, 高)

# 3. 显示图片（按任意键关闭）
cv2.imshow('Test Image', img_cv)
cv2.waitKey(0)
cv2.destroyAllWindows()

把这段代码保存为 test_env.py，在虚拟环境中运行：

python test_env.py

如果看到图片弹出来，终端打印了尺寸信息，恭喜你——环境搭建完成，可以开始标注了。

  常见问题排查：
  cv2.imshow 报错： 可能是没有 GUI 支持。Linux 服务器上可以改用 cv2.imwrite 保存图片来验证。
Pillow 打不开某些格式： 比如 .tiff 或 .bmp，需要安装额外插件：pip install pillow-heif 或 pip install pillow-tiff。
虚拟环境激活后 pip 还是全局的： 检查 which pip（Linux/macOS）或 where pip（Windows），确保路径指向虚拟环境内的 pip。

2.5 本章小结

这一章我们干了三件事：装 Python 环境、装图像处理库、装标注工具。看起来步骤多，其实熟练了十分钟搞定。嗯，这里要注意——虚拟环境一定要用，别偷懒。我见过太多人图省事直接装全局，结果项目一多，依赖乱成一锅粥，最后只能重装系统。