企业官网建设流程全解析

1. 为什么还要折腾一个"老"标注工具

语义分割这个方向，做数据集的人都知道，标注环节是整个流水线里最耗人力、最容易出错、也最容易被低估的一环。模型结构可以换、损失函数可以调、数据增强可以堆，但标注质量一旦拉胯，后面所有努力都是白费。我见过太多团队在标注工具上反复横跳，最后要么自己写一个半成品，要么被迫用商业平台按张付费，成本高得离谱。

Semantic-Segmentation-Editor 这个工具，第一次接触是在一个图像处理的小项目里。当时的需求很朴素：给几百张图做像素级的多类别标注，导出成训练能直接吃的掩码格式。试过几个方案之后，这个工具留了下来，原因很简单——它把"多边形标注"和"语义分割掩码导出"这两件事做得足够直接，没有花里胡哨的云端协作，也没有强制登录，本地跑起来就能干活。

但它的安装过程，说实话，不算友好。官方文档写得比较简略，Windows 和 Linux 两套环境的依赖差异又大，尤其是 Ubuntu 16.04 这种老系统，Python 版本、Qt 库、编译工具链全是坑。我在 Win10 和 Ubuntu 16.04 上各装过好几轮，踩的坑足够写一篇完整的记录。这篇就把两套环境的图文安装过程拆开讲清楚，顺带把每个步骤背后的原因、容易卡住的地方、以及装完之后怎么验证，都说明白。

适合谁看：做语义分割数据集、需要本地标注工具、手头是 Win10 或 Ubuntu 16.04 环境的人。如果你用的是更新的 Ubuntu 或者 macOS，思路可以借鉴，但具体包版本要自己调整。下面所有操作我都实际跑过，命令和路径以我自己的环境为准，你照着改就行。

2. 装之前先把工具的家底摸清楚

2.1 这个工具到底依赖什么

Semantic-Segmentation-Editor 本质上是一个基于 Python + Qt 的桌面应用。它的核心依赖分三层：第一层是 Python 运行时和包管理，第二层是 Qt 图形界面库（PyQt5 或 PyQt4，取决于版本），第三层是图像处理和数值计算库，主要是 NumPy、Pillow、scikit-image 这一类。

这里有个关键点很多人忽略：这个工具对 Python 版本是有要求的。老版本代码里大量用了 Python 2 的语法，如果你直接拿 Python 3.10 去跑，大概率在 import 阶段就报语法错误。我实测下来，Python 3.6 到 3.8 是比较稳的区间，Python 2.7 也能跑但没必要，除非你的系统环境实在换不了。

Qt 这一层是安装过程中最容易出问题的。PyQt5 的 wheel 包在不同平台上的依赖不一样，Windows 上通常没问题，Ubuntu 16.04 上因为系统自带的 Qt 库版本太老，经常出现"装上了但一启动就崩"的情况。后面我会专门讲怎么处理。

2.2 两套环境的差异预判

在动手之前，先建立一个心理预期：Win10 和 Ubuntu 16.04 的安装难度不是一个量级。

Win10 的优势在于 Python 安装包和 pip 生态非常成熟，PyQt5 有预编译的 wheel，基本是"下一步下一步"就能搞定。主要坑在于路径里有空格或中文、以及某些 Visual C++ 运行库缺失。

Ubuntu 16.04 的麻烦在于系统太老。它自带的 Python 是 3.5，pip 版本也旧，很多新包已经不支持这个版本了。更麻烦的是 Qt 相关的系统库，比如 libxcb 系列，缺一个就会导致界面起不来，而且报错信息往往很隐晦。所以 Ubuntu 这边的核心思路是：尽量用虚拟环境隔离 Python，系统库该补的补上，不要试图去动系统自带的 Python。

提示：不管你用哪个系统，都强烈建议用虚拟环境（virtualenv 或 conda）。这个工具的依赖不算多，但版本敏感，装到全局环境里以后跟别的项目冲突了很难排查。

2.3 需要提前准备的东西

列一个清单，装之前先确认：

• Python 3.6~3.8 的安装包或可执行文件
• pip 最新版（至少 20.x 以上）
• 虚拟环境工具（virtualenv 或 conda，二选一）
• 工具源码（从代码托管平台克隆或下载压缩包）
• 一个用来测试的图片文件夹，装完后验证用

