视频教程：CLI 数据导入与格式转换

视频教程：CLI 数据导入与格式转换

视频时长：约 15 分钟
难度：中级
前置要求：已完成 CLI 安装与首条命令执行（见 视频教程：CLI 安装与首条命令）

---

视频概述

本视频详细讲解 RAILWISE-CLI 的数据导入与格式转换功能。工程现场使用的测量仪器品牌众多，数据格式各异，本教程将帮助您掌握：

1. 主流仪器原始数据格式（GSI、RAW、TXT 等）的导入方法
2. CSV、JSON 等通用格式的导入与映射配置
3. 坐标系统之间的批量转换
4. 批量导入与自动化处理技巧

视频内容结构

章节	时间点	内容
支持的格式概述	00:00 - 01:30	CLI 支持的数据格式清单、适用场景
徕卡 GSI 格式导入	01:30 - 04:00	GSI-8/GSI-16 格式解析、导入命令、常见问题
拓普康 RAW 格式导入	04:00 - 06:00	RAW 格式解析、导入命令、参数配置
CSV 格式导入	06:00 - 08:30	CSV 列映射、自定义分隔符、编码处理
JSON 格式导入	08:30 - 10:00	JSON 结构解析、嵌套数据提取
坐标系统转换	10:00 - 12:30	CGCS2000、地方坐标系、WGS84 转换
批量导入	12:30 - 14:00	批量文件处理、通配符、目录遍历
常见问题	14:00 - 14:45	乱码、格式错误、缺失字段处理
课后练习	14:45 - 15:00	练习任务布置

---

前置知识

1. 已完成 CLI 安装与首条命令 教程
2. 了解常见测量仪器数据格式的基本概念
3. 熟悉文件编码（UTF-8、GBK 等）的基本概念

---

步骤详解

步骤 1：支持的格式概述（00:00 - 01:30）

视频画面：格式支持矩阵表格展示

RAILWISE-CLI 支持以下数据格式：

格式	文件扩展名	适用仪器品牌	自动识别	备注
GSI	.gsi	徕卡（Leica）	✅	GSI-8 / GSI-16
RAW	.raw	拓普康（Topcon）	✅	原始观测数据
TXT	.txt	索佳（Sokkia）、南方测绘	✅	文本格式
CSV	.csv	通用	✅	需配置列映射
JSON	.json	通用	✅	结构化数据
DXF	.dxf	AutoCAD	✅	图形数据导入
Excel	.xlsx, .xls	通用	✅	多工作表支持
RINEX	.obs, .nav	GNSS	✅	GPS/北斗观测数据

[截图占位符：格式支持矩阵界面]

---

步骤 2：徕卡 GSI 格式导入（01:30 - 04:00）

视频画面：GSI 文件内容展示、导入命令执行

GSI 格式简介

GSI（Geo Serial Interface）是徕卡仪器的标准数据格式，分为 GSI-8 和 GSI-16 两种：

• GSI-8：每个数据字段 8 位，精度较低
• GSI-16：每个数据字段 16 位，精度较高，推荐使用

GSI 文件示例

*110001+0000000000001089 21.324+0000000000002947 22.324+0000000000001567 31..00+0000000000000000
*110002+0000000000002098 21.324+0000000000002951 22.324+0000000000001572 31..00+0000000000000000
*110003+0000000000003105 21.324+0000000000002945 22.324+0000000000001569 31..00+0000000000000000

导入命令

# 基本导入
railwise surveyor import data/leveling_data.gsi --format gsi

# 指定仪器型号
railwise surveyor import data/leveling_data.gsi \
  --format gsi \
  --instrument leica_ls15 \
  --encoding utf-8

# 导入并指定坐标系统
railwise surveyor import data/survey_data.gsi \
  --format gsi \
  --coordinate-system CGCS2000 \
  --output data/imported.json

导入参数说明

