navPlace Extension

[glenrobson]

Links

• Original Issue: Consider navPlace property api#1246
• Pull Request: navPlace extension api#2016
• Preview: https://preview.iiif.io/api/navplace_extension/api/extension/navplace/

Background and Summary

The navPlace property has been discussed for a number of years but has been held back due to a lack of use cases and worries on the scope of the navPlace property. With the formation of the Maps TSG this group has been able to discuss in detail the requirements for navPlace and are now in a position to submit this extension to the Presentation API to support linking a IIIF Manifest or Canvas to a geographical place.

Use case that the navPlace will support include:

• Linking a IIIF image of a map to the extent that it covers
• Linking pages of an atlas to the parts of the World they cover
• Geotagging a photograph to a location

Note just as with navDate, navPlace is intended to enable a viewer to relate a IIIF item to a geographical place and it does not allow you to specify the relationship between the place and the item for example you can not say the place is where the item was created, published or covers.

Proposed Solution

We hope the TRC will approve this extension. We have a number of implementations and also a couple of cookbook recipes demonstrating the new features that will be shared with the TRC once this extension is approved.

[azaroth42]

Recommended changes:

1. Add the requirements for navPlace as a property, in the style of the Presentation 3 API documentation.

For example:

• A Collection MAY have the navPlace property with at least one entry.
  Clients MAY render navPlace on a Collection.

2. Remove or provide explanation of the properties block in the example of the spec, and how it interacts with the metadata and label of the resource that has the navPlace extension added to it. What is a "IIIF compatible label"?

[thehabes]

Thank you @azaroth42, these are helpful points. I neglected the "property" language and didn't even notice. I will hang on that properties block comment for a moment during the call and see what people think.

In response, what I really meant for the value is "IIIF Presentation API 3 compatible label" It directs the user to use the language map (b/c that's IIIF Presentation API 3 friendly) as opposed to a standard string value label: "like this". Section 3.3 gets into explaining more about properties right after the full Manifest example.

Maybe it is best to keep the navPlace snippet as simple as possible and just remove that label. It doesn't really help the snippet anyway, since section 2.2 doesn't talk about metadata or the properties object. It may also be worth adding a line like "See section 3.3 for more about using metadata with properties".

[kirschbombe]

Introduction

• Could this also be used for a celestial or spherical coordinate system? Does it have to be "earthbound"?
• Where is says "In IIIF Presentation API 3 the property navDate allows for a calendar date to be associated with a resource in a client friendly format. However, places are extents in space, independent of time and what may or may not be present in that space." Would it make more sense to say something like, "While the navDate property allows a machine-readable date..., navPlace..."
• change "client friendly" to "machine-readable"? (client friendly is vague)

Objectives and scope

• The first paragraph covers objectives of IIIF, but it seems like it should instead focus on the objectives of navPlace

Terminology

• array, JSON object, number, string, and boolean are described in the JSON spec, not the IIIF Presi API
• might add Feature Object and Feature Collection Object to the terminology and note that these are defined by the GeoJSON spec

Position

• does GeoJSON enforce a lat long order? I know some systems put lat first and others long. Might be worth noting if there is anything to note? (I missed that it does mention the order, but I still think it could be made more explicit, esp since GeoJSON is reversed from a number of systems - I think)

Is it necessary to treat the context in two places (2.1.1 and 3.1)?

[thehabes]

Hi @kirschbombe!

Introduction

• It depends on how you look at it. WGS84 is made up of a reference ellipsoid, a standard coordinate system, altitude data, and a geoid. Nothing about that says it has to be applied to planet Earth. However, the specific values that make up that data were derived from the planet Earth. The ellipsoid and geoid used are from Earth's center of mass, shape and specific spherical harmonics. For other spheres, you should use values that offer the best precision for the sphere. WGS84 was designed for Earth and is rarely used for other surfaces without adjustments.
• I don't want the relationship between them to be seen as a corollary. navDate is a good parallel as it shares similar technical and UX aspects, but we don't have navPlace "because of" navDate. I want them to be thought about explicitly separately. Perhaps there is a clearer way to say this bit.
• The presi 3 spec on navDate says "A date that clients may use for navigation purposes..." which is why I went with "client friendly". It does not use "machine-readable" because it will be "GeoJSON-LD" and no other format. Look at seeAlso, for example.

Objectives and Scope

• Hmm good point. Maybe flip the paragraphs in this section, and have the first paragraph trail into how the objective of navPlace fits the objectives of IIIF, or something like that.

Terminology

• The IIIF Presentation API 3 spec says "The terms array, JSON object, number, string, and boolean in this document are to be interpreted as defined by the Javascript Object Notation (JSON) specification." So the IIIF Presi 3 spec is still a valid place to send people for details on their meaning (is that cheating?) :)
• Section 2.1 does this, I think.