Windows 上还要确认系统是 64 位，因为 PyQt5 的 wheel 基本只提供 64 位版本。Ubuntu 上要确认有 sudo 权限，因为补系统库需要 apt 安装。

3. Win10 环境下的完整安装链路

3.1 Python 与虚拟环境的搭建

第一步是装 Python。我推荐用 3.7 或 3.8，去官网下载对应的 Windows installer。安装的时候有一个细节必须注意：勾选"Add Python to PATH"。这个选项如果不勾，后面在命令行里敲 python 会提示找不到命令，还得手动配环境变量，很麻烦。

装完之后打开 PowerShell 或 CMD，验证一下：

python --version pip --version

如果 pip 版本低于 20，先升级：

python -m pip install --upgrade pip

接下来建虚拟环境。我习惯在项目目录下建一个 venv 文件夹：

cd D:\projects python -m venv sse_env sse_env\Scripts\activate

激活之后命令行前面会出现 (sse_env) 的标识，说明已经进到隔离环境里了。这一步的意义在于，后面装的所有包都只在这个环境里生效，不会污染系统 Python。

3.2 依赖安装与 PyQt5 的版本选择

进入虚拟环境后，先装核心依赖。这里不要直接 pip install -r requirements.txt，因为很多老项目的 requirements 文件里写的版本号已经过时了，直接装会失败。我的做法是手动装，逐个确认。

pip install numpy pillow scikit-image pip install PyQt5==5.15.4

PyQt5 的版本选择有讲究。5.15.x 是最后一个支持 Python 3.6+ 且 wheel 比较全的大版本，再新的 6.x 改动太大，老代码不一定兼容。5.15.4 是我实测在 Win10 上最稳的一个小版本。

装完之后验证 PyQt5 能不能正常导入：

python -c "from PyQt5 import QtWidgets; print('Qt ok')"

如果这行能打印出 Qt ok，说明图形库没问题。如果报 DLL load failed，通常是缺 Visual C++ 运行库，去装一个 vc_redist.x64.exe 就行。

3.3 源码获取与首次启动

把工具源码放到项目目录下，假设文件夹叫 Semantic-Segmentation-Editor。进入这个目录，直接运行主程序：

cd Semantic-Segmentation-Editor python main.py

如果一切正常，会弹出一个窗口，左边是图片列表，中间是画布，右边是类别管理。第一次启动可能会慢几秒，因为 Qt 要初始化。

这里有个常见问题：如果源码里用的是 PyQt4 的导入语句，而你装的是 PyQt5，会报 ImportError。解决办法是把代码里的from PyQt4 import ...改成from PyQt5 import ...，同时注意 PyQt5 里有些类的路径变了，比如 QtGui 下的部分组件移到了 QtWidgets。这个改动量不大，但需要你稍微看一下报错信息定位。

注意：Windows 上如果项目路径包含中文或空格，Qt 加载资源文件时可能出错。把项目放在纯英文、无空格的路径下最保险，比如 D:\projects\sse。

3.4 Win10 上的实测验证流程

装完不算完，得验证功能是否真的可用。我的验证流程分三步：

第一步，准备一个测试图片文件夹，放三五张不同尺寸的图。在工具里打开这个文件夹，确认图片能正常加载、缩略图能显示。

第二步，新建两个类别，比如"前景"和"背景"，用多边形工具在图上画几笔，确认标注能保存、能切换类别颜色。

第三步，导出掩码。选一张标注好的图，导出成 PNG 掩码，然后用 Python 读一下这个掩码，确认像素值和类别对应关系正确：

from PIL import Image import numpy as np mask = np.array(Image.open('test_mask.png')) print(np.unique(mask))

如果打印出来的值跟你定义的类别索引一致，说明整条链路是通的。这一步很关键，因为有些时候界面能画，但导出环节的编码有问题，掩码值全变成 0 或者 255，训练时才发现就晚了。

4. Ubuntu 16.04 上的硬骨头怎么啃

4.1 系统 Python 的隔离策略

Ubuntu 16.04 自带 Python 3.5，这个版本现在很多包都不支持了。所以第一原则是：不要动系统 Python，用虚拟环境建一个 Python 3.7 的独立环境。

