5.4.1.  Package namespaces

This specification uses “opengis” in the text for denoting a package or module in OGC namespace, but the fully qualified name depends on the programming language. For example, the metadata package is spelled “org.opengis.metadata” in Java but only “opengis.metadata” (without “org” prefix) in Python. Except in language-specific notes, this specification uses the shorter form in the text and lets readers adapt to their programming language of interest.

6.1.1.  Naming conventions

The interface and property names defined in OGC/ISO standards may be modified for compliance with the conventions in use in target programming languages. The main changes are described below:

6.1.2.  Multiplicity conventions

The UML diagrams may specify arbitrary multiplicities (minimum and maximum number of occurrences) for each property. But GeoAPI recognizes only the following four multiplicities, materialized in the API as annotations (Clause 6.1.3) and in the method signatures. If a different multiplicity is needed, then [0 … ∞] should be used with a restriction documented in the text attached to the property.

• [0 … 0] — the property cannot be set (this happen sometimes in subtypes).

• [0 … 1] — the property is optional or conditional.

• [1 … 1] — the property is mandatory.

• [0 … ∞] — the property can appear an arbitrary number of times, including zero or one.

Some programming languages have an Optional construct for differentiating the [0 … 1] and [1 … 1] cases. This construct is used where appropriate, but shall be considered only as a hint. It may appear in a mandatory property if that property was optional in the parent interface. Conversely, absence of Optional construct is not a guarantee that the value will never be null. Some properties fall in gray area, where they are usually not null but may be null in some rare situations. For example, the ellipsoid property of a Geodetic Reference Frame is mandatory when used in the context of geographic or projected coordinate reference systems, which are by far the most common cases. Even when used in other contexts, the ellipsoid is optional but still recommended. Consequently, GeoAPI does not use the Optional construct for the ellipsoid property in order to keep the most common usages simpler, but robust applications should be prepared to handle a null value. Developers should refer to the API documentation for the policy on null values.

When the multiplicity is [0 … ∞], the property type is a collection such as a list. In such case an absent property is represented by an empty collection, not a null value. When the multiplicity is [1 … ∞] the collection shall never be empty, but there is no language construct in Java and Python for enforcing that requirement.

6.1.3.  Annotated API

The opengis​.annotation package allows GeoAPI to document the UML elements from the various specification documents used for defining the Java and Python constructs. Those annotations encode the source document, stereotype, original name, and obligation level of the various types, properties and operations published by GeoAPI. The source document may be completed by a version number when the GeoAPI construct is based on a different edition of a normative document than the dated references listed in Clause 3. GeoAPI defines two annotations in the Java language (no annotation in Python): @UML which is applied on types and properties (fields or methods), and @Classifier which can be applied only on types. Those annotations are shown in the figure below:

An example in Annex D.1.1 shows how these annotations are applied in the Java language and how they are available at runtime by introspection.

6.1.4.  Derived methods

GeoAPI may define additional methods not explicitly specified in OGC/ISO abstract models, when the values returned by those methods can be derived from the values provided by standard OGC/ISO properties. Those extensions are enabled by the way properties are handled. In OGC/ISO abstract models each property could have its value stored verbatim, for example as a column in a database table, an XML element in a file or a field in a class. For enabling efficient use of OGS/ISO models in relational databases or XML files, those models are generally non-redundant: each value is stored in exactly one property. By contrast in GeoAPI all properties are getter methods: no matter how implementations store property values, users can fetch them only through method calls. Since methods are free to compute values from other properties, GeoAPI uses this capability for making some information more easily accessible in situations where property values can be reached only indirectly in OGC/ISO models. Those additional methods introduce apparent duplications, but they should be thought as links to the real properties rather than copies of the property values. Those methods are added sparsely, in places where introducing them brings some harmonization by reducing the needs to perform special cases. Examples include fetching the head of an arbitrary Generic­Name, fetching the Geodetic Reference Frame indirectly associated to a ProjectedCRS, fetching axes of an arbitrary Coordinate Reference System (including compound ones), and more. Those additional methods can be recognized by the absence of @UML annotation.

