Cursor API
Cursor API is a service to dynamically generate the list of Canvas. It is used to provide a part of the list of all Canvases when sequences of Manifest has a very long list of Canvas and their comprehensive list is not practical. This service returns Cursor which is compliant with Cursor API, an we define the @type of the object as cs:Cursor.
Cursor has a structure as follows.
-
Cursor-
@context(Required) -
@type(Required) -
@id(Required) -
label(Required) -
service(Required)-
@context(Required) -
@id(Required) profile
-
nextprevwithin-
sequence(Required)
-
@id of service specifies the URI of Cursor itself. This URI should be dereferencable. The URI of Cursor recommends the following pattern.
{scheme}://{host}/{prefix}/{identifier}/cursornext specifies the value of cursorIndex for the beginning of the next cursor, while prev specifies the value of cursorIndex for the beginning of the previous cursor.
within specifies information about tl:Manifest that includes the Cursor.
sequence is a structure of Sequence (http://iiif.io/api/presentation/2.1/#sequence) in IIIF Presentation API 2.1. Its canvases property has a structure that extends Canvas (http://iiif.io/api/presentation/2.1/#canvas) in IIIF Presentation API 2.1. At this moment, this extended Canvas is our own extension of IIIF Presentation API 2.1, so we refer to it as a @type of cs:Canvas. In the following we call this structure as cs:Canvas.
cs:Canvas has a structure as follows.
-
cs:Canvas@context-
@type(Required) -
@id(Required) -
label(Required) -
height(Required) -
width(Required) -
cursorIndex(Required)
cursorIndex property of cs:Canvas takes an integer value, and when it is used under a structure having viewingHint property as time, the value is interpreted as Unix time (second).
A viewer that is compliant with Cursor API makes a query using cursorIndex query parameter to URI specified by @id of service, and receives an object returned by the API.
This query may be represented by the following URI.
http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor?cursorIndex=1493596800Cursor API compares the value specified in the value of cursorIndex query parameter and the value of cursorIndex property of cs:Canvas, and selects all or part of cs:Canvases that have the value of cursorIndex which is equal or above of the value of cursorIndex query parameter, and returns Cursor with sequence that has the ordered list (array) of canvases.
The length of canvases in the sequence is dependent on a specific implementation of Cursor API under API Compliance Level 0 (minimum implementation level), but API Compliance Level 1 and higher (optional implementation levels) may accept the length within query parameters.
For example, in the case of Timeline, we can think of an implementation of Cursor API that returns the list of time series images for one day after the time specified by the query parameter of cursorIndex. In this case, it is possible to get time series images of the next day by using the value of cursorIndex specified by next property in the Cursor. This query can be described in the following way.
http://agora.ex.nii.ac.jp/digital-typhoon/service/iiif/Hsfd/cursor?cursorIndex=1493683200Example
{
"@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": "Digital Typhoon: Himawari-8 Clipping (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"
}
]
}
]
}
}