原文链接：https://iiif.io/api/extension/navplace/
翻译：羊牧东岭

image.png

本文档的状态

本文档不受语义版本控制，后续更新将在文档本身进行跟踪。
版权所有 © 2012-2021 编辑和贡献者。由IIIF联盟根据CC-BY许可发布，请参阅免责声明。

一、介绍

在IIIF展示API 3中，并没有提供专为地理位置而设计的资源属性。然而，位置概念对许多资源而言是首要的描述信息，因此需要为之设置单独的属性来表达。

1.1 目标与范围

本项扩展为IIIF展示API 3定义了一个新的属性navPlace，它由GeoJSON-LD格式的地球地理坐标来定义。客户端可使用该属性，借助基于 Web 的地图平台（例如 Google Earth、Leaflet 和 OpenLayers）的功能优势，从而提供一种基于地图接口来丰富数据呈现的方法。
位于其他天体或人造世界上的资源的空间坐标，本来也可以使用 GeoJSON 的语义模式来表示。不过，navPlace属性采用现有的 GeoJSON 规范来促进与一些行业标准映射库或其它方法之间的交互性，而它们往往使用WGS84作为地球表面投影的参考坐标系。因此，navPlace属性不支持标记地球世界以外的实体位置。但是并不排除在未来进一步开发相应的扩展，以应对更广泛的情形。

1.2 目标用例

将地理坐标与网络资源相关联的原因是多种多样的。本项扩展并不意在满足地理空间实践上所有的数据要求。我们所致力的应用范围包括：

  • 将IIIF资源链接到单个或多个地理区域
  • 为地图图像提供单个地理边界框
  • 表示出现在数字对象中的位置，例如行程或旅行日志

不在范围内的情况包括：

1.3 术语

本扩展使用下列术语：

  • 嵌入(embedded)：当资源 (A) 嵌入到被嵌资源 (B) 中时，资源 A 的完整JSON表示便存在于资源 B 的JSON表示之中，并且如果解除对资源 A 的URI的引用，不会产生额外的意义。例如：画布 A 嵌入清单 B 中。
  • 引用(referenced)：当资源（A）被资源（B）引用时，资源 A 的一份不完整的JSON表示便存在于资源 B 的表示之中，如果解除对资源 A 的URI的引用，将产生额外的意义。例如：清单 A 被集合 B 所引用。
  • HTTP (S)： HTTP或HTTPS 的URI标准和互联网协议。
  • 位置(location)：地点位置的定量描述。在这里我们使用坐标。

本文档使用的这些术语——数组、JSON对象、数字、字符串和布尔值，应按照Javascript 对象表示法 (JSON)规范的定义来解释。
本文档中的关键字必须、不得、需要、应该、不应、应该、不应、推荐、可以和可选的，其定义如 RFC2119 中所述。

2. navPlace属性和 GeoJSON-LD

2.1 navPlace属性

