# @arcnautical/maritime-routing 中文文档

规范地址：https://npmcn.com/package/%40arcnautical/maritime-routing/

版本：1\.0\.1
npm 元数据更新时间：2026-09-18T14:50:15.038Z
中文译文更新时间：2026-11-06T21:44:23.408Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arcnautical/maritime-routing
原文对照：https://npmcn.com/package/%40arcnautical/maritime-routing/?lang=original
项目主页：https://github.com/arcnautical/maritime-routing
源码仓库：https://github.com/arcnautical/maritime-routing

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：590 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-03-22T20:10:58.145Z
- 最新版本发布：2026-09-18T14:50:14.857Z
- 近 30 天下载量：2306（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

出产级出海航道发动机——A\*出海航道勘察,Dijkstra出海航道点出海航道,510+出海口数据库,有气象意识的ETA,EEZ分析. 零从属.

## 安装

```sh
npm install @arcnautical/maritime-routing
```

也可以使用：`pnpm add @arcnautical/maritime-routing`、`yarn add @arcnautical/maritime-routing`、`bun add @arcnautical/maritime-routing`

## README

# @ arcaniz/ 海洋路线

[![npm version](https://img.shields.io/npm/v/@arcnautical/maritime-routing.svg?style=flat-square)](https://www.npmjs.com/package/@arcnautical/maritime-routing) [![npm downloads](https://img.shields.io/npm/dm/@arcnautical/maritime-routing.svg?style=flat-square)](https://www.npmjs.com/package/@arcnautical/maritime-routing) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://npmcn.com/package/%40arcnautical/maritime-routing/LICENSE) [![Tests: 42 passing](https://img.shields.io/badge/tests-42%20passing-success?style=flat-square)](https://npmcn.com/package/%40arcnautical/maritime-routing/tests/maritime-routing.test.mts) [![Zero dependencies](https://img.shields.io/badge/dependencies-0-success?style=flat-square)](https://npmcn.com/package/%40arcnautical/maritime-routing/package.json) [![GitHub stars](https://img.shields.io/github/stars/arcnautical/maritime-routing?style=flat-square)](https://github.com/arcnautical/maritime-routing)

用于JavaScript/TypeScript的生产级海上通路引擎. **零从属.**

计算全世界任何两个港口之间的现实海洋航道,保证能避让土地、了解天气的ETA和专属经济区过境分析.

## 为什么会这样

每一个航运技术的启动都重塑了海上航道。 现有的开源选项( :[海路号](https://www.npmjs.com/package/searoute-js) ——自2020年以来未保持,使用2000年数据)生产使用不足. 商业API每年收费600-6900欧元.

此库取自 [弧线](https://arcnautical.com/),海洋风险情报平台. 对1 790条真实世界路线进行了测试,陆地过境率为0%.

> **这个引擎能驱动活航风险产品.** `@arcnautical/maritime-routing` 是开源核心 [弧线](https://arcnautical.com/)是因为 车道风险情报。 live app take any profile - > 目的地航道并给它打分 制裁曝光 海盗/冲突 窒息性依赖和天气 然后电子邮件给你 a 该具体走廊的路由风险简介.
> 
> 在您自己的车道上尝试一下 - 完整的计算结果显示为没有注册 : **[https://arcaniz.com (中文(简体) )](https://arcnautical.com/)**

## 特征

| 特性 | 说明 |
| --- | --- |
| **A. 海洋路径调查** | 从OpenStreetMap衍生出0.05°海洋位图上的道路(7200x3600细胞). 路线保证永不跨越陆地. |
| **Dijkstra 路口路线** | 48个战略阻塞点(苏伊士,巴拿马,马六甲,直布罗陀等地)有相距加权图路由. |
| **510+ 港口数据库** | 联合国/LOCODE标准。 按姓名、国家或代码搜索。 包括坐标、港口类型和海洋区域. |
| **天气速度模型** | 基于Beaufort的减速(Kwon,2008年;Lu等2015年). 每个船型和装载条件。 具有Cbeta因子的方向意识. |
| **EEZ 过境分析** | 检测哪个专属经济区是过境路线。 制裁也包括在内. |
| **避免区域** | 环绕用户指定多边形(如海盗区,冲突地区)的路线. |
| **路由点** | 强制路线通过特定的坐标. |
| **GeoJSON 输出** | 所有路线作为GeoJSON LineString返回,准备进行地图渲染. |

## 安装

```bash
npm install @arcnautical/maritime-routing
```

需要节点.js QQ 18.

## 快速启动

```ts
import { computeRoute } from '@arcnautical/maritime-routing';

// Compute a route from Singapore to Rotterdam
const route = computeRoute('SGSIN', 'NLRTM');

console.log(route.distance_nm);        // ~8,440 nm
console.log(route.duration_hours);      // ~603 hours at 14 knots
console.log(route.waypoints.length);    // waypoints transited
console.log(route.hazard_zones_crossed); // chokepoints on route

// GeoJSON for map rendering
const geojson = route.route_geojson;
// -> FeatureCollection with LineString geometry
```

## API 参考

### 路由计算

```ts
import {
  computeRoute,
  computeRouteInternal,
} from '@arcnautical/maritime-routing';

// Simple route (returns handler-compatible format)
const route = computeRoute('SGSIN', 'NLRTM');

// Route with options
const route = computeRoute('SGSIN', 'NLRTM', {
  avoid_zones: [[[30, 12], [50, 12], [50, 32], [30, 32], [30, 12]]], // avoid Red Sea
  via_waypoints: [{ lat: -34.4, lon: 18.5 }], // force via Cape of Good Hope
});

// Internal format (with segment breakdown)
const internal = computeRouteInternal('SGSIN', 'NLRTM');
console.log(internal.segments);       // per-leg distance + bearing
console.log(internal.totalDistanceNm);
console.log(internal.geojson);        // GeoJSON Feature
```

### 海洋路径调查

```ts
import { findOceanPath } from '@arcnautical/maritime-routing';

// Find a path between two coordinates
// Returns [lon, lat][] (GeoJSON convention)
const path = findOceanPath(1.26, 103.84, 51.90, 4.50);
// -> ~500 coordinate pairs, guaranteed to never cross land

// Performance: 8-50ms for typical segments
// Automatically subdivides routes > 5,000nm
```

### 端口数据库

```ts
import {
  searchPorts,
  getPortByLocode,
  getPortsByRegion,
  resolveAisDestination,
  findNearestPort,
  PORTS,
} from '@arcnautical/maritime-routing';

// Search by name, country, or LOCODE
const ports = searchPorts('Singapore');    // [{ locode: 'SGSIN', ... }]
const ports = searchPorts('Japan', 50);   // up to 50 results

// Exact lookup
const sg = getPortByLocode('SGSIN');      // { name: 'Singapore', lat: 1.26, ... }

// By region
const medPorts = getPortsByRegion('mediterranean'); // 30+ ports

// Parse messy AIS destination strings
const port = resolveAisDestination('NL RTM');   // -> Rotterdam
const port = resolveAisDestination('>>SGSIN<<'); // -> Singapore

// Find nearest port to coordinates
const port = findNearestPort(51.9, 4.5);  // -> Rotterdam

// All 510+ ports
console.log(PORTS.length);
```

### 天气速度模型

```ts
import {
  computeSeaStateFactor,
  computeRouteEta,
  windToBeaufort,
  waveToBeaufort,
} from '@arcnautical/maritime-routing';

// Compute speed reduction from weather
const result = computeSeaStateFactor({
  baseSpeedKnots: 14,
  waveHeightM: 3.0,
  windSpeedKt: 25,
  swellHeightM: 1.5,
  vesselType: 'bulk',     // container | bulk | tanker | lng | general
  loadCondition: 'laden', // laden | ballast
  // Optional direction-aware inputs:
  waveDirectionDeg: 270,
  vesselHeadingDeg: 90,   // heading into waves = worst case
});

console.log(result.effectiveSpeedKnots); // reduced speed
console.log(result.beaufortNumber);      // 6
console.log(result.speedReductionPct);   // % reduction
console.log(result.seaStateFactor);      // 0-1 retention

// Compute ETA for a full route
const eta = computeRouteEta(
  segments,          // [{ distanceNm, bearing }]
  segmentWeather,    // per-segment weather data
  14,                // base speed (knots)
  'container',       // vessel type
  'laden',           // load condition
);
console.log(eta.totalTransitHours);
console.log(eta.worstSegmentIndex);
```

### EEZ 过境分析

```ts
import { analyzeRouteEezTransit } from '@arcnautical/maritime-routing';

const result = analyzeRouteEezTransit(segments, totalDistanceNm);

for (const eez of result.transitEezs) {
  console.log(`${eez.countryName}: ${(eez.routeFraction * 100).toFixed(1)}%`);
  if (eez.isSanctioned) console.log('  ⚠ SANCTIONED');
}

console.log(result.sanctionedEezFraction); // 0-1
console.log(result.summary);              // human-readable
```

### 大地测量设施

```ts
import {
  haversineDistance,
  haversineDistanceNm,
  bearing,
  interpolateGreatCircle,
  pointInPolygon,
} from '@arcnautical/maritime-routing';

// Distance in nautical miles
const nm = haversineDistanceNm(1.26, 103.84, 51.90, 4.50); // ~5,700

// Initial bearing (degrees)
const brg = bearing(1.26, 103.84, 51.90, 4.50); // ~315°

// Great circle arc interpolation
const points = interpolateGreatCircle(0, 0, 45, 90, 100);
// -> 101 [lat, lon] pairs along the arc

// Point-in-polygon test
const inside = pointInPolygon(5, 5, [[0,0], [10,0], [10,10], [0,10]]);
```

## 数据来源

| 数据 | 来源 | 许可证 |
| --- | --- | --- |
| 海洋网格 | OpenStreetMap 水多边形 | ODbL 数据 |
| 端口数据库 | UN/LOCODE+公共海洋数据 | 公有领域 |
| 速度模型 | Kwon 2008,Lu等2015 (英语) | 学术文献 |
| 专属经济区边界 | 联合国大陆架界限委员会/佛兰德海洋研究所 | 公有领域 |
| 路径图 | 公共海事知识 | 不详 |

## 业绩

| 运行 | 时间 |
| --- | --- |
| 端口查询( LOCODE) | < 0.1毫米口径 |
| 端口搜索( 按名称) | < 1 分钟 |
| 海洋路径调查(单一部分) | 8-50毫米口径 |
| 完全路线计算(新加坡-鹿特丹) | 约250米 |
| 速度模型计算 | < 0.1毫米口径 |
| 网格装入( 只有第一次通话) | ~900毫秒( x) |

包大小:~200KB (编译JS)+106KB (海洋网格)+90KB (EEZ数据).

## 与海道的比较

| 特性 | @ arcaniz/ 海洋路线 | 海路号 |
| --- | --- | --- |
| 上次更新 | 2026 (英语) | 2020 (英语) |
| 类型脚本 | 土著 | 没有 |
| 依赖关系 | **无** | 多个 |
| 回避土地 | **保证d** (位图) | 没有( 仅是图表) |
| 端口数据库 | 510+ 港口 | 无 |
| 天气模型 | Beaufort + 克贝塔 | 无 |
| 专属经济区分析 | 对 | 无 |
| 避免区域 | 对 | 没有 |
| 路由点 | 对 | 没有 |
| 狭窄的通道 | 苏伊士,巴拿马,博斯普鲁斯等地. | 有限 |
| 决议 | 0.05°(~5.5公里) | 变量 |
| 数据来源 | OSM (2024) (英语) | ORNL(2000年) |

## 高级使用

### 自定义海洋网格

```ts
import { setGridPath, loadGridFromBuffer } from '@arcnautical/maritime-routing';

// Use a custom grid file
setGridPath('/path/to/my-ocean-grid.bin.gz');

// Or load from a buffer (e.g., fetched from CDN)
const buffer = await fetch('https://cdn.example.com/ocean-grid.bin.gz')
  .then(r => r.arrayBuffer());
loadGridFromBuffer(new Uint8Array(buffer));
```

### 生成自己的海洋网格

海洋网由OSM水多形文件产生:

```bash
# Download water polygons from osmdata.openstreetmap.de
# Then run the generator:
npx tsx scripts/generate-ocean-grid.ts /path/to/water_polygons.shp
```

### 海洋区域

港口分为16个海洋区,用于通航:

`pacific`, (中文(简体) ), `south_china_sea`, (中文(简体) ), `southeast_asia`, (中文(简体) ), `indian_ocean`, (中文(简体) ), `persian_gulf`, (中文(简体) ), `red_sea`, (中文(简体) ), `mediterranean`, (中文(简体) ), `atlantic_north`, (中文(简体) ), `atlantic_south`, (中文(简体) ), `caribbean`, (中文(简体) ), `north_sea`, (中文(简体) ), `baltic`, (中文(简体) ), `black_sea`, (中文(简体) ), `arctic`, (中文(简体) ), `oceania`, (中文(简体) ), `east_pacific`

### 船舶类型

速度模型支持5个具有明显海上维护特征的船只类型:

| 类型 | 引用速度 | 典型的西北地区 |
| --- | --- | --- |
| `container` | 20千吨 | 50 000-200 000美元 |
| `bulk` | 14千吨 | 30 000-400 000人 |
| `tanker` | 14千吨 | 5万至320 000美元 |
| `lng` | 19亿吨 | 70 000-180 000人 |
| `general` | 14千吨 | 5 000至40 000人 |

## 许可证

麻省理工学院 - 看 [自由主义](https://npmcn.com/package/%40arcnautical/maritime-routing/LICENSE)。 。 。 .

## 关于

由 [弧线](https://arcnautical.com/) ——为车队管理人员,承销商,合规团队提供海上风险情报.

ArcNatical提供航行风险分数、制裁筛选、海盗/冲突威胁情报和自动合规报告。 您使用的路由引擎 为我们的商业平台提供了动力.

如果你需要超出航道的海上风险情报, [联系](https://arcnautical.com/)。 。 。 .

## 常见问题

### @arcnautical/maritime-routing 是什么？

出产级出海航道发动机——A\*出海航道勘察,Dijkstra出海航道点出海航道,510\+出海口数据库,有气象意识的ETA,EEZ分析\. 零从属\.

### 如何安装 @arcnautical/maritime-routing？

在项目目录运行 npm install @arcnautical/maritime-routing，或使用 pnpm add / yarn add / bun add。

### @arcnautical/maritime-routing 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arcnautical/maritime-routing 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @arcnautical/maritime-routing 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @arcnautical/maritime-routing 可以商用吗？

@arcnautical/maritime-routing 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @arcnautical/maritime-routing 的下载量有多少？

根据 npm 官方下载统计，@arcnautical/maritime-routing 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,306 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arcnautical/maritime-routing 还在维护吗？

最新版本 1\.0\.1 发布于 2026/09/18（1 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/03/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。