RAILWISE-CLI 数据格式与导入指南

RAILWISE-CLI 数据格式与导入指南

目标读者：负责数据准备与导入的技术人员、数据处理工程师
预计阅读时间：20 分钟
前置要求：了解基本测量数据格式概念

---

1. 支持的原始数据格式

RAILWISE-CLI 内置解析器支持主流全站仪、水准仪、GNSS 接收机的原始数据格式：

1.1 全站仪数据格式

品牌	格式标识	文件扩展名	说明
徕卡（Leica）	gsi / gsi16	.gsi, .GSI	徕卡 GSI-8 / GSI-16 标准格式
徕卡（Leica）	fiducial	.fid	徕卡 Fiducial 格式
拓普康（Topcon）	topcon-raw	.raw, .RAW	拓普康原始观测格式
拓普康（Topcon）	sdr	.sdr	SDR 数据格式
南方测绘（South）	south-raw	.dat, .DAT	南方全站仪原始格式
天宝（Trimble）	trimble-dc	.dc	Trimble DC 格式
通用	csv	.csv	标准逗号分隔值（需列映射）
通用	json	.json	结构化 JSON 格式

1.2 水准仪数据格式

品牌	格式标识	文件扩展名	说明
徕卡（Leica）	gsi	.gsi	数字水准仪 GSI 格式
天宝（Trimble）	dini	.dini	DiNi 数字水准仪格式
拓普康（Topcon）	topcon-level	.lvl	拓普康水准仪格式
通用	csv-leveling	.csv	标准 CSV 水准数据

1.3 GNSS 数据格式

格式标识	文件扩展名	说明
rinex-obs	.o, .obs	RINEX 观测文件（2.x / 3.x）
rinex-nav	.n, .nav	RINEX 导航电文
trimble-rt17	.rt17	Trimble RT17 格式
ubx	.ubx	u-blox UBX 二进制格式

---

2. 格式详解：徕卡 GSI 格式

2.1 GSI-8 格式结构

*410000+0000000000000000 81..10+0000000000001234 82..10+0000000000005678
*410001+0000000000000001 11..10+0000000000010000 21..10+0000000000020000
 31..10+0000000000030000 51..10+0000000000000000

字段解析：

字段标识	含义	数据类型	示例值
41	点号（Point ID）	字符串	00000001
11	水平方向（Hz）	角度（gon/度）	100.0000
21	垂直角（V）	角度	102.0000
31	斜距（SD）	距离（米）	30.0000
51	棱镜常数（PC）	常数（mm）	0
81	东坐标（E）	坐标（米）	1234.000
82	北坐标（N）	坐标（米）	5678.000
83	高程（H）	高程（米）	详见官方文档

2.2 GSI-16 格式差异

GSI-16 使用 16 位字符宽度，精度更高：

*410000+000000000000000000000000 81..10+0000000000000012345678

提示

CLI 导入时会自动检测 GSI-8 与 GSI-16 格式，无需手动指定。如遇识别错误，可在导入参数中显式声明 format: "gsi16"。

2.3 导入示例

# 基础导入
railwise surveyor import data/station1.gsi --format gsi

# 指定编码与坐标系
railwise surveyor import data/station1.gsi \
  --format gsi \
  --encoding "utf-8" \
  --coordinate-system CGCS2000 \
  --instrument-height 1.600 \
  --prism-height 1.500

# 批量导入目录
railwise surveyor import data/2025-01-15/ \
  --format gsi \
  --recursive \
  --merge-output observations.json

---

3. 格式详解：CSV 通用格式

3.1 CSV 列映射配置

当使用通用 CSV 格式时，需提供列映射文件：

mapping.yaml

csv_format:
  delimiter: ","                      # 分隔符
  header_row: 0                        # 表头行号（0-based）
  encoding: "utf-8"

  column_mapping:
    point_id: "测点编号"
    epoch: "观测日期"                  # 支持日期解析
    easting: "X"                       # 或 E, 东坐标
    northing: "Y"                      # 或 N, 北坐标
    elevation: "H"                     # 或 Z, 高程
    instrument_height: "仪高"
    prism_height: "镜高"
    horizontal_angle: "水平角"
    vertical_angle: "竖直角"
    slope_distance: "斜距"
    face: "盘位"                      # 1=盘左, 2=盘右

  date_format: "yyyy-MM-dd HH:mm:ss"   # 日期格式模板
  coordinate_unit: "meter"             # 坐标单位：meter / millimeter
  angle_unit: "degree"                 # 角度单位：degree / gon / radian

3.2 CSV 导入命令