有两种路子。一是用 conda，直接 conda create -n sse python=3.7，省心，但 conda 本身要装。二是用 virtualenv，前提是你系统里已经有一个 Python 3.7。如果系统没有，可以通过 deadsnakes 源装一个，但 Ubuntu 16.04 的源支持有限，操作起来略麻烦。

我实测最顺的方式是装 Miniconda，然后用 conda 建环境：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh conda create -n sse python=3.7 conda activate sse

conda 的好处是它自带了一套 Qt 相关的库，能绕开一部分系统库缺失的问题。这一点在 Ubuntu 16.04 上特别有价值。

4.2 Qt 系统库缺失的排查与补齐

即便用了 conda，Ubuntu 16.04 上启动 Qt 界面时还是可能报错，典型的是：

qt.qpa.plugin: Could not load the Qt platform plugin "xcb"

这个报错的本质是系统缺少 xcb 相关的动态库。解决办法是补装一批系统库：

sudo apt-get update sudo apt-get install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \ libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 \ libxcb-xfixes0 libxkbcommon-x11-0

这一串库看着多，但每一个都是 Qt 界面渲染需要的。缺哪个补哪个，报错信息里通常会提示具体是哪个 so 文件找不到。我建议一次性全装上，省得反复试。

还有一个隐藏坑：如果是在没有图形界面的服务器上跑，需要配置 X11 转发或者用虚拟显示。但标注工具本身就是要人看着画的，所以一般都是在有桌面的环境里用，这个问题不常见。

4.3 依赖安装的版本锁定

Ubuntu 环境下 pip 装包，版本锁定比 Windows 更重要。因为 conda 环境里的 numpy 等基础包可能跟 pip 装的版本冲突。我的做法是先用 conda 装基础科学计算包，再用 pip 装工具特有的依赖：

conda install numpy pillow scikit-image pip install PyQt5==5.15.4

PyQt5 这里有个细节：conda 环境里如果已经装了 pyqt，pip 再装 PyQt5 可能会冲突。可以先 conda list 看一下有没有 pyqt，有的话用 conda 的版本也行，不一定要 pip 装。关键是保证python -c "from PyQt5 import QtWidgets"能跑通。

4.4 启动脚本与权限处理

Ubuntu 下启动工具，跟 Windows 类似，进源码目录跑 main.py。但有两个额外注意点：

一是文件权限。如果源码是从压缩包解压的，某些文件可能没有执行权限，虽然 Python 脚本不需要执行权限也能跑，但如果工具有调用外部脚本的逻辑，就要 chmod +x 一下。

二是显示环境变量。如果你通过 SSH 连到 Ubuntu 桌面，DISPLAY 变量要设对，否则 Qt 找不到显示设备。本地桌面环境一般不用管，远程的话需要 export DISPLAY=:0 或者对应的值。

启动命令：

cd ~/projects/Semantic-Segmentation-Editor python main.py

如果窗口能弹出来，说明 Ubuntu 这边的硬骨头基本啃完了。接下来同样走一遍验证流程：加载图片、画标注、导出掩码、用 numpy 检查掩码值。

5. 两套环境安装过程的对照与取舍

5.1 关键差异对照表

把两套环境的差异整理成一张表，方便你快速定位自己可能遇到的问题：

这张表的核心信息是：Windows 的坑集中在 Python 和运行库，Ubuntu 的坑集中在系统库和 Qt 插件。知道坑在哪，排查就有方向了。

5.2 为什么 Ubuntu 16.04 更推荐 conda

很多人问，为什么不在 Ubuntu 上直接用 pip + virtualenv。原因是 Ubuntu 16.04 的系统库太老，pip 装的 PyQt5 wheel 依赖的系统 so 文件版本可能对不上，而 conda 自带的 Qt 库是一套自洽的、经过测试的组合，能规避大量版本冲突。

代价是 conda 环境体积大一些，装起来慢一点。但对于一个要长期用的标注工具来说，稳定性比省那点磁盘空间重要得多。我在 Ubuntu 上第一次用 pip 装，折腾了大半天界面都起不来，换 conda 之后二十分钟搞定，这个对比很说明问题。

5.3 装完之后建议做的固化操作

不管哪个系统，装完并验证通过之后，建议做两件事固化环境：

