# @allmaps/annotation 中文文档
规范地址：https://npmcn.com/package/%40allmaps/annotation/
版本：1\.0\.0-beta\.38
npm 元数据更新时间：2026-10-01T09:24:30.658Z
中文译文更新时间：2026-11-05T22:31:12.296Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40allmaps/annotation
原文对照：https://npmcn.com/package/%40allmaps/annotation/?lang=original
项目主页：https://allmaps.org/
源码仓库：https://github.com/allmaps/allmaps
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：487 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2021-01-28T08:58:57.758Z
- 最新版本发布：2026-09-22T07:06:18.328Z
- 近 30 天下载量：11936（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 3 个）
## 中文简介
生成和解析 IIIF 地理参考说明的函数
## 安装
```sh
npm install @allmaps/annotation
```
也可以使用：`pnpm add @allmaps/annotation`、`yarn add @allmaps/annotation`、`bun add @allmaps/annotation`
## README
# @allmaps/注释
剖析和生成地理参考说明.
## 如何运作
此模块可以生成和剖析 [地理参考说明](https://iiif.io/api/extension/georef/)。 。 。 .
A 类 **地理参考注释** 是一个 [网络注释](https://www.w3.org/TR/annotation-model/) 存储所需的元数据 [地理参考](https://en.wikipedia.org/wiki/Georeferencing) (单位:千美元) [IIIF 图像](https://iiif.io/api/image/3.0/)。看看这个 [实例](https://npmcn.com/package/%40allmaps/annotation/examples/annotation.example.json)。 。 。 .
地理参考注释包含以下数据:
- 这个 [IIIF 图像的 URI](https://iiif.io/api/image/3.0/#3-identifier),以及其像素中的维度.
- 一个多边形资源掩码,它定义了图像的制图部分.
- 地控点列表(GCP),定义了资源坐标和地理空间坐标之间的映射.
多张地图可以在 **注释页** (见 [光谱](https://iiif.io/api/presentation/3.0/#2-resource-type-overview)) (中文(简体) ).
Allmaps提供应用软件和软件包,用于与GeoReference June合作. [全部地图查看器](https://npmcn.com/package/apps/viewer/) 能够 [比如说](https://viewer.allmaps.org/#data=data%3Atext%2Fx-url%2Chttps%3A%2F%2Fraw.githubusercontent.com%2Fallmaps%2Fannotation%2Fdevelop%2Fexamples%2Fannotation.example.json) 在浏览器中扭曲 IIIF 映射, 只需装入一个 GeoReference 注释 .
A 类 **地理参考地图** 是Allmaps内部使用的格式来描述一个地图,并在函数和软件包之间传递。 它以更实际的形式载有同样的信息。 看这个 [实例](https://npmcn.com/package/%40allmaps/annotation/examples/map.example.json)。 。 。 .
此模块允许 **解析** 地理参考地图和 **生成** 地理参考说明取自地理参考地图.
这个模块被写入TypeScript并使用Zod来构建.
## 安装
这是一个只在浏览器和Node.js中工作的无害环境管理模块.
节点.js:
用 pnpm 安装 :
```sh
pnpm install @allmaps/annotation
```
浏览器 :
```html
```
## 使用量
```js
import { parseAnnotation, generateAnnotation } from '@allmaps/annotation'
// Fetch an annotation
const annotation = await fetch(annoationUrl).then((response) => response.json())
// Create a georeferencedMap from the annotation
const georeferencedMaps = parseAnnotation(annotation)
const georeferencedMap = georeferencedMaps[0]
// Use or modify the georeferencedMap(s)
// ...
// Generate Georeference Annotation
// Note: returns an annotation or annotation page based on input
const georeferenceAnnotation = generateAnnotation(georeferencedMap)
const georeferenceAnnotationPage = generateAnnotation(georeferencedMaps)
```
详见下文API.
## 许可证
麻省理工学院
## API 密码
### `Annotation`
###### 类型
```ts
{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...; }; body: { ...; }; }
```
### `AnnotationPage`
###### 类型
```ts
{ id?: string | undefined; type: "AnnotationPage"; '@context'?: string | Array | undefined; items: Array<{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...;...
```
### `AnnotationPageSchema`
###### 类型
```ts
AnnotationPage1Schema
```
### `AnnotationSchema`
###### 类型
```ts
Annotation1Schema
```
### `FeaturePropertiesSchema`
###### 类型
```ts
Annotation1FeaturePropertiesSchema
```
### `GCPSchema`
###### 类型
```ts
GeoreferencedMap2GCPSchema
```
### `GeoreferencedMap`
###### 类型
```ts
{ '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type: "GeoreferencedMap"; id?: string | undefined; created?: string | undefined; modified?: string | undefined; ... 5 more ...; _allmaps?: unknown; }
```
### `GeoreferencedMapSchema`
###### 类型
```ts
GeoreferencedMap2Schema
```
### `GeoreferencedMapsSchema`
###### 类型
```ts
GeoreferencedMaps2Schema
```
### `PartOf`
###### 类型
```ts
Array
```
### `PartOfItem`
###### 类型
```ts
{
id: string
type: string
label?: z.infer
partOf?: PartOfItemType[]
}
```
### `ResourceSchema`
###### 类型
```ts
GeoreferencedMap2ResourceSchema
```
### `SvgSelectorSchema`
###### 类型
```ts
SvgSelector1Schema
```
### `generateAnnotation(mapOrMaps)`
从单一的地理参考地图生成地理参考注释或 a 注释页,包含多个地理参考说明,来自一系列地理参考地图.
###### 参数
- `mapOrMaps` (单位:千美元)`unknown`(中文(简体) )
- 单一地理参考地图, 或一系列地理参考地图
###### 回返
地理参考注释或注释页(`{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...; }; body: { ...; }; } | { ...; }`) (中文(简体) ).
###### 实例
```ts
import fs from 'fs'
import { generateAnnotation } from '@allmaps/annotation'
const map = JSON.parse(fs.readFileSync('./examples/map.example.json'))
const annotation = generateAnnotation(map)
```
### `parseAnnotation(annotation)`
分析一个地理参考注释或包含多个地理参考说明的注释页 并返回一系列地理参考地图.
###### 参数
- `annotation` (单位:千美元)`unknown`(中文(简体) )
- 地理参考注释或注释页,包含多个地理参考说明
###### 回返
地图阵列`Array<{ '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type: "GeoreferencedMap"; id?: string | undefined; created?: string | undefined; modified?: string | undefined; ... 5 more ...; _allmaps?: unknown; }>`) (中文(简体) ).
###### 实例
```ts
import fs from 'fs'
import { parseAnnotation } from '@allmaps/annotation'
const annotation = JSON.parse(fs.readFileSync('./examples/annotation.example.json'))
const maps = parseAnnotation(annotation)
```
### `validateAnnotation(annotation)`
###### 参数
- `annotation` (单位:千美元)`unknown`(中文(简体) )
###### 回返
`{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...; }; body: { ...; }; } | { ...; }`。 。 。 .
### `validateGeoreferencedMap(mapOrMaps)`
###### 参数
- `mapOrMaps` (单位:千美元)`unknown`(中文(简体) )
###### 回返
`Array<{ '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type: "GeoreferencedMap"; id?: string | undefined; created?: string | undefined; modified?: string | undefined; ... 5 more ...; _allmaps?: unknown; }> | { '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type...`。 。 。 .
## 常见问题
### @allmaps/annotation 是什么？
生成和解析 IIIF 地理参考说明的函数
### 如何安装 @allmaps/annotation？
在项目目录运行 npm install @allmaps/annotation，或使用 pnpm add / yarn add / bun add。
### @allmaps/annotation 支持 TypeScript 吗？
该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/allmaps\_\_annotation 是否存在。
### @allmaps/annotation 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @allmaps/annotation 可以商用吗？
@allmaps/annotation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @allmaps/annotation 的下载量有多少？
根据 npm 官方下载统计，@allmaps/annotation 在 2026/10/06 – 2026/11/04 这 30 天内被下载 11,936 次，日均约 398 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @allmaps/annotation 还在维护吗？
最新版本 1\.0\.0-beta\.38 发布于 2026/09/22（1 个月前）；至今共发布 53 个版本，其中过去 12 个月发布了 3 个；首次发布于 2021/01/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。