Position

• Yes. See 2.1.4 and 2.1.5. Those are straight out of the GeoJSON spec.

• They are for 2 different purposes. 2.1.1 shows you how to make the @context property for the web resource. 3.1 says what they are and why you need them. See section 4.6 of presi 3, which also notes it twice (differently, but still twice). So I would say yes, have both, but could be convinced otherwise.

[azaroth42]

Are there implementations for Mirador, UV or other "regular" IIIF client?

[glenrobson]

Not for navPlace yet, although there are examples using different ways of encoding geo coordinates in manifests before something like navPlace was available. See this example from UCD that uses a geo service:

https://digital.ucd.ie/view/ucdlib:256179

[azaroth42]

Explanation of my 😕 reaction -- not against the spec approach or principle, but think it needs a bit more work before publication.

[tomcrane]

Same as Rob I think - the intent is to attach locations to IIIF resources by borrowing GeoJSON as a useful existing spec, rather than specifically to get GeoJSON objects into a GeoJSON aware environment. So better to disallow properties - it's the viewer's job to construct that if it wants to push the GeoJSON into a GeoJSON-aware rendering environment.

[kirschbombe]

Agree with @azaroth42, especially areas that could use more clarification.

[azaroth42]

One more ...

a single or multiple geographic areas

Can the value of navPlace ever be an array of JSON objects? or is the 'multiple' via a FeatureCollection, and the value MUST be a JSON object?

[thehabes]

This is great, we needed to bring it outside of the IIIF Maps group to get to these. The perspectives really help highlight what needs to be called out for other professionals trying to understand what this is. From today, I have a much better idea on how to frame details around using metadata with this pattern. A bit more about what the client is responsible for and what their options are for metadata would go a long way in helping to describe the scope.

[thehabes]

@azaroth42 the value cannot be an array of JSON objects. It is always a single object, which is a Feature Collection, which can contain as many Features as you would like (until you break the internet).

[mixterj]

I am concerned about the lack of support for non-earth geo-locations. In a quick search, I was able to find an example of the moon landing in 1969

I would like to add geo-coordinates to this image, how would I? To clarify, I very much like the GeoJson approach but I just want clarification about non-earth coordinates.

For reference Wikidata does account for non-earth coordinates in a rather nice way - Mare Tranquillitatis

[kirschbombe]

I'm also wondering if it would be useful at this stage to build in a way to give each Feature object a "motivation" of sorts. The issue mentions that the extension does not allow one to specify the relationship between the place and the item, but I think this can be an important distinction to make (we have different Place metadata fields in more complex schemas that allow us to specify that relationship (place of publication, subject, geographic coverage, etc.). This would be especially helpful where there might be several relationships at play in a single manifest or Feature Collection.

[thehabes]

@mixterj To show that photograph located to a specific point on the moon, you need

• A reference ellipsoid, a standard coordinate system, altitude data, and a geoid
• You need a viewer that shows the projection of that system on a 2D plane, hopefully with a basemap of the surface of the moon.
• The data to mark that location in the system on the viewer over the correct basemap project and connect the metadata to a UI for human readability