第一，导出依赖清单。conda 环境用conda env export > environment.yml，pip 环境用pip freeze > requirements.txt。这样以后换机器或者重装，直接按清单恢复，不用再回忆装了哪些包。

第二，写一个启动脚本。Windows 上写个 .bat，Ubuntu 上写个 .sh，内容就是激活环境 + 进目录 + 跑 main.py。以后双击或一条命令就能启动，省去每次手动敲的麻烦。

# Ubuntu 启动脚本示例 #!/bin/bash source ~/miniconda3/etc/profile.d/conda.sh conda activate sse cd ~/projects/Semantic-Segmentation-Editor python main.py

6. 安装过程中最容易被卡住的几个点

6.1 PyQt5 装上了但导入报错

这个问题的表现是 pip 显示安装成功，但from PyQt5 import QtWidgets报错。在 Windows 上多半是缺 Visual C++ 运行库，装 vc_redist 即可。在 Ubuntu 上多半是 Qt 插件路径没配好，可以试着设一下环境变量：

export QT_DEBUG_PLUGINS=1

这个变量打开后，再运行程序会打印详细的插件加载日志，能直接看到是哪个插件、哪个库加载失败。这是排查 Qt 问题最有效的手段，比盲目猜要快得多。

6.2 界面能开但图片加载不出来

有时候窗口正常弹出，但打开图片文件夹后列表是空的，或者点图片画布不显示。这通常是图像处理库的问题。检查 Pillow 和 scikit-image 是否装在了当前虚拟环境里，而不是系统环境里。用pip list确认一下。

另一个可能是图片格式不支持。这个工具对常见格式（jpg、png、bmp）支持没问题，但如果是 tiff 或者某些特殊编码的图，可能需要额外装 imagecodecs 之类的包。

6.3 导出掩码值不对

这是最隐蔽的坑。界面画得好好的，导出的掩码拿去训练，发现模型完全不收敛。原因往往是掩码的像素值编码跟你的预期不一致。有的工具导出的是调色板模式的 PNG，直接读出来是索引值；有的是灰度图，值域被压缩过。

我的经验是，导出后一定用 numpy 检查 unique 值，确认它跟你定义的类别索引一一对应。如果不对，要么在工具里改导出设置，要么在训练的数据加载环节做一次映射转换。这个检查花不了两分钟，但能省掉后面几天的调试。

6.4 老系统上的编码问题

Ubuntu 16.04 的默认 locale 有时候是 POSIX，Python 读写文件时如果遇到非 ASCII 路径会报编码错误。可以在启动脚本里加一行：

export LANG=en_US.UTF-8 export LC_ALL=en_US.UTF-8

这样能避免大部分路径编码相关的诡异问题。Windows 上相对少见，但如果项目路径有中文，也建议改成英文。

7. 装好之后怎么把它用顺手

工具装完只是起点，真正影响效率的是使用习惯。分享几个我在实际标注中总结的做法。

第一，类别定义要提前规划好，不要边标边加。类别索引一旦定了，掩码值就定了，中途改索引会导致前面标的数据全部作废。我一般会在一个文本文件里先把类别和索引写死，标注时严格按这个来。

第二，大图先缩放再标。这个工具支持缩放，但标注精度和速度的平衡点通常在 50% 到 100% 之间。太大的图全尺寸标很累，缩太小边缘又画不准。我的做法是先用低缩放快速勾大致轮廓，再放大修边缘。

第三，定期导出备份。标注数据是纯人力堆出来的，丢了很心疼。我习惯每标完一批就导出一次掩码，存到单独的备份目录，不要只依赖工具内部的工程文件。

第四，多类别标注时善用颜色区分。工具里每个类别可以设不同颜色，把对比度高的颜色分配给容易混淆的类别，能显著降低标错的概率。这个细节很小，但实测有效。

关于这个工具本身，它的定位就是一个轻量、本地、够用的语义分割标注器。它不追求功能大而全，但在核心的"画多边形、导掩码"这件事上做得扎实。安装过程虽然有点折腾，但一旦跑通，后面就是纯粹的体力活了。我在两套环境上都跑通了完整流程，Windows 适合快速上手，Ubuntu 适合跟训练环境放一起。选哪个看你的主力工作机是什么，没必要为了装工具专门换系统。