railwise surveyor import data/observations.csv \
  --format csv \
  --mapping mapping.yaml \
  --output imported.json

---

4. 坐标系统与转换

4.1 内置坐标系统

# .railwise/config.yaml 中配置
coordinate_systems:
  default: "CGCS2000"

  available:
    - name: "CGCS2000"
      epsg: 4490
      type: "geographic"              # geographic / projected / local

    - name: "CGCS2000_3Degree_39"
      epsg: 4511
      type: "projected"
      parent: "CGCS2000"
      projection: "Transverse_Mercator"
      parameters:
        central_meridian: 117.0
        latitude_of_origin: 0.0
        scale_factor: 1.0
        false_easting: 500000.0
        false_northing: 0.0

4.2 自定义地方坐标系

coordinate_systems:
  - name: "宁波地方坐标系"
    type: "local"
    method: "four_parameter"          # 四参数 / 七参数
    parameters:
      dx: 123.456                     # 平移参数 X
      dy: 789.012                     # 平移参数 Y
      rotation: 0.12345               # 旋转角（弧度）
      scale: 1.00000234               # 尺度比
    source_epsg: 4511                 # 源坐标系

4.3 坐标转换命令

# 导入时自动转换
railwise surveyor import data/local.csv \
  --source-crs "宁波地方坐标系" \
  --target-crs "CGCS2000"

# 独立转换已有数据
railwise surveyor transform data/local.json \
  --source-crs "宁波地方坐标系" \
  --target-crs "CGCS2000" \
  --output converted.json

---

5. 数据预处理选项

5.1 导入参数详解

railwise surveyor import <input> [options]

参数	类型	默认值	说明
--format	string	自动检测	数据格式标识
--encoding	string	utf-8	文件编码
--coordinate-system	string	配置文件默认值	目标坐标系
--instrument-height	float	1.600	默认仪器高（米）
--prism-height	float	1.500	默认棱镜高（米）
--temperature	float	20.0	温度（℃），用于气象改正
--pressure	float	1013.25	气压（hPa），用于气象改正
--skip-invalid	boolean	false	跳过无效记录
--merge-sessions	boolean	false	合并多个测回数据
--recursive	boolean	false	递归导入子目录
--output	string	-	输出文件路径
--output-var	string	-	输出变量名（工作流内使用）

### 5.2 气象改正

原始距离观测值支持自动气象改正：

```bash
railwise surveyor import data/obs.gsi \
  --temperature 28.5 \
  --pressure 1005.0 \
  --humidity 65 \
  --apply-meteorological-correction

改正公式依据 GB 50026-2020 附录：

ΔD = (279.66 - 79.53 * e / (273.15 + t)) * D * 10^-6

其中：
  D = 原始斜距（米）
  t = 温度（℃）
  P = 气压（hPa）
  e = 水汽压（hPa），可由相对湿度计算

---

6. 数据导出

6.1 支持的导出格式

# 导出为 CSV
railwise surveyor export data.json --format csv --output out.csv

# 导出为 JSON（结构化）
railwise surveyor export data.json --format json --output out.json

# 导出为 DXF（AutoCAD）
railwise surveyor export data.json --format dxf --output out.dxf

# 导出为 Shapefile（GIS）
railwise surveyor export data.json --format shp --output out.shp

6.2 导出参数

参数	说明
--format	目标格式：csv / json / dxf / shp / kml / gml
--coordinate-system	输出坐标系
--precision	坐标小数位精度
--include-metadata	包含元数据字段
--filter	数据过滤条件

---

7. 常见问题

Q1: 导入中文点号出现乱码？

原因：原始文件使用 GBK/GB2312 编码，CLI 默认按 UTF-8 解析。

解决：

railwise surveyor import data.gsi --encoding "gbk"
# 或先转换编码
iconv -f GBK -t UTF-8 data.gsi > data_utf8.gsi

Q2: 如何导入多个测回数据？

railwise surveyor import data/ \
  --format gsi \
  --merge-sessions \
  --session-pattern "*.gsi"

Q3: 自定义格式如何扩展？

创建自定义解析器插件（详见官方插件开发文档），或先通过脚本转换为 CSV/JSON 标准格式后导入。

Q4: 导入时报 “Unknown instrument model”？

在配置文件中添加仪器型号映射：

instruments:
  custom:
    models: ["MyInstrument-X1"]
    formats: ["csv"]
    parser: "generic_csv"

---

8. 相关文档

• cli-quickstart.md — 快速入门指南
• cli-agents-configuration.md — 智能体配置详解
• cli-workflow-orchestration.md — 工作流编排
• cli-troubleshooting.md — 常见问题排查

---

元数据标签