6.2.1.  Primitive types

From ISO 19103:2015 §7.2.1 and 7.2.5 to 7.2.11

Each primitive type of the OGC/ISO specifications maps to zero, one or two object structures in GeoAPI. Where the mapping can be made directly to a programming language primitive type, such as int and float, the language primitive is preferred. In languages where “primitives” and “wrappers” are distinct, wrappers may be used instead of primitives on a case-by-case basis. The following table shows the mapping used by GeoAPI to represent the primitive types in the ISO 19100 series.

Table 3 — Primitive types mapping

Notes:

• (1) Wrapper types such as java​.lang​.Integer or java​.util​.Optional­Int may be used where appropriate.

• (2) Sometimes substituted by long or java​.lang​.Long where the value may exceed 2³².

• (3) Decimal differs from Real, as Decimal is exact in base 10 while Real may not.

• (4) Substituted by org​.opengis​.util​.International­String where the string representation depends on the locale.

• (5) Actually an extension data type defined in ISO 19103:2015 annex C.2. See internationalization in Clause 6.2.8.

6.2.2.  Date and time

From ISO 19103:2015 §7.2.2 to 7.2.4

The ISO 19103 Date interface gives values for year, month and day while the Time interface gives values for hour, minute and second. DateTime is the combination of a date with a time, with or without timezone. GeoAPI maps the ISO date and time interfaces to the types provided in the standard library of target languages. In some cases like Java, this mapping forces GeoAPI to choose whether the time component shall include timezone information or not since the choices are represented by different types (e.g. LocalDateTime, OffsetDateTime and ZonedDateTime). The timezone information is often desired for geospatial data (for example in the acquisition time of a remote sensing image), but may be undesired for some other cases like office opening hours. In the latter case, the decision to include timezone or not depends if the opening hours apply to one specific office or to all offices spanning the multiple timezones of a country. GeoAPI generally includes timezone information, but this policy may be adjusted on a case-by-case basis.

Table 4 — Date and time types mapping

Notes:

• (1) Some properties defined in GeoAPI 3.x use the legacy java​.util​.Date class for historical reasons.

DateTime is distinct from Instant. The former is expressed in the proleptic Gregorian calendar as described in ISO 8601-1:2019, while the latter is an instantaneous point on the selected time scale, astronomical or atomic. An Instant does not have year, month or day components. It is instead a duration elapsed since an epoch, and its conversion to a Date­Time may be complicated. In GeoAPI, temporal objects in metadata are typically Date­Time while coordinates in a temporal coordinate reference system are typically Instant.

6.2.3.  Collections

From ISO 19103:2015 §7.3

GeoAPI implements ISO 19103 collection interfaces using the standard Collections Frameworks provided by Java and Python. A Set is a finite collection of objects where each object appears only once. A Bag is similar to a Set except that it may contain duplicated instances. The order of elements in a Set or a Bag is not specified. A Sequence is similar to a Bag except that elements are ordered.

Table 5 — Collections mapping

Unless otherwise required by the semantic of a property, GeoAPI preferably uses the Collection type in Java method signatures. This allows implementers to choose their preferred subtypes, usually Set or Sequence. The Set type is not the default type because enforcing element uniqueness may constraint implementations to use hash tables or similar algorithms, which is not always practical.

6.2.4.  Controlled vocabulary

From ISO 19103:2015 §6.5

A controlled vocabulary is an established list of standardized terminology (names, words or phrases) with associated definitions for use to identify, describe, index or retrieve information. A controlled vocabulary implementation commonly found in many programming languages is enumeration.

GeoAPI distinguishes two different types of controlled vocabularies: enumerations are closed controlled vocabularies: it is not possible to add new members (except by releasing new GeoAPI versions). By contrast, code lists are open vocabularies: they provide a basic set of members defined at compile-time, but users are free to add new members at runtime. Many programming languages provide an enum construct for the closed case. For the opened case, GeoAPI defines the Code­List abstract class in Java.

Table 6 — Enumerated types mapping

Notes:

• (1) GeoAPI does not yet provide an extensible implementation of code list in the Python language, but this limitation may be addressed in a future version.

Code lists can be extended by calls to valueOf(String) methods in the Java language. Extensions should follow ISO 19103 recommendation: Extensions of a code list use the existing code list values and merely add additional unique values. These additional values should not replace an existing code by changing the name or definition, or have the same definition as an existing value.

The figure below shows one closed (on the left side) and one opened (on the right side) enumeration derived from ISO 19115. The Controlled­Vocabulary parent interface is a GeoAPI addition. Its indirect inheritance by Pixel­Orientation is because the Enum class is defined by programming language standard library and cannot be modified directly. An example in Annex D.1.2 shows how code lists are used in the Java language.

6.2.5.  Name types

From ISO 19103:2015 §7.5

A Generic­Name is a sequence of identifiers rooted within the context of a namespace. NameSpace defines a domain in which names can be mapped to objects. For example, names could be primary keys in a database table, in which case the namespace is materialized by the table. Each storage (XML, shapefiles, netCDF, …) may have their own constraints for names in their namespaces.

GenericName is the base interface for all names in a NameSpace. A generic name can be either a Local­Name, or a Scoped­Name which is an aggregate of a Local­Name (the head) for locating another Name­Space and a Generic­Name (the tail) valid in that name space. For example if “urn:ogc:def:crs:EPSG:10:4326” is a Scoped­Name, then “urn” is the head and “ogc:def:crs:EPSG:10:4326” is the tail. GeoAPI extends the model by allowing navigation in the opposite direction, with “urn:ogc:def:crs:EPSG:10” as the path and “4326” as the tip.

TypeName and MemberName are subtypes of LocalName for referencing a type (for example a class) and a member (for example a property in a class) respectively. All those types are mapped to Java and Python classes as below:

Table 7 — Name types mapping

6.2.6.  Record types

From ISO 19103:2015 §7.7

Records define new data type as an heterogeneous aggregation of component data types (the fields). A Record­Type defines dynamically constructed data type. It is identified by a Type­Name and contains an arbitrary number of fields as (name, type) pairs. A Record is an instance of Record­Type containing the actual field values.

Record and RecordType are lookup mechanisms that associate field names to values and value types respectively. Field names are locally mapped, and field types are most often primitives. Because the Record­Type describes the structure of a set of records, it is essentially a metaclass for that set of records viewed as a class. In dynamic languages such as Python, the Record and Record­Type interfaces are not really needed because those languages can handle dynamically constructed data types natively, but they can nevertheless be useful as marker interfaces.

Table 9 — Record types mapping

6.2.7.  Web types

From ISO 19103:2015 §C.3

ISO 19103 defines the following data types for use in World Wide Web environments. Those types are often found in XML documents. GeoAPI maps the ISO types to standard types of the target languages without introducing new interfaces.

Table 10 — Web types mapping

6.2.8.  Internationalization

From ISO 19103:2015 §C.2

The International­String interface is defined by GeoAPI to handle textual sequences which may potentially need to be translated for users of different locales. Conceptually this act as a Character­String but may, depending on the implementation, provide access to locale specific representations of that string. GeoAPI International­String is closely related, but not identical, to ISO 19103 Language­String. The main difference is that the latter is a character string in one specific language, while International­String can be a collection of character strings in different locales. This is useful, for example, when an implementation is operating on a server that serves multiple languages simultaneously, to allow sending string representations in the locale of the client rather than the locale of the server running the GeoAPI implementation.

The toString() method (__str__ in Python) returns the text in a language at implementer’s choice. The toString(Locale) method tries to return the text in the specified language if available, and otherwise fallbacks on a language at implementer’s choice. This specification makes no recommendation about the default or fallback languages because some programming languages provide their own mechanism (e.g. using Language Range as defined by IETF RFC 4647). Consequently, GeoAPI delegates most internationalization types to the target language standard library, as shown in the following table. An example in [International__xad_String] shows the use of International­String in the Java language.

Table 11 — Linguistic types mapping

Notes:

• (1) Sometimes substituted by Char­Sequence or International­String.

