cognis-digital/geopulse
GitHub: cognis-digital/geopulse
geopulse 是一个开源的态势感知数据引擎，将多个公开灾害与事件数据源标准化并导出为 ATAK 和 Google Earth 可直接使用的格式。
Stars: 0 | Forks: 0
# geopulse
**开放态势感知数据引擎。** geopulse 拉取**真实的、公开的**信息源
涵盖多个领域——地震、野火、恶劣天气、火山、
灾害、航空 (ADS-B)、空间天气、海啸以及地缘政治 OSINT ——
将它们标准化为单一的事件模型，并**将其导出为你可直接导入**
[ATAK](https://tak.gov/) (Android Team Awareness Kit)
和 [Google Earth](https://earth.google.com/) 的格式。**
像 worldmonitor.app 这样的查看器会为你展示实时地图。geopulse 的优势在于解决另一半问题：**让数据变得可移植**——一条有效的 Cursor-on-Target
数据流、一个 ATAK Data Package，或者一个可直接拖入操作员和响应人员日常使用工具的 Google Earth KMZ 文件。
## 为什么会有这个项目
公共信息源生态系统内容丰富但较为分散：USGS 使用 GeoJSON，NWS 使用
CAP，GDACS 使用 GeoRSS，FIRMS 使用 CSV，OpenSky 使用位置数组。
它们都不讲 **CoT**，也不会生成 **ATAK Data Package**，而且要将它们中的任何一个干净利落地导入 Google Earth（包括文件夹、样式、时间戳）都需要手动操作。
geopulse 就是这个适配层：
```
public feeds ─┐
(9 sources) ├─► normalized Event ─► exporters ─► CoT / ATAK DP / KML / KMZ / GeoJSON
┘ (model.py)
```
## 安装
**前置条件：** Python **3.10+**（3.10 / 3.11 / 3.12 已通过 CI 测试）和 `git`。
geopulse **没有第三方依赖项**——核心完全是基于纯标准库
（`urllib` + `xml` + `zipfile`）构建的。不需要编译器，也不需要构建工具。
安装程序会在 `./.venv` 中创建一个隔离的 virtualenv，以可编辑模式安装 geopulse，验证 CLI，并打印接下来的步骤。它们是幂等的——可以安全地
重复运行。
**Make targets** (带有 GNU make 的 Linux/macOS/Windows): `make install` · `make test`
· `make demo` · `make lint` · `make clean` · `make docker`。
**运行它：** 安装后，在 venv 内你的 PATH 中就会有 `geopulse` 命令。
`python -m geopulse ` 也可以在任何地方使用（如果在 Windows 上 `Scripts\` 不在
PATH 中，这会很有用）。设置 `GEOPULSE_OFFLINE=1`（或传递 `--offline`）可以纯粹依靠
捆绑的示例运行，无需联网。
## 快速开始
```
# 哪些是有线的，以及在什么 license 下？
geopulse list-sources
# 一条命令：live feeds -> 一个 ATAK 数据包
geopulse export --category all --format datapackage --out sa.zip
# 一条命令：live feeds -> 一个 Google Earth KMZ
geopulse export --category all --format kmz --out sa.kmz
# 单个类别，离线（捆绑示例），作为 Cursor-on-Target 文件
geopulse --offline export --category earthquakes --format cot --out cot/
# 为您自己的 pipeline 获取原始的规范化 events
geopulse pull-all --out events.json
```
一切都**离线**可用。每个源都附带一个小型**捆绑示例**（真实的
数据源 schema），因此测试、演示和 `--offline` 运行都不需要联网。在线时，
`fetch`/`export` 会访问真实的 endpoint，并且只有在 endpoint
无法访问时才回退到示例。**geopulse 绝不伪造数据。**
## 类别 × 数据源 × 许可证
| 类别 | 数据源 | Endpoint | 许可证 / 条款 |
|---|---|---|---|
| earthquakes | USGS Earthquake Hazards Program | `earthquake.usgs.gov/.../summary/all_day.geojson` | 公共领域 (USGS / U.S. Gov work) |
| wildfires | NASA FIRMS (VIIRS S-NPP NRT) | `firms.modaps.eosdis.nasa.gov/api/area/csv/...` | NASA 开放数据，免费（需署名）。实时的 Area API 需要一个免费的 `MAP_KEY` → 设置 `GEOPULSE_FIRMS_KEY`；也存在无需密钥的归档数据 |
| weather | NOAA / NWS Alerts (CAP) | `api.weather.gov/alerts/active` | 公共领域 (NOAA) |
| volcanoes | USGS Volcano Hazards Program (+ Smithsonian GVP ref) | `volcanoes.usgs.gov/vsc/api/volcanoApi/elevated` | 公共领域 (USGS)；建议对 GVP 进行署名 |
| disasters | GDACS (Global Disaster Alert & Coordination System) | `gdacs.org/xml/rss.xml` | 免费使用，需署名 (JRC EC / UN OCHA) |
| aviation | OpenSky Network (ADS-B) | `opensky-network.org/api/states/all` | 非商业/研究用途免费使用（需署名） |
| spaceweather | NOAA SWPC | `services.swpc.noaa.gov/products/alerts.json` | 公共领域 (NOAA) |
| tsunami | NOAA NWS Tsunami Warning System (PTWC/NTWC) | `api.weather.gov/alerts/active?event=Tsunami...` | 公共领域 (NOAA) |
| geopolitical | GDELT Project (geolocated OSINT news) | `api.gdeltproject.org/api/v2/geo/geo` | 开放数据，免费使用需署名 |
**关于授权：** geopulse 链接至每个数据源并对其进行署名；它在本地 `~/.cache/geopulse` 下缓存获取的
数据（可通过 `GEOPULSE_CACHE` 覆盖），但**不会**捆绑或重新分发任何受许可的数据集。特别是，它特意
使用 **GDELT（开放）** 进行 OSINT 事件地理定位，而**不**使用受许可的
ACLED。只有在数据源是公开/开放许可的情况下才添加新数据源，并在此表和 `Source.license` 中注明其条款。
## 标准化的 `Event`
每个 fetcher 都会发出 `geopulse.model.Event`：
| 字段 | 含义 |
|---|---|
| `id` | **确定性**派生自 SHA1 的 id（`geopulse--`），以便在重复运行时进行去重 |
| `category` | 九个规范类别之一 |
| `lat`, `lon` | WGS84 十进制小数度 |
| `time` | 事件时间，**带时区的 UTC** |
| `severity` | 粗略的顺序：`info < minor < moderate < severe < extreme` |
| `title`, `description` | 人类可读的文本 |
| `attrs` | 特定于数据源的附加信息（magnitude、FRP、callsign、alert level 等） |
| `source`, `source_url`, `license` | 出处，带入每次导出中 |
## 导出器
| 格式 | 文件 | 你将获得什么 |
|---|---|---|
| **Cursor-on-Target 2.0** | `export/cot.py` | 格式良好的 `` XML，包含 `version/type/time/start/stale/uid`、``、``（`contact`/`remarks`/`color` + 出处）。仅包含良性的 SA 类型代码。 |
| **ATAK Data Package** | `export/datapackage.py` | 一个 `.zip` 文件，包含根目录下的 `MANIFEST.xml`（`MissionPackageManifest` v2），每个事件对应一个 `/.cot`，以及一个 `overlays/geopulse.kml` 叠加层。可直接导入 ATAK。 |
| **KML / KMZ** | `export/kml.py` | 每个类别对应一个 ``，每个事件对应一个带有 ``/`` 的 ``，以及按类别的 `