# GeoAI Workbench 本地实验控制台

这是一个完全独立于无人机产品的本地实验工作台。它以“新建运行、案例库、结果
工作区”展示能力：允许的能力可以上传受限文件类型并运行固定本地脚本，但不提供
删除、覆盖、任意路径或任意命令执行。地图会直接请求公开 ArcGIS 影像切片；配置
天地图 token 后还会直接请求天地图影像和注记切片。

## 启动

首次使用先安装和构建前端：

```powershell
Set-Location .\apps\workbench-console
npm install
npm run build
Set-Location ..\..
```

再从仓库根目录运行：

```powershell
py -3.12 .\scripts\serve_workbench_console.py
```

然后在浏览器打开 <http://127.0.0.1:6173>。服务默认只监听本机回环地址；若端口
已占用，可以显式传入另一个 `6xxx` 端口：

```powershell
py -3.12 .\scripts\serve_workbench_console.py --port 6174
```

开发 Vue 页面时，保持结果服务在 `6173`，并在另一个 PowerShell 中运行：

```powershell
Set-Location .\apps\workbench-console
npm run dev
```

Vite 开发服务固定使用 `http://127.0.0.1:6174/apps/workbench-console/`，会通过本机代理读取 `6173` 的结果工件。

## 地图底图

Cesium 默认加载公开 ArcGIS World Imagery 底图。要叠加天地图影像和注记，在
`apps/workbench-console/.env.local` 中填写下列值后重新执行 `npm run build`：

```text
VITE_TIANDITU_TOKEN=<your-token>
```

Change detection also exposes the read-only `GET /api/change-detection/scans` endpoint. The page renders the low-cost parameter scan contact sheet, a selected threshold/area overlay, scan metrics, and downloads for the three materialized candidate GeoJSON results without presenting the scan as a formal model run.

The change-detection page also accepts a user-submitted parameter scan: upload a before/after pair, select threshold and minimum-area combinations (up to 24), choose processing mode/resolution, and start a background job. Poll `GET /api/change-detection/scan-jobs/<job-id>` until it completes; the resulting scan then appears in the read-only scan workspace with overlays, statistics, and GeoJSON artifacts.

普通图片的最小连通区域使用处理后影像的 px 面积，只用于滤除零碎噪声，与 CRS 无关。参数扫描允许该选项留空，留空时自动使用 `256 px`；需要比较保留小目标和过滤噪声的差异时再多选面积组合。变化检测二进制上传会对文件名做 URL 百分号编码，因此中文文件名可以安全通过浏览器请求头，服务端解码后仍会执行扩展名白名单和安全文件名处理。

若某一组合没有检测到变化，结果区会显示 0 个图斑，并提供空 GeoJSON 下载，不会将“无变化”误报成处理失败。

规则四边形与原始图斑都从同一份已清理掩膜逐区生成。最小连通区域仅按像素在掩膜阶段应用一次，避免在 GeoTIFF 地图单位中二次过滤而遗漏图斑；因此新生成的原始图斑数、规则四边形数和对应掩膜区域数一致。旧扫描成果不会被覆盖；修复后会以新的扫描成果供人工复核和转为正式案例。

扫描结果不会自动进入案例库。确认某个组合后，在扫描结果区点击“将当前组合转为正式案例”，控制台会通过 `POST /api/change-detection/scans/<scan-id>/promote` 创建新的正式运行目录；成功后刷新案例库即可查看。正式案例优先展示规则四边形，仍提供原始不规则图斑、掩膜和概率栅格下载。GeoTIFF 结果同时提供源 CRS 和 EPSG:4326 矢量；普通图片结果使用 px 像素坐标。

可先参考同目录的 `.env.example`。`VITE_` 变量会被打包进本地浏览器代码，因此
只应填入适合客户端使用的天地图访问 token，不要填入其他服务密钥。

## 目录职责

- `apps/workbench-console/src/`：Vue 3 组件、路由、Pinia 状态与能力适配层。
- `apps/workbench-console/dist/`：Vite 构建产物（不提交 Git）。
- `scripts/serve_workbench_console.py`：本地控制台服务和受限运行 API；仅暴露构建后的控制台、结果工件与必要原图，且只调用固定虚拟环境和能力脚本。
- `shared/outputs/`：能力原始输出；控制台不复制、不修改这些文件。