参数	说明	示例值
--format	数据格式	gsi, raw, csv, json
--instrument	仪器型号	leica_ls15, leica_ts16, topcon_gm52
--encoding	文件编码	utf-8, gbk, iso-8859-1
--coordinate-system	坐标系统	CGCS2000, WGS84, 宁波独立坐标系
--output	输出文件	data/output.json
--verbose	详细输出	显示解析过程

[截图占位符：GSI 导入命令执行与输出结果]

---

步骤 3：拓普康 RAW 格式导入（04:00 - 06:00）

视频画面：RAW 文件内容展示、导入命令执行

RAW 格式简介

拓普康 RAW 格式是拓普康仪器的原始数据格式，包含完整的观测信息。

RAW 文件示例

TOPCON RAW DATA
JOB:Survey_20250615
DATE:2025-06-15
TIME:08:30:15

STN:1
XYZ:1000.000,2000.000,50.000
BS:2,0.00000

SD:1001,150.235,1.523,289.3520,89.1523
SD:1002,200.567,1.456,125.4523,90.0125

导入命令

# 基本导入
railwise surveyor import data/survey_data.raw --format raw

# 指定拓普康仪器
railwise surveyor import data/survey_data.raw \
  --format raw \
  --instrument topcon_gm52 \
  --encoding utf-8

[截图占位符：RAW 导入命令执行与输出结果]

---

步骤 4：CSV 格式导入（06:00 - 08:30）

视频画面：CSV 文件编辑、列映射配置、导入执行

CSV 格式简介

CSV 是最通用的数据交换格式，但需要配置列映射以正确解析。

CSV 文件示例

point_id,x,y,z,date,time,instrument,observer
P001,1000.000,2000.000,50.000,2025-06-15,08:30:00,TS16,张工
P002,1100.500,2100.300,51.200,2025-06-15,08:35:00,TS16,张工
P003,1200.800,2200.600,52.100,2025-06-15,08:40:00,TS16,张工

列映射配置

创建 mappings/csv_mapping.yaml：

# CSV 列映射配置
csv_mapping:
  # 必需列
  required_columns:
    - point_id
    - x
    - y
    - z

  # 列映射（CSV列名 → 内部字段名）
  column_mapping:
    point_id: "point_id"
    x: "coordinate_x"
    y: "coordinate_y"
    z: "coordinate_z"
    date: "observation_date"
    time: "observation_time"
    instrument: "instrument_id"
    observer: "observer_name"

  # 数据类型
  data_types:
    point_id: "string"
    x: "float"
    y: "float"
    z: "float"
    date: "date"
    time: "time"

  # 坐标系统
  coordinate_system: "CGCS2000"

  # 分隔符
  delimiter: ","

  # 编码
  encoding: "utf-8"

  # 跳过行数
  skip_rows: 1  # 跳过表头

导入命令

# 使用列映射导入
railwise surveyor import data/survey_data.csv \
  --format csv \
  --mapping mappings/csv_mapping.yaml

# 自动推断列映射（简单 CSV）
railwise surveyor import data/simple_data.csv \
  --format csv \
  --auto-map

[截图占位符：CSV 列映射配置界面与导入结果]

---

步骤 5：JSON 格式导入（08:30 - 10:00）

视频画面：JSON 文件结构展示、导入命令执行

JSON 格式简介

JSON 是结构化数据格式，适合程序生成的数据或 API 响应数据。

JSON 文件示例

{
  "project": "宁波地铁3号线监测",
  "date": "2025-06-15",
  "observations": [
    {
      "point_id": "P001",
      "coordinates": {
        "x": 1000.000,
        "y": 2000.000,
        "z": 50.000
      },
      "observation_time": "2025-06-15T08:30:00+08:00",
      "instrument": "TS16-001",
      "observer": "张工"
    },
    {
      "point_id": "P002",
      "coordinates": {
        "x": 1100.500,
        "y": 2100.300,
        "z": 51.200
      },
      "observation_time": "2025-06-15T08:35:00+08:00",
      "instrument": "TS16-001",
      "observer": "张工"
    }
  ]
}