navPlace属性用来标记与资源相关的一或多个地理区域，资源本身则使用了包含一或多个要素的 GeoJSON 要素集合(Feature Collection)。这些区域应该是地图上有界而离散的区域。这些区域并不意味着任何程度的准确性、时间性或存在状态。

  1. {
  2.    "navPlace":{
  3.       "id": "http://example.com/feature-collection/1",
  4.       "type": "FeatureCollection",
  5.       "features":[
  6.          {
  7.             "id": "http://example.com/feature/1",
  8.             "type": "Feature",
  9.             "properties":{},
  10.             "geometry":{
  11.                "type": "Point",
  12.                "coordinates":[
  13.                   9.938,
  14.                   51.533
  15.                ]
  16.             }
  17.          }
  18.       ]
  19.    }
  20. }
  1.     ]             }          }       ]    } } <br />navPlace属性可以与[IIIF展示API 3 定义类型](https://iiif.io/api/presentation/3.0/#21-defined-types)一同使用。
  • 集合可以具有navPlace属性。
    客户端可以将navPlace在集合上呈现。
  • 清单可以具有navPlace属性。
    客户端可以将navPlace在清单上呈现。
  • 范围可以具有navPlace属性。
    客户端可以将navPlace在范围上呈现。
  • 画布可以具有navPlace属性。
    客户端可以将navPlace在画布上呈现。
  • 其他类型的资源不得具有navPlace属性。
    客户端应该忽略出现在其他类型资源中的navPlace属性。

navPlace属性的值遵循特定的模式：

  • 该属性的值必须是一个JSON对象，该对象符合第 2.2.2 节中描述的 GeoJSON 要素集合的要求。
  • 该值应该是一个嵌入的要素集合。但是，该值可以是一项被引用的要素集合。navPlace属性引用的要素集合必须具有id和type属性。引用的特征集合不得具有features属性，以便客户端认识到应该检索它以便进行处理。
  1. {"navPlace":{"id": "https://example.org/iiif/1/feature-collection", "type": "FeatureCollection"}}

2.2 GeoJSON

本扩展使用已发布的GeoJSON 规范中描述的技术术语。

2.2.1 GeoJSON 作为关联数据

GeoJSON-LD是 GeoJSON 规范的公开可用的词汇表，以及链接数据的环境(context)。该navPlace扩展的环境文件(context file)指向该环境，以保证地理数据值被恰当地描述。下例展示了如何使用@context属性来设置具有navPlace属性的IIIF资源。第 3 部分有更多关于链接数据兼容性的详细信息。

  1. {
  2.     "@context":[
  3.        "http://iiif.io/api/extension/navplace/context.json",
  4.        "http://iiif.io/api/presentation/3/context.json"
  5.     ]
  6. }

2.2.2 要素集合(Feature Collection)

要素集合表示空间有界区域的聚合。在 GeoJSON 规范中查看可视化示例。本文档中的术语“特征集合”也就是 GeoJSON 规范中的“要素集合对象”。

  • 要素集合具有type属性，其值为“FeatureCollection”。
  • 要素集合具有一个features属性，值为一个JSON数组。数组的每个元素都是下文所定义的要素(Feature)。虽然此数组可能为空，但应用于本扩展的语境时，它不应为空。
  • 一个要素集合可以有一个id属性。出于本扩展的目的，该id属性的值必须是常用的HTTP(S) URI 标识符。要素集合可以通过 URI 访问。

2.2.3 要素(Feature)

要素表示一个空间有界区域。每个要素都是一个 GeoJSON 对象。在 GeoJSON 规范中查看可视化示例。在本文档中，术语“要素”也就是 GeoJSON 规范中的“要素对象”。

  • 要素具有type属性，其值为“Feature”。
  • 要素具有geometry属性，该属性的值必须是2.2.4 Geometry Objects and Position 定义的Geometry 对象，或者在要素未定位的情况下，是JSON中的null值。
  • 要素具有properties属性，该属性的值是具有零或多个属性的JSON对象。关于如何使用此属性提供与地理坐标相关的信息，请参阅第 3.2 节。

  • 要素可以具有id属性。出于本扩展的目的，该id属性的值必须是常用的HTTP(S) URI 标识符。id 可以是这类要素集合的URI：该要素集合所含的要素，在结尾处带有独特的片段。该要素可以通过 URI 访问。

    2.2.4 Geometry对象和位置

    Feature 对象通过geometry属性所引用的 Geometry 对象，是一个 GeoJSON 对象。在 GeoJSON 规范中查看可视化示例。

  • Geometry 对象具有type属性，该属性的值来自本节中的 Geometry 对象类型表。

  • Geometry 对象具有coordinates属性，其值是位置数组，其结构由几何类型决定。
  • 位置是一个数字数组，它必须含有两个或多个元素。前两个元素是经度和纬度，或东距(easting)和北距(northing)，正好按照该顺序并使用十进制数。海拔可以作为可选的第三个元素包括在内。 | Geometry对象类型 | 描述 | | —- | —- | | Point | “coordinates”属性是单个位置 | | MultiPoint | “coordinates”属性是包含位置的数组 | | LineString | “coordinates”属性是包含两或多个位置的数组 | | MultiLineString | “coordinates”属性是包含 LineString 数组的数组 | | Polygon | “coordinates”属性必须是线性闭环坐标数组的数组。对于具有多个闭环的多边形，第一个必须是外环，其它闭环必须是内环。外环是外边界，内环（如果存在）是内部的孔洞。 | | MultiPolygon | “coordinates”属性是包含Polygon数组的数组 | | GeometryCollection | 具有“geometries”属性，其值是一个数组。该数组的每个元素都是一个 GeoJSON Geometry 对象。此数组可能为空。 |

有关这些形状的示例，请参阅https://datatracker.ietf.org/doc/html/rfc7946#appendix-A上的 GeoJSON 规范的“示例”部分

3. 关联数据

3.1 关联数据环境

navPlace 扩展的链接数据环境必须包含在IIIF展示API 3的链接数据环境(在顶级对象中)之前。navPlace 扩展的链接数据的环境文件通过环境范围包括了GeoJSON-LD 环境。这意味着 GeoJSON-LD 环境 URI 不必明确包含在顶级对象中。需要注意的是，由于IIIF展示API 3 的链接数据环境将JSON-LD的@version设置为 1.1，因此所有链接数据环境都作为JSON-LD 1.1进行处理。
请参阅IIIF展示API 3的链接数据环境和扩展部分，以获取有关使用@context属性的进一步指导。

3.2 GeoJSON-LD properties属性的环境的注意事项

properties的值可以是任何JSON对象，用于提供与地理坐标相关的附加信息。其中使用的术语 应该由 注册的IIIF API扩展或本地链接数据环境来描述。如果客户端遇到了无法理解的属性，则必须忽略。

4. 完整的清单示例

下面您可看到带有navPlace属性的IIIF清单示例。通过包含多个链接数据环境以涵盖 Web 资源中使用的所有术语，它与JSON-LD 1.1 达成了兼容。可以在 JSON-LD playground 中查看下面清单，了解链接数据处理的示例。

  1. {
  2.    "@context":[
  3.       "http://iiif.io/api/extension/navplace/context.json",
  4.       "http://iiif.io/api/presentation/3/context.json"
  5.    ],
  6.    "id":"https://example.org/iiif/manifest/1",
  7.    "type":"Manifest",
  8.    "label":{
  9.       "en":[
  10.          "navPlace Extension Example Manifest"
  11.       ]
  12.    },
  13.    "items":[
  14.       {
  15.          "id":"https://example.org/iiif/canvas/p1",
  16.          "type":"Canvas",
  17.          "label":{
  18.             "en":[
  19.                "Picture of Göttingen taken during the 2019 IIIF Conference"
  20.             ]
  21.          },
  22.          "type":"Canvas",
  23.          "height":3024,
  24.          "width":4032,
  25.          "items":[
  26.             {
  27.                "id":"https://example.org/iiif/page/p1/1",
  28.                "type":"AnnotationPage",
  29.                "items":[
  30.                   {
  31.                      "id":"https://example.org/iiif/annotation/p0001-image",
  32.                      "type":"Annotation",
  33.                      "motivation":"painting",
  34.                      "label":{
  35.                         "en":[
  36.                            "Picture of Göttingen"
  37.                         ]
  38.                      },
  39.                      "body":{
  40.                         "id":"https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen/full/max/0/default.jpg",
  41.                         "type":"Image",
  42.                         "format":"image/jpeg",
  43.                         "height":3024,
  44.                         "width":4032,
  45.                         "service":[
  46.                            {
  47.                               "id":"https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen",
  48.                               "profile":"level1",
  49.                               "type":"ImageService3"
  50.                            }
  51.                         ]
  52.                      },
  53.                      "target":"https://example.org/iiif/canvas/p1"
  54.                   }
  55.                ]
  56.             }
  57.          ]
  58.       }
  59.    ],
  60.    "navPlace":{
  61.       "id" : "https://example.org/iiif/feature-collection/2",
  62.       "type":"FeatureCollection",
  63.       "features":[
  64.          {
  65.             "id":"https://example.org/iiif/feature/2",
  66.             "type":"Feature",
  67.             "properties":{
  68.                "label":{
  69.                   "en":[
  70.                      "navPlace Extension Example Manifest"
  71.                   ]
  72.                }
  73.             },
  74.             "geometry":{
  75.                "type":"Point",
  76.                "coordinates":[
  77.                   9.938,
  78.                   51.533
  79.                ]
  80.             }
  81.          }
  82.       ]
  83.    }
  84. }

{

5. 实施的注意事项

5.1 网络上的 GeoJSON-LD

我们选用 GeoJSON-LD 不是没有理由的。它是基于 Web 的地图平台所支持的主要的地理坐标数据格式。在网络上使用时，扩展驱动的开发者将地理坐标数据保存为 GeoJSON-LD 格式。这种做法为互动的地理坐标数据消除了障碍，并促进了已有、当前和未来的基于 Web 的地图平台开发的强大功能。

5.2 IIIF Cookbook

IIIF Cookbook 示范了IIIF展示API 3对数字对象的实现。关于navPlace特性的IIIF Cookbook还在编写中。当相应内容发布后，本规范将及时更新相关链接。

附录

A. 致谢

非常感谢IIIF社区的持续参与、创新想法和相关反馈。感谢Sean Gilles和 MapBox 提供的 GeoJSON 链接数据环境及其对标准化地理网络数据的推广。我们还想感谢IETF通过 GeoJSON 规范所提出的语义。特别感谢IIIFMaps和IIIFCookbook社区作为这项开发技术的实施者。本文档的初始版本由 IIIFMaps Technical Specification Group 编写。

B. 更新日志

日期 描述
2021-10-18 初始版本