Cursor API 1.0 for IIIF

Cursor API

Cursor APIは、Canvasのリストを動的に生成するサービスである。例えば、ManifestのsequencesがCanvasの長大なリストとなって列挙が実用的ではない場合でも、Canvasリストの一部を切り出して提供することが可能となる。このサービスはCursor APIに準拠したCursorを返戻するが、そのオブジェクトの@typeをcs:Cursorとする。

Cursorの構造は以下のようになる。

Cursor
- @context（必須）
- @type（必須）
- @id（必須）
- label（必須）
- service（必須）
  - @context（必須）
  - @id（必須）
  - profile
- next
- prev
- within
- sequence（必須）

serviceの@idには自身のCursorのURIを記載する。このURIは参照解決可能なものでなければならない。CursorのURIは、次のパターンを推奨する。

{scheme}://{host}/{prefix}/{identifier}/cursor

nextには次の切り出し範囲の始点となるcursorIndex値、prevには前の切り出し範囲の始点となるcursorIndex値を記載する。

withinには、このCursorを含んでいるtl:Manifestに関する情報を記載する。

sequenceは、IIIF Presentation API 2.1のSequence (http://iiif.io/api/presentation/2.1/#sequence)構造である。そのcanvasesプロパティは、IIIF Presentation API 2.1のCanvas (http://iiif.io/api/presentation/2.1/#canvas)を拡張した構造を含みうるものとする。この拡張されたCanvasは、現時点ではIIIF Presentation API 2.1の独自拡張であり、@typeはcs:Canvasとしている。ここでは、この拡張されたCanvasをcs:Canvasと呼ぶ。

cs:Canvasの構造は以下のようになる。

cs:Canvas
- @context
- @type（必須）
- @id（必須）
- label（必須）
- height（必須）
- width（必須）
- cursorIndex（必須）

cs:CanvasのcursorIndexプロパティは整数値を取り、viewingHintプロパティ値をtimeとする構造の下で利用される場合、Unix time（秒）として解釈される。

Cursor APIに対応したビューワは、serviceの@idで示されるURIに対し、クエリパラメータcursorIndexを用いて問い合わせを行い、返戻オブジェクトを得る。

この問い合わせは、例えば、次のような形となる。

http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor?cursorIndex=1493596800

Cursor APIは、クエリパラメータcursorIndexで指定された値と、cs:Canvasの持つcursorIndexプロパティ値を比較し、クエリパラメータcursorIndex値以上のcursorIndexプロパティ値を持つcs:Canvasの全てまたは一部範囲を抽出して、その順序付きリスト（配列）からなるcanvasesを含むsequenceを持ったCursorを返す。

このsequenceのcanvases長は、API Compliance Level 0（必要最低限の実装レベル）では、Cursor APIの実装依存とし、API Compliance Level 1以降（オプションの実装レベル）では、クエリパラメータによる変更指定が可能となるよう検討する。

例えば、Timelineであれば、クエリパラメータcursorIndexで指定された時刻以降の1日間分の時系列画像を返すCursor API実装などが考えられる。この場合、Cursorのnextに記載されたcursorIndex値を用いて問い合わせを行うことで、次の1日間分の時系列画像を取得できることになる（この問い合わせは、以下の記述例であれば、次の形となる）。

http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor?cursorIndex=1493683200

記述例

{
  "@context": [
    "http://iiif.io/api/presentation/2/context.json",
    "http://codh.rois.ac.jp/iiif/cursor/1/context.json"
  ],
  "@type": "cs:Cursor",
  "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor?cursorIndex=1493596800",
  "label": "デジタル台風：ひまわり8号クリッピング (2017-05-01T00:00:00Z ～ 2017-05-01T23:50:00Z)",
  "service": {
    "@context": "http://codh.rois.ac.jp/iiif/cursor/1/context.json",
    "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor",
    "profile": "http://codh.rois.ac.jp/iiif/cursor/1/level0.json"
  },
  "next": 1493683200,
  "prev": 1493510400,
  "within": "http://codh.rois.ac.jp/iiif/iiif-curation-viewer/sample/himawari/timeline.json",
  "sequence": {
    "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor?cursorIndex=1493596800",
    "@type": "sc:Sequence",
    "label": "2017-05-01T00:00:00Z ～ 2017-05-01T23:50:00Z",
    "canvases": [
      {
        "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501000000",
        "@type": "cs:Canvas",
        "label": [
          {
            "@value": "2017-05-01T09:00:00+09:00",
            "@language": "ja"
          },
          {
            "@value": "2017-05-01T00:00:00Z",
            "@language": "en"
          }
        ],
        "height": 11000,
        "width": 11000,
        "cursorIndex": 1493596800,
        "images": [
          {
            "@type": "oa:Annotation",
            "@motivation": "sc:painting",
            "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501000000",
            "resource": {
              "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501000000.tif/full/full/0/default.jpg",
              "@type": "dctypes:Image",
              "format": "image/jpeg",
              "service": {
                "@context": "http://iiif.io/api/image/2/context.json",
                "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501000000.tif",
                "profile": "http://iiif.io/api/image/2/level1.json"
              },
              "width": 11000,
              "height": 11000
            },
            "on": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501000000"
          }
        ]
      },
      {
        "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501235000",
        "@type": "cs:Canvas",
        "label": [
          {
            "@value": "2017-05-02T08:50:00+09:00",
            "@language": "ja"
          },
          {
            "@value": "2017-05-01T23:50:00Z",
            "@language": "en"
          }
        ],
        "height": 11000,
        "width": 11000,
        "cursorIndex": 1493682600,
        "images": [
          {
            "@type": "oa:Annotation",
            "@motivation": "sc:painting",
            "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501235000",
            "resource": {
              "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501235000.tif/full/full/0/default.jpg",
              "@type": "dctypes:Image",
              "format": "image/jpeg",
              "service": {
                "@context": "http://iiif.io/api/image/2/context.json",
                "@id": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501235000.tif",
                "profile": "http://iiif.io/api/image/2/level1.json"
              },
              "width": 11000,
              "height": 11000
            },
            "on": "http://agora.ex.nii.ac.jp/digital-typhoon/iiif/2017/05/01/20170501235000"
          }
        ]
      }
    ]
  }
}

仕様

ontology.xml

context.json

IIIF拡張仕様

Curation API

Timeline API

Cursor API

ソフトウェア実装

IIIF Curation Viewer

IIIF Curation Viewer for Timeline