diff --git a/spec/semantic-annotations/24-049.adoc b/spec/semantic-annotations/24-049.adoc new file mode 100644 index 00000000..89fc1474 --- /dev/null +++ b/spec/semantic-annotations/24-049.adoc @@ -0,0 +1,75 @@ += GeoPackage Extension for Semantic Annotations +:comment: ### Document type; mandatory. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:doctype: standard +:comment: ### Document subtype; optional. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:docsubtype: implementation +:comment: ### Version number; optional. Dot-delimited, preferably with this structure .. +:edition: 1.0.0 +:comment: ### Language of the document; mandatory. Specified in two-letter code: "en" for English, "fr" for French +:language: en +:comment: ### Document status/stage; mandatory. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:status: swg-draft +:comment: ### Relevant committee; mandatory. The permitted types are: technical, planning, and strategic-member-advisory +:committee: technical +:comment: ### Internal reference number; mandatory +:docnumber: 24-049 +:comment: ### Date on which the standard was updated; mandatory +:received-date: 2024-09-01 +:comment: ### Date on which the standard was approved by the issuing authority; mandatory +:issued-date: 2024-09-09 +:comment: ### Date on which the standard was published; mandatory +:published-date: 2024-10-14 +:comment: ### External link referencing the document; optional. If not provided, a default value is created following this structure: "http://www.opengis.net/doc/{abbrevation of doctype}/{abbrev}/{version}", +:external-id: http://www.opengis.net/IS/GPKG-SemanticAnnotations/1.0 +:comment: ### Author one +:fullname: Jérôme Jacovella-St-Louis +:comment: ### Author two +:fullname_2: Jeff Yutzler +:comment: ### Role of the authors; mandatory +:role: editor +:comment: ### Comma delimited keywords; mandatory +:keywords: ogcdoc, OGC document, GeoPackage, Semantic Annotations, GeoDataClass, Associations +:comment: ### Semicolon-delimited list of the submitting organizations; mandatory +:submitting-organizations: US Army Geospatial Center (AGC); Ecere Corporation; Compusult Limited; TechMaven Geospatial; Image Matters, LLC. +:comment: ### Metanorma flavor; mandatory +:mn-document-class: ogc +:comment: ### Desired output formats; mandatory +:mn-output-extensions: html,pdf,doc,rxl +:comment: ### Enable local relaton cache for quick inclusion of prefetched references; optional. For further information, visit: https://www.metanorma.org/author/ref/document-attributes/#caches, https://www.metanorma.org/author/topics/building/reference-lookup/#lookup-result-caching +:local-cache-only: +:comment: ### URI to which the PDF version of this standard is published; optional +:pdf-uri: ./24-049.pdf +:comment: ### URI to which the XML version of this standard is published; optional +:xml-uri: ./24-049.xml +:comment: ### Directory name used as prefix for the location of image files; optional +:imagesdir: images +:comment: ### Enable rendering of AsciiMath, MathML, and LaTeX ("latexmath" needs to be indicated in the code to use LaTeX, or set ":stem: latexmath" to interpret by default); optional +:stem: + +// Clauses +include::sections/00-preface.adoc[] + +include::sections/01-scope.adoc[] + +include::sections/02-conformance.adoc[] + +include::sections/03-references.adoc[] + +include::sections/04-terms_and_definitions.adoc[] + +// include::sections/unused-conventions.adoc[] + +include::sections/05-overview.adoc[] + +include::sections/06-semantic-annotations.adoc[] + +// Annexes +include::sections/aa-ats.adoc[] + +// include::sections/ab-implementations.adoc[] + +// Revision history +include::sections/ah-history.adoc[] + +// Bibliography +include::sections/az-bibliography.adoc[] diff --git a/spec/semantic-annotations/sections/00-preface.adoc b/spec/semantic-annotations/sections/00-preface.adoc new file mode 100644 index 00000000..3dcd0a58 --- /dev/null +++ b/spec/semantic-annotations/sections/00-preface.adoc @@ -0,0 +1,96 @@ + +//// +== Keywords + +Keywords inserted here automatically by Metanorma +//// + + +.Preface + +This Standard describes an extension for semantic annotations in GeoPackage. +This extension was developed and validated during several OGC initiatives, +including the Vector Tile Pilots (https://www.ogc.org/initiatives/vt-pilot-2018/[Phase 1+extension] and https://www.ogc.org/initiatives/vtp2/[Phase2]), +https://docs.ogc.org/per/19-018.html[Testbed 15], https://docs.ogc.org/per/20-019r1.html[Testbed 16] as well the Releasable Basemap Tiles code sprint. + +//// +[NOTE] +==== +Insert Preface Text here. Give OGC specific commentary: describe the technical content, reason for document, history of the document and precursors, and plans for future work. + +There are two ways to specify the Preface: "simple clause" or "full clasuse" + +If the Preface does not contain subclauses, it is considered a simple preface clause. This one is entered as text after the `.Preface` label and must be placed between the AsciiDoc document attributes and the first AsciiDoc section title. It should not be give a section title of its own. + +If the Preface contains subclauses, it needs to be encoded as a full preface clause. This one is recognized as a full Metanorma AsciiDoc section with the title "Preface", i.e. `== Preface`. (Simple preface content can also be encoded like full preface.) + +==== +//// + +//// +*OGC Declaration* +//// + +//// +[THIS TEXT IS ALREADY ADDED AUTOMATICALLY IN THE FRONTISPIECE OF ALL OGC DOUCMENTS] + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. + +Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation. +//// + +//// +NOTE: Uncomment ISO section if necessary + +*ISO Declaration* + +ISO (the International Organization for Standardization) is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization. + +International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2. + +The main task of technical committees is to prepare International Standards. Draft International Standards adopted by the technical committees are circulated to the member bodies for voting. Publication as an International Standard requires approval by at least 75 % of the member bodies casting a vote. + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. +//// + +[abstract] +== Abstract + +This Standard describes an extension for semantic annotations in GeoPackage. + +An annex defines an Abstract Test Suite for the extension. + +[.preface] +== Security Considerations + +//If no security considerations have been made for this Standard, use the following text. + +No security considerations have been made for this Standard. + +//// +If security considerations have been made for this Standard, follow the examples found in IANA or IETF documents. Please see the following example. + +“VRRP is designed for a range of internetworking environments that may employ different security policies. The protocol includes several authentication methods ranging from no authentication, simple clear text passwords, and strong authentication using IP Authentication with MD5 HMAC. The details on each approach including possible attacks and recommended environments follows. + +Independent of any authentication type VRRP includes a mechanism (setting TTL=255, checking on receipt) that protects against VRRP packets being injected from another remote network. This limits most vulnerabilities to local attacks. +NOTE: The security measures discussed in the following sections only provide various kinds of authentication. No confidentiality is provided at all. This should be explicitly described as outside the scope....” +//// + +//// +== Submitting organizations + +Submitting organisations added automatically by Metanorma from document attributes +//// + +[.preface] +== Submitters +The following individuals submitted this candidate standard to the OGC: + +|=== +|Name |Affiliation +|Jérôme Jacovella-St-Louis (editor) | Ecere Corporation +|Jeff Yutzler (editor) | Image Matters LLC. +|Adam Parsons | Compusult Limited +|Jordan Bess | Tech Maven Geospatial +|Jeff Harrison | U.S. Army Geospatial Center +|=== diff --git a/spec/semantic-annotations/sections/01-scope.adoc b/spec/semantic-annotations/sections/01-scope.adoc new file mode 100644 index 00000000..e83d6bb5 --- /dev/null +++ b/spec/semantic-annotations/sections/01-scope.adoc @@ -0,0 +1,8 @@ + +== Scope + +This Engineering Report describes an extension for storing Releasable Basemap Tiles (RBT) in GeoPackage developed during an OGC Code Sprint initiative. + +This extension regroups requirements specific to storing RBT data products in GeoPackages, requirements for storing vector tiles in GeoPackages, requirements for defining semantic annotations in GeoPackages, as well as requirements to include portrayal information in GeoPackages. + +In addition to the extension itself, this Engineering Report includes details of three implementations developed during the code sprint, including Technology Integration Experiments demonstrating interoperability between them. diff --git a/spec/semantic-annotations/sections/02-conformance.adoc b/spec/semantic-annotations/sections/02-conformance.adoc new file mode 100644 index 00000000..1fa543c2 --- /dev/null +++ b/spec/semantic-annotations/sections/02-conformance.adoc @@ -0,0 +1,16 @@ + +== Conformance + +This extension defines of a single mandatory conformance class, but is broken down into conceptual requirement classes which may eventually correspond to individual standardized OGC GeoPackage extensions. + +The requirements apply to either of these two standardization target types: + +* data products, +* software producing such data products. + +Conformance with this extension shall be checked using all the relevant tests specified in Annex A (normative) of this document. +The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the NSG Compliance Testing Policies and Procedures and the NSG Compliance Testing web site. + +In order to conform to this candidate NSG data product standard, a software implementation producing a compliant data product shall implement the core requirement classes defined in this extension. + +All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified. diff --git a/spec/semantic-annotations/sections/03-references.adoc b/spec/semantic-annotations/sections/03-references.adoc new file mode 100644 index 00000000..be0c5e3a --- /dev/null +++ b/spec/semantic-annotations/sections/03-references.adoc @@ -0,0 +1,9 @@ + +[bibliography] +== References + +The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. +For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies. + +* [[[OGC12-128r19,OGC 12-128r19]]], +* [[[OGC17-083r4,OGC 17-083r4]]], diff --git a/spec/semantic-annotations/sections/04-terms_and_definitions.adoc b/spec/semantic-annotations/sections/04-terms_and_definitions.adoc new file mode 100644 index 00000000..a61e35f0 --- /dev/null +++ b/spec/semantic-annotations/sections/04-terms_and_definitions.adoc @@ -0,0 +1,43 @@ + +== Terms and Definitions + +//// +Note that the initial notice about terms ("This document uses the terms defined in OGC Policy Directive 49...") +is inserted automatically by Metanorma using the agreed standardised language, and you should not enter it here. +//// + +[[term-2DTMS]] +=== 2-Dimensional Tile Matrix Set (2DTMS) + +tiling scheme consisting of a set of tile matrices defined at different scales covering approximately the same area and having a common coordinate reference system. + +[.source] +<> + +[[term-geodataclass]] +=== geodataclass + +a URI identifying a class of geospatial data whose component data layers conform to a particular logical schema + +A registry of geodataclasses would ideally resolve these URIs to metadata including these schemas. +A geodataclass serves multiple purposes, including the ability to easily identify, using a simple identifier comparison, +relevant datasets for a particular purpose, the compatibility of datasets as inputs for processes, the compatibility +of the output of a process with the input of another process, as well as the compatibility of portrayal style information +with a particular dataset (see also https://github.com/opengeospatial/styles-and-symbology/issues/12). + +[[term-mvt]] +=== Mapbox vector tiles (MVT) + +a https://github.com/mapbox/vector-tile-spec/tree/master/2.1[specification] developed by Mapbox for encoding tiled vector data using https://protobuf.dev/[protocol buffers]. + +[[term-rbt]] +=== releasable basemap tiles (RBT) + +tilesets of foundational geospatial data developed by the US Army Geospatial Center for public release, +including vector tilesets of cultural and physical features, hillshaded elevation data and optional imagery + +[[term-tie]] +=== technology integration experiment (TIE) + +experiments performed between different implementations of a specification or standard to test and demonstrate interoperability between them, and in the case of TIEs +performed in the context of an initiative to validate a draft specification or standard, to validate the soundness and completeness of the requirements specified therein diff --git a/spec/semantic-annotations/sections/05-overview.adoc b/spec/semantic-annotations/sections/05-overview.adoc new file mode 100644 index 00000000..7b6ebafb --- /dev/null +++ b/spec/semantic-annotations/sections/05-overview.adoc @@ -0,0 +1,25 @@ +[[OverviewClause]] +== Overview + +This Engineering Report describes an extension for storing Releasable Basemap Tiles (RBT) in GeoPackage developed during the March 2024 OGC Code Sprint initiative sponsored by the US Army Geospatial Center (AGC). + +The report is organized into four main sections: + +* <> describes the RBT extension as a whole, including requirements for declaring conformance to this extension, as well as requirements specific to storing RBT data products, + +* <> describes requirements related to storing vector tiles in GeoPackages, based on the draft extensions developed in previous initiatives such as +the Vector Tile Pilots (https://www.ogc.org/initiatives/vt-pilot-2018/[Phase 1+extension] and https://www.ogc.org/initiatives/vtp2/[Phase2]), + +* <> describes requirements related to semantic annotations, also based on previously developed draft extensions, providing a mechanism to identify content and associate portrayal rules with content, + +* <> describes requirements related to including styles (portrayal information) in GeoPackages, also based on previously developed draft extensions, + +and three annexes: + +* <> defines an Abstract Test Suite for this extension, upon which an Executable Test Suite could be based, + +* <> describes three implementations of both producers and consumers (viewers) of GeoPackages using this extension +developed during the code sprint by three participants: <>, <> and <>, +including Technology Integration Experiments demonstrating interoperability between these different implementations, as well as <> from these implementation efforts, + +* <> provides recommendations for future work that could be undertaken to build upon the results from the sprint, improve interoperability and performance for RBT content, and move this extension along the standardization process. diff --git a/spec/semantic-annotations/sections/06-semantic-annotations.adoc b/spec/semantic-annotations/sections/06-semantic-annotations.adoc new file mode 100644 index 00000000..0ea16bca --- /dev/null +++ b/spec/semantic-annotations/sections/06-semantic-annotations.adoc @@ -0,0 +1,63 @@ +[[SemanticAnnotationsClause]] +== Semantic Annotations + +=== Semantic Annotations Requirements + +A semantic annotation is a semantically grounded term that can be applied to another concept. +These requirements define how semantic annotations can be applied to any business object in the current GeoPackage (layers, features, tiles, styles, etc.). + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/semantic-annotations +description:: For defining semantic annotations +part:: A semantic annotation SHALL be defined as an entry in a `gpkgext_semantic_annotations` table with the following columns +* `id`, the a primary key +* `type`, a semantically grounded type (category) for the annotation +* `title`, a human-readable title for the annotation +* `description`, an optional human-readable text description for the annotation +* `uri`, the resolvable URI for the semantic concept +==== + +.Example SQL statement for creating the `gpkgext_semantic_annotations` table +[source,sql] +---- +CREATE TABLE gpkgext_semantic_annotations ( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + type TEXT NOT NULL, title TEXT NOT NULL, + description TEXT, + uri TEXT +) +---- + +See <> for an implementation example of the `gpkgext_semantic_annotations` table. + +NOTE: This RBT extension relies on semantic annotations for the association of both tilesets and styles to a `GeoDataClass` `type` of semantic annotation. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/sa-reference +description:: For associating semantic annotations +part:: Associating a particular business object with a semantic annotation SHALL be done by adding an entry to a `gpkgext_sa_reference` table with the following columns: +* `table_name`, the name of the table containing the business object +* `key_column_name`, the name of the integer column in the specified table that acts as a key; if no such column exists, `rowid` can be used +* `key_value`, the value of the key column that uniquely identifies the row +* `sa_id`, a foreign key to `gpkgext_semantic_annotations` +==== + +.Example SQL statement for creating the `gpkgext_sa_reference` table +[source,sql] +---- +CREATE TABLE gpkgext_sa_reference ( + table_name TEXT NOT NULL, + key_column_name TEXT NOT NULL, + key_value INTEGER NOT NULL, + sa_id INTEGER NOT NULL REFERENCES gpkgext_semantic_annotations, + UNIQUE(table_name, key_column_name, key_value, sa_id) +) +---- + +See <> for an implementation example of the `gpkgext_sa_reference` table. + +NOTE: There can be a many-to-many mapping between business object rows and semantic annotations. diff --git a/spec/semantic-annotations/sections/aa-ats.adoc b/spec/semantic-annotations/sections/aa-ats.adoc new file mode 100644 index 00000000..afdcdc49 --- /dev/null +++ b/spec/semantic-annotations/sections/aa-ats.adoc @@ -0,0 +1,186 @@ +[appendix,obligation="normative"] +[[annex-ats]] +== Conformance Class Abstract Test Suite + +=== Conformance Class Semantic Annotations GeoPackage Extension + +//// + +[[conf_rbt,/conf/rbt]] +[conformance_class] +==== +[%metadata] +identifier:: https://fgs-dps.gs.mil/#rbt/conf +target:: https://fgs-dps.gs.mil/#rbt/req +classification:: Target Type:Data Product +abstract-test:: /conf/rbt/extensions +abstract-test:: /conf/rbt/geodataclasses +abstract-test:: /conf/rbt/world-mercator +abstract-test:: /conf/rbt/map-tiles +abstract-test:: /conf/rbt/physical-cultural-features +abstract-test:: /conf/rbt/hillshade +abstract-test:: /conf/rbt/included-styles +abstract-test:: /conf/rbt/vector-tiles +abstract-test:: /conf/rbt/vector-tiles-layers +abstract-test:: /conf/rbt/vector-tiles-fields +abstract-test:: /conf/rbt/content-types +abstract-test:: /conf/rbt/mapbox-vector-tiles +abstract-test:: /conf/rbt/semantic-annotations +abstract-test:: /conf/rbt/sa-reference +abstract-test:: /conf/rbt/styles +abstract-test:: /conf/rbt/style-sheets +abstract-test:: /conf/rbt/symbol-images +abstract-test:: /conf/rbt/symbol-content +abstract-test:: /conf/rbt/fonts +abstract-test:: /conf/rbt/mapboxgl-style +==== + +==== Abstract Test for Requirement RBT Extensions + +[[conf_rbt_extensions,/conf/rbt/extensions]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/extensions +target:: /req/rbt/extensions +test-purpose:: Verify that the RBT GeoPackage properly declare extended tables +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard + +*When:* querying the content of the `gpkg_extensions` table + +*Then:* + +- assert that all entries listed in <> are present, including an entry for every user data table making use of these extensions. +-- +==== + +==== Abstract Test for Requirement GeoDataClasses + +[[conf_rbt_geodataclasses,/conf/rbt/geodataclasses]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/geodataclasses +target:: /req/rbt/geodataclasses +test-purpose:: Verify that the RBT GeoPackage properly identify RBT tilesets using GeoDataClass semantic annotations +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/semantic-annotations` and `/conf/rbt/sa-reference` tests + +*When:* querying the semantic annotations + +*Then:* + +- assert that corresponding entries exist annotating the `gpkg_contents` table for the mandatory _cultural_ and _physical_ tilesets, as well as for the optional imagery, COCOM and digital elevation model tilesets (if present) + +- assert that corresponding entries exist annotating the `gpkgext_vt_layers` table for the mandatory _cultural_ and _physical_ tilesets +-- +==== + + +==== Abstract Test for Requirement World Mercator 2DTMS + +[[conf_rbt_world-mercator,/conf/rbt/world-mercator]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/world-mercator +target:: /req/rbt/world-mercator +test-purpose:: Verify that the RBT GeoPackage tile sets use the World Mercator 2D Tile Matrix Set +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses` test + +*When:* inspecting the gpkg_tile_matrix and gpkg_tile_matrix_sets tables associated with the identified cultural, physical, imagery COCOM, and elevation model RBT tilesets + +*Then:* + +- assert that the entries correspond to those expected for the `http://www.opengis.net/def/tilematrixset/OGC/1.0/WorldMercatorWGS84Quad` 2D Tile Matrix Set using the EPSG:3395 world Mercator coordinate reference system. +-- +==== + +==== Abstract Test for Requirement Map Tiles + +[[conf_rbt_map-tiles,/conf/rbt/map-tiles]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/map-tiles +target:: /req/rbt/map-tiles +test-purpose:: Verify that the RBT GeoPackage tile sets includes the mandatory hillshade tileset, and encodes all mandatory and optional imagery tilesets as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses` and `/conf/rbt/content-types` tests + +*When:* inspecting the available user defined tiles tables and `gpkg_contents` table + +*Then:* + +- assert that the `data_type` of the `gpkg_contents` table for these tilesets is `tiles` + +- assert that the `tile_data` of the the user defined tiles table contains PNG for the _hillshade_ tileset, and PNG and/or JPEG for the optional imagery tilesets, without any additional encoding applied + +- assert that the `gpkgext_content_types` table declares these tilesets as using JPEG (except for _hillshade_) or PNG using the `image/jpeg` and/or `image/png` media type and a NULL encoding +-- +==== + +==== Abstract Test for Requirement Physical and Cultural Features + +[[conf_rbt_physical-cultural-features,/conf/rbt/physical-cultural-features]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/physical-cultural-features +target:: /req/rbt/physical-cultural-features +test-purpose:: Verify that the RBT GeoPackage tile sets includes and encodes the mandatory physical and cultural vector features tile sets as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses`, `/conf/rbt/vector-tiles`, `/conf/rbt/vector-tiles-layers` and `/conf/rbt/content-types` tests + +*When:* inspecting the available user defined tiles tables, `gpkgext_vt_layers`, `gpkg_contents` and their associated semantic annotations tables + +*Then:* + +- assert that a physical features tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-physical` is included + +- assert that a cultural features tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-cultural` is included + +- assert that the `data_type` of the `gpkg_contents` table for these tilesets is `vector-tiles` and that the `tile_data` of the the user defined tiles table contains gzip'ed Mapbox Vector Tiles + +- assert that the `gpkgext_content_types` table declares these tilesets as using Mapbox Vector Tile using the `application/vnd.mapbox-vector-tile` and the `gzip` encoding + +- assert that the Mapbox Vector Tiles for these tilesets contain embedded attributes +-- +==== + +==== Abstract Test for Requirement Hillshade + +[[conf_rbt_hillshade,/conf/rbt/hillshade]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/hillshade +target:: /req/rbt/hillshade +test-purpose:: Verify that the RBT GeoPackage tile sets includes and encodes the mandatory hillshaded digital elevation model as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/map-tiles` test + +*When:* inspecting the content of the user defined tiles table for the hillshaded tileset + +*Then:* + +- assert that a hillshade tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-hillshade` is included + +- assert that the content of the hillshade tileset is pre-rendered map tileset, in a monochrome translucent hillshaded style encoded as PNG images +-- +==== + +==== Abstract Test for Requirement Included Styles + +[[conf_rbt_included-styles,/conf/rbt/included-styles]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/included-styles +target:: /req/rbt/included-styles +test-purpose:: Verify that the RBT GeoPackage tile sets includes at least one style in a MapboxGL representation +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses`, `/conf/rbt/styles`, `/conf/rbt/style-sheets`, `/conf/rbt/symbol-images`, `/conf/rbt/symbol-content` and `/conf/rbt/mapboxgl-style` tests + +*When:* inspecting the content of the `gpkgext_styles` table for styles associated to the _physical_, _cultural_ and _hillshade_ RBT tilesets using the `GeoDataClass` annotation + +*Then:* + +- assert that at least one style in a MapboxGL representation is available for styling the physical and cultural and hillshade RBT tilesets + +- assert that all style sheets applicable to any of the RBT tilesets include styling rules for at least the physical and cutural tilesets + +- assert that all symbols referenced by MapboxGL style sheets are at least available as a sprite sheet where the `sprite` property of the MapboxGL style corresponds to a `uri` of an entry in the `gpkgext_symbol_content` table whose `content` blob contains all symbols + +- assert that individual entries in the `gpkgext_symbol_images` table, with offsets and dimensions of individual symbols, exist for all symbols referencing the sprite sheets in the `gpkgext_symbol_content` table for each Mapbox GL style +-- +==== + +NOTE: The Abstract Test Suites corresponding to the requirements in the Vector Tiles, Semantic Annotations and Styling sections will be elaborated in the corresponding +OGC GeoPackage extensions to be developed as separate documents, as documented in the Future Work section. + +//// diff --git a/spec/semantic-annotations/sections/ah-history.adoc b/spec/semantic-annotations/sections/ah-history.adoc new file mode 100644 index 00000000..17393308 --- /dev/null +++ b/spec/semantic-annotations/sections/ah-history.adoc @@ -0,0 +1,11 @@ + +[appendix] +== Revision History + +[%unnumbered] +[width="90%",options="header"] +|=== +|Date |Release |Editor | Primary clauses modified |Description +|2024-03-22 |0.1 |J. St-Louis |all |initial version +|2024-05-30 |0.2 |J. St-Louis |all |final draft ready for review +|=== diff --git a/spec/semantic-annotations/sections/az-bibliography.adoc b/spec/semantic-annotations/sections/az-bibliography.adoc new file mode 100644 index 00000000..a1b758d4 --- /dev/null +++ b/spec/semantic-annotations/sections/az-bibliography.adoc @@ -0,0 +1,20 @@ + + +[bibliography] +== Bibliography + +* [[[OGC18-074,OGC 18-074]]], +* [[[OGC18-086r1,OGC 18-086r1]]], +* [[[OGC18-076,OGC 18-076]]], +* [[[OGC18-101,OGC 18-101]]], +* [[[OGC19-082r1,OGC 19-082r1]]], +* [[[OGC20-092, OGC 20-092]]], +* [[[OGC19-088r2,OGC 19-088r2]]], +* [[[OGC19-018,OGC 19-018]]], +* [[[OGC20-019r1,OGC 20-019r1]]], +* [[[MapboxGLStyle,MapboxGLStyle]]], Mapbox GL Style Specification, https://docs.mapbox.com/style-spec/ +* [[[MapLibreStyle,MapLibreStyle]]], MapLibre Style Specification, https://maplibre.org/maplibre-style-spec/ +* [[[MVT,MVT]]], Mapbox Vector Tiles Specification version 2.1, https://github.com/mapbox/vector-tile-spec/tree/master/2.1 +* [[[CDBWShop,CDBWShop]]], CDB 2.0 2023 Summer Workshop GitHub Repository, https://github.com/opengeospatial/CDBV2-2023-Summer-Workshop +* [[[MBTiles,MBTiles]]], MBTiles Specification version 1.3, https://github.com/mapbox/mbtiles-spec/blob/master/1.3/spec.md +* [[[TileJSON,TileJSON]]], TileJSON Specification version 3.0, https://github.com/mapbox/tilejson-spec/tree/master/3.0.0 diff --git a/spec/styling/24-050.adoc b/spec/styling/24-050.adoc new file mode 100644 index 00000000..c9203ad8 --- /dev/null +++ b/spec/styling/24-050.adoc @@ -0,0 +1,75 @@ += GeoPackage Extension for Portrayal Information +:comment: ### Document type; mandatory. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:doctype: standard +:comment: ### Document subtype; optional. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:docsubtype: implementation +:comment: ### Version number; optional. Dot-delimited, preferably with this structure .. +:edition: 1.0.0 +:comment: ### Language of the document; mandatory. Specified in two-letter code: "en" for English, "fr" for French +:language: en +:comment: ### Document status/stage; mandatory. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:status: swg-draft +:comment: ### Relevant committee; mandatory. The permitted types are: technical, planning, and strategic-member-advisory +:committee: technical +:comment: ### Internal reference number; mandatory +:docnumber: 24-050 +:comment: ### Date on which the standard was updated; mandatory +:received-date: 2024-09-01 +:comment: ### Date on which the standard was approved by the issuing authority; mandatory +:issued-date: 2024-09-09 +:comment: ### Date on which the standard was published; mandatory +:published-date: 2024-10-14 +:comment: ### External link referencing the document; optional. If not provided, a default value is created following this structure: "http://www.opengis.net/doc/{abbrevation of doctype}/{abbrev}/{version}", +:external-id: http://www.opengis.net/IS/GPKG-Styling/1.0 +:comment: ### Author one +:fullname: Jérôme Jacovella-St-Louis +:comment: ### Author two +:fullname_2: Jeff Yutzler +:comment: ### Role of the authors; mandatory +:role: editor +:comment: ### Comma delimited keywords; mandatory +:keywords: ogcdoc, OGC document, GeoPackage, Styling, Portrayal, Symbology, SLD, SE, CartoSym +:comment: ### Semicolon-delimited list of the submitting organizations; mandatory +:submitting-organizations: US Army Geospatial Center (AGC); Ecere Corporation; Compusult Limited; TechMaven Geospatial; Image Matters, LLC. +:comment: ### Metanorma flavor; mandatory +:mn-document-class: ogc +:comment: ### Desired output formats; mandatory +:mn-output-extensions: html,pdf,doc,rxl +:comment: ### Enable local relaton cache for quick inclusion of prefetched references; optional. For further information, visit: https://www.metanorma.org/author/ref/document-attributes/#caches, https://www.metanorma.org/author/topics/building/reference-lookup/#lookup-result-caching +:local-cache-only: +:comment: ### URI to which the PDF version of this standard is published; optional +:pdf-uri: ./24-050.pdf +:comment: ### URI to which the XML version of this standard is published; optional +:xml-uri: ./24-050.xml +:comment: ### Directory name used as prefix for the location of image files; optional +:imagesdir: images +:comment: ### Enable rendering of AsciiMath, MathML, and LaTeX ("latexmath" needs to be indicated in the code to use LaTeX, or set ":stem: latexmath" to interpret by default); optional +:stem: + +// Clauses +include::sections/00-preface.adoc[] + +include::sections/01-scope.adoc[] + +include::sections/02-conformance.adoc[] + +include::sections/03-references.adoc[] + +include::sections/04-terms_and_definitions.adoc[] + +// include::sections/unused-conventions.adoc[] + +include::sections/05-overview.adoc[] + +include::sections/06-styling.adoc[] + +// Annexes +include::sections/aa-ats.adoc[] + +// include::sections/ab-implementations.adoc[] + +// Revision history +include::sections/ah-history.adoc[] + +// Bibliography +include::sections/az-bibliography.adoc[] diff --git a/spec/styling/sections/00-preface.adoc b/spec/styling/sections/00-preface.adoc new file mode 100644 index 00000000..c12de518 --- /dev/null +++ b/spec/styling/sections/00-preface.adoc @@ -0,0 +1,97 @@ + +//// +== Keywords + +Keywords inserted here automatically by Metanorma +//// + + +.Preface + +This Standard describes an extension for storing styles (cartographic symbology, portrayal information) in GeoPackage. +This extension was developed and validated during several OGC initiatives, +including the Vector Tile Pilots (https://www.ogc.org/initiatives/vt-pilot-2018/[Phase 1+extension] and https://www.ogc.org/initiatives/vtp2/[Phase2]), +https://docs.ogc.org/per/19-018.html[Testbed 15], https://docs.ogc.org/per/20-019r1.html[Testbed 16] as well the Releasable Basemap Tiles code sprint. + + +//// +[NOTE] +==== +Insert Preface Text here. Give OGC specific commentary: describe the technical content, reason for document, history of the document and precursors, and plans for future work. + +There are two ways to specify the Preface: "simple clause" or "full clasuse" + +If the Preface does not contain subclauses, it is considered a simple preface clause. This one is entered as text after the `.Preface` label and must be placed between the AsciiDoc document attributes and the first AsciiDoc section title. It should not be give a section title of its own. + +If the Preface contains subclauses, it needs to be encoded as a full preface clause. This one is recognized as a full Metanorma AsciiDoc section with the title "Preface", i.e. `== Preface`. (Simple preface content can also be encoded like full preface.) + +==== +//// + +//// +*OGC Declaration* +//// + +//// +[THIS TEXT IS ALREADY ADDED AUTOMATICALLY IN THE FRONTISPIECE OF ALL OGC DOUCMENTS] + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. + +Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation. +//// + +//// +NOTE: Uncomment ISO section if necessary + +*ISO Declaration* + +ISO (the International Organization for Standardization) is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization. + +International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2. + +The main task of technical committees is to prepare International Standards. Draft International Standards adopted by the technical committees are circulated to the member bodies for voting. Publication as an International Standard requires approval by at least 75 % of the member bodies casting a vote. + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. +//// + +[abstract] +== Abstract + +This Standard describes an extension for storing styles (cartographic symbology, portrayal information) in GeoPackage. + +An annex defines an Abstract Test Suite for the extension. + +[.preface] +== Security Considerations + +//If no security considerations have been made for this Standard, use the following text. + +No security considerations have been made for this Standard. + +//// +If security considerations have been made for this Standard, follow the examples found in IANA or IETF documents. Please see the following example. + +“VRRP is designed for a range of internetworking environments that may employ different security policies. The protocol includes several authentication methods ranging from no authentication, simple clear text passwords, and strong authentication using IP Authentication with MD5 HMAC. The details on each approach including possible attacks and recommended environments follows. + +Independent of any authentication type VRRP includes a mechanism (setting TTL=255, checking on receipt) that protects against VRRP packets being injected from another remote network. This limits most vulnerabilities to local attacks. +NOTE: The security measures discussed in the following sections only provide various kinds of authentication. No confidentiality is provided at all. This should be explicitly described as outside the scope....” +//// + +//// +== Submitting organizations + +Submitting organisations added automatically by Metanorma from document attributes +//// + +[.preface] +== Submitters +The following individuals submitted this candidate standard to the OGC: + +|=== +|Name |Affiliation +|Jérôme Jacovella-St-Louis (editor) | Ecere Corporation +|Jeff Yutzler (editor) | Image Matters LLC. +|Adam Parsons | Compusult Limited +|Jordan Bess | Tech Maven Geospatial +|Jeff Harrison | U.S. Army Geospatial Center +|=== diff --git a/spec/styling/sections/01-scope.adoc b/spec/styling/sections/01-scope.adoc new file mode 100644 index 00000000..e83d6bb5 --- /dev/null +++ b/spec/styling/sections/01-scope.adoc @@ -0,0 +1,8 @@ + +== Scope + +This Engineering Report describes an extension for storing Releasable Basemap Tiles (RBT) in GeoPackage developed during an OGC Code Sprint initiative. + +This extension regroups requirements specific to storing RBT data products in GeoPackages, requirements for storing vector tiles in GeoPackages, requirements for defining semantic annotations in GeoPackages, as well as requirements to include portrayal information in GeoPackages. + +In addition to the extension itself, this Engineering Report includes details of three implementations developed during the code sprint, including Technology Integration Experiments demonstrating interoperability between them. diff --git a/spec/styling/sections/02-conformance.adoc b/spec/styling/sections/02-conformance.adoc new file mode 100644 index 00000000..1fa543c2 --- /dev/null +++ b/spec/styling/sections/02-conformance.adoc @@ -0,0 +1,16 @@ + +== Conformance + +This extension defines of a single mandatory conformance class, but is broken down into conceptual requirement classes which may eventually correspond to individual standardized OGC GeoPackage extensions. + +The requirements apply to either of these two standardization target types: + +* data products, +* software producing such data products. + +Conformance with this extension shall be checked using all the relevant tests specified in Annex A (normative) of this document. +The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the NSG Compliance Testing Policies and Procedures and the NSG Compliance Testing web site. + +In order to conform to this candidate NSG data product standard, a software implementation producing a compliant data product shall implement the core requirement classes defined in this extension. + +All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified. diff --git a/spec/styling/sections/03-references.adoc b/spec/styling/sections/03-references.adoc new file mode 100644 index 00000000..be0c5e3a --- /dev/null +++ b/spec/styling/sections/03-references.adoc @@ -0,0 +1,9 @@ + +[bibliography] +== References + +The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. +For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies. + +* [[[OGC12-128r19,OGC 12-128r19]]], +* [[[OGC17-083r4,OGC 17-083r4]]], diff --git a/spec/styling/sections/04-terms_and_definitions.adoc b/spec/styling/sections/04-terms_and_definitions.adoc new file mode 100644 index 00000000..a61e35f0 --- /dev/null +++ b/spec/styling/sections/04-terms_and_definitions.adoc @@ -0,0 +1,43 @@ + +== Terms and Definitions + +//// +Note that the initial notice about terms ("This document uses the terms defined in OGC Policy Directive 49...") +is inserted automatically by Metanorma using the agreed standardised language, and you should not enter it here. +//// + +[[term-2DTMS]] +=== 2-Dimensional Tile Matrix Set (2DTMS) + +tiling scheme consisting of a set of tile matrices defined at different scales covering approximately the same area and having a common coordinate reference system. + +[.source] +<> + +[[term-geodataclass]] +=== geodataclass + +a URI identifying a class of geospatial data whose component data layers conform to a particular logical schema + +A registry of geodataclasses would ideally resolve these URIs to metadata including these schemas. +A geodataclass serves multiple purposes, including the ability to easily identify, using a simple identifier comparison, +relevant datasets for a particular purpose, the compatibility of datasets as inputs for processes, the compatibility +of the output of a process with the input of another process, as well as the compatibility of portrayal style information +with a particular dataset (see also https://github.com/opengeospatial/styles-and-symbology/issues/12). + +[[term-mvt]] +=== Mapbox vector tiles (MVT) + +a https://github.com/mapbox/vector-tile-spec/tree/master/2.1[specification] developed by Mapbox for encoding tiled vector data using https://protobuf.dev/[protocol buffers]. + +[[term-rbt]] +=== releasable basemap tiles (RBT) + +tilesets of foundational geospatial data developed by the US Army Geospatial Center for public release, +including vector tilesets of cultural and physical features, hillshaded elevation data and optional imagery + +[[term-tie]] +=== technology integration experiment (TIE) + +experiments performed between different implementations of a specification or standard to test and demonstrate interoperability between them, and in the case of TIEs +performed in the context of an initiative to validate a draft specification or standard, to validate the soundness and completeness of the requirements specified therein diff --git a/spec/styling/sections/05-overview.adoc b/spec/styling/sections/05-overview.adoc new file mode 100644 index 00000000..7b6ebafb --- /dev/null +++ b/spec/styling/sections/05-overview.adoc @@ -0,0 +1,25 @@ +[[OverviewClause]] +== Overview + +This Engineering Report describes an extension for storing Releasable Basemap Tiles (RBT) in GeoPackage developed during the March 2024 OGC Code Sprint initiative sponsored by the US Army Geospatial Center (AGC). + +The report is organized into four main sections: + +* <> describes the RBT extension as a whole, including requirements for declaring conformance to this extension, as well as requirements specific to storing RBT data products, + +* <> describes requirements related to storing vector tiles in GeoPackages, based on the draft extensions developed in previous initiatives such as +the Vector Tile Pilots (https://www.ogc.org/initiatives/vt-pilot-2018/[Phase 1+extension] and https://www.ogc.org/initiatives/vtp2/[Phase2]), + +* <> describes requirements related to semantic annotations, also based on previously developed draft extensions, providing a mechanism to identify content and associate portrayal rules with content, + +* <> describes requirements related to including styles (portrayal information) in GeoPackages, also based on previously developed draft extensions, + +and three annexes: + +* <> defines an Abstract Test Suite for this extension, upon which an Executable Test Suite could be based, + +* <> describes three implementations of both producers and consumers (viewers) of GeoPackages using this extension +developed during the code sprint by three participants: <>, <> and <>, +including Technology Integration Experiments demonstrating interoperability between these different implementations, as well as <> from these implementation efforts, + +* <> provides recommendations for future work that could be undertaken to build upon the results from the sprint, improve interoperability and performance for RBT content, and move this extension along the standardization process. diff --git a/spec/styling/sections/06-styling.adoc b/spec/styling/sections/06-styling.adoc new file mode 100644 index 00000000..4abf6c3e --- /dev/null +++ b/spec/styling/sections/06-styling.adoc @@ -0,0 +1,234 @@ +[[StylingClause]] +== Styling + +=== Styling Requirements + +These requirements provide a mechanism to include the style sheets, symbols and fonts needed to portray the data stored in a GeoPackage in one or more style, as intended by the producer. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/styles +description:: For defining styles +part:: Styles to portray the data in a GeoPackage SHALL be defined as entries in the `gpkgext_styles` table containing the following column: +* `id`, a primary key +* `style`, text naming a specific style +* `description`, an optional text description +* `uri`, a resolvable URI +==== + +.Example SQL statement for creating the `gpkgext_styles` table +[source,sql] +---- +CREATE TABLE gpkgext_styles ( + id INTEGER PRIMARY KEY, + style TEXT NOT NULL, + description TEXT, + uri TEXT, + UNIQUE(uri) +) +---- + +See <> for an implementation example of the `gpkgext_styles` table. + +[recommendation] +==== +[%metadata] +identifier:: /rec/rbt/styles-uris +description:: Guidance on style URIs +part:: Where possible, style URIs SHOULD resolve to a network-accessible resource. +part:: When that is not possible, style URIs SHOULD be unique. +part:: If no existing URI scheme is available, a style URI SHOULD take the form of: `gpkgstyle::[geodataclass]::[org]::[style]` +==== + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/style-sheets +description:: For encoding style sheets +part:: Style sheets, a list of styling rules encoded in a particular styling language, corresponding to a particular style SHALL be defined as entries in the `gpkgext_stylesheets` table containing the following column: +* `id`, a primary key +* `style_id`, a foreign key to `gpkgext_styles` +* `format`, the format of the stylesheet (e.g., `mbstyle` or `sld`) +* `stylesheet`, the actual stylesheet BLOB (since some stylesheets are binary) +==== + +.Example SQL statement for creating the `gpkgext_stylesheets` table +[source,sql] +---- +CREATE TABLE gpkgext_stylesheets ( + id INTEGER PRIMARY KEY, + style_id INTEGER REFERENCES gpkgext_styles, + format TEXT NOT NULL, + stylesheet BLOB NOT NULL, + UNIQUE(style_id, format) +) +---- + +See <> for an implementation example of the `gpkgext_stylesheets` table. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/symbols +description:: For defining symbols +part:: Symbols SHALL be defined in a `gpkgext_symbols` table contains containing the following columns: +* `id`, a primary key +* `symbol`, text naming a specific symbol +* `description`, an optional text description +* `uri`, a resolvable URI +==== + +.Example SQL statement for creating the `gpkgext_symbols` table +[source,sql] +---- +CREATE TABLE gpkgext_symbols ( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + uri TEXT, + symbol TEXT NOT NULL, + title TEXT NOT NULL, + description TEXT +) +---- + +See <> for an implementation example of the `gpkgext_symbols` table. + +[recommendation] +==== +[%metadata] +identifier:: /rec/rbt/symbol-uris +description:: Guidance on symbol URIs +part:: Where possible, symbol URIs SHOULD resolve to a network-accessible resource. +part:: When that is not possible, symbol URIs SHOULD be unique. +part:: If no existing URI scheme is available, a symbol URI SHOULD take the form of: `gpkgsym::[geodataclass]::[org]::[style]::[symbol]` +(`[style]` could be replaced by e.g., `multiple` if the symbol applies to multiple styles) +==== + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/symbol-images +description:: For defining symbols +part:: Images representing symbols SHALL be defined in a `gpkgext_symbol_images` table contains containing the following columns: +* `id`, a primary key +* `symbol_id`, a foreign key to `gpkgext_symbols` +* `content_id`, a foreign key to `gpkgext_symbol_content` +* `width`, `height`, optional parameters that are required for sprites or for when there are multiple versions of the same image with different sizes +* `offset_x`, `offset_y`, `pixel_ratio`, optional parameters for sprite information (NULL if the entire image is used) +==== + +.Example SQL statement for creating the `gpkgext_symbol_images` table +[source,sql] +---- +CREATE TABLE gpkgext_symbol_images ( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + symbol_id INTEGER NOT NULL REFERENCES gpkgext_symbols, + content_id INTEGER NOT NULL REFERENCES gpkgext_symbol_content, + width INTEGER, + height INTEGER, + offset_x INTEGER, + offset_y INTEGER, + pixel_ratio INTEGER +) +---- + +See <> for an implementation example of the `gpkgext_symbol_images` table. + +NOTE: If a symbol sprite sheet is included as a single image containing multiple symbols, multiple entries of this table will reference the same sprite sheet symbol content entry. + +NOTE: Multiple images may be defined for the same symbol so as to offer different resolutions, differerent styles and/or for both an individual and sprite sheet version of the same symbol. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/symbol-content +description:: For defining symbols +part:: The actual data for an image SHALL be encoded in a `gpkgext_symbol_content` table containing the following column: +* `id`, a primary key +* `format`, the media type (formerly MIME type, e.g., `image/svg+xml` or `image/png`) of the symbol +* `content`, the actual symbol BLOB +* `uri`, a resolvable name to uniquely reference a specific content entry e.g., for use in Mapbox GL styles `sprite` property to reference a particular sprite sheet +==== + +.Example SQL statement for creating the `gpkgext_symbol_content` table +[source,sql] +---- +CREATE TABLE gpkgext_symbol_content ( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + format TEXT NOT NULL, + content BLOB NOT NULL, + uri TEXT NOT NULL +) +---- + +See <> for an implementation example of the `gpkgext_symbol_content` table. + +NOTE: Multiple versions of the same image may be included (e.g., both SVG and PNG). + +[[FontsClause]] +=== Fonts Requirements + +These requirements define how fonts required by styles can be included in the GeoPackage. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/fonts +description:: For optionally including fonts +part:: If included, fonts required by styles SHALL be encoded in a `gpkgext_fonts` table containing the following column: +* `id`, a primary key +* `name`, the name of the font +* `font`, the TrueType or OpenType font as a BLOB, +* `glyphs`, a BLOB consisting of a zipped protobuf ranges of signed distanced field glyphs (as returned by the https://docs.mapbox.com/api/maps/font[Mapbox Fonts API]) with `{rangeLo-rangeHi}.pbf` filenames within the zip +part:: At least `font` or `glyphs` SHALL be included in every entry +==== + +.Example SQL statement for creating the `gpkgext_fonts` table +[source,sql] +---- +CREATE TABLE gpkgext_fonts( + id INTEGER PRIMARY KEY, + name TEXT UNIQUE, + font BLOB, + glyphs BLOB +) +---- + +See <> for an implementation example of the `gpkgext_fonts` table. + +[[CartoSymCSSStyleClause]] +=== CartoSym-CSS Style Encoding Requirements + +These requirements define how to include style sheets specified using the https://docs.ogc.org/DRAFTS/18-067r4.html#rc-cscss[CartoSym-CSS style encoding] within a GeoPackage. + +[[CartoSymJSONStyleClause]] +=== CartoSym-JSON Style Encoding Requirements + +These requirements define how to include style sheets specified using the https://docs.ogc.org/DRAFTS/18-067r4.html#rc-json[CartoSym-JSON style encoding] within a GeoPackage. + +[[SLDSEStyleClause]] +=== SLD/SE Style Encoding Requirements + +These requirements define how to include style sheets specified using the https://www.ogc.org/standard/sld/[Stylable Layer Descriptior] / https://www.ogc.org/standard/se/[Symbology Encoding] (SLD/SE) style encoding within a GeoPackage. + +[[CartoSymJSONLStyleClause]] +=== Mapbox GL Styling Specification Requirements + +These requirements define how to include style sheets specified in the https://docs.mapbox.com/style-spec[Mapbox GL Styling Specification] within a GeoPackage. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/mapboxgl-style +description:: For including MapboxGL style sheets +part:: Styling rules encode according to the MapboxGL style sheets SHALL be included in the `gpkgext_stylesheets` table. +part:: The MapboxGL style sheet SHALL refer to a particular tileset by setting the `url` field of a `source` to the GeoDataClass of that tileset, as associated using a `GeoDataClass` type of semantic annotations (`/req/rbt/semantic-annotations`). +==== + +NOTE: By supporting a TileJSON representation of the schemas associated with a GeoDataClass, it would be possible for the `url` field to both function as a representative data source for the style, +while also corresponding to a GeoDataClass. However, it does not however limit the use of this style strictly with that representative data source. The style should be suitable to portray +any RBT data source conforming to the same schemas associated with the GeoDataClass. + +NOTE: An alternative was considered to specify the GeoDataClasses for the style in a separate `geoDataClass` property of the source, instead the `url` field. +A final decision on this approach should consider the possibility of the GeoDataClass registry on the OGC definition server to return a TileJSON representation of the schemas, +and would benefit from additional implementation testing, as detailed in the Future Work section of this Engineering Report. diff --git a/spec/styling/sections/aa-ats.adoc b/spec/styling/sections/aa-ats.adoc new file mode 100644 index 00000000..a9188246 --- /dev/null +++ b/spec/styling/sections/aa-ats.adoc @@ -0,0 +1,186 @@ +[appendix,obligation="normative"] +[[annex-ats]] +== Conformance Class Abstract Test Suite + +=== Conformance Class Styling GeoPackage Extension + +//// + +[[conf_rbt,/conf/rbt]] +[conformance_class] +==== +[%metadata] +identifier:: https://fgs-dps.gs.mil/#rbt/conf +target:: https://fgs-dps.gs.mil/#rbt/req +classification:: Target Type:Data Product +abstract-test:: /conf/rbt/extensions +abstract-test:: /conf/rbt/geodataclasses +abstract-test:: /conf/rbt/world-mercator +abstract-test:: /conf/rbt/map-tiles +abstract-test:: /conf/rbt/physical-cultural-features +abstract-test:: /conf/rbt/hillshade +abstract-test:: /conf/rbt/included-styles +abstract-test:: /conf/rbt/vector-tiles +abstract-test:: /conf/rbt/vector-tiles-layers +abstract-test:: /conf/rbt/vector-tiles-fields +abstract-test:: /conf/rbt/content-types +abstract-test:: /conf/rbt/mapbox-vector-tiles +abstract-test:: /conf/rbt/semantic-annotations +abstract-test:: /conf/rbt/sa-reference +abstract-test:: /conf/rbt/styles +abstract-test:: /conf/rbt/style-sheets +abstract-test:: /conf/rbt/symbol-images +abstract-test:: /conf/rbt/symbol-content +abstract-test:: /conf/rbt/fonts +abstract-test:: /conf/rbt/mapboxgl-style +==== + +==== Abstract Test for Requirement RBT Extensions + +[[conf_rbt_extensions,/conf/rbt/extensions]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/extensions +target:: /req/rbt/extensions +test-purpose:: Verify that the RBT GeoPackage properly declare extended tables +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard + +*When:* querying the content of the `gpkg_extensions` table + +*Then:* + +- assert that all entries listed in <> are present, including an entry for every user data table making use of these extensions. +-- +==== + +==== Abstract Test for Requirement GeoDataClasses + +[[conf_rbt_geodataclasses,/conf/rbt/geodataclasses]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/geodataclasses +target:: /req/rbt/geodataclasses +test-purpose:: Verify that the RBT GeoPackage properly identify RBT tilesets using GeoDataClass semantic annotations +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/semantic-annotations` and `/conf/rbt/sa-reference` tests + +*When:* querying the semantic annotations + +*Then:* + +- assert that corresponding entries exist annotating the `gpkg_contents` table for the mandatory _cultural_ and _physical_ tilesets, as well as for the optional imagery, COCOM and digital elevation model tilesets (if present) + +- assert that corresponding entries exist annotating the `gpkgext_vt_layers` table for the mandatory _cultural_ and _physical_ tilesets +-- +==== + + +==== Abstract Test for Requirement World Mercator 2DTMS + +[[conf_rbt_world-mercator,/conf/rbt/world-mercator]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/world-mercator +target:: /req/rbt/world-mercator +test-purpose:: Verify that the RBT GeoPackage tile sets use the World Mercator 2D Tile Matrix Set +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses` test + +*When:* inspecting the gpkg_tile_matrix and gpkg_tile_matrix_sets tables associated with the identified cultural, physical, imagery COCOM, and elevation model RBT tilesets + +*Then:* + +- assert that the entries correspond to those expected for the `http://www.opengis.net/def/tilematrixset/OGC/1.0/WorldMercatorWGS84Quad` 2D Tile Matrix Set using the EPSG:3395 world Mercator coordinate reference system. +-- +==== + +==== Abstract Test for Requirement Map Tiles + +[[conf_rbt_map-tiles,/conf/rbt/map-tiles]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/map-tiles +target:: /req/rbt/map-tiles +test-purpose:: Verify that the RBT GeoPackage tile sets includes the mandatory hillshade tileset, and encodes all mandatory and optional imagery tilesets as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses` and `/conf/rbt/content-types` tests + +*When:* inspecting the available user defined tiles tables and `gpkg_contents` table + +*Then:* + +- assert that the `data_type` of the `gpkg_contents` table for these tilesets is `tiles` + +- assert that the `tile_data` of the the user defined tiles table contains PNG for the _hillshade_ tileset, and PNG and/or JPEG for the optional imagery tilesets, without any additional encoding applied + +- assert that the `gpkgext_content_types` table declares these tilesets as using JPEG (except for _hillshade_) or PNG using the `image/jpeg` and/or `image/png` media type and a NULL encoding +-- +==== + +==== Abstract Test for Requirement Physical and Cultural Features + +[[conf_rbt_physical-cultural-features,/conf/rbt/physical-cultural-features]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/physical-cultural-features +target:: /req/rbt/physical-cultural-features +test-purpose:: Verify that the RBT GeoPackage tile sets includes and encodes the mandatory physical and cultural vector features tile sets as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses`, `/conf/rbt/vector-tiles`, `/conf/rbt/vector-tiles-layers` and `/conf/rbt/content-types` tests + +*When:* inspecting the available user defined tiles tables, `gpkgext_vt_layers`, `gpkg_contents` and their associated semantic annotations tables + +*Then:* + +- assert that a physical features tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-physical` is included + +- assert that a cultural features tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-cultural` is included + +- assert that the `data_type` of the `gpkg_contents` table for these tilesets is `vector-tiles` and that the `tile_data` of the the user defined tiles table contains gzip'ed Mapbox Vector Tiles + +- assert that the `gpkgext_content_types` table declares these tilesets as using Mapbox Vector Tile using the `application/vnd.mapbox-vector-tile` and the `gzip` encoding + +- assert that the Mapbox Vector Tiles for these tilesets contain embedded attributes +-- +==== + +==== Abstract Test for Requirement Hillshade + +[[conf_rbt_hillshade,/conf/rbt/hillshade]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/hillshade +target:: /req/rbt/hillshade +test-purpose:: Verify that the RBT GeoPackage tile sets includes and encodes the mandatory hillshaded digital elevation model as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/map-tiles` test + +*When:* inspecting the content of the user defined tiles table for the hillshaded tileset + +*Then:* + +- assert that a hillshade tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-hillshade` is included + +- assert that the content of the hillshade tileset is pre-rendered map tileset, in a monochrome translucent hillshaded style encoded as PNG images +-- +==== + +==== Abstract Test for Requirement Included Styles + +[[conf_rbt_included-styles,/conf/rbt/included-styles]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/included-styles +target:: /req/rbt/included-styles +test-purpose:: Verify that the RBT GeoPackage tile sets includes at least one style in a MapboxGL representation +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses`, `/conf/rbt/styles`, `/conf/rbt/style-sheets`, `/conf/rbt/symbol-images`, `/conf/rbt/symbol-content` and `/conf/rbt/mapboxgl-style` tests + +*When:* inspecting the content of the `gpkgext_styles` table for styles associated to the _physical_, _cultural_ and _hillshade_ RBT tilesets using the `GeoDataClass` annotation + +*Then:* + +- assert that at least one style in a MapboxGL representation is available for styling the physical and cultural and hillshade RBT tilesets + +- assert that all style sheets applicable to any of the RBT tilesets include styling rules for at least the physical and cutural tilesets + +- assert that all symbols referenced by MapboxGL style sheets are at least available as a sprite sheet where the `sprite` property of the MapboxGL style corresponds to a `uri` of an entry in the `gpkgext_symbol_content` table whose `content` blob contains all symbols + +- assert that individual entries in the `gpkgext_symbol_images` table, with offsets and dimensions of individual symbols, exist for all symbols referencing the sprite sheets in the `gpkgext_symbol_content` table for each Mapbox GL style +-- +==== + +NOTE: The Abstract Test Suites corresponding to the requirements in the Vector Tiles, Semantic Annotations and Styling sections will be elaborated in the corresponding +OGC GeoPackage extensions to be developed as separate documents, as documented in the Future Work section. + +//// diff --git a/spec/styling/sections/ah-history.adoc b/spec/styling/sections/ah-history.adoc new file mode 100644 index 00000000..17393308 --- /dev/null +++ b/spec/styling/sections/ah-history.adoc @@ -0,0 +1,11 @@ + +[appendix] +== Revision History + +[%unnumbered] +[width="90%",options="header"] +|=== +|Date |Release |Editor | Primary clauses modified |Description +|2024-03-22 |0.1 |J. St-Louis |all |initial version +|2024-05-30 |0.2 |J. St-Louis |all |final draft ready for review +|=== diff --git a/spec/styling/sections/az-bibliography.adoc b/spec/styling/sections/az-bibliography.adoc new file mode 100644 index 00000000..a1b758d4 --- /dev/null +++ b/spec/styling/sections/az-bibliography.adoc @@ -0,0 +1,20 @@ + + +[bibliography] +== Bibliography + +* [[[OGC18-074,OGC 18-074]]], +* [[[OGC18-086r1,OGC 18-086r1]]], +* [[[OGC18-076,OGC 18-076]]], +* [[[OGC18-101,OGC 18-101]]], +* [[[OGC19-082r1,OGC 19-082r1]]], +* [[[OGC20-092, OGC 20-092]]], +* [[[OGC19-088r2,OGC 19-088r2]]], +* [[[OGC19-018,OGC 19-018]]], +* [[[OGC20-019r1,OGC 20-019r1]]], +* [[[MapboxGLStyle,MapboxGLStyle]]], Mapbox GL Style Specification, https://docs.mapbox.com/style-spec/ +* [[[MapLibreStyle,MapLibreStyle]]], MapLibre Style Specification, https://maplibre.org/maplibre-style-spec/ +* [[[MVT,MVT]]], Mapbox Vector Tiles Specification version 2.1, https://github.com/mapbox/vector-tile-spec/tree/master/2.1 +* [[[CDBWShop,CDBWShop]]], CDB 2.0 2023 Summer Workshop GitHub Repository, https://github.com/opengeospatial/CDBV2-2023-Summer-Workshop +* [[[MBTiles,MBTiles]]], MBTiles Specification version 1.3, https://github.com/mapbox/mbtiles-spec/blob/master/1.3/spec.md +* [[[TileJSON,TileJSON]]], TileJSON Specification version 3.0, https://github.com/mapbox/tilejson-spec/tree/master/3.0.0 diff --git a/spec/vector-tiles/24-048.adoc b/spec/vector-tiles/24-048.adoc new file mode 100644 index 00000000..a871b670 --- /dev/null +++ b/spec/vector-tiles/24-048.adoc @@ -0,0 +1,75 @@ += GeoPackage Extension for Tiled Feature Data +:comment: ### Document type; mandatory. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:doctype: standard +:comment: ### Document subtype; optional. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:docsubtype: implementation +:comment: ### Version number; optional. Dot-delimited, preferably with this structure .. +:edition: 1.0.0 +:comment: ### Language of the document; mandatory. Specified in two-letter code: "en" for English, "fr" for French +:language: en +:comment: ### Document status/stage; mandatory. Visit: https://www.metanorma.org/author/ogc/authoring/ for permitted types +:status: swg-draft +:comment: ### Relevant committee; mandatory. The permitted types are: technical, planning, and strategic-member-advisory +:committee: technical +:comment: ### Internal reference number; mandatory +:docnumber: 24-048 +:comment: ### Date on which the standard was updated; mandatory +:received-date: 2024-09-01 +:comment: ### Date on which the standard was approved by the issuing authority; mandatory +:issued-date: 2024-09-09 +:comment: ### Date on which the standard was published; mandatory +:published-date: 2024-10-14 +:comment: ### External link referencing the document; optional. If not provided, a default value is created following this structure: "http://www.opengis.net/doc/{abbrevation of doctype}/{abbrev}/{version}", +:external-id: http://www.opengis.net/IS/GPKG-VectorTiles/1.0 +:comment: ### Author one +:fullname: Jérôme Jacovella-St-Louis +:comment: ### Author two +:fullname_2: Jeff Yutzler +:comment: ### Role of the authors; mandatory +:role: editor +:comment: ### Comma delimited keywords; mandatory +:keywords: ogcdoc, OGC document, GeoPackage, Vector Tiles +:comment: ### Semicolon-delimited list of the submitting organizations; mandatory +:submitting-organizations: US Army Geospatial Center (AGC); Ecere Corporation; Compusult Limited; TechMaven Geospatial; Image Matters, LLC. +:comment: ### Metanorma flavor; mandatory +:mn-document-class: ogc +:comment: ### Desired output formats; mandatory +:mn-output-extensions: html,pdf,doc,rxl +:comment: ### Enable local relaton cache for quick inclusion of prefetched references; optional. For further information, visit: https://www.metanorma.org/author/ref/document-attributes/#caches, https://www.metanorma.org/author/topics/building/reference-lookup/#lookup-result-caching +:local-cache-only: +:comment: ### URI to which the PDF version of this standard is published; optional +:pdf-uri: ./24-048.pdf +:comment: ### URI to which the XML version of this standard is published; optional +:xml-uri: ./24-048.xml +:comment: ### Directory name used as prefix for the location of image files; optional +:imagesdir: images +:comment: ### Enable rendering of AsciiMath, MathML, and LaTeX ("latexmath" needs to be indicated in the code to use LaTeX, or set ":stem: latexmath" to interpret by default); optional +:stem: + +// Clauses +include::sections/00-preface.adoc[] + +include::sections/01-scope.adoc[] + +include::sections/02-conformance.adoc[] + +include::sections/03-references.adoc[] + +include::sections/04-terms_and_definitions.adoc[] + +// include::sections/unused-conventions.adoc[] + +include::sections/05-overview.adoc[] + +include::sections/06-vector-tiles.adoc[] + +// Annexes +include::sections/aa-ats.adoc[] + +// include::sections/ab-implementations.adoc[] + +// Revision history +include::sections/ah-history.adoc[] + +// Bibliography +include::sections/az-bibliography.adoc[] diff --git a/spec/vector-tiles/sections/00-preface.adoc b/spec/vector-tiles/sections/00-preface.adoc new file mode 100644 index 00000000..cf549dc7 --- /dev/null +++ b/spec/vector-tiles/sections/00-preface.adoc @@ -0,0 +1,96 @@ + +//// +== Keywords + +Keywords inserted here automatically by Metanorma +//// + + +.Preface + +This Standard describes an extension for storing vector tiles in GeoPackage. +This extension was developed and validated during several OGC initiatives, +including the Vector Tile Pilots (https://www.ogc.org/initiatives/vt-pilot-2018/[Phase 1+extension] and https://www.ogc.org/initiatives/vtp2/[Phase2]), +https://docs.ogc.org/per/19-018.html[Testbed 15], https://docs.ogc.org/per/20-019r1.html[Testbed 16] as well the Releasable Basemap Tiles code sprint. + +//// +[NOTE] +==== +Insert Preface Text here. Give OGC specific commentary: describe the technical content, reason for document, history of the document and precursors, and plans for future work. + +There are two ways to specify the Preface: "simple clause" or "full clasuse" + +If the Preface does not contain subclauses, it is considered a simple preface clause. This one is entered as text after the `.Preface` label and must be placed between the AsciiDoc document attributes and the first AsciiDoc section title. It should not be give a section title of its own. + +If the Preface contains subclauses, it needs to be encoded as a full preface clause. This one is recognized as a full Metanorma AsciiDoc section with the title "Preface", i.e. `== Preface`. (Simple preface content can also be encoded like full preface.) + +==== +//// + +//// +*OGC Declaration* +//// + +//// +[THIS TEXT IS ALREADY ADDED AUTOMATICALLY IN THE FRONTISPIECE OF ALL OGC DOUCMENTS] + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. + +Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation. +//// + +//// +NOTE: Uncomment ISO section if necessary + +*ISO Declaration* + +ISO (the International Organization for Standardization) is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization. + +International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2. + +The main task of technical committees is to prepare International Standards. Draft International Standards adopted by the technical committees are circulated to the member bodies for voting. Publication as an International Standard requires approval by at least 75 % of the member bodies casting a vote. + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. +//// + +[abstract] +== Abstract + +This Standard describes an extension for storing vector tiles in GeoPackage. + +An annex defines an Abstract Test Suite for the extension. + +[.preface] +== Security Considerations + +//If no security considerations have been made for this Standard, use the following text. + +No security considerations have been made for this Standard. + +//// +If security considerations have been made for this Standard, follow the examples found in IANA or IETF documents. Please see the following example. + +“VRRP is designed for a range of internetworking environments that may employ different security policies. The protocol includes several authentication methods ranging from no authentication, simple clear text passwords, and strong authentication using IP Authentication with MD5 HMAC. The details on each approach including possible attacks and recommended environments follows. + +Independent of any authentication type VRRP includes a mechanism (setting TTL=255, checking on receipt) that protects against VRRP packets being injected from another remote network. This limits most vulnerabilities to local attacks. +NOTE: The security measures discussed in the following sections only provide various kinds of authentication. No confidentiality is provided at all. This should be explicitly described as outside the scope....” +//// + +//// +== Submitting organizations + +Submitting organisations added automatically by Metanorma from document attributes +//// + +[.preface] +== Submitters +The following individuals submitted this candidate standard to the OGC: + +|=== +|Name |Affiliation +|Jérôme Jacovella-St-Louis (editor) | Ecere Corporation +|Jeff Yutzler (editor) | Image Matters LLC. +|Adam Parsons | Compusult Limited +|Jordan Bess | Tech Maven Geospatial +|Jeff Harrison | U.S. Army Geospatial Center +|=== diff --git a/spec/vector-tiles/sections/01-scope.adoc b/spec/vector-tiles/sections/01-scope.adoc new file mode 100644 index 00000000..e83d6bb5 --- /dev/null +++ b/spec/vector-tiles/sections/01-scope.adoc @@ -0,0 +1,8 @@ + +== Scope + +This Engineering Report describes an extension for storing Releasable Basemap Tiles (RBT) in GeoPackage developed during an OGC Code Sprint initiative. + +This extension regroups requirements specific to storing RBT data products in GeoPackages, requirements for storing vector tiles in GeoPackages, requirements for defining semantic annotations in GeoPackages, as well as requirements to include portrayal information in GeoPackages. + +In addition to the extension itself, this Engineering Report includes details of three implementations developed during the code sprint, including Technology Integration Experiments demonstrating interoperability between them. diff --git a/spec/vector-tiles/sections/02-conformance.adoc b/spec/vector-tiles/sections/02-conformance.adoc new file mode 100644 index 00000000..1fa543c2 --- /dev/null +++ b/spec/vector-tiles/sections/02-conformance.adoc @@ -0,0 +1,16 @@ + +== Conformance + +This extension defines of a single mandatory conformance class, but is broken down into conceptual requirement classes which may eventually correspond to individual standardized OGC GeoPackage extensions. + +The requirements apply to either of these two standardization target types: + +* data products, +* software producing such data products. + +Conformance with this extension shall be checked using all the relevant tests specified in Annex A (normative) of this document. +The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the NSG Compliance Testing Policies and Procedures and the NSG Compliance Testing web site. + +In order to conform to this candidate NSG data product standard, a software implementation producing a compliant data product shall implement the core requirement classes defined in this extension. + +All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified. diff --git a/spec/vector-tiles/sections/03-references.adoc b/spec/vector-tiles/sections/03-references.adoc new file mode 100644 index 00000000..be0c5e3a --- /dev/null +++ b/spec/vector-tiles/sections/03-references.adoc @@ -0,0 +1,9 @@ + +[bibliography] +== References + +The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. +For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies. + +* [[[OGC12-128r19,OGC 12-128r19]]], +* [[[OGC17-083r4,OGC 17-083r4]]], diff --git a/spec/vector-tiles/sections/04-terms_and_definitions.adoc b/spec/vector-tiles/sections/04-terms_and_definitions.adoc new file mode 100644 index 00000000..a61e35f0 --- /dev/null +++ b/spec/vector-tiles/sections/04-terms_and_definitions.adoc @@ -0,0 +1,43 @@ + +== Terms and Definitions + +//// +Note that the initial notice about terms ("This document uses the terms defined in OGC Policy Directive 49...") +is inserted automatically by Metanorma using the agreed standardised language, and you should not enter it here. +//// + +[[term-2DTMS]] +=== 2-Dimensional Tile Matrix Set (2DTMS) + +tiling scheme consisting of a set of tile matrices defined at different scales covering approximately the same area and having a common coordinate reference system. + +[.source] +<> + +[[term-geodataclass]] +=== geodataclass + +a URI identifying a class of geospatial data whose component data layers conform to a particular logical schema + +A registry of geodataclasses would ideally resolve these URIs to metadata including these schemas. +A geodataclass serves multiple purposes, including the ability to easily identify, using a simple identifier comparison, +relevant datasets for a particular purpose, the compatibility of datasets as inputs for processes, the compatibility +of the output of a process with the input of another process, as well as the compatibility of portrayal style information +with a particular dataset (see also https://github.com/opengeospatial/styles-and-symbology/issues/12). + +[[term-mvt]] +=== Mapbox vector tiles (MVT) + +a https://github.com/mapbox/vector-tile-spec/tree/master/2.1[specification] developed by Mapbox for encoding tiled vector data using https://protobuf.dev/[protocol buffers]. + +[[term-rbt]] +=== releasable basemap tiles (RBT) + +tilesets of foundational geospatial data developed by the US Army Geospatial Center for public release, +including vector tilesets of cultural and physical features, hillshaded elevation data and optional imagery + +[[term-tie]] +=== technology integration experiment (TIE) + +experiments performed between different implementations of a specification or standard to test and demonstrate interoperability between them, and in the case of TIEs +performed in the context of an initiative to validate a draft specification or standard, to validate the soundness and completeness of the requirements specified therein diff --git a/spec/vector-tiles/sections/05-overview.adoc b/spec/vector-tiles/sections/05-overview.adoc new file mode 100644 index 00000000..7b6ebafb --- /dev/null +++ b/spec/vector-tiles/sections/05-overview.adoc @@ -0,0 +1,25 @@ +[[OverviewClause]] +== Overview + +This Engineering Report describes an extension for storing Releasable Basemap Tiles (RBT) in GeoPackage developed during the March 2024 OGC Code Sprint initiative sponsored by the US Army Geospatial Center (AGC). + +The report is organized into four main sections: + +* <> describes the RBT extension as a whole, including requirements for declaring conformance to this extension, as well as requirements specific to storing RBT data products, + +* <> describes requirements related to storing vector tiles in GeoPackages, based on the draft extensions developed in previous initiatives such as +the Vector Tile Pilots (https://www.ogc.org/initiatives/vt-pilot-2018/[Phase 1+extension] and https://www.ogc.org/initiatives/vtp2/[Phase2]), + +* <> describes requirements related to semantic annotations, also based on previously developed draft extensions, providing a mechanism to identify content and associate portrayal rules with content, + +* <> describes requirements related to including styles (portrayal information) in GeoPackages, also based on previously developed draft extensions, + +and three annexes: + +* <> defines an Abstract Test Suite for this extension, upon which an Executable Test Suite could be based, + +* <> describes three implementations of both producers and consumers (viewers) of GeoPackages using this extension +developed during the code sprint by three participants: <>, <> and <>, +including Technology Integration Experiments demonstrating interoperability between these different implementations, as well as <> from these implementation efforts, + +* <> provides recommendations for future work that could be undertaken to build upon the results from the sprint, improve interoperability and performance for RBT content, and move this extension along the standardization process. diff --git a/spec/vector-tiles/sections/06-vector-tiles.adoc b/spec/vector-tiles/sections/06-vector-tiles.adoc new file mode 100644 index 00000000..7428944c --- /dev/null +++ b/spec/vector-tiles/sections/06-vector-tiles.adoc @@ -0,0 +1,351 @@ +[[VectorTilesClause]] +== Vector Tiles + +[[VectorTilesRequirementClass]] +=== Vector Tiles Requirements + +==== Introduction + +These requirements define how to encode tiled feature data (commonly known as _vector tiles_) in a GeoPackage data store. + +For vector tilesets, all of the http://www.geopackage.org/guidance/getting-started.html#tiles[Tiles Option] applies. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/vector-tiles +description:: For defining how vector tiles are encoded +part:: Vector tilesets SHALL be stored in a GeoPackage with individual tiles stored in the `tile_data` blob of a tile pyramid user data table. +part:: The `data_type` of a vector tileset entry in the `gpkg_contents` table SHALL be `vector-tiles`. +part:: The Coordinate Reference System (SRS) specified for a vector tileset in the `gpkg_spatial_ref_sys` (see clause 1.1.2 in the core GeoPackage standard) SHALL be https://docs.ogc.org/is/17-083r4/17-083r4.html#toc15[compatible (see 2DTMS _6.2.1.1. TileMatrixSet CRS Compatibility_)] with the Coordinate Reference System of the 2D Tile Matrix Set definition for that tileset. +==== + +.Example SQL statement for creating a user-defined table storing vector tiles +[source,sql] +---- +CREATE TABLE tiles_physical( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + zoom_level INTEGER NOT NULL, + tile_column INTEGER NOT NULL, + tile_row INTEGER NOT NULL, + tile_data BLOB NOT NULL, + UNIQUE (zoom_level, tile_column, tile_row) +) +---- + +See <> for an implementation example of a user-defined vector tiles table. + +There are two additional required metadata tables for vector tiles, `gpkgext_vt_layers` and `gpkgext_vt_fields`, that mirror the https://github.com/mapbox/mbtiles-spec/blob/master/1.3/spec.md#vector_layers[vector_layers key from the JSON object from the metadata from MBTiles]. +This allows client software to understand the feature schemas without having to open individual tiles. +As with other GeoPackage tables, this extension takes no position on how either of these tables are to be used by a client. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/vector-tiles-layers +description:: For describing the layers contained in vector tilesets +part:: GeoPackage containing vector tiles SHALL include a `gpkgext_vt_layers` table describing the layers in a vector tile set. The columns in this table are: +* `id`, the primary key +* `table_name`, which matches the entry in `gpkg_contents` +* `name`, the layer name +* `description`, an optional text description +* `minzoom` and `maxzoom`, the optional integer minimum and maximum zoom levels +* `attributes_table_name`, the optional name of an attributes table containing the attributes (when encoding attributes into a separate attributes tables rather than embedding them in the vector tiles -- should be NULL for this RBT extension) +* `geometry_dimension`, the dimension of the geometry found in the layer (NULL: unknown/mixed, 0: Point/MultiPoint, 1: LineString/MultiLineString, 2: Polygon/MultiPolygon) +==== + +.Example SQL statement for creating the `gpkgext_vt_layers` table +[source,sql] +---- +CREATE TABLE gpkgext_vt_layers ( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + table_name TEXT NOT NULL REFERENCES gpkg_contents (table_name), + name TEXT NOT NULL, + description TEXT, + minzoom INTEGER, + maxzoom INTEGER, + attributes_table_name TEXT, + geometry_dimension INTEGER +) +---- + +See <> for an implementation example of the `gpkgext_vt_layers` table. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/vector-tiles-fields +description:: For describing the fields contained in vector tilesets +part:: GeoPackage containing vector tiles SHALL include a `gpkgext_vt_fields` table describing the fields (attributes) for a tiled feature data layer. The columns in this table are: +* `id`, the primary key +* `layer_id`, a foreign key to `id` in `gpkgext_vt_layers` +* `name`, the field name +* `type`, either "String", "Number", or "Boolean" +==== + +.Example SQL statement for creating the `gpkgext_vt_fields` table +[source,sql] +---- +CREATE TABLE gpkgext_vt_fields ( + id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, + layer_id INTEGER REFERENCES gpkgext_vt_layers, + name TEXT NOT NULL, + type TEXT +) +---- + +See <> for an implementation example of the `gpkgext_vt_fields` table. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/content-types +description:: For specifying the media types and content encoding of user data tables +part:: The GeoPackage SHALL include a `gpkgext_content_types` table identifying the media type containing the following columns: +* `content_id`, a foreign key to the corresponding entry in the `gpkg_contents` +* `media_type`, text indicating a media type used in the `tile_data` blobs of the corresponding tile pyramid user data table (e.g., `image/png` or `application/vnd.mapbox-vector-tile`) +* `encoding`, the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding[content encoding] (e.g., `deflate` or `gzip` compression), _NULL_ if no additional encoding is used for the same `tile_data` blobs +==== + +.Example SQL statement for creating the `gpkgext_content_types` table +[source,sql] +---- +CREATE TABLE gpkgext_content_types ( + content_id INTEGER REFERENCES gpkg_contents, + media_type TEXT, + encoding TEXT +) +---- + +NOTE: Multiple entries for the same `content_id` indicate that multiple data media types can be found in the corresponding tiles table (e.g., JPEG and PNG). + +[[AttributeTablesRequirementClass]] +=== Attribute Tables Requirements + +These requirements allow to store attributes of vector tiles in features tables, which is more compact compared to duplicating the same attribute informaiton in multiple vector tiles. +Use of this requirement class is agnostic of the vector tiles encoding, but requires that the encoded vector tiles have a unique feature identifier referencing a row of their associated attributes table. + +[[gpkg-attributes-vt-layers]] +[float] +==== `gpkgext_vt_layers` +Set the `attributes_table_name` column to the appropriate table for each vector tiles layer with attributes in an attributes table. + +Use the primary key of the attributes table as the feature ID in the encoded vector tiles. + +It is recommended to use the http://www.geopackage.org/spec120/#extension_rtree[RTree Extension] to optimize spatial look up of features, as well as to store the spatial extent of each feature +which will allow to list tiles within the extent. + +For a more direct mapping of features and tiles, the Tiles / Features Mapping requirement class can also be used. + +[[TilesFeaturesMappingRequirementClass]] +=== Tiles / Features Mapping Requirements + +These requirements define how to associate features with the tiles in which they are located, and vice-versa (many to many association). +The use of the Attributes Table requirement class as well as the R-Tree extension is technically sufficient to look up the extent of a particular feature, which can then be used to list +all possible tiles within that extent where geometry for that feature could exist. Use of feature IDs inside tiles also enable to look up features while iterating through geometry found within loaded tiles. + +Use of this requirements class, based on the https://www.geopackage.org/spec/related-tables/[Related Table Extension], provides the ability to perform these lookup operations in a more direct manner. + +This requirements class defines a relationship between features of a vector tiles layer and vector tiles (or tiled feature data) containing those features. +When this requirements class is used, it is possible to perform a relational query and isolate only the vector tiles containing relevant features. +In some circumstances this has the potential to greatly improve application performance. +This extension is agnostic to the underlying _format_ of the vector tiles. + +[float] +==== Background +The http://docs.opengeospatial.org/is/18-000/18-000.html[GeoPackage Related Tables Extension] (RTE) defines the rules and requirements for creating relationships in a GeoPackage data store between geospatial data tables and other tables that contain or reference related content such as attributes or media. +As an example, this can be used to establish a many-to-many relationship between features (e.g., points, lines, or areas) and multimedia files. +By definition, the "left" side of the relationship is the "base" data and the "right" side of the relationship is the "related" data. +The mapping table links related rows in those tables of those types by reference to their primary keys. + +When relating vector tiles with the attributes of the features in those tiles, the base data is the vector tiles and the related data is the attributes as illustrated below. + +// by <>. + +The "GeoPackage Extension for Related Tables" allows a GeoPackage to contain additional data that is related to geospatial (e.g., features) or attributes data. +When relating tiled feature data with attributes, the tiled feature data is the "base" data and the attributes are the "related" data. + +//// +.Table Diagram +[#img-model] +image::images/vt+attributes_basic.png[] +//// + +//// +REVIEW: gpkg_extensions for each req. class +[float] +==== `gpkg_extensions` +To use this extension, add the following rows to this table as described in http://www.geopackage.org/guidance/getting-started.html#gpkg_extensions[`gpkg_extensions`]. + +[[gpkg_vector_tiles_attributes_ger_table]] +.gpkg_extensions Table Rows +[cols=",,,,",options="header",] +|======================================================================================================================================================================== +| table_name | column_name | extension_name | definition | scope +|`gpkgext_relations`|null|`related_tables`|https://github.com/opengeospatial/geopackage-related-tables | `read-write` +|_name of actual <>_|null|`related_tables`|https://github.com/opengeospatial/geopackage-related-tables|`read-write` +|======================================================================================================================================================================== + +[NOTE] +========== +The values in the `definition` column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by the OGC, it will gain the "gpkg_" prefix and get a different definition permalink. +========== + +//// + +[float] +==== `gpkgext_relations` +This table describes extended relationships. +The table requires the following columns: + +.gpkgext_relations Table Rows +[cols=",",options="header",] +|======================================================================================================================================================================== +| Column | Description +| `id` | primary key +| `base_table_name` | Name of the vector tiles table +| `base_primary_column` | `id` (all user-defined tiles tables have this column) +| `related_table_name` | Name of the user-defined attributes table +| `related_primary_column` | Name of the primary key column in `related_table_name` +| `relation_name` | `vector_tiles_attributes` +| `mapping_table_name` | Name of a <> +|======================================================================================================================================================================== + +Add a row to this table for each vector tiles layer with attributes in an attributes table. + +[[gpkg-attributes-udmt]] +[float] +==== User-defined Mapping Table +A link:http://www.geopackage.org/guidance/extensions/related_tables.html#user-defined-mapping-table[user-defined mapping table] describes the many-to-many relationships between base data (tiles) and related data (features). +A user-defined mapping table requires at least the following columns: + +.gpkgext_relations Table Rows +[cols=",",options="header",] +|==== +| Column | Description +| `base_id` | tile ID (the primary key value of the base data table) +| `related_id` | feature ID (the primary key value of the related data table) +|==== + +[[WKBCollectionEncodingRequirementClass]] +=== WKB Collection Encoding Requirements + +These requirements define how to encode vector tiles in a GeoPackage data store using an extension of the Well-Known Binary (WKB) specification as defined in +https://portal.ogc.org/files/?artifact_id=25355[OGC Simple Feature Access] Section 8 "Well-known Binary Representation for Geometry". WKB is also used to encode +non-tiled vector data in GeoPackage feature tables. This extension allows to encode the geometry of multiple features in a single blob, while including an identifier +which can be mapped to an attributes table, as well as the ability to mark artificial segments. + +.WKB Collection Layout +[options="header"] +|=== +| Field | Type | Size +| Endianness | 0: big, 1: little | 1 byte +| Coordinate Type | 1: Z, 2: M (bits) | 1 byte +| Geometry Type | 1: (multi)point, 2: (multi)linestring, 3: (multi)polygon | 2 bytes +| Feature Count | uint32 | 4 bytes +| **Feature Table** (one entry per feature) | | +| Feature ID | uint64 | 8 bytes +| Offset from start | uint64 | 8 bytes +| **# Features with artificial segments** | uint32 | 4 bytes +| **Artificial Segments Table** (for each feature with artificial segment) | | +| # Artificial segments | uint32 | 4 bytes +| (Multi)Polygon: _**For Each artificial segment**_ | | +| Polygon index | uint32 | 4 bytes +| Contour index | uint32 | 4 bytes +| Artificial **_From_** Point index | uint32 | 4 bytes +| Artificial **_To_** Point index | uint32 | 4 bytes +| (Multi)LineString : _**For Each artificial segment**_ | | +| LineString index | uint32 | 4 bytes +| Artificial **_From_** Point index | uint32 | 4 bytes +| Artificial **_To_** Point index | uint32 | 4 bytes +| **Feature Geometry** (for each feature) | | +| Encoded geometry | https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary[Well-known binary] (https://portal.ogc.org/files/?artifact_id=25355[Simple Feature Access] / Section 8)| +|=== + +NOTE: A client that does not understand or care about artificial segments information will simply skip over it with the feature table offsets. + +//// + +[[GeoJSONEncodingRequirementClass]] +=== GeoJSON Encoding Requirements + +These requirements define how to encode vector tiles in a GeoPackage data store using the https://datatracker.ietf.org/doc/html/rfc7946[GeoJSON specification]. + +The content of the vector tiles SHALL be feature collections encoded as GeoJSON. + + +REVIEW: Extension definition + +==== Extension Title + +GeoJSON Vector Tiles + +[float] +==== Extension Name or Template + +`im_vector_tiles_geojson` (If this extension is adopted by the OGC, then `gpkg_geojson_vector_tiles` will be named as an alias.) + +[float] +==== Extension Type + +This extension defines an encoding for the <>. + +[float] +==== Applicability + +This extension defines a specific encoding for GeoJSON Vector Tiles in a GeoPackage. + +[float] +==== Specification + +If this extension is in use, then all of the <> applies. + + +[float] +===== User Data Tables +Like other tile-based content, the physical data is stored in a https://tools.ietf.org/html/rfc7946#section-3.3[GeoJSON Feature Collection]. + +[float] +===== `gpkg_extensions` +To use this extension, add a row to this table for each tile pyramid user data table. + +[[im_vector_tiles_geojson_ger_table]] +.gpkg_extensions Table Rows +[cols=",,,,",options="header",] +|======================================================================================================================================================================== +| table_name | column_name | extension_name | definition | scope +| _tile pyramid user data table name_ | `tile_data` | `im_vector_tiles_geojson` | _a reference to this file_ | _read-write_ +|======================================================================================================================================================================== + +[NOTE] +========== +The values in the `definition` column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by the OGC, it will gain the "gpkg_" prefix and get a different definition permalink. +========== +//// + + +[[MapboxVectorTilesRequirementClass]] +=== Mapbox Vector Tiles Encoding Requirements + +These requirements define how to encode vector tiles in a GeoPackage data store using the https://github.com/mapbox/vector-tile-spec/tree/master/2.1[Mapbox Vector Tiles (MVT) specification version 2.1], +based on https://github.com/google/protobuf[Google Protocol Buffers] for encoding the data of each tile. + +[requirement] +==== +[%metadata] +identifier:: /req/rbt/mapbox-vector-tiles +description:: For describing how tiles are encoded using Mapbox Vector Tiles +part:: Tilesets encoded using Mapbox Vector Tiles SHALL be stored as blobs in the `tile_data` fields of http://www.geopackage.org/guidance/getting-started.html#user-data-tables[user-defined tiles tables]. +part:: The `tile_data` blobs SHALL be encoded Google Protocol Buffers (PBF) using the schema https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto[defined for MVT]. +part:: If an encoding such as `gzip` or `deflate` is specified in the `gpkgext_content_types` table, the PBF blob SHALL have this additional encoding applied. +==== + +[recommendation] +==== +[%metadata] +identifier:: /rec/rbt/mvt-id +description:: For specifying a unique feature ID +part:: Features contained in Mapbox Vector Tiles contained in a GeoPackage vector tileset SHOULD make use of the MVT `id` field to store a persistent numeric identifier +uniquely identifying a particular feature of the parent layer. This enables client to recognize features across tile boundaries (for example, to reconstruct the original features) +without resorting to attribute comparison, which might not be accurate. +==== diff --git a/spec/vector-tiles/sections/aa-ats.adoc b/spec/vector-tiles/sections/aa-ats.adoc new file mode 100644 index 00000000..9a4054ab --- /dev/null +++ b/spec/vector-tiles/sections/aa-ats.adoc @@ -0,0 +1,186 @@ +[appendix,obligation="normative"] +[[annex-ats]] +== Conformance Class Abstract Test Suite + +=== Conformance Class Vector Tiles GeoPackage Extension + +//// + +[[conf_rbt,/conf/rbt]] +[conformance_class] +==== +[%metadata] +identifier:: https://fgs-dps.gs.mil/#rbt/conf +target:: https://fgs-dps.gs.mil/#rbt/req +classification:: Target Type:Data Product +abstract-test:: /conf/rbt/extensions +abstract-test:: /conf/rbt/geodataclasses +abstract-test:: /conf/rbt/world-mercator +abstract-test:: /conf/rbt/map-tiles +abstract-test:: /conf/rbt/physical-cultural-features +abstract-test:: /conf/rbt/hillshade +abstract-test:: /conf/rbt/included-styles +abstract-test:: /conf/rbt/vector-tiles +abstract-test:: /conf/rbt/vector-tiles-layers +abstract-test:: /conf/rbt/vector-tiles-fields +abstract-test:: /conf/rbt/content-types +abstract-test:: /conf/rbt/mapbox-vector-tiles +abstract-test:: /conf/rbt/semantic-annotations +abstract-test:: /conf/rbt/sa-reference +abstract-test:: /conf/rbt/styles +abstract-test:: /conf/rbt/style-sheets +abstract-test:: /conf/rbt/symbol-images +abstract-test:: /conf/rbt/symbol-content +abstract-test:: /conf/rbt/fonts +abstract-test:: /conf/rbt/mapboxgl-style +==== + +==== Abstract Test for Requirement RBT Extensions + +[[conf_rbt_extensions,/conf/rbt/extensions]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/extensions +target:: /req/rbt/extensions +test-purpose:: Verify that the RBT GeoPackage properly declare extended tables +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard + +*When:* querying the content of the `gpkg_extensions` table + +*Then:* + +- assert that all entries listed in <> are present, including an entry for every user data table making use of these extensions. +-- +==== + +==== Abstract Test for Requirement GeoDataClasses + +[[conf_rbt_geodataclasses,/conf/rbt/geodataclasses]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/geodataclasses +target:: /req/rbt/geodataclasses +test-purpose:: Verify that the RBT GeoPackage properly identify RBT tilesets using GeoDataClass semantic annotations +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/semantic-annotations` and `/conf/rbt/sa-reference` tests + +*When:* querying the semantic annotations + +*Then:* + +- assert that corresponding entries exist annotating the `gpkg_contents` table for the mandatory _cultural_ and _physical_ tilesets, as well as for the optional imagery, COCOM and digital elevation model tilesets (if present) + +- assert that corresponding entries exist annotating the `gpkgext_vt_layers` table for the mandatory _cultural_ and _physical_ tilesets +-- +==== + + +==== Abstract Test for Requirement World Mercator 2DTMS + +[[conf_rbt_world-mercator,/conf/rbt/world-mercator]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/world-mercator +target:: /req/rbt/world-mercator +test-purpose:: Verify that the RBT GeoPackage tile sets use the World Mercator 2D Tile Matrix Set +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses` test + +*When:* inspecting the gpkg_tile_matrix and gpkg_tile_matrix_sets tables associated with the identified cultural, physical, imagery COCOM, and elevation model RBT tilesets + +*Then:* + +- assert that the entries correspond to those expected for the `http://www.opengis.net/def/tilematrixset/OGC/1.0/WorldMercatorWGS84Quad` 2D Tile Matrix Set using the EPSG:3395 world Mercator coordinate reference system. +-- +==== + +==== Abstract Test for Requirement Map Tiles + +[[conf_rbt_map-tiles,/conf/rbt/map-tiles]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/map-tiles +target:: /req/rbt/map-tiles +test-purpose:: Verify that the RBT GeoPackage tile sets includes the mandatory hillshade tileset, and encodes all mandatory and optional imagery tilesets as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses` and `/conf/rbt/content-types` tests + +*When:* inspecting the available user defined tiles tables and `gpkg_contents` table + +*Then:* + +- assert that the `data_type` of the `gpkg_contents` table for these tilesets is `tiles` + +- assert that the `tile_data` of the the user defined tiles table contains PNG for the _hillshade_ tileset, and PNG and/or JPEG for the optional imagery tilesets, without any additional encoding applied + +- assert that the `gpkgext_content_types` table declares these tilesets as using JPEG (except for _hillshade_) or PNG using the `image/jpeg` and/or `image/png` media type and a NULL encoding +-- +==== + +==== Abstract Test for Requirement Physical and Cultural Features + +[[conf_rbt_physical-cultural-features,/conf/rbt/physical-cultural-features]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/physical-cultural-features +target:: /req/rbt/physical-cultural-features +test-purpose:: Verify that the RBT GeoPackage tile sets includes and encodes the mandatory physical and cultural vector features tile sets as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses`, `/conf/rbt/vector-tiles`, `/conf/rbt/vector-tiles-layers` and `/conf/rbt/content-types` tests + +*When:* inspecting the available user defined tiles tables, `gpkgext_vt_layers`, `gpkg_contents` and their associated semantic annotations tables + +*Then:* + +- assert that a physical features tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-physical` is included + +- assert that a cultural features tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-cultural` is included + +- assert that the `data_type` of the `gpkg_contents` table for these tilesets is `vector-tiles` and that the `tile_data` of the the user defined tiles table contains gzip'ed Mapbox Vector Tiles + +- assert that the `gpkgext_content_types` table declares these tilesets as using Mapbox Vector Tile using the `application/vnd.mapbox-vector-tile` and the `gzip` encoding + +- assert that the Mapbox Vector Tiles for these tilesets contain embedded attributes +-- +==== + +==== Abstract Test for Requirement Hillshade + +[[conf_rbt_hillshade,/conf/rbt/hillshade]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/hillshade +target:: /req/rbt/hillshade +test-purpose:: Verify that the RBT GeoPackage tile sets includes and encodes the mandatory hillshaded digital elevation model as expected +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/map-tiles` test + +*When:* inspecting the content of the user defined tiles table for the hillshaded tileset + +*Then:* + +- assert that a hillshade tileset with the GeoDataClass `http://www.opengis.net/def/geodataclass/NSG/0/rbt-hillshade` is included + +- assert that the content of the hillshade tileset is pre-rendered map tileset, in a monochrome translucent hillshaded style encoded as PNG images +-- +==== + +==== Abstract Test for Requirement Included Styles + +[[conf_rbt_included-styles,/conf/rbt/included-styles]] +[abstract_test] +==== +[%metadata] +identifier:: /conf/rbt/included-styles +target:: /req/rbt/included-styles +test-purpose:: Verify that the RBT GeoPackage tile sets includes at least one style in a MapboxGL representation +test-method:: ++ +-- +*Given:* a GeoPackage conforming to the core GeoPackage standard passing the `/conf/rbt/geodataclasses`, `/conf/rbt/styles`, `/conf/rbt/style-sheets`, `/conf/rbt/symbol-images`, `/conf/rbt/symbol-content` and `/conf/rbt/mapboxgl-style` tests + +*When:* inspecting the content of the `gpkgext_styles` table for styles associated to the _physical_, _cultural_ and _hillshade_ RBT tilesets using the `GeoDataClass` annotation + +*Then:* + +- assert that at least one style in a MapboxGL representation is available for styling the physical and cultural and hillshade RBT tilesets + +- assert that all style sheets applicable to any of the RBT tilesets include styling rules for at least the physical and cutural tilesets + +- assert that all symbols referenced by MapboxGL style sheets are at least available as a sprite sheet where the `sprite` property of the MapboxGL style corresponds to a `uri` of an entry in the `gpkgext_symbol_content` table whose `content` blob contains all symbols + +- assert that individual entries in the `gpkgext_symbol_images` table, with offsets and dimensions of individual symbols, exist for all symbols referencing the sprite sheets in the `gpkgext_symbol_content` table for each Mapbox GL style +-- +==== + +NOTE: The Abstract Test Suites corresponding to the requirements in the Vector Tiles, Semantic Annotations and Styling sections will be elaborated in the corresponding +OGC GeoPackage extensions to be developed as separate documents, as documented in the Future Work section. + +//// diff --git a/spec/vector-tiles/sections/ah-history.adoc b/spec/vector-tiles/sections/ah-history.adoc new file mode 100644 index 00000000..17393308 --- /dev/null +++ b/spec/vector-tiles/sections/ah-history.adoc @@ -0,0 +1,11 @@ + +[appendix] +== Revision History + +[%unnumbered] +[width="90%",options="header"] +|=== +|Date |Release |Editor | Primary clauses modified |Description +|2024-03-22 |0.1 |J. St-Louis |all |initial version +|2024-05-30 |0.2 |J. St-Louis |all |final draft ready for review +|=== diff --git a/spec/vector-tiles/sections/az-bibliography.adoc b/spec/vector-tiles/sections/az-bibliography.adoc new file mode 100644 index 00000000..a1b758d4 --- /dev/null +++ b/spec/vector-tiles/sections/az-bibliography.adoc @@ -0,0 +1,20 @@ + + +[bibliography] +== Bibliography + +* [[[OGC18-074,OGC 18-074]]], +* [[[OGC18-086r1,OGC 18-086r1]]], +* [[[OGC18-076,OGC 18-076]]], +* [[[OGC18-101,OGC 18-101]]], +* [[[OGC19-082r1,OGC 19-082r1]]], +* [[[OGC20-092, OGC 20-092]]], +* [[[OGC19-088r2,OGC 19-088r2]]], +* [[[OGC19-018,OGC 19-018]]], +* [[[OGC20-019r1,OGC 20-019r1]]], +* [[[MapboxGLStyle,MapboxGLStyle]]], Mapbox GL Style Specification, https://docs.mapbox.com/style-spec/ +* [[[MapLibreStyle,MapLibreStyle]]], MapLibre Style Specification, https://maplibre.org/maplibre-style-spec/ +* [[[MVT,MVT]]], Mapbox Vector Tiles Specification version 2.1, https://github.com/mapbox/vector-tile-spec/tree/master/2.1 +* [[[CDBWShop,CDBWShop]]], CDB 2.0 2023 Summer Workshop GitHub Repository, https://github.com/opengeospatial/CDBV2-2023-Summer-Workshop +* [[[MBTiles,MBTiles]]], MBTiles Specification version 1.3, https://github.com/mapbox/mbtiles-spec/blob/master/1.3/spec.md +* [[[TileJSON,TileJSON]]], TileJSON Specification version 3.0, https://github.com/mapbox/tilejson-spec/tree/master/3.0.0