SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场portolan-cli

portolan-cli

数据与分析

查看项目

更新于 10-16 04:39

技能介绍

用途

Portolan CLI 是一个用于发布和管理云原生地理空间数据目录的命令行工具。它编排格式转换（GeoParquet、COG）、版本管理以及同步到对象存储（S3、GCS、Azure），无需运行服务器，仅使用静态文件。

Portolan 是 STAC（SpatioTemporal Asset Catalog）的一个 profile，而非竞争规范。其规范定义了目录结构、格式要求和版本规则。

主要能力

  • 格式转换与云优化：支持 GeoParquet（云优化矢量数据）、COG（云优化 GeoTIFF 栅格数据）、COPC（云优化点云数据）、PMTiles（用于 Web 地图渲染的云优化矢量/栅格瓦片）。
  • 版本管理：每个集合遵循语义化版本（主版本：破坏性变更如模式变更、列删除、CRS 变更；次版本：新功能如新列、新条目；补丁：数据更新）。每个集合的 versions.json 记录版本历史及每个资产的 SHA-256 校验和。
  • 同步与存储：支持推送到 S3、GCS、Azure 等对象存储，支持拉取、同步、克隆远程目录。
  • 目录结构：采用扁平层级加 STAC 元数据。单文件集合直接使用集合级资产；分区集合（>2GB）使用每个分区的条目子目录。所有 STAC 链接使用相对路径（SELF_CONTAINED），目录可跨托管位置移植。
  • JSON 输出：所有命令支持 --json 或 --format json，输出统一信封格式 {"success": true, "command": "...", "data": {...}, "errors": []}。
  • Python API：提供 Catalog、FormatType、detect_format 等接口。

使用方式

安装

pipx install portolan-cli    # 隔离安装（推荐）
pip install portolan-cli     # 或使用 pip
uv pip install portolan-cli  # 或使用 uv

主要命令

  • portolan init：初始化新目录，支持 --auto、--title 等选项。
  • portolan scan：扫描目录中的地理空间文件及潜在问题，支持 --json、--max-depth。
  • portolan check：校验目录或检查文件云原生状态，支持 --metadata、--geo-assets、--fix。
  • portolan add：跟踪文件到目录，支持单个文件、多个文件、目录或全部。
  • portolan push：推送本地目录变更到云对象存储，支持 --collection、--dry-run。
  • portolan pull：从远程目录拉取更新，支持 --collection、--dry-run、--workers。
  • portolan sync：同步本地与远程存储（拉取+推送），支持 --fix、--force。
  • portolan clone：克隆远程目录到本地。
  • portolan status：显示集合的本地与远程版本状态，支持 --offline、--json。
  • portolan list：列出目录中所有文件及跟踪状态。
  • portolan info：显示文件、集合或目录信息。
  • portolan rm：移除文件跟踪，支持 --keep、--dry-run、-f。
  • portolan partition：分区大型 GeoParquet 文件以提升查询性能，支持 --preview、--target-rows。
  • portolan extract：从外部源（如 ArcGIS）提取数据到目录，支持 --layers、--filter、--resume。
  • portolan metadata：管理目录元数据以生成 README，支持 init、validate。
  • portolan readme：从 STAC 元数据和 metadata.yaml 生成 README.md，支持 --stdout、--check。
  • portolan stac-geoparquet：生成 items.parquet 以高效查询 STAC。
  • portolan config：管理目录配置，支持 set、get、list。
  • portolan clean：移除所有 Portolan 元数据但保留数据文件，支持 --dry-run。

常见工作流

发布新目录：

portolan init --title "My Geospatial Data"
portolan scan /data/geospatial
portolan check --geo-assets --fix    # 转换为云原生格式
portolan add demographics/
portolan push s3://mybucket/my-catalog --collection demographics

完整同步（推荐）：

portolan sync s3://mybucket/my-catalog --collection demographics
portolan sync s3://mybucket/my-catalog -c demographics --fix

适用场景

  • 需要以静态文件方式发布云原生地理空间数据目录。
  • 需要将矢量、栅格、点云数据转换为云优化格式并同步到对象存储。
  • 需要为地理空间数据目录进行版本管理和校验。
  • 需要从 ArcGIS 等外部源提取数据并纳入目录管理。
  • 需要生成 README 和 STAC 查询文件以支持数据发现。

限制

  • 需要预先安装 Python 环境（pipx、pip 或 uv）。
  • 推送和拉取需要配置对象存储访问权限。
  • 分区集合适用于大于 2GB 的数据。
  • 非云原生文件需通过 portolan check --fix 转换（矢量转 GeoParquet，栅格转 COG）。
  • Shapefile 需确保 .shp、.shx、.dbf 文件齐全。
  • 具体收费、价格、平台支持范围等未在资料中提供。