PROJJSON

[paulushub]

Reference: PROJJSON/High level objects

How does GeoAPI maps to the PROJJSON defined CRS like BoundCRS, which is also defined in the WKT specifications/Bound CRS?
Also, is the implementation of derived DerivedCRS interface supposed to cover all the derived types or serve as the base?

Coordinate Reference Systems (CRS):

• Common ones:
• GeographicCRS
• GeodeticCRS
• ProjectedCRS
• CompoundCRS
• BoundCRS

More esoteric ones:

• VerticalCRS
• EngineeringCRS
• TemporalCRS
• ParametricCRS
• DerivedGeographicCRS
• DerivedGeodeticCRS
• DerivedProjectedCRS
• DerivedVerticalCRS
• DerivedEngineeringCRS
• DerivedTemporalCRS
• DerivedParametricCRS

[desruisseaux]

Hello Paul, and welcome!

BoundCRS

A little bit of history: the BoundCRS type does not exist in OGC Topic 2 / ISO 19111, which is the abstract model from which, in principle, everything else would be derived (EPSG, WKT, PROJJSON, GeoAPI, etc.). This omission is intentional, because BoundCRS encourages a practice called "early binding" (in GIGS terms) that the OGC/ISO group wishes to discourage. Nevertheless, BoundCRS has been added in ISO 19162 (a.k.a. WKT 2) because one of WKT 2 design goals was to be backward compatible with WKT 1, and WKT 1 has a TOWGS84 element. Therefore, BoundCRS is a compromise added in the WKT 2 encoding only (not in the conceptual model) as a compromise for providing something equivalent to the WKT 1 TOWGS84 element for users who nevertheless want that functionality. PROJJSON is derived from WKT 2, therefore it inherited that BoundCRS object despite its intentional omission from ISO 19111.

The recommended approach is that datum (a.k.a. reference frames) are merely identifiers, and transformations between datum are specified in a separated database such as the EPSG registry. The purpose of TOWGS84 / BoundCRS can be understood as adding (at least virtually) an entry in such database as a side-effect of reading the CRS definition. We acknowledge that there is practical reasons why users want to do that (the software may have no connection to an EPSG database, or the transformation may not exist in the EPSG database), which is why BoundCRS has been added in the CRS encoding. But at the conceptual level, a software parsing a BoundCRS should dispatch the information in two separated classes: ISO 19111 CRS (in GeoAPI: CoordinateReferenceSystem) and ISO 19111 RegisterOperations (in current GeoAPI: CoordinateOperationFactory — will be retrofitted in ISO 19111 RegisterOperations in next GeoAPI release).

This separation is called "late binding" in GIGS terms. It may sound complicated, but it exists because it is impossible to achieve high accuracy with the "early binding" model in important cases. This blog tries to explain why.

DerivedCRS

DerivedCRS is intended to be the base interface of all derived CRS. In the latest revision of ISO 19111, all derived CRS subclasses implement two interfaces. For example, DerivedGeodeticCRS extends both DerivedCRS and GeodeticCRS. The same pattern is applied to all other types. GeoAPI does not (yet) provide such DerivedGeodeticCRS interfaces, because we can leave that task to implementers. For example, an implementation in Java could be as below:

class MyDerivedGeodeticCRS implements DerivedCRS, GeodeticCRS {
    // ...
}

Note that the class does not need to be public. In practice, CRS are often handled either as a DerivedCRS or as a GeodeticCRS, and the user can switch between the two views with e.g. if (crs instanceof DerivedCRS) checks. On my side, I have not yet seen a situation where we wanted to enforce at compile time the fact that a CRS is both derived and geodetic (or vertical, etc.), since runtime checks were used anyway. But this analysis may change if there is a need for such compile-time checks.

[paulushub]

Note that the class does not need to be public. In practice, CRS are often handled either as a DerivedCRS or as a GeodeticCRS,

Sounds a little confusing to me.
For an application using the factory, should the user called a method createDerivedCRS or createGeodeticCRS?
How is he/she supposed to decide?

If created from WKT, the user must do the extra of checking if (crs instanceof DerivedCRS) or the other before processing?

Sorry, just trying to get some clarity on the API.

[desruisseaux]

Indeed, the proposed usage of DerivedCRS lack documentation in GeoAPI. An application using the factory should invoke createDerivedCRS. It has no choice, because a fundamental property of derived CRS is the conversion from base CRS, and only createDerivedCRS allows to specify that. Users do not need to specify that they want a DerivedGeographicCRS because the implementation can detect that by itself. For example:

public DerivedCRS createDerivedCRS(Map<String,?>             properties,
                                   CoordinateReferenceSystem baseCRS,
                                   Conversion                fromBase,
                                   CoordinateSystem          derivedCS)
{
    return switch (baseCRS) {
        case GeographicCRS base -> new MyDerivedGeographicCRS(properties, base, fromBase, derivedCS);
        case VerticalCRS   base -> new MyDerivedVerticalCRS  (properties, base, fromBase, derivedCS);
        // etc.
    }
}

If created from WKT, the user usually don't know in advance what will be the CRS type. The method signature in GeoAPI (derived from OGC 01-009) is simply:

CoordinateReferenceSystem createFromWKT(String wkt) throws FactoryException;

Therefore, if users want to know more about the type, they usually need to do instanceof checks anyway no matter the type they are interested in.

[paulushub]

Thanks for the clarification.
I am personally not a fan of those runtime checks like (instanceof), and will likely provide a quick means to determine the CRS type, say CoordinateReferenceType on the CoordinateReferenceSystem, similar to the GeometryType.

I was thinking ReferenceSystemType will play that role in ReferenceSystem, but there is no reference of it in the whole GeoAPI, by my search.