导入命令

# 基本导入（自动解析结构）
railwise surveyor import data/survey_data.json --format json

# 指定数据路径（嵌套 JSON）
railwise surveyor import data/survey_data.json \
  --format json \
  --json-path "observations"  # 指定数据数组路径

# 导入并转换坐标系统
railwise surveyor import data/survey_data.json \
  --format json \
  --json-path "observations" \
  --coordinate-system CGCS2000 \
  --output data/converted.json

[截图占位符：JSON 导入命令执行与输出结果]

---

步骤 6：坐标系统转换（10:00 - 12:30）

视频画面：坐标转换命令执行、转换前后数据对比

支持的坐标系统

坐标系统	EPSG 代码	适用地区
CGCS2000	4490	全国统一
WGS84	4326	GPS 全球
北京54	4214	历史项目
西安80	4610	历史项目
宁波独立坐标系	自定义	宁波地区
上海独立坐标系	自定义	上海地区

坐标转换命令

# 单个文件转换
railwise surveyor convert data/wgs84_data.json \
  --from WGS84 \
  --to CGCS2000 \
  --output data/cgcs2000_data.json

# 批量转换目录
railwise surveyor convert data/raw/*.gsi \
  --from 宁波独立坐标系 \
  --to CGCS2000 \
  --output-dir data/converted/

# 转换并指定中央子午线
railwise surveyor convert data/local_data.csv \
  --from 地方坐标系 \
  --to CGCS2000 \
  --central-meridian 121.467 \
  --false-easting 500000 \
  --output data/cgcs2000_data.csv

自定义坐标系统配置

编辑 .railwise/config.yaml：

coordinate_systems:
  custom:
    - name: "宁波独立坐标系"
      type: "gauss_kruger"
      params:
        ellipsoid: "CGCS2000"
        central_meridian: 121.467
        false_easting: 500000
        false_northing: 0
        scale_factor: 1.0

[截图占位符：坐标转换命令执行与结果对比]

---

步骤 7：批量导入（12:30 - 14:00）

视频画面：批量文件处理、通配符使用、目录遍历

批量导入命令

# 使用通配符批量导入
railwise surveyor import data/*.gsi \
  --format gsi \
  --output data/batch_imported.json

# 递归导入子目录
railwise surveyor import data/**/*.gsi \
  --format gsi \
  --recursive \
  --output data/all_imported.json

