Conventions

Typographic and naming conventions

The elements defined in a computer language, such as classes and methods in Java or elements in an XML document, appear in monospaced font in this document. In order to facilitate an understanding of the relationships between Apache SIS and the standards, these elements are also represented using the following colour codes:

Elements in blue are defined in an ISO or OGC standard other than GeoAPI.
Elements in green are Java element defined in GeoAPI.
Elements in brown are defined in Apache SIS.
Elements left in black are either defined elsewhere (for example the standard Java library), or there is simply no emphasis on that element for the discussion.

For example to represent a projected coordinate reference system (Mercator, Lambert, etc), SC_ProjectedCRS is an UML and XML element defined by the ISO 19111 standard. Then org.opengis.referencing.crs.ProjectedCRS is the implementation-neutral GeoAPI interface derived from that standard, and org.apache.sis.referencing.crs.DefaultProjectedCRS is the implementation class provided by Apache SIS.

Apache SIS implements most GeoAPI interfaces by a classes of the same name than the interface but prefixed by Abstract, Default or General word. The General prefix is sometimes used instead of Default to indicate that alternative implementations are available for some specific cases. For example the Envelope interface is implemented by at least two Apache SIS classes: GeneralEnvelope and Envelope2D. The first implementation can represent envelopes with any number of dimensions while the second implementation is specialized for two-dimensional envelopes.

Apache SIS classes prefixed by Abstract should not (in principle) be instantiated. Users should instantiate a non-abstract subclass instead. However many SIS classes are only conceptually abstract, without abstract Java keyword in class definition. Such classes can be instantiated by a new AbstractXXX(…) statement despite being conceptually abstract. Such instantiations should be avoided, but are nevertheless permitted in last resort when it is not possible to determine the exact subtype.

Text in gray boxes, like below (click to expand), are for information purpose only and can be ignored.

Note about the definition of terms

Source of term definitions

Standards sometimes favour the application of certain generic terms to particular contexts, which may differ from the context in which other communities use these terms. For example, the terms domain and range may apply to arbitrary mathematical functions in order to designate a set of possible values of inputs and outputs respectively. The ISO 19123 standard applies these terms to CV_Coverage objects, seen as functions in which the domain is the set of spatio-temporal coordinates encompassed by the data, and the range is the set of values encompassed.

However the functions to which above terms are applied by ISO standards are not the same as the functions to which they are applied by other libraries. For example UCAR’s netCDF library applies these terms instead to the function for converting pixel indices (its domain) to spatial-temporal coordinates (its range). Thus the UCAR library’s range may be the domain of ISO 19123.

The Apache SIS library prefers as much as possible to use terms in the sense of OGC and ISO norms. Particular care must be taken, however, with the interfaces between SIS and certain other external libraries, in order to reduce the risk of confusion.