# ocean-cli

**Repository Path**: leoZhangs/ocean-cli

## Basic Information

- **Project Name**: ocean-cli
- **Description**: 读取 NetCDF 文件中的变量，经过标准化管道（解包 + 经度翻滚 + 纬度翻转），支持 BMP 图像和 CSV 文本两种输出格式。1D 变量直接打印到终端，2D+ 变量默认输出 BMP 图像，可通过 --format csv 导出带坐标标签的 CSV 文件。支持双变量矢量运算（模长、加减乘除），运算结果经裁剪抽稀后输出。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: NetCDF

## README

# ocean-cli

面向海洋数值模式数据的 NetCDF 处理库与命令行工具集，C++17 编写，基于 netCDF-C 实现。

## 项目结构

| 目录 | 说明 |
|------|------|
| `data` | 核心数据容器（GridData / GridDataset / Value）与运算、处理管道 |
| `data_reader` | 数据读取器（NetCDF / 图片等），含标准化管道（解包 + 经度翻滚 + 纬度翻转） |
| `data_writer` | 数据写出器（NetCDF / BMP） |
| `thirdparty/netcdf_cxx` | netCDF 的 C++ 封装层 |
| `app/ncp` | 命令行工具：查询、导出 BMP/CSV、双变量矢量运算 |

## 命令行工具

# ncp — NetCDF 数据查询与导出工具

读取 NetCDF 文件中的变量，经过标准化管道（解包 + 经度翻滚 + 纬度翻转），支持 BMP 图像和 CSV 文本两种输出格式。1D 变量直接打印到终端，2D+ 变量默认输出 BMP 图像，可通过 `--format csv` 导出带坐标标签的 CSV 文件。支持双变量矢量运算（模长、加减乘除），运算结果经裁剪抽稀后输出。

---

## 构建

```bash
cmake --preset linux-release
cmake --build build/linux-release --target ncp
```

## 命令格式

```
ncp <文件路径> [选项]
```

## 选项

| 选项 | 说明 |
|------|------|
| `-i, --info` | 打印文件元数据（维度、变量、全局属性） |
| `-v, --variable <名称>` | 变量名 |
| `-o, --output <路径>` | 输出文件路径。`-` 在 CSV 模式下输出到 stdout |
| `--lon <min,max>` | 经度裁剪范围，如 `100,160` |
| `--lat <min,max>` | 纬度裁剪范围，如 `10,40` |
| `--width <N>` | 输出宽度（像素），抽稀降采样 |
| `--height <N>` | 输出高度（像素），抽稀降采样 |
| `--level <索引>` | 额外维度索引，逗号分隔。不足自动补 0 |
| `--colormap <gray\|jet>` | 色彩映射（BMP 模式），默认 jet |
| `--format <auto\|bmp\|csv>` | 输出格式。auto: 1D→终端 2D+→BMP（默认） |
| `--compute <method>` | 矢量运算：`magnitude`\|`add`\|`sub`\|`mul`\|`div` |
| `--var2, --variable2 <名称>` | 第二个变量名（`--compute` 时必需） |
| `--file2 <路径>` | 第二个 nc 文件路径（默认同主文件） |
| `--level2 <索引>` | 第二个变量的层级索引（默认同 `--level`） |

## 处理管道

```
NetCDF 文件
  │
  ├── readGridDatasetF / readGridData          ← 按维度索引读取
  │   └── 解包 (scale_factor + add_offset + _FillValue → NaN)
  │   └── 经度翻滚 (归一化到 [-180, 180])
  │   └── 纬度翻转 (归一化为升序)
  │
  ├── [矢量模式] 双变量 → magnitude / elementWiseOp
  │
  ├── [可选] SpatialSubsetProcessor            ← 经纬裁剪 + 间隔抽稀
  │
  └── 输出: saveAsBMP / writeCSV2D
```

## 使用示例

### 查看元数据

```bash
ncp ocean.nc -i
```

### 列出变量

```bash
ncp ocean.nc
```

### 单变量 → BMP

```bash
# 全分辨率 Jet 色图
ncp ocean.nc -v temp

# 指定输出路径
ncp ocean.nc -v temp -o result/temp.bmp

# 灰度图
ncp ocean.nc -v temp --colormap gray
```

### 裁剪 + 抽稀

```bash
# 裁剪到东海区域，降采样到 360×180
ncp ocean.nc -v temp \
    --lon 100,160 --lat 10,40 \
    --width 360 --height 180
```

### 多维度层级

```bash
# 4D 数据 (time, depth, lat, lon) → time=0, depth=5
ncp 4d_ocean.nc -v temp --level 0,5

# 3D 数据 (depth, lat, lon) → depth=5
ncp 3d_data.nc -v var --level 5

# --level 不足时自动补 0：等价于 --level 5,0
ncp 4d_ocean.nc -v temp --level 5
```

### 1D 坐标 → 终端

```bash
ncp ocean.nc -v st_ocean
```

输出：
```
st_ocean
1.0000,3.0985,5.8719,9.4416,...共54个值
```

### CSV 导出

```bash
# 2D 变量 → CSV，首行经度标签，首列纬度标签，4 位小数
ncp ocean.nc -v temp --level 0,0 --format csv

# 裁剪抽稀后输出 CSV
ncp ocean.nc -v temp --lon 100,160 --lat 10,40 \
    --width 10 --height 8 --format csv -o crop.csv

# 输出到 stdout
ncp ocean.nc -v temp --width 5 --height 4 --format csv -o -
```

CSV 格式示例：
```
      ,-179.9500,-107.9500,-35.9500,36.0500,108.0500
-81.9500,     nan,     nan,     nan,    nan,     nan
-38.9500,  20.6063,  17.5163,  20.2600,21.2475,17.9313
  4.0500,  29.4112,  28.5475,  28.3213,    nan,     nan
```

### 矢量运算

```bash
# 同文件双变量 → 风速模长
ncp uv.nc -v u --var2 v --compute magnitude

# 双文件双变量
ncp u.nc -v ua --file2 v.nc --var2 va --compute magnitude

# 差异场 (u - v) 裁剪输出
ncp uv.nc -v u --var2 v --compute sub \
    --lon 100,160 --lat 10,40 --width 360 --height 180

# 不同层级运算
ncp uv.nc -v u --level 0 --var2 v --level2 5 \
    --compute add --format csv -o add.csv

# 其他运算: add / sub / mul / div
ncp data.nc -v a --var2 b --compute mul
```

输出默认命名：`{var1}_{compute}_{var2}.{bmp|csv}`，如 `u_magnitude_v.bmp`。

## 错误处理

| 场景 | 行为 |
|------|------|
| 文件不存在 | 报错退出 (exit 1) |
| 变量名不存在 | 打印可用变量列表 |
| `--level` 索引越界 | 打印维度名及允许范围 |
| `--compute` 缺 `--var2` | 提示 `--var2` 必需 |
| 读取/处理失败 | 打印错误信息，exit 1 |