# 按日期筛选导入
railwise surveyor import data/*.gsi \
  --format gsi \
  --date-from 2025-06-01 \
  --date-to 2025-06-15 \
  --output data/june_imported.json

# 批量导入并自动合并
railwise surveyor import data/*.csv \
  --format csv \
  --mapping mappings/csv_mapping.yaml \
  --merge \
  --output data/merged.json

批量导入工作流

name: "批量数据导入工作流"
description: "批量导入并处理多期观测数据"

steps:
  - name: "批量导入 GSI 文件"
    agent: "surveyor"
    action: "batch_import"
    input: "data/2025-06/*.gsi"
    params:
      format: "gsi"
      instrument: "leica_ts16"
      merge: true
    output_var: "all_data"

  - name: "数据质检"
    agent: "inspector"
    action: "check"
    input_var: "all_data"
    params:
      checks: ["完整性", "一致性"]

  - name: "坐标转换"
    agent: "surveyor"
    action: "convert"
    input_var: "all_data"
    params:
      from: "宁波独立坐标系"
      to: "CGCS2000"
    output: "data/processed/all_cgcs2000.json"

[截图占位符：批量导入命令执行与进度展示]

---

关键操作要点

要点 1：编码问题处理

# 检测文件编码
file -i data/survey_data.gsi
# 输出：text/plain; charset=iso-8859-1

# 转换编码
iconv -f GBK -t UTF-8 data/survey_data.gsi > data/survey_data_utf8.gsi

# 批量转换编码
for f in data/*.gsi; do
  iconv -f GBK -t UTF-8 "$f" > "${f%.gsi}_utf8.gsi"
done

要点 2：缺失字段处理

# CSV 映射配置中的默认值
csv_mapping:
  column_mapping:
    point_id: "point_id"
    x: "coordinate_x"
    y: "coordinate_y"
    z: "coordinate_z"

  # 默认值
  default_values:
    coordinate_system: "CGCS2000"
    instrument: "TS16-001"
    observer: "未知"
    observation_date: "{{today}}"

要点 3：数据验证规则

# 导入时验证
csv_mapping:
  validation:
    rules:
      - field: "coordinate_x"
        type: "range"
        min: 0
        max: 1000000

      - field: "coordinate_y"
        type: "range"
        min: 0
        max: 1000000

      - field: "coordinate_z"
        type: "range"
        min: -100
        max: 1000

      - field: "point_id"
        type: "pattern"
        regex: "^P[0-9]{3}$"

---

常见问题（FAQ）

Q1: 导入后中文字符显示乱码？

原因：文件编码与系统编码不一致。

解决：

# 检测编码
file -i data.gsi

# 转换后重新导入
iconv -f GBK -t UTF-8 data.gsi > data_utf8.gsi
railwise surveyor import data_utf8.gsi --encoding utf-8

Q2: CSV 导入提示 “列映射错误”？

原因：CSV 列名与映射配置不匹配。

解决：

1. 检查 CSV 文件表头是否与映射配置一致
2. 使用 --auto-map 自动推断
3. 修改映射配置文件匹配实际列名

Q3: 坐标转换后位置偏差很大？

原因：中央子午线或投影参数设置错误。

解决：

# 检查当前坐标系统参数
railwise config get coordinate_systems

# 重新配置正确的中央子午线
railwise surveyor convert data.json \
  --from 地方坐标系 \
  --to CGCS2000 \
  --central-meridian 121.467  # 确认正确的中央子午线

Q4: 批量导入时部分文件失败？

原因：文件格式不一致或文件损坏。

解决：

# 使用 --continue-on-error 跳过错误文件
railwise surveyor import data/*.gsi \
  --continue-on-error \
  --error-log import_errors.log

# 查看错误日志
cat import_errors.log

Q5: 如何导入 Excel 文件？

# 导入 Excel（自动识别第一个工作表）
railwise surveyor import data/survey_data.xlsx --format excel

# 指定工作表
railwise surveyor import data/survey_data.xlsx \
  --format excel \
  --sheet "观测数据"

# 指定单元格范围
railwise surveyor import data/survey_data.xlsx \
  --format excel \
  --sheet "观测数据" \
  --range "A1:H100"

---

课后练习

练习 1：多格式导入对比

下载同一组数据的 GSI、CSV、JSON 三种格式，分别导入并对比结果一致性。

练习 2：自定义坐标系统

配置一个自定义坐标系统（使用您所在地区的中央子午线），将示例数据从 CGCS2000 转换到该坐标系统。

练习 3：批量导入脚本

编写一个脚本，自动导入某目录下所有 GSI 文件，按日期排序，合并为一个 JSON 文件。

练习 4：数据质量检查

导入一组包含错误数据的 CSV 文件，使用质检功能识别并标记异常数据。

---

相关文档链接

• CLI 安装与首条命令 — 前置教程
• CLI 智能体配置与工作流 — 智能体配置教程
• CLI 数据格式与导入 — 详细格式说明
• CLI 常见问题与故障排查 — 故障排查手册

---

视频资源

• 视频文件：video-cli-03-data-import.mp4
• 示例数据包：sample-data-formats.zip（含 GSI、RAW、CSV、JSON 示例）
• 讲义下载：handout-cli-03.pdf
• 字幕文件：video-cli-03-data-import.srt

---

元数据标签

---

本文档最后更新于 2025-06-15 | 版本 v1.0.0 | 宁波睿威工程技术有限公司 版权所有