How would you suggest supplying all of that in a IIIF resource, staying Linked Data compatible and never breaking the schema? Admittedly, I looked into it and cannot. Specs are missing. However, I found a way to do it for planet earth without having to write a coordinate system specification.

navPlace is meant to leverage available schemas, specifications and vocabularies that are widely used and already exist. If you know of ones for the moon, then you can make an extension for supplying moon related geospatial information. If you can find a way to do it for any ellipsoid, then IIIF awaits your coordinate reference system extension :)

[azaroth42]

It is always a single object, which is a Feature Collection,

Then the definition of the value is MUST not SHOULD :)

There also should be more information, and an example, of the referenced rather than embedded pattern.

I think what is meant is:

 "navPlace": {"id": "http://.../", "type": "FeatureCollection"}

with no features property?

Also, given the Feature example has an id ... it would be good to clarify if a Feature can be a reference or if they must be embedded.

[azaroth42]

Changing my vote to 👎 given the substantial nature of many of the above requested changes -- seems like they should be reviewed again by TRC.

[kirschbombe]

To accommodate other coordinate systems, could we for now add a property that specifies the system? So in the current case, it would be GeoJSON or WGS84. This would leave room to later use navPlace for other systems instead of creating new properties (like navPlaceMars :))

[thehabes]

@kirschbombe to give features a "motivation", you would have to extend the GeoJSON spec to include "motivation" and so not only would you need an extension for navPlace, but also an extension for GeoJSON. You can use GeoJSON in Web Annotation, where you have more control over motivation and purpose already.

If you put the setting for coordinate systems it into properties then you need the linked data context to back it up. Again, navPlace wants to use existing specs and standards, we are avoiding having to write any coordinate system specification of our own.

[zimeon]

I'm also 👎 at the moment based on the need for additional TRC discussion. Certainly want to see a navPlace extension agreed though. Thoughts:

• Need to understand whether to use properties or not. One consideration is whether the specification of multiple features in a FeatureCollection is intended to support independent features that might want individual labels (hence cannot inherit from IIIF description) or not (in which case properties: {} seems reasonable)
• I think GeoJSON for earthbound coordinates is the 99% use case so any solution that generalizes SHOULD NOT overly complicate the simple case. The use of scoped contexts relies upon navPlace to bring in the GeoJSON-LD context for contents so I think one would likely need at add another level of nesting to be able to say GeoJSON vs. other coordinate/representation types.

[glenrobson]

I'm also wondering if it would be useful at this stage to build in a way to give each Feature object a "motivation" of sorts. The issue mentions that the extension does not allow one to specify the relationship between the place and the item, but I think this can be an important distinction to make (we have different Place metadata fields in more complex schemas that allow us to specify that relationship (place of publication, subject, geographic coverage, etc.). This would be especially helpful where there might be several relationships at play in a single manifest or Feature Collection.

Just to note that navDate doesn't specify the date it is representing (e.g. publication or creation date etc.) so I think navPlace should be as vague.

It should be noted though that navDate can only have one value so there is less need for a motivation.

[kirschbombe]