• (2) Defined as a unit of measurement in ISO 19103 §C.4.24.

• (3) From ISO 19103 §7.2.10 (primitive types).

6.2.9.  Units of measurement

From ISO 19103:2015 §C.4

ISO 19103 represents measurements and their units by two base interfaces: Measure for the result from performing the act of ascertaining the value of a characteristic of some entity, and UnitOf­Measure as a quantity adopted as a standard of measurement for other quantities of the same kind. Those two base interfaces have a parallel set of subtypes. For example, Length as a Measure specialization for distances, accompanied by UomLength as an UnitOf­Measure specialization for length units. Likewise Area is accompanied with UomArea, Time is accompanied with UomTime, etc.

GeoAPI does not define any interface for the ISO 19103 Measure and UnitOf­Measure types because Java and Python already have their own library for units of measurement. For example, Java has standardized a set of quantity interfaces in the Java Specification Request JSR 385. When such language-specific standard exists and provides equivalent functionality to ISO 19103, that external standard is used. See Java profile (Annex B.1) or Java example code (Annex D.1.5) for more information.

6.3.1.  Package mapping

From ISO 19115-1:2014 §6.5.[2…14] and §6.6; ISO 19157:2013

The mapping of ISO packages to GeoAPI packages follows a parallel naming scheme, shown in the table below. Some minor packages (for example Portrayal catalogue which contains only one interface) have been aggregated into another package. All packages are defined by ISO 19115 except Data quality which is defined by ISO 19157 but considered by GeoAPI as metadata for historical reasons, and Reference system which has been retrofitted in the ISO 19111 interfaces from the referencing package.

Table 12 — Metadata package mapping

6.3.2.  Reference systems

Derived from ISO 19115-1:2014 §6.5.8

The way GeoAPI handles reference systems in metadata differs significantly from ISO 19115. Coordinate Reference Systems (CRS) are defined in details by the ISO 19111 standard. But the ISO 19115 metadata standards do not reference those CRS interfaces directly (except in one case), at the cost of some overlaps. By contrast GeoAPI does not enforce such separation between standards when a bidirectional dependency can bring harmonization. A bidirectional dependency does not imply that implementers have to support both ISO standards.

Reference Systems interfaces are defined in GeoAPI referencing packages. A Reference System may be a Coordinate Reference System (ISO 19111:2019) or may use geographic identifiers (ISO 19112:2019). GeoAPI supports both cases by defining Reference­System as the common parent of Coordinate Reference System and Reference System using Geographic Identifier. This is done by inserting the ISO 19115 Reference­System interface between IdentifiedObject and CoordinateReferenceSystem in ISO 19111 type hierarchy as shown below (note: this diagram does not show all types, properties and associations for brevity reasons):

More information about the Coordinate­Reference­System interface is given in the Referencing packages section (Clause 6.5). The following table lists all association to a reference system from the metadata packages:

Table 13 — Associations from a metadata object to a reference system

6.3.3.  Nil values

ISO/TS 19115-3:2016 – XML schema implementation for fundamental concepts allows property values to be nil even when the property is declared mandatory by ISO 19115-1 standard. In such case, ISO 19115-3 requires to specify why the property is nil. Nil reasons can be:

• Template: the metadata is only a template with values to be provided later.

• Withheld: the value is not divulged.

• Unknown: a correct value probably exists but is not known and not computable.

• Missing: the correct value is not readily available and may not exist.

• Inapplicable: there is no value.

GeoAPI does not provide a mechanism for specifying the reason why a property is nil. Instead, the GeoAPI rules of method return values have been relaxed for the metadata packages. Elsewhere in GeoAPI, methods which have a mandatory obligation in the specification must return an instance of the return type and cannot return the Java null or Python None reference. However, in the metadata package this rule is relaxed because data sets are encountered so frequently which have nil values for any of above-cited reasons. In the GeoAPI metadata packages, methods for mandatory properties should return a valid instance, but users should be prepared to receive null (Java), None (Python) or an empty collection. This modification has been adopted to allow implementations sufficient latitude about how to handle metadata records with nil values. Nonetheless, sophisticated implementations can determine if a metadata record conforms with the ISO 19115-1 specification by inspecting the annotations at runtime (Annex D.1.1).

