学视觉算法（ OpenCV 、Open3d）的人，大概都经历过一个阶段：

函数看得懂，流程也知道，甚至 API 文档都收藏了不少。
但一到自己真正上手，还是会卡在最现实的问题上：

参数到底该怎么调？

比如：

• Canny 的两个阈值到底差多少才合适？
• GaussianBlur 的 sigma 改大之后，图像到底是“更干净”还是“更糊”？
• 形态学开运算、闭运算，看名字像懂了，结果一跑图才发现还是没概念

这些问题，单靠看教程其实不太容易真正吃透。
因为图像处理这件事，很多时候不是“知道原理”就够了，你还得看到变化本身。

所以我做了一个小项目，叫 cvAlgoVis。

它本质上是一个可交互的计算机视觉实验工作台：
前端负责实时调参和展示，后端用视觉算法处理图像并返回结果。
你改一个参数，界面就立刻刷新，不需要反复改代码、保存、重跑、再对比。

如果你也在学传统视觉，或者平时需要演示算法效果，这个工具可能会比你想象中更顺手。

软件介绍

简单说，cvAlgoVis 是一个把“图像处理实验”做成交互式界面的项目。

技术栈不复杂，也很常见：

• 前端：React + TypeScript + Vite
• 后端：FastAPI + OpenCV + NumPy
• 测试：Pytest

但它的价值不在于“用了什么技术”，而在于它把一件本来很碎的事串起来了：

• 原图
• 处理后结果
• 参数调节
• 代码片段

以前这些东西通常分散在不同窗口里。
现在它们被收拢到一个四方格工作台里，学习和演示的体验会顺很多。

界面布局

主页采用四方格布局：

• 左上：效果显示区（处理后图像）
• 右上：参数设置区
• 左下：原始图像区
• 右下：代码区

这套布局的好处很直接：

你不需要在“代码编辑器、图片预览、参数说明、终端输出”之间来回切换。
所有关键信息都在一个屏幕里，而且位置相对稳定，盯一会儿就习惯了。

尤其是做演示的时候，这种布局非常舒服。
别人可以很直观地看到：

“你刚才调了哪个参数，它让图像发生了什么变化，对应代码又是什么。”

这和单纯给一张结果图，是完全不一样的。

核心的价值：能看懂

我越来越觉得，很多人学不进去 OpenCV，不是因为它难,而是因为它缺少一个“参数和结果之间的直觉桥梁”。

文档告诉你：

• threshold1
• threshold2
• kernel_size
• sigma
• iterations

但它不会告诉你，
当你把这个值从 3 改成 7 的时候，图像会有什么变化。

所以在 cvAlgoVis 里，我比较在意两件事：

1. 参数变化要实时看到结果

不是调完再跑一次，不是保存后再打开图。
而是调完立刻看到变化。

2. 参数不能只有控件，还要有解释

右上角参数区除了滑块和输入框，还尽量给出一些简要说明。
至少让你知道：这个参数在控制什么，它为什么会影响结果。

这件事看起来很小，但对初学者非常重要。
因为“知道自己在调什么”，和“盲调”完全不是一种学习体验。

九大类算法

现在这个仓库，已经把opencv常见的视觉算法整理成九大类，基本够做一套比较完整的学习和演示路线：

1. 颜色与强度处理

• RGB / HSV / YUV / Lab
• HDR 增强

2. 几何变换

• 仿射
• 透视
• 旋转
• 缩放
• 平移
• 倾斜

3. 阈值与二值化

• 二值化
• 自适应阈值
• 全局阈值
• Otsu

4. 去噪与平滑

• Gaussian
• Median
• Mean
• Bilateral

5. 形态学处理

• 开运算
• 闭运算
• 梯度
• 黑帽
• 白帽
• 顶帽
• 底帽

6. 梯度与边缘检测

• Canny
• Laplacian

7. 图像分割

• Watershed
• GrabCut

8. 特征检测与描述

• Harris
• Shi-Tomasi
• FAST
• SIFT
• SURF
• ORB
• LBP
• HOG

9. 匹配与检索

• KNN
• BF
• FLANN
• Template Match
• Template Match + Homology

说白了，这已经不只是一个“演示几个滤波效果”的小玩具了。
它更像一个可以继续长大的可视化实验平台。

代码区

我不太喜欢那种“界面看着很热闹，但代码区只是摆设”的项目。

所以这里每个算法都尽量配了对应的 Python 代码片段，
右下角代码区可以直接看，也可以直接复制。

而且代码高亮不是纯前端随便糊一下，
是后端通过 Pygments 生成，主题用了 Monokai。
看起来会舒服很多，也更适合做演示截图。

另外，代码区还支持字号调节。
这个细节其实挺实用的，特别是投屏讲解或者录屏的时候。

软件设计

除了功能本身，我比较看重它的结构是不是“好继续做”。

cvAlgoVis 这点上还挺顺的。

现在整个系统的思路大概是：

• 后端通过 catalog 统一维护算法、模块和参数定义
• 前端启动后先拉 /catalog
• 再根据返回结果自动渲染算法选择和参数面板
• 参数变化后，前端节流调用 /process
• 后端返回处理后的图像
• /code-snippet 再提供对应算法的代码片段和高亮内容

这个设计的好处是：
如果以后继续加算法，不用每次都从头重新设计前端表单。
只要把算法实现、参数定义和 snippet 补进去，整条链路就能跟着长。

这会让项目越做越像“平台”，而不是一个一次性 demo。

最适合哪些人

1. 正在学 OpenCV 的同学

如果你已经能看懂一些基础函数，但还没有形成“参数直觉”，这个项目会非常合适。

2. 需要做演示的人

不管是课程展示、社团分享、比赛答辩，还是组内讲解，这种可视化方式都很直观。

3. 做实验和调参的人

很多时候你只是想快速看看不同参数对结果的影响，
这时候一个能实时反馈的可视化工作台，效率真的会高很多。

本地跑起来也不复杂

后端：

cd backend
python -m venv .venv

Windows：

.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

前端：

cd frontend
npm install
npm run dev

如果你用的是 Git Bash，建议优先用：

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

这样可以避开 uvicorn: command not found 这类环境问题。

最后想说点更实在的

我一直觉得，技术项目最怕两件事：

• 只会展示结果，不关心理解过程
• 只顾堆功能，不顾使用体验

而 cvAlgoVis 最让我满意的地方，是它正在努力避免这两件事。

它不是想把所有算法都塞进来，而是想让你在“看结果、调参数、读代码”这条链路上走得更顺一点。

你可以把它当成一个学习工具。
也可以把它当成一个演示工具。
或者，干脆把它当成你之后扩展更多视觉算法的一个起点。

如果你对传统视觉、算法教学、参数实验这些方向感兴趣，这个项目值得去看一眼。

仓库地址在这里：

https://github.com/CryptoPyGeek/cvAlgoVis

如果你觉得这个方向有意思，欢迎顺手点个 Star。
也欢迎继续提 issue、提 PR，把这个小工具慢慢打磨成一个更完整的可视化视觉实验平台。

后续我会将open3d算法放入到软件中去