当前已接入 `00-change-detection`、`01-object-detection`、`02-semantic-mapping`、`04-spatial-measurement`、`09-anomaly-detection` 和 `15-trajectory-analysis`。变化检测案例显示两期原图、变化叠加、像素坐标 GeoJSON 图斑和概率/配准指标；上传接口只接受一对 JPG/JPEG/PNG/TIF/TIFF，服务端固定调用 `.venvs/00-change-detection`。异常检测分别上传正常参考影像和待检测影像，展示原图、方法对比、热力图、候选表和下载工件。田墩实飞案例会显示
实飞轨迹、计划航线、禁飞区与适飞区，并提供轨迹和区域范围的聚焦按钮。其他能力
保留目录和边界状态，待其首个 Demo 产出可检查工件后再接入。
## 本地运行工作台

控制台现支持可操作的本地实验运行，并保持与无人机产品完全独立。能力页面提供新建运行入口和可搜索扩展的案例库，案例由本地服务从运行目录自动发现，不再依赖前端硬编码 Tabs。

- 轨迹分析上传 `XLSX`、`KMZ`、禁飞区 `GeoJSON` 和可选适飞区 `Gzip`，原始、处理和输出分别归档在 `shared/data/raw`、`shared/data/processed`、`shared/outputs`。
- 目标检测上传最多 12 张 `JPG/JPEG/PNG`，原图和标注图默认并列对比，每次生成独立运行编号。
- 语义分割上传最多 6 张 `JPG/JPEG/PNG/TIF/TIFF`，任务预设从能力目录动态读取；当前只有通用颜色流程可运行，排洪沟、边坡、竖井和尾矿库任务在模型与真值齐备前保持禁用。结果展示原图、栅格叠加、GeoJSON 矢量预览、类别比例和可下载工件。
- 空间测量上传最多 4 份 `PNG/TIF/TIFF` 单波段标签栅格，展示彩色栅格、GeoAI 矢量对象、计数、面积、周长和对象明细；只有有效投影 CRS 才使用地图单位。
- 变化检测上传一对 `JPG/JPEG/PNG/TIF/TIFF`，每次运行可选择自动识别、普通图片或 GeoTIFF 地理参考模式；阈值支持 `0.01～0.99`（默认 `0.5`），分辨率支持 GeoTIFF 原始分辨率/自动以及 `1024/1536/2048/3072` 档位。GeoTIFF 模式保留 CRS 和地图坐标，普通图片模式输出像素坐标。单文件最大 `1024 MB`，单次 Base64 JSON 请求最大 `3072 MB`。
- 异常检测分别上传 1～6 张正常参考影像和 1～6 张待检测影像，支持 `JPG/JPEG/PNG/TIF/TIFF`。3 张以上固定机位且全部尺寸一致时自动启用同位置规则和通用局部外观/结构变化通道，否则回退为全局规则；局部通道不使用颜色或物品类别规则。结果页显示实际选择的模式。大文件使用二进制流，后台任务完成后进入案例库；结果展示参考输入、待检测原图、规则/Isolation Forest 对比、热力图、候选区字段与下载工件。案例列表右侧的“复用输入”会把该案例的原始参考图、待检测图和四项可编辑参数回填到新运行表单，不自动启动检测，也不修改历史案例。
- 本地 API 还包括 `GET/POST /api/change-detection/runs` 和 `PUT /api/change-detection/uploads/<upload-id>`；变化检测前端使用二进制流上传，服务端按原字节暂存并复制到独立 raw、processed 和 output 目录，不修改原始 TIFF，也不覆盖既有运行。
- 本地 API 为 `GET/POST /api/trajectory/runs`、`GET/POST /api/object-detection/runs`、`GET/POST /api/semantic-mapping/runs`、`GET/POST /api/spatial-measurement/runs`、`GET/POST /api/anomaly-detection/runs` 和只读的 `GET /api/semantic-mapping/tasks`；异常检测另有二进制上传和后台任务状态端点。服务仅监听回环地址，端口必须是 `6xxx`，只调用固定虚拟环境和能力脚本，不接受任意命令或任意路径。