images and images/{imageId} endpoints

[pomakis]

Back in OGC Testbed 15, the OGC developed an experimental "OGC API - Images" API. Such an API is directly related to coverages because it allows a coverage to be built up and managed as a set of source images. I haven't seen anything come of this API since Testbed-15, and figure that now might be a good time to bring it up again to see if it might have any future within the framework of "OGC API - Coverages".

An implementation of these endpoints is available on CubeWerx's test implementation server at https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_mosaic_2019/images. A client can GET, POST and DELETE source images, and the coverage, as well as the map and tiles that derive from it, is updated automatically.

[jerstlouis]

Some thoughts:

• The GET on individual images I think could potentially be implemented as a collection hierarchy + Coverages API (e.g. supporting sub-setting etc. on individual images).
• If the hierarchical approach is seen as as a way forward then the POST and DELETE (of images in this case) might be related to other mechanism to create collections POSTing to /collections (e.g. virtual collections from process execution or styles)
• One important aspect of the Images API was the ChangeSets part, a form of delta updates (and associated Tiles functionality to get list of affected tiles between two checkpoints or time stamps)

[pebau]

On the semantic level of coverages, WCS-T provides such functionality, including all consistency checks to obtain / maintain a valid coverage:

• InsertCoverage: add a new one
• DeleteCoverage: delete from server
• UpdateCoverage: Modify a coverage, or part of it, on the server

[jerstlouis]

@cportele @pvretano @pomakis @pebau @joanma747
Right, I suggest the Testbed 15 Images API and WCS-T functionality could all be integrated into /collections (POST) and/or /collections/{collectionId} (PUT / PATCH / DELETE) mechanism, in a way which also mirrors the ability to manage multiple Feature Collections for example, and the ChangeSets / Delta Updates (including the tile-based version) could also work with both.

[joanma747]

Sure!. Please be aware that a collection can be anything (not just a coverage). You need to create a collection and them "specialize" it as a coverage.
In practice this means that we need at least 2-3 operations to create a coverage:

/collections POST (sending a collection description document) will create a collection
/collections/{collectionId}/coverage POST (sending a CIS document) will create the coverage
/collections/{collectionId}/coverage/rangeset PUT (sending a TIFF file) will populate the rangeset with values (assuming that the CIS did not already contained the rangeset)

The /images API was designed in Testbed 15 to have a simplified way of maintaining a set of imagery. Is far as can remember it was never connected to a coverage but it seems a good idea to do so in here or in future experiments.

[jerstlouis]

@joanma747 regarding specializing it, potentially some server implementations might be be able to automatically provide both a Features and Coverage view after you upload one type of data. A point cloud would be one example I am thinking of... (also a 3D Data API aka GeoVolumes view as well as 3D Tiles .pnts files / i3s, and if a Point Clouds API is something else, yet another view to give you a .las file...).

Even in the specializing case, I would think that /collections/{collectionId}/coverage should also be a PUT, as it makes that specific resource available or replaces it?

With virtual collections (data generated on the fly from processing or rendering a map), POSTing a process execution document or a style to /collections would automatically create all the resources.

[cportele]

In practice this means that we need at least 2-3 operations to create a coverage

It should be simpler with feature collections than with coverages. You would simply POST your shapefile/gml/geojson/you-name-it to /collections and that would create the new feature collection.

[jerstlouis]

@cportele well I am proposing you can do exactly the same thing with a .geotiff, .netCDF, .cisjson to create a coverage!

But for multiple .geotiff files part of a single coverage, hierarchies (e.g. using : separator, like bigcoveage:myfile001.tif), you can manage multiple images making up that bigger coverage.

[joanma747]

Well, now we have two possibilities:

• summit a POST to \collections (send a shapefile or a CIS document) and the server does the magic to create the collection and all the related resources at once
• summit a succession of small steps to create each resource individually until you have a full collection defined. You have full control of the details.

I have to say I did not think about the first possibility but, now that you mentioned, it seems very elegant (simplicity=elegance).

For coverages, sending to "\collections" a CIS document, a ZIP with a CIS+image, a fully internally documented GeoTIFF, or a JPEG2000 with GMLJP2 should work automatically. A PNG will create a "trivial" coverage that could them be "modified" by POSTING a CIS document describing the domainset and a rangetype to /collections/collectionId/coverage

[jerstlouis]

See #171 and the new Scenes requirements class in #172.

The requirements define the listing of scenes (aka Images), retrieving scene metadata, and retrieving coverage data from an individual scene.

Permissions suggest the additional support of methods for creating / updating / deleting scenes, which may be further specified in an extension (based on the general CRUD extension as defined in Features - Part 4), as well as the possibility to support scene-level metadata queryables in coverage requests.

A recommendation suggest the implementation of OGC API - Records Local Resource Catalogues on the /scenes and /scenes/{sceneId} resources.

(The 'ChangeSets' aspect is not addressed by this Scenes requirements class, but compatible with it).