# Research

This section contains background research into the standards performed in order to make the implementation phase go smoothly. The documents referred to in these sections are available for download as attachments to this page.

## Coverages

A coverage domain does not need to be continuous. A coverage, in its most abstract, is merely:

some set of direct positions for all of which we have a set of values.

The set of direct positions may be finite (i.e. a random or regular group of points) or infinite (i.e. a set of polygons, a mix of points, lines and polygons). The values can be of any kind of measure: nominal, ordinal, interval, or ratio and can also be a vector of, possibly mixed, values. The coverage is however required to have a value for each position in the original set. The key for the discrete/continuous will be how the values are generated.

An example of a discrete coverage might be `"countryNameCoverage"`. The domain of such a coverage could be the set of polygons of territories claimed to be occupied by some nation state (i.e. in today's world, all the land masses.) For our purposes let's call this a set of mostly non-overlapping polygons. The coverage, by its construction, guaranttees that for any point within those polygons we can get a "name" for a country. So if we give it a point in Boston we get `"USA"`, if we give it a point in the mississippi we get `"USA"` but if we give it a point in the Amazon, we could get `"Brazil"`. The coverage can define rules about how it resolves disputed areas like land in Antarctica. So this is "discrete" in that we get the same result wherever we are within a polygon - any point we ask for within the alaska polygon will always give us `"USA"`.

An example of a continous coverage, based on the same polygons, could be `"populationDensityCoverage"`. There, our two queries in the Alaska polygon could return completely different values and indeed, in general, we expect different points to have different values even within the same polygon.

Do not confuse continuous coverage with the continuity of the values however. We could have a third coverage using the same polygons which is `"sexOfclosestHumanCoverage"` which would return `"female"` `"unknown"` `"male"` for any position in the polygons. Again every point in Alaska would have an answer but that answer would be different for different places in Alaska so the coverage is continuous although the values are not.

An "image" can be turned into a coverage in several ways although a common one will be to characterize the domain as a single, continuous rectangular block everywhere over which the coverage can return a vector of values, say one value for each of the image bands. The return vector would vary with position across the single domain so this would be a continuous construction. Alternatively, we could define an "image" as a multi-domain discrete coverage where the domain is a set of equally sized polygons arranged side-by-side and the value returned is the same for each position within each polygon. Note in passing that we are not talking about how the values are generated - that's a detail of the internals of the coverage.

In many ways coverages are the end goal of GI Systems so they are rich and complex. Also, GeoTools has for a long time mixed up the notion of `GridCoverage` with the notion of `Coverage` causing some confusion.

## ISO 19123 Primers

A detailed examination of the ISO19123 specification is being carried out on a conceptual level. This examination is being done from the standpoint of implementing a 4D + bands coverage capability into GeoAPI/GeoTools. It is detailed enough that, used in conjunction with the Javadocs, correct usage of the concepts should occur. Strengths, deficiencies, and typos are pointed out during the discussion, with the overall intent to constructively impact this particular standards document. Deficiencies, where identified, are usually accompanied by a suggestion to resolve them.

### Draft 7 (December 22, 2006)

Draft seven includes a preliminary treatment of coverage services. These are things like resampling, subsetting, rendering, etc. Basically, anything which needs to deal with the coverage as a whole instead of a coverage value at one particular point. Coverage services are operations which are not characteristic of a particular feature, but which could be applied to a number of features.

Geographic Services, specified in ISO 19119 (OGC Abstract Specification Topic 12) lays claim to these operations. Since we are in search of a minimum effort way to adopt Simone's high performance JAI work into the new coverage framework, now might be the appropriate time to refactor the coverage processing stuff using a "Service" mindset. Right now this would involve articulating the JAI coverage operations as platform-specific services. When we later need to implement these same services for other coverage implementations (e.g. multiarray2), we will need to make a platform-neutral service specification as well as a second service specification for multiarray2. This sounds like a lot of work, but has the advantage that we can hide the implementation details from the client.

### Draft 6 (December 11, 2006)

Draft 6 represents a major reorganization of the primer. Prior to this release, the document grew by addition, meaning that I wrote about what I was learning at the time. There was no particular plan, and the primer essentially recorded my learning curve. I did not have my mind around the whole of the spec, and I was in no position to write a document which assembled all the pieces in the proper order.

Draft 6 goes a long way toward addressing these problems. Rather than recording my learning curve, I've organized the document such that the reader follows a logical path which helps nudge the big pieces into place. The primer contains substantial new text which should give the reader a much broader exposure to the coverage data type than the previous versions attempted. At the same time, the "proposed additions" to 19123 became smaller, easier to understand, and easier to implement. Changes to the model are presented where necessary, reasons for the changes are presented, and the reasons generally concern ensuring that the model adheres to the text of the standard.

To comment or criticize, edit the OpenOffice document with change tracking on, save, then email your copy to bnordgren@fs.fed.us. I should be able to merge your comments in.

ISO 19123 Efficiency Spreadsheet: OpenOffice 2.0 format, MS Excel (exported)
Use of EMF: OpenOffice 2.0 format or PDF
Spreadsheet templates for "Use of EMF": OpenOffice 2.0 format
Coverage Framework Design : OpenOffice 2.0 format or PDF
ISO 19123 Primer (coverages): OpenOffice 2.0 format or PDF
ISO 19109 Primer (feature models): OpenOffice 2.0 format or PDF

## Feature models

The relationship between coverages and features in the ISO/TC211 world (which is what the coverage schema is based on) is not obvious. This has precipitated a second document examining this relationship, investigating the means of implementing a feature model in software, and a comparison of the requirements precipitated by using the TC/211 feature model in a real world environment. Among other things, the coverage effort requires behavioral capabilities from a feature model if coverages are to be modeled as features. These issues and more are explored in the ISO 19109 Primer.

Update: The ISO19109 primer now contains a comparison of Ecore and the General Feature Model, as well as a set of interfaces to be proposed to GeoAPI.

Update: The ISO19109 primer now contains a proposed application schema for attaching XML-Schema derived descriptions of attribute ordering. This is an expression of the ComplexFeature effort in terms of the General Feature Model.

# ISO 19123 progress and future plan

The following is a list of tasks that need to be done before we reach stables ISO 19123 interfaces. This proposed plan may changes according the feedback from contributors and OGC/GeoAPI members. Please feel free to edit this page (or add comments at the bottom of it) if this proposal should be modified.

• First draft of ISO 19123 UML models as Java interfaces. This step is now completed.
• Revisit the `@todo` tags and see if we can reach an agreement on some of them. We don't need to resolve all `@todo` tags at this state.
• Copy the best ideas from Stephane Fellah's interfaces (`com.owsx` packages) to the proposed `org.opengis.coverage` package, if peoples agree. Example of features that deserve a close look is the axis handling. (A special section of the ISO19123 primer is devoted to a review of this proposal.)
• Move the methods from the legacy `org.opengis.coverage` package (the one backed by the legacy OGC grid coverage specification) to the new `org.opengis.coverage`package (the one backed by ISO 19123), and deprecate them (with some few exceptions; see next point below). The goal is to provide a migration path from the legacy specification to ISO 19123. Deprecated methods would be removed in a future GeoAPI release (not before 2.2).
• We may keep a few methods from the legacy Coverage interface that we choose to not deprecate. Example: the `Coverage.evaluate(...)` methods overloaded for various Java array of primitive type. Those methods exist for performance reasons. Some others methods exists for interoperability with Java2D. The later are obviously not part of ISO 19123 and will still be needed in the new set of interfaces.
• We will need a `CoverageFactory` and some kind of `GridCoverageExchange`. They are not part of ISO 19123, so we may need to make our own. We will stay close of legacy OGC specification if possible, but changes are likely to be needed. For example experience with Geotools users show that `Format` is actually used most of the time as a `GridCoverageStore`, and maybe should be renamed that way.
• Up to this stage, all the interfaces were created in the GeoAPI "pending" directory. We should try to implement them in Geotools (actually adapt current implementation to the new interfaces).
• If the Geotools implementation shows that the Coverage interfaces derived from ISO 19123 are workable, submit them to OGC as a new official GeoAPI package. We will need to go through an OGC vote.
• If the interfaces are accepted by OGC vote, move them to the main GeoAPI branch and make a new GeoAPI release.

## References

ISO 19123 interfaces in the pending directory:

## Attachments:

ISO19123 Primer.pdf (application/pdf)
ISO19123 Primer.odt (application/vnd.oasis.opendocument.text)
ISO19123 Primer.pdf (application/pdf)
ISO19123 Primer.odt (application/vnd.oasis.opendocument.text)
ISO19109 Primer.pdf (application/pdf)
ISO19109 Primer.odt (application/vnd.oasis.opendocument.text)
ISO19109 Primer.pdf (application/pdf)
ISO19109 Primer.odt (application/vnd.oasis.opendocument.text)
ISO19109 Primer.pdf (application/pdf)
ISO19109 Primer.odt (application/vnd.oasis.opendocument.text)
ISO19123 Primer.pdf (application/pdf)
ISO19123 Primer.odt (application/vnd.oasis.opendocument.text)
Coverage Framework Design.pdf (application/pdf)
Coverage Framework Design.odt (application/vnd.oasis.opendocument.text)
Use of EMF.pdf (application/pdf)
Use of EMF.odt (application/vnd.oasis.opendocument.text)