# 使用说明与数据样例

## 1. 样例项目目录

当前样例位于 `work/样例文件`，建议在网页中点击“选择项目文件夹并扫描”，然后选择该目录。

```text
样例文件/
├─ Vpm.xlsx
├─ Vpr.xlsx
├─ 地质分层.xlsx
├─ 副井(0-266)/
├─ 副井(266-554)/
├─ 副井(554-842)/
└─ 副井(842-966.3)/
```

网页将递归读取四个图片目录，图片不需要合并或移动。

## 2. 样例数据内容

| 文件/目录 | 实际内容 | 识别方式 |
| --- | --- | --- |
| `Vpm.xlsx` | `Sheet1`，1930 行，字段为“深度（m）”“声波速度（Vpm）（m）”；数据深度 0-964.0 m，间隔 0.5 m。 | 导入后映射为“深度”“Vpm”。 |
| `Vpr.xlsx` | `Sheet1`，1930 行，字段为“深度（m）”“岩块速度（Vpr）（m/S）”；与 Vpm 同深度点。 | 导入后映射为“深度”“Vpr”。 |
| `地质分层.xlsx` | “地质分层”页：钻孔编号、分层终止深度、岩性、地质描述；共 21 段，最深 966.30 m。 | 映射终止深度、岩性、描述；起深由上一层终止深度自动计算。 |
| `地质分层.xlsx` | “原始数据”页：含深度、VP、Vpr、KV、完整性评价。 | 可作为 Vpr 来源，但推荐使用独立 `Vpr.xlsx`。 |
| 图片目录 | 共 124 张图片，名称如 `0-6.jpg`、`266-274.jpg`、`962-966.3.jpg`。 | 从文件名解析第一个“起深-止深”数值对。 |

## 3. 首次使用步骤

1. 打开 `声波测井岩体完整性评价.html`。
2. 点击“选择项目文件夹并扫描”，选择 `work/样例文件`。
3. 页面依次弹出 Vpm、地质分层、Vpr 的字段映射。确认默认映射，或按列名手工调整后点击“确认导入”。
4. 保持“起深、终深、缺失 Vpr”为空，让网页使用自动范围和导入的 Vpr。
5. 点击“生成/更新评价表”。
6. 检查主表：Vpm 应逐点显示；第一列为地质分层区间；图片列按图片文件名区间合并。
7. 修改 Vpm/Vpr 或备注后，点击“保存 CSV”。

## 4. 样例结果说明

### 4.1 0-6 m 图片块

- 图片：`副井(0-266)/0-6.jpg`。
- 对应测点：0.0、0.5、1.0、...、6.0 m。
- 图片、地质分层区间、岩性描述纵向合并。
- 测点深度、Vpm、Vpr、Kv、完整性和备注逐行显示。

### 4.2 计算示例

| 测点深度 | Vpm | Vpr | Kv | 完整性 |
| --- | ---: | ---: | ---: | --- |
| 0.0 m | 788 | 1400 | 0.316808 | 破碎 |
| 0.5 m | 788 | 1400 | 0.316808 | 破碎 |
| 1.0 m | 776.25 | 1400 | 0.307431 | 破碎 |

计算：`Kv = (Vpm / Vpr)^2`。

## 5. 图片与本地文件说明

- 选择项目文件夹会递归读取子目录中的图片文件，但不会上传图片。
- 浏览器只在本次页面会话中持有文件读取权限；再次打开网页或导入 CSV 后，需要重新选择项目根目录。
- 推荐将 CSV 成果保存到项目根目录或其子目录，图片相对路径可保持稳定。
- 文件名必须有起深和止深。例：`12-18.jpg`、`ZK01_12.0-18.0_岩芯.jpg`。

## 6. 常见问题

| 现象 | 原因与处理 |
| --- | --- |
| 只显示 0 m 一行 | 使用最新版网页；起深、终深、缺失 Vpr 留空。空值应采用自动范围，而不是 0。 |
| 未显示图片 | 再次选择项目根目录；检查文件名是否包含起深-止深。 |
| 第一列区间不对 | 确认导入的是“地质分层”页，并将第二列映射为分层终止深度。 |
| Kv 显示 `--` | Vpr 为空或不大于 0；导入 Vpr、指定缺失 Vpr 或使用经验建议。 |
| Excel 无法导入 | 检查网络以加载 Excel 解析脚本；或将工作表另存为 CSV。 |