# @maplat/tin 中文文档

规范地址：https://npmcn.com/package/%40maplat/tin/

版本：1\.1\.1
npm 元数据更新时间：2026-11-01T17:47:13.335Z
中文译文更新时间：2026-11-01T20:00:26.680Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40maplat/tin
原文对照：https://npmcn.com/package/%40maplat/tin/?lang=original
项目主页：https://github.com/code4history/MaplatTin/wiki
源码仓库：https://github.com/code4history/MaplatTin

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

- 包体积（解压后）：400 kB，35 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- 首次发布：2019-09-15T10:42:16.918Z
- 最新版本发布：2026-11-01T17:47:13.007Z
- 已发布版本数：37（近 12 个月 12 个）

## 中文简介

JavaScript库，基于控制点在两个平面的坐标系之间相互执行同胚转换。

## 安装

```sh
npm install @maplat/tin
```

也可以使用：`pnpm add @maplat/tin`、`yarn add @maplat/tin`、`bun add @maplat/tin`

## README

# MaplatTin

[![CI](https://github.com/code4history/MaplatTin/actions/workflows/ci.yml/badge.svg)](https://github.com/code4history/MaplatTin/actions/workflows/ci.yml) [![License](https://img.shields.io/npm/l/@maplat/tin)](https://npmcn.com/package/%40maplat/tin/LICENSE)

## 关于MaplatTin

mapplattin是一个定义和执行同态的JavaScript库 基于控制点的两平面坐标系之间的转换。它 保证了一个非线性但保持拓扑的（同胚）双向 映射，这是允许 [Maplat](https://github.com/code4history/Maplat) 查看器叠加历史 精确的现代地图上的地图 **不扭曲原始图像**.

mapplattin是在Apache许可证2.0下开源的（从0.14.2版本开始）。

**[阅读本文档的日语版本](https://npmcn.com/package/%40maplat/tin/README.ja.md)**

## 关键特性

-   **生成转换定义** -创建坐标变换 基于控制点和边缘约束的定义
-   **双向坐标变换** -转换坐标 两个方向上的两个平面
-   **拓扑保存** -在期间保持同胚性质 转换
-   **灵活的配置** -顶点处理模式(正常/鸟瞰 视图)，拓扑检查模式（严格/自动/松散），y轴方向控制
-   **边缘约束** -指定约束边缘以获得更精确的转换
-   **状态管理** -保存和恢复转换定义
-   开源（从0.14.2版本开始的Apache 2.0）——是Maplat生态系统的一部分

## 快速入门

> **当前版本: `1.1.1`**． 这个街区是唯一一个 这个存储库携带一个发布版本（ADR-0012）；外面的一切都是 针对1.0版本编写的。 npm: [`@maplat/tin`](https://www.npmjs.com/package/@maplat/tin) [![npm](https://img.shields.io/npm/v/@maplat/tin)](https://www.npmjs.com/package/@maplat/tin)

### 安装

```bash
# pnpm (recommended)
pnpm add @maplat/tin

# npm
npm install @maplat/tin
```

### 最小的使用

```typescript
import Tin from '@maplat/tin';

// Create a new instance with basic configuration
const tin = new Tin({
  wh: [500, 500], // Width and height of the source plane
  yaxisMode: Tin.YAXIS_FOLLOW,
});

// Set control points: Array of [source, target] coordinates
tin.setPoints([
  [[100, 100], [200, 200]],
  [[200, 200], [400, 400]],
  [[150, 150], [320, 350]],
  [[200, 100], [420, 220]],
]);

// Initialize the TIN network
tin.updateTin();

// Forward transform: source to target
const transformed = tin.transform([160, 160], false);

// Backward transform: target to source
const restored = tin.transform(transformed, true);
```

### CDN (jsDelivr)

```html
<!-- MaplatTin (UMD) -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/tin@1.1.1/dist/maplat_tin.umd.js"></script>
<script>
  const tin = new maplatTin.default({ wh: [500, 500] });
</script>
```

或者使用ES模块：

```html
<script type="module">
  import Tin from 'https://cdn.jsdelivr.net/npm/@maplat/tin@1.1.1/dist/maplat_tin.js';
  const tin = new Tin({ wh: [500, 500] });
</script>
```

_注意：请确保使用最新的兼容版本。_

### API参考

-   **API签名** (release-dependent):明白了 [`docs/api/`](https://npmcn.com/package/%40maplat/tin/docs/api/)
-   **概念性指南** （release-independent）：参见 [Wiki api参考](https://github.com/code4history/MaplatTin/wiki/API-Reference)

### 开发

#### 设置

克隆存储库并安装依赖项。

```bash
git clone https://github.com/code4history/MaplatTin.git
cd MaplatTin
pnpm install
```

#### 开发服务器

使用热重新加载启动开发服务器。

```bash
pnpm dev
```

#### 构建

```bash
pnpm build         # Build library (dist/)
pnpm build:demo    # Build demo site (dist-demo/)
```

#### 测试

```bash
pnpm test          # Run unit tests (Vitest)
pnpm typecheck     # Run type checks (TypeScript)
pnpm lint          # Run linter and formatter (ESLint/Prettier)
```

测试覆盖率:

-   `tests/edgebound/` -内部EdgeBound约束引擎测试（455个测试）
-   `tests/tin.test.ts` -使用真实地图数据进行TIN转换测试
-   `tests/transform.test.ts` -坐标变换测试

## 先决条件

> 源自 `engines` 场 `package.json` (adr - 0012: release-dependent)。

-   node . js: `>=20.0.0` （通过GitHub Actions测试LTS）
-   规划: `>=9.0.0` (要求; `package.json` 实施规划)

## 生态系统

MaplatTin是Maplat生态系统的一部分 [历史代码](https://github.com/code4history). 查看完整的生态系统地图（8个存储库+产品/企业网站）：

📖 **生态系统图** - - - - - - _(该图目前保存在一个私人规划中 库;下面的姊妹存储库表是公共替代品)_

### 妹妹存储库

| 存储库 | 许可证 | npm | 角色 |
| --- | --- | --- | --- |
| [Maplat](https://github.com/code4history/Maplat) | Apache 2.0 | `@maplat/ui` | 主要查看器 |
| [MaplatCore](https://github.com/code4history/MaplatCore) | Apache 2.0 | `@maplat/core` | 核心库 |
| [MaplatTin](https://github.com/code4history/MaplatTin) | Apache 2.0 | `@maplat/tin` | 锡转换 |
| [MaplatTransform](https://github.com/code4history/MaplatTransform) | Apache 2.0 | `@maplat/transform` | 坐标变换 |
| [MaplatEditor](https://github.com/code4history/MaplatEditor) | Apache 2.0 | \- - - - - - | 数据创作工具（桌面） |
| [楚辞](https://github.com/code4history/Chuci) | 麻省理工学院 | `@c4h/chuci` | 多媒体滑动器和查看器Web组件 |
| [屈原](https://github.com/code4history/Quyuan) | 麻省理工学院 | `@c4h/quyuan` | GeoJSON模板引擎+多媒体浏览器Web组件 |
| [Weiwudi](https://github.com/code4history/Weiwudi) | 麻省理工学院 | `@c4h/weiwudi` | Service Worker用于tile缓存 |

> mapplateditor是用于创建地图和poi的数据创作工具 上面的观众渲染。Maplat生态系统是端到端的： 作者与mapplateditor，服务于任何查看器库。

## 链接

| 观众 | 链接 | 目的 |
| --- | --- | --- |
| 项目信息/功能/案例 | [https://www.maplat.jp/en/](https://www.maplat.jp/en/) | 产品网站 |
| 赞助商/业务查询 | [https://www.nayuta-inc.co.jp/en/](https://www.nayuta-inc.co.jp/en/) | 公司网站（Nayuta, Inc.） |

> ADR-0013: apache许可的存储库（这个）链接到两个站点。 麻省理工学院授权的姊妹reppos （Weiwudi / Quyuan / chui）没有Nayuta链接。

## 许可证

Apache License 2.0 -参见 [许可证](https://npmcn.com/package/%40maplat/tin/LICENSE).

```
Copyright 2019-2026 Kohei Otsuka, Code for History / Nayuta, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

> **专利的通知**： Maplat坐标变换技术获得专利 日本（专利号：6684776）。

> **过去的版本**： 0.14.2之前的版本在 Maplat有限许可1.1。license恢复到Apache 2.0需要 1.0.0-rc1版本生效。早期版本可在npmjs.com上获得 保持在原始的有限许可条款下。

## 贡献者

-   大冢浩平表示
-   历史代码

我们欢迎您的贡献！欢迎提交 [问题和拉取请求](https://github.com/code4history/MaplatTin/issues).

## 常见问题

### @maplat/tin 是什么？

JavaScript库，基于控制点在两个平面的坐标系之间相互执行同胚转换。

### 如何安装 @maplat/tin？

在项目目录运行 npm install @maplat/tin，或使用 pnpm add / yarn add / bun add。

### @maplat/tin 支持 TypeScript 吗？

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

### @maplat/tin 支持 ESM 还是 CommonJS？

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

### @maplat/tin 需要什么版本的 Node\.js？

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

### @maplat/tin 可以商用吗？

@maplat/tin 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @maplat/tin 还在维护吗？

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