6.3.4.  Departures from ISO 19115

Metadata in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.

6.4.1.  Geometry base class

Each geometric object is considered an infinite set of points (except the Point object which contains only itself). As a set, their most fundamental operations are of the same nature as the standard operations of Java collections. We could therefore see a geometry as a kind of java​.util​.Set in which the elements are points, except that the number of elements contained in the set is infinite (with the exception of geometries representing a simple point). To better represent this concept, the ISO standard and GeoAPI define a Transfinite­Set interface which we could see as a Set of potentially infinite size. Although a parent relationship exists conceptually between these interfaces, GeoAPI does not define Transfinite­Set as a sub-interface of java​.util​.Set, as the definition of certain methods such as size() and iterator() would be problematic. However, we find very similar methods such as contains(…) and intersects(…).

ISO 19107 defines two types of structures to represent a point: GM​_Point and Direct­Position. The first type is a true geometry and may therefore be relatively cumbersome, depending on the implementation. The second type is not formally considered to be a geometry; it extends neither GM​_Object nor Transfinite­Set. It barely defines any operations besides the storing of a sequence of numbers representing a coordinate. It may therefore be a more lightweight object. In order to allow API to work equally with these two types of positions, ISO 19107 defines Position as a union of Direct­Position and GM​_Point. GeoAPI represents the union as parent interface for compatibility with languages that do not support union.

6.4.2.  Departures from ISO 19107

Geometries in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.

6.4.3.  Renaming

The parent class of all geometries is called GM​_Object in the ISO 19107 standard. GeoAPI interfaces use the Geometry name instead, as the omission of the GM_ prefix would leave a name too similar to Java’s Object class.

6.5.1.  Coordinate systems

From ISO 19111:2019 §10 and §C.3

A Coordinate System (CS) contains the set of axes that spans a given coordinate space. Each axis defines an approximate direction (north, south, east, west, up, down, port, starboard, past, future, etc.), units of measurement, minimal and maximal values, and what happen after reaching those extremum. For example, in longitude case, after +180° the coordinate values continue at −180°.

In addition to axis definitions, another important coordinate system characteristic is their type (CartesianCS, SphericalCS, etc.). The CS type implies the set of mathematical rules for calculating geometric quantities such as angles, distances and surfaces. Usually the various CS subtypes do not define any new programmatic methods compared to the parent type, but are nevertheless important for type safety. For example, many calculations or associations are legal only when all axes are perpendicular to each other. In such case the coordinate system type is restricted to CartesianCS in method signatures.

6.5.2.  Factories

From OGC 01-009 §12.3.[6…7] and §12.4.6

The referencing packages include factory types defined originally in the OGC 01-009 specification. These factories define a normalized approach to object instantiation and, if used exclusively, simplify the work of switching between implementations. Subtypes of Object­Factory instantiate objects by assembling components passed as arguments and subtypes of Authority­Factory instantiate objects based on identifiers in some third party database, notably those in the EPSG geodetic dataset.

TODO: Some methods of CRSAuthorityFactory and CoordinateOperationAuthorityFactory to be replaced by ISO 19111:2019 RegisterOperations.

Code that needs to instantiate one of the objects defined in GeoAPI referencing packages should first obtain the factory in some platform dependent manner and then use the factory methods to instantiate the desired object instances. These instances can then be used through the interfaces defined in the GeoAPI library.

In Java, factory implementations are discovered by java​.util​.Service­Loader. In Python, GeoAPI does not have a recommended mechanism yet.

GeographicCRS WGS84 = crsAuthorityFactory.createGeographicCRS("EPSG::4326");

6.5.3.  Coordinate operations

From ISO 19111:2019 §12 and §C.5

A Coordinate Operation can transform or convert coordinate tuples from one Coordinate Reference System (CRS) to another CRS. There are four kinds of coordinate operations in GeoAPI:

• A coordinate conversion is the implementation of some mathematical formulas without empirically derived parameters. Conversions can be as accurate as floating point computations allow. Map projections are kinds of coordinate conversions.

• A coordinate transformation involves empirically derived parameters. Because those parameters have observational error and because transformation methods are only approximations of a complex reality, the coordinate transformation results also have errors. Furthermore, several transformations may exist for the same pair of coordinate reference systems, differing in their method, parameter values, domain of validity and accuracy characteristics.

• TODO: Point motion operation.

• A concatenated operation defines a sequential execution of any of above operations.

GeoAPI provides three ways to create a coordinate operation, described in the following sub-sections.

6.5.4.  Math transforms

From OGC 01-009 §12.4.5

The Coordinate­Operation object introduced in previous section provides high-level information (source and target CRS, domain of validity, positional accuracy, operation parameter values, etc). The actual mathematical work is performed by a separated object obtained by a call to getMath­Transform(). At the difference of Coordinate­Operation instances, Math­Transform instances do not carry any metadata. They are kind of black box which know nothing about the source and target CRS, the domain or the accuracy (actually the same MathTransform can be used for different pairs of CRS if the mathematical work is the same), Furthermore, Math­Transform may be implemented in a very different way than what Coordinate­Operation said. In particular many conceptually different coordinate operations such as unit conversions, axis swapping, etc. can be implemented by Math­Transform as affine transforms and concatenated for efficiency. The result may be a Math­Transform doing in a single step a calculation described by Coordinate­Operation as a chain of distinct operations. Having Math­Transform separated from Coordinate­Operation gives more flexibility to implementers for optimizations.

MathTransform has a method taking a DirectPosition (the coordinates in source CRS) in input and returning a Direct­Position (the coordinates in target CRS) in output. But Math­Transform provides also various methods operating on an arbitrary number of coordinate tuples packed in arrays of float or double types. If there is many points to transform, the methods operating on arrays will generally be much more efficient than the method operating on Direct­Position. The example in Annex D.1.8 shows how to transform in Java the coordinates of 6 cities.

6.5.4.1.  Partial derivatives

From OGC 01-009 §12.4.5.6

MathTransform can also provide the derivative of the transform function at a point. For example, if P is a map projection converting degrees of latitude and longitude (φ, λ) into projected coordinates (x, y) in metres, then the derivative said what would be the displacement V⃗ in metres if the latitude is increased by 1° north, and what would be the displacement U⃗ in metres if the longitude is increased by 1° east. Those vectors are potentially different for every locations on the map. The figure below illustrates the vectors evaluated at two locations, P₁ and P₂:

Figure 13 — Derivatives of a map projection

The derivative is the matrix of the non-translating portion of the approximate affine map at the point. The derivative at a location P can be represented by a Jacobian matrix as below. The first matrix column gives the V⃗ vector and the second column gives the U⃗ vector of Figure 13, in that order because this example uses latitude, longitude axis order as inputs.

$J_P\left(\varphi ,\lambda \right)=\left[\begin{array}{cc}\frac{\partial x}{\partial \varphi }& \frac{\partial x}{\partial \lambda }\\ \frac{\partial y}{\partial \varphi }& \frac{\partial y}{\partial \lambda }\end{array}\right]$  (1)

Jacobian matrices can easily be concatenated in a chain of operations. The Jacobian matrix of the whole chain is the product of the Jacobian matrices of each step. Another useful property is that for obtaining the Jacobian of the reverse operation P⁻¹, the equations do not need to be derived. The Jacobian of the forward projection can be computed, then the matrix inverted:

$J_{P^{-1}}={\left(J_P\right)}^{-1}$  (2)

6.5.5.  Well-Known Text (WKT)

From ISO 19162:2019 and OGC 01-009 §7.1

Most objects in the opengis​.referencing packages can be imported and exported in Well-Known Text (WKT) format. This format allows the exchange of CRS definitions with implementations of other OGC standards such as web services. GeoAPI provides two toWKT() methods for producing a WKT representation of an object:

• One method is defined in the Identified­Object parent interface and is inherited notably by Coordinate­Reference­System. But that method can also be used with Coordinate­Operation and various components such as Datum. Well Known Text (WKT) character strings produced by that method shall be compliant with the format defined in the ISO 19162:2019 standard.

• A second toWKT() method is defined in the Math­Transform interface, which is not an object defined by ISO standards. Character strings produced by that method shall be compliant with the format defined in OGC 01-009 §7.1. Other sections such as OGC 01-009 §7.2 should be ignored since they are replaced by ISO 19162.

Difference between the two WKT representations is illustrated below. For a very simple operation doing only a swapping of latitude and longitude axes, the ISO 19162 representation of the Coordinate­Operation object can be as below:

COORDINATEOPERATION[“Axis order change (2D)”,
  SOURCECRS[GEODCRS[“RGF93”, …definition omitted for brevity…, ID[“EPSG”, 4171]]],
  TARGETCRS[GEODCRS[“RGF93 (lon-lat)”, …definition omitted for brevity…, ID[“EPSG”, 7084]]],
  METHOD[“Axis Order Reversal (2D)”, ID[“EPSG”, 9843]],
  AREA[“World.”], BBOX[-90.00, -180.00, 90.00, 180.00]]

Figure 14 — ISO 19162 representation of a coordinate operation

The OGC 01-009 §7.1 representation of the Math­Transform associated to above coordinate operation can be as below. All metadata information (source and target CRS, domain of validity, etc.) are lost, and the human-readable ”Axis Order Reversal” operation is replaced by a more mathematical “Affine parametric transformation” operation.

PARAM_MT[“Affine”,
  PARAMETER[“num_row”, 3],
  PARAMETER[“num_col”, 3],
  PARAMETER[“elt_0_0”, 0.0],
  PARAMETER[“elt_0_1”, 1.0],
  PARAMETER[“elt_1_0”, 1.0],
  PARAMETER[“elt_1_1”, 0.0]]

Figure 15 — OGC 01-009 representation of a math transform

Those two representations are complementary. CoordinateOperation.toWKT() provides high-level information about the operation together with metadata for understanding the context. MathTransform.toWKT() said more information about how the operation is implemented, which is useful for analyzing the validity of transformation results.

The converse operation – creating an object from a WKT definition – is done by create­FromWKT(…) methods defined in CRSFactory and Math­Transform­Factory interface.

6.5.6.  Departures from ISO 19111

The main departures of GeoAPI from the ISO 19111 standards are inspired by the legacy OGC 01-009 standard published in 2001. That legacy standard included COM, CORBA and Java profiles. In support for those profiles, some aspects of the legacy model were better suited to programming languages compared to the more web-focused standards published the following years. GeoAPI retains some OGC 01-009 aspects when appropriate and adapt them to the ISO 19111 interfaces. References to OGC 01-009 clauses are given in sub-sections below.

6.5.7.  Parameters

From ISO 19111:2019 §11.2, ISO 19115-1:2014 §6.5.12, ISO 19157:2013 §C.2.2.4

The concept of operation parameters is defined in many OGC/ISO standards:

• ISO 19111:2019 provides CC​_Operation­Parameter,

• ISO 19115-1:2014 provides SV​_Parameter,

• ISO 19157:2013 provides DQM​_Parameter,

• ISO 19143:2010 provides Argument, and

• OGC 01-004 (a legacy standard, but still useful to GeoAPI) provided GC​_Parameter­Info.

GeoAPI provides a unified parameter framework in the org​.opengis​.parameter Java package. The ISO 19111 model is adopted as the basis because it provides a clear separation between the definition of a parameter (name, aliases, identifier, expected value type and units) and the actual parameter value. The parameter properties that are defined by other standards but not present in CC​_Operation­Parameter are retrofitted in the GeoAPI parameter framework.

Table 17 — Main parameter properties and their mapping to ISO standards

ISO 19157 Description type contains a mandatory text and an optional illustration. Only the text description is explicitly stored in the GeoAPI unified parameter type. However, if needed implementations can associate the description property to an object that implement both the International­String and Description interfaces.

6.6.1.  Moving feature

From OGC 18-075 figure 3

Features often have an attribute of type Geometry (ISO 19107:2003). A sub-type of Geometry is Trajectory (ISO 19141:2008). A feature where the geometry is a trajectory is a moving feature. In addition of time-dependent positions defined by the trajectory, a moving feature may also have time-dependent attribute values. Those attributes are represented by the Dynamic­Attribute sub-type.

6.7.1.  Expression

From ISO 19143:2010 §7.[3…6]

An expression is a function that receives a resource (typically a Feature) in input and produces a value (typically a character string, a number or a geometry) in output. The output is restricted to Boolean if the expression is used as an operand of a Logical­Operator (Clause 6.7.2).

Expressions extend the mechanism provided by the target platform for defining functions. For example, in the Java language, Expression extends the java​.util​.function​.Function interface (Annex B.2).

An expression can be a literal, a reference to the values of a particular property in resources, or a named procedure (for example arithmetic operations between the results of two sub-expressions). An expression can have zero or more parameters and generates a single result. The parameters themselves are in-turn expressions and shall appear in the order in which they are defined in the Filter­Capabilities (Clause 6.7.3).

ValueReference is an expression whose value is computed by retrieving the value indicated by a name or a XPath in a resource (typically a property in Feature instances), and Literal is an expression whose value is a constant.

Parameters are specified at Expression creation time. For example, an expression computing x+1 where x is the value of a Feature property can be created with two parameters: a Value­Reference retrieving the x value for each feature and a Literal whose value is the integer 1. When apply(f) is invoked on that “Add” expression where f is a Feature instance, the “Add” expression invokes in turn apply(f) on the two above-cited parameters. The values computed by those parameters are added, then returned by the “Add” expression.

6.7.2.  Filter

From ISO 19143:2010 §7.[7…11]

A filter is a predicate that identifies a subset of resources from a collection of resources. Each resource instance is evaluated against a filter, which always evaluates to true or false. If the filter evaluates to true, the resource instance is included in the result set. If the filter evaluates to false, the resource instance is ignored. Roughly speaking, a filter encodes the information present in the WHERE clause of a SQL statement.

There are various sub-interfaces of this interface that represent many types of filters, such as simple property comparisons or spatial queries. The following diagram shows the 4 basic types of filters together with the code lists identifying which operation is applied. More specialized sub-types such as Binary­Comparison­Operator and Distance­Operator are not shown in this diagram.

In above diagram, the operator­Type property defined in the Filter parent interface is overridden by more specialized types (shown as associations) in each sub-interface. This is type covariance. Likewise expression is defined in parent interface with unconstrained multiplicity, but that multiplicity is restrained in sub-interfaces.

Filter operands are expressions. For example, a filter named “PropertyIs­EqualTo” uses two expressions. The first expression may be a Value­Reference fetching the value of a property and the second expression may be a Literal with the desired value.

6.7.3.  Capabilities

From ISO 19143:2010 §7.13

FilterCapabilities is the entry point for listing which expressions and filter operators are available. It capabilities are separated in the following categories:

• IdCapabilities lists names that represent the resource identifier elements that the service supports.

• Scalar­Capabilities advertises which logical, comparison and arithmetic operators the service supports.

• Spatial­Capabilities advertises which spatial operators and geometric operands the service supports.

• Temporal­Capabilities advertises which temporal operators and temporal operands the service supports.

• Available­Function describes functions that may be used in filter expressions.

• Extended­Capabilities advertises any additional operators added to the filter syntax.

The enumeration of scalar, spatial and temporal capabilities use de code lists shown in Clause 6.7.2. The arguments of available functions are described by the unified parameter API (Clause 6.5.7).

6.7.4.  Departures from ISO 19143

The ISO 19143 model is slightly modified in GeoAPI for retrofitting with existing interfaces in Java and Python. Some modifications are also applied for generalization when non-encoded property values can be computed. The aim is to facilitate computational operations without preventing the encoding of ISO 19143 compliant XML documents, as omitted types (for example) can be inferred.