Metadata-Version: 2.4
Name: miaosuan-terrain
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: maturin>=1.0 ; extra == 'dev'
Provides-Extra: dev
Summary: 高程数据访问包 / Elevation data access package for network simulation engine
Keywords: terrain,elevation,cesium,sqlite,simulation
Author: Miaosuan Team
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://example.com/miaosuan-terrain
Project-URL: Repository, https://example.com/miaosuan-terrain

# miaosuan-terrain

仿真引擎高程数据访问包。

`miaosuan-terrain` 为网络仿真引擎提供统一、稳定的高程查询能力，包括单点高程查询、批量高程查询、链路剖面采样等。该包只负责高程数据的访问、下载、缓存、格式适配和 Provider 抽象，不直接内置大体积高程数据。

## 核心设计

- **Python 包与高程数据分离**：高程数据作为外部数据资产，通过 HTTP 下载并缓存在 Worker 本地。
- **Registry 驱动**：通过 Registry 描述可用数据集、版本、下载地址、覆盖范围等。
- **统一 Provider 接口**：仿真引擎只依赖 `TerrainProvider`，不依赖具体数据格式。
- **本地缓存**：完整 SQLite 高程数据文件下载后原子写入缓存目录，避免运行时依赖网络。

## 安装

```bash
pip install miaosuan-terrain
```

> 发布 wheel 已包含预编译的 Rust 扩展。若从源码安装, 需要 Rust 工具链:
> ```bash
> pip install maturin
> maturin develop --release
> ```

开发依赖：

```bash
pip install -e ".[dev]"
```

## 快速开始

### 通过环境变量配置

```bash
export MIAOSUAN_TERRAIN_REGISTRY_URL=https://example.com/terrain/registry.json
export MIAOSUAN_TERRAIN_DATASET=china-lowres-cesium
export MIAOSUAN_TERRAIN_CACHE_DIR=/var/cache/miaosuan-terrain
```

```python
from miaosuan_terrain import create_provider

terrain = create_provider()

# 单点高程
height = terrain.elevation(39.9042, 116.4074)

# 链路剖面
profile = terrain.profile(
    start_lat=39.90,
    start_lon=116.30,
    end_lat=39.95,
    end_lon=116.45,
    step_m=50,
)
# profile -> [(lat, lon, elevation_m), ...]
```

### 显式指定数据集

```python
terrain = create_provider(
    dataset="china-lowres-cesium",
    registry_url="https://example.com/terrain/registry.json",
    cache_dir="/var/cache/miaosuan-terrain",
)
```

### 直接使用本地 SQLite（测试/离线）

```python
terrain = create_provider(db_path="/path/to/terrain.sqlite")
```

## Registry 格式

```json
{
  "datasets": [
    {
      "id": "china-lowres-cesium",
      "name": "中国低精度 Cesium 高程数据",
      "version": "v2026.06.01",
      "format": "cesium-sqlite",
      "url": "https://example.com/terrain/china-lowres-cesium-v2026.06.01.sqlite",
      "size": 536870912,
      "sha256": "...",
      "coverage": {
        "min_lon": 73.0,
        "min_lat": 18.0,
        "max_lon": 135.0,
        "max_lat": 54.0
      },
      "description": "基于 Cesium terrain 数据合并生成的 SQLite 高程数据文件"
    }
  ]
}
```

## 缓存目录结构

```text
/var/cache/miaosuan-terrain/
  datasets/
    china-lowres-cesium/
      v2026.06.01/
        terrain.sqlite
        metadata.json
        .complete
```



## Rust 加速后端

`miaosuan-terrain` 的核心查询逻辑已使用 Rust + PyO3 重写, 默认通过 `create_provider()` 自动启用 Rust 后端, 不可用时自动回退到纯 Python 实现。

```python
# 强制使用 Rust 后端 (默认)
terrain = create_provider(db_path="/path/to/terrain.sqlite", use_rust=True)

# 强制使用纯 Python 后端
terrain = create_provider(db_path="/path/to/terrain.sqlite", use_rust=False)
```

也可通过环境变量控制:

```bash
export MIAOSUAN_TERRAIN_USE_RUST=true   # 默认 true
```

性能对比 (release 构建, 参考数据 `nasadem-china-10.sqlite`):

| 测试项 | Python | Rust | 加速比 |
|---|---|---|---|
| 单点高程 (cache hot) | ~1.26 ms | ~6.8 µs | **~184x** |
| 批量高程 x100 (cache hot) | ~130 ms | ~0.65 ms | **~200x** |
| 链路剖面 step=50m | ~19.3 ms | ~0.12 ms | **~160x** |
| 单点高程 (cold multi-tile) | ~457 µs | ~186 µs | **~2.5x** |

完整基准测试见 `benchmarks/` 目录。

## 支持的数据格式

当前第一阶段支持：

- `cesium-sqlite`：由 tileserver-go `convert` 命令生成的 SQLite 文件，内部存储 gzip 压缩的 Cesium quantized-mesh-1.0 `.terrain` 瓦片。

后续可扩展：

- GeoTIFF / COG
- 多数据集自动选择
- 流式读取

## 模块结构

```text
miaosuan_terrain/
  __init__.py
  provider.py                # TerrainProvider 抽象接口
  factory.py                 # create_provider 工厂
  registry.py                # Registry 解析
  cache.py                   # 本地缓存管理
  providers/
    cesium_sqlite.py         # 纯 Python Cesium SQLite Provider
    cesium_sqlite_rust.py    # Rust 后端 Python 包装
  utils/
    download.py              # HTTP 下载
    checksum.py              # 文件校验
    geo.py                   # 地理计算
src/
  lib.rs                     # Rust 核心实现
Cargo.toml                   # Rust 构建配置
pyproject.toml               # maturin 配置
```

## 测试

```bash
PYTHONPATH=. python3 -m pytest tests/ -v
```

## 许可证

MIT