@thehabes - let me rephrase the "motivation" suggestion (not that it has to be "motivation," I'm just using that as an example) - it would be nice to be able to explicitly state the relationship between the IIIF resource and the place. If this is possible through WebAnnotation, then can the extension mention how this would work (or a recipe)? I'm not proposing a solution, rather I'm suggesting a use case that I think might be useful to address with the extension.

[thehabes]

it would be nice to be able to explicitly state the relationship between the IIIF resource and the place

This is not possible in GeoJSON-LD. Since we are using GeoJSON-LD, and not some derivative or extended version, you would have to use something IIIF Presentation API 3 has to do this, either outside the navPlace property or inside navPlace.properties which suggest you supply the linked data context (and therefore vocabulary) of the terms you use in there, or they will be ignored. It is worth noting foreign members (properties) on IIIF resources are also ignored for the same reason.

There is a geo recipe that does get into this, published at https://iiif.io/api/cookbook/recipe/0139-geolocate-canvas-fragment/. It uses motivation "tagging" because there is no widely used standardized published ontology or linked data extension for geographic motivations on Web Annotations. You can write one though! Bert is doing this for georeferencing, and you can see what work is involved at this repo: https://github.com/thehabes/GeoreferencePrototype. You can also look at an example of writing a GeoJSON extension spec at https://github.com/kgeographer/geojson-t. Remember the key phrase here "Using available web standards". For what you want to do with this, a lot more extending is involved to make it Linked Data compatible and IIIF friendly.

You can see how the OGC community handles some of this https://www.ogc.org/docs/is. You might also like this "meta-spec" about making sure web maps have a standard way of doing these things https://maps4html.org/HTML-Map-Element-UseCases-Requirements/. My favorites are the coordinate reference system standards. You will realize quickly how out of scope this becomes. Right now, we just want to get in the door. How do you connect geographic coordinates with IIIF resources (most of which represent a Real World Object) in a standards compliant manner, and further can those coordinates be viewed easily across various web mapping UI systems. Attaching specific motivations and purposes to geospatial information are each their own individual challenge, as each will require some specific technical aspect that must be described.

[thehabes]

Certainly, navPlace is meant to spark these thoughts. But it can't be the end all extension for geospatial practices. Those practices are not all well described and need specifications of their own first before we can approach intertwining them with IIIF. For now, navPlace can do what the web has standardized around: draw shapes intentionally located to a specific spot on a WGS84 projection of the surface of Earth and connect some metadata with the shape (standard UI being a pop up upon some input). Even at this "unit level" of functionality in relation to the surface of the Earth, different coordinate systems are used and formats other than GeoJSON are used. Of those systems, WGS84 is the most widely used and interchanged, and everything shims through GeoJSON eventually. The IIIF Maps research supports this foundation is strong enough to leverage. In this way, navPlace is at least as versatile and serializable as necessary to be used in mapping on the web for its scope (which we roughly refer to as geolocating stuff).

Research also revealed what foundations need strengthening. As the state of mapping on the web matures, future extensions can leverage new foundations. IIIF Maps TSG will have to be a part of the maturing process and knows navPlace is only a baby step; this extension is not useful for a noticeable amount of the IIIF Maps community interested in specific use cases like georeferencing and geospatial systems not of Earth or reality. I think a lot can be learned from the video game people on this front. I would like to convey to you in spatial terms just how difficult my adventure through the world of Assassin's Creed Valhalla was (which contains an inset world of their interpretation of Valhalla for a side quest). If I hand you a coordinate point for a location in any of that, there would be a complete failure to process without knowing the foundation of spatial communication in that system. Instead, all I can really convey is that there was a lot of kicking and screaming in my living room, and those coordinates I can give you once I pull them out of Google Maps (and invert their order, shame on you Google Maps).

[tpendragon]

I want to see this here, but given the number of comments here I feel like we should look at another iteration. Things I'd particularly like to see are just some cleaning up of the language to more closely match the IIIF 3 format (it took me a while to figure out where I could attach a navPlace property) and I'd like to see this properties discussion worked out. I'm a little uncomfortable with part of the specification being "put whatever you want here" without some guidance as to why you might want some content there. I assume there's just external software that you want to interact with here? If the properties property just wasn't there at all, what wouldn't work?

I'm not concerned about it being earth-bound - I even prefer it, getting this integration really nailed down with the 99% use cases seems better and it can be refined later. IIIF has a long history of that, and I think it's part of what makes it great.

Is there a chance we'll be able to see this functionality do something in a viewer, too? Or an experience of some kind?

[glenrobson]

Issue 72 (navPlace Extension)

+1: 3 [glenrobson jcreel thehabes]
0: 9 [cubap emulatingkat jtweed julsraemy markpatton mbennett-uoe nfreire shuddles tomcrane]
-1: 9 [awead azaroth42 kirschbombe ksclarke mcwhitaker mixterj tpendragon triplingual zimeon]
Not TRC: 1 [mapninja]
Ineligible: 0 []

Result: 3 / 21 = 0.14

Issue is rejected