├── CHARTER.adoc
├── LICENSE
├── README.md
├── geozarr-interop-table.md
├── geozarr-spec.md
├── geozarr_swg_charter.html
└── standard
    ├── README.md
    └── template
        ├── .github
            └── workflows
            │   ├── docker.yml
            │   └── generate.yml
        ├── .gitignore
        ├── .gitlab-ci.yml
        ├── Gemfile
        ├── Makefile
        ├── Makefile.win
        ├── README.adoc
        ├── UML
            └── README.adoc
        ├── abstract_tests
            ├── ATS_class_example1.adoc
            ├── ATS_test_example1.adoc
            ├── ATS_test_example2.adoc
            └── README.adoc
        ├── code
            └── README.adoc
        ├── document.adoc
        ├── figures
            └── README.adoc
        ├── images
            └── README.adoc
        ├── metanorma.yml
        ├── requirements
            ├── README.adoc
            ├── requirement001.adoc
            ├── requirement002.adoc
            └── requirements_class.adoc
        └── sections
            ├── annex-a.adoc
            ├── annex-bibliography.adoc
            ├── annex-history.adoc
            ├── annex-n.adoc
            ├── clause_0_front_material.adoc
            ├── clause_1_scope.adoc
            ├── clause_2_conformance.adoc
            ├── clause_3_references.adoc
            ├── clause_4_terms_and_definitions.adoc
            ├── clause_5_conventions.adoc
            ├── clause_6_informative_text.adoc
            ├── clause_7_annex_mapping.adoc.adoc
            ├── clause_7_format_requirements.adoc
            ├── clause_7a_format_overview.adoc
            ├── clause_7b_format_core.adoc
            ├── clause_7c_format_coordinates.adoc
            ├── clause_7d_format_pyramiding.adoc
            ├── clause_7e_format_dataset_types.adoc
            └── clause_8_media_types.adoc


/CHARTER.adoc:
--------------------------------------------------------------------------------
  1 | :Title: OGC GeoZarr Standards Working Group Charter
  2 | :titletext: {Title}
  3 | :doctype: book
  4 | :encoding: utf-8
  5 | :lang: en
  6 | :toc:
  7 | :toc-placement!:
  8 | :toclevels: 4
  9 | :numbered:
 10 | :sectanchors:
 11 | :source-highlighter: pygments
 12 | 
 13 | <<<
 14 | [cols = ">",frame = "none",grid = "none"]
 15 | |===
 16 | |{set:cellbgcolor:#FFFFFF}
 17 | |[big]*Open Geospatial Consortium*
 18 | |Submission Date: 2023-05-01
 19 | |Approval Date: 2023-12-04
 20 | |Internal reference number of this OGC(R) document: 23-046
 21 | |Category: OGC(R) Standards Working Group Charter
 22 | |Authors: Christophe Noel, Brianna R. Pagán
 23 | |===
 24 | 
 25 | [cols = "^", frame = "none"]
 26 | |===
 27 | |[big]*{titletext}*
 28 | |===
 29 | 
 30 | [cols = "^", frame = "none", grid = "none"]
 31 | |===
 32 | |*Copyright notice*
 33 | |Copyright (C) 2023 Open Geospatial Consortium
 34 | |To obtain additional rights of use, visit http://www.opengeospatial.org/legal/
 35 | |===
 36 | 
 37 | <<<
 38 | 
 39 | To: OGC members & interested parties
 40 | 
 41 | A new OGC Standards Working Group (SWG) is being formed. The OGC members listed below have proposed the OGC GeoZarr SWG.  The SWG proposal provided in this document meets the requirements of the OGC Technical Committee (TC) Policies and Procedures.
 42 | 
 43 | The SWG name, statement of purpose, scope, list of deliverables, audience, and language specified in the proposal will constitute the SWG's official charter. Technical discussions may occur no sooner than the SWG's first meeting.
 44 | 
 45 | This SWG will operate under the OGC IPR Policy. The eligibility requirements for becoming a participant in the SWG at the first meeting (see details below) are that:
 46 | 
 47 | * You must be an employee of an OGC member organization or an individual
 48 | member of OGC;
 49 | 
 50 | * The OGC member must have signed the OGC Membership agreement;
 51 | 
 52 | * You must notify the SWG chair of your intent to participate to the first meeting. Members may do so by logging onto the OGC Portal and navigating to the Observer page and clicking on the link for the SWG they wish to join and;
 53 | 
 54 | * You must attend meetings of the SWG. The first meeting of this SWG is at the time and date fixed below. Attendance may be by teleconference.
 55 | 
 56 | Of course, participants also may join the SWG at any time. The OGC and the SWG welcomes all interested parties.
 57 | 
 58 | Non-OGC members who wish to participate may contact us about joining the OGC. In addition, the public may access some of the resources maintained for each SWG: the SWG public description, the SWG Charter, Change Requests, and public comments, which will be linked from the SWG’s page.
 59 | 
 60 | Please feel free to forward this announcement to any other appropriate lists. The OGC is an open standards organization; we encourage your feedback.
 61 | 
 62 | == Purpose of the Standards Working Group
 63 | 
 64 | The GeoZarr Standard Working Group (SWG) is chartered to develop a Zarr encoding for geospatial gridded data in the form of Zarr conventions (based on the approach described in the draft Zarr Enhancement Proposal 4).  Zarr specifies a protocol and format used for storing Zarr arrays, while GeoZarr defines **conventions** and recommendations for storing **multidimensional georeferenced grid** of geospatial observations (including rasters). If appropriate, the GeoZarr SWG may also contribute to the Climate and Forecast (CF) conventions (e.g. alternative CRS encoding) by proposing changes based on the [CF community governance process](https://cfconventions.org/governance.html).
 65 | 
 66 | 
 67 | 
 68 | == Business Value Proposition
 69 | 
 70 | In the geospatial world, new cloud-native data formats are emerging. Zarr is a generic data format for n-dimensional arrays that enables access to data in compressed chunks of the original array and has become increasingly popular to use for geospatial purposes. Zarr facilitates portability and interoperability on both object stores and hard disks. In June 2022, the OGC endorsed a community standard of Zarr V2.0 (https://zarr.readthedocs.io/en/stable/spec/v2.html). The purpose of this charter is to adopt a more explicit GeoZarr as an OGC Standard which would provide guidance to standardize the approach for encoding various aspects of geospatial data in zarrs.
 71 | 
 72 | == Scope of Work
 73 | 
 74 | The goal of the GeoZarr specification is to establish flexible and inclusive conventions for the Zarr cloud-native format, specifically designed to meet the diverse requirements within the geospatial domain. These conventions aim to provide a clear and standardized framework for organizing and describing data, ensuring unambiguous representation. 
 75 | 
 76 | In addition to the encoding geospatial data and metadata using Zarr, the specification will aim to to provide a multidimensional alternative to the two-dimensional Cloud-Optimized GeoTiff format which has gained popularity due to its serverless capabilities. These capabilities allow for inherent support of traditionally server-based functions, including visualization (similar to OGC API Maps), data subset access (analogous to OGC API Coverages), and symbology (equivalent to OGC API Styles). These aspects are planned to be incorporated as optional profiles (e.g. conformance classes).
 77 | 
 78 | The objectives of GeoZarr conventions includes:
 79 | 
 80 | 1. Compatibility: Ensuring easy compatibility with popular mapping and data analysis tools such as GDAL, Xarray, ArcGIS, QGIS, and other visualisation tools, enabling seamless integration into existing workflows.
 81 | 2. Dimensions: Supporting multidimensional data, such as hyperspectral and altitude information, to address diverse geospatial data requirements.
 82 | 3. Data Discovery: Providing metadata for discovering, accessing, and retrieving the data, including composite products made of multiple data arrays.
 83 | 4. Mixing Data: Facilitating the combination of different types of geospatial data, including satellite images, elevation maps, and weather models, to create comprehensive and informative datasets.
 84 | 5. Flexibilty: Allowing scientists and researchers to work with diverse data types and projections in their preferred software and programming languages, promoting flexibility and adaptability in geospatial data processing and analysis.
 85 | 
 86 | Specifically, the convention should provide guidance to standardize the approach for encoding various aspects of geospatial data, including, for example the following list of potential conformance classes:
 87 | 
 88 | * Multiple related variables with heterogeneous coordinates (e.g., children or linked datasets)
 89 | * Multiple resolutions of the data, possibly leveraging multiscale array representations
 90 | * Data subsets that are only available at certain resolutions
 91 | * Multi-dimensional optimizations (spatial chunking scheme, temporal chunking scheme)
 92 | * Supporting typical Earth observation (EO) products (for example, how to encode multispectral bands)
 93 | * Accessing the symbology of the corresponding data
 94 | 
 95 | Part of the effort of this working group is to determine what should be kept as a part of the GeoZarr core requirements, and what aspects of geospatial data should be kept as separate conformance classes, which may or may not be applicable to specific sub-domains of the geospatial community. 
 96 | 
 97 | === Statement of relationship of planned work to the current OGC standards baseline
 98 | As the existing draft GeoZarr metadata utilizes Climate and Forecast (CF) attributes, there is an expected relationship with the OGC CF-netCDF Data Model Extension Standard and the OGC netCDF SWG. If necessary, any adjustments or enhancements required for the GeoZarr specification will be considered as a proposal to improve CF conventions as well.
 99 | There are strong connections to other OGC raster / array container standards, specifically NetCDF, HDF5, and GeoTiff. The GeoZarr SWG should seek to leverage existing metadata conventions wherever possible.
100 | 
101 | As a chunked storage format, there is potentially a strong connection to the `OGC API - Tiles` standard. Map tiles could essentially be mapped 1:1 to an appropriately defined multiscale Zarr array.
102 | 
103 | === What is Out of Scope?
104 | In early conversations around creating a draft GeoZarr specification, concerns arose multiple times around the CF encoding of CRS which may pose issues, see https://github.com/zarr-developers/geozarr-spec/issues/20. While these concerns will be discussed and suggestions created for potentially updating CF conventions, if resolutions cannot be made with the GeoZarr specification, we consider out of scope waiting on any subsequent updates to CF conventions to reflect these suggestions. 
105 | 
106 | === Specific Existing Work Used as Starting Point
107 | * GeoZarr draft specification: https://github.com/zarr-developers/geozarr-spec/ 
108 | 
109 | === Is This a Persistent SWG
110 | 
111 | [x] YES
112 | 
113 | [ ] NO
114 | 
115 | === When can the SWG be Inactivated
116 | 
117 | The SWG can be inactivated once the SWG identifies no new tasks for the SWG and there are no open Change Requests.
118 | 
119 | == Description of deliverables
120 | The GeoZarr SWG will deliver a candidate Standard and associated developer resources.
121 | 
122 | The SWG expects to have a candidate Standard ready for OGC Architecture Board (OAB) review and public comment within nine months of creation of the SWG. Because example implementations will be developed at the same time the candidate Standard is formalized, reference implementations that fully use GeoZarr should be documented at the same time the candidate Standard goes to vote.
123 | 
124 | === Initial Deliverables
125 | 
126 | The following deliverables will be the initial results of work of the SWG.
127 | 
128 | * OGC GeoZarr Standard
129 | 
130 | * GeoZarr developer resources
131 | 
132 | The targeted start date for this SWG immediately upon approval of the SWG charter. 
133 | 
134 | === Additional SWG Tasks
135 | 
136 | No specific additional tasks are currently planned for the SWG.
137 | 
138 | == IPR Policy for this SWG
139 | 
140 | [x] RAND-Royalty Free
141 | 
142 | [ ] RAND for fee
143 | 
144 | == Anticipated Audience / Participants
145 | 
146 | This SWG will develop a Standard for general use in the geospatial community and suitable for data exchange beyond this community. Geospatial data providers and software implementers will be interested in assisting with the development of this Standard as well as the output of the SWG.
147 | 
148 | == Domain Working Group Endorsement
149 | 
150 | The SWG convenors will discuss the charter with potentially interested Domain Working Groups (DWGs) at the first opportunity.
151 | 
152 | == Other informative information about the work of this SWG
153 | 
154 | === Collaboration
155 | 
156 | All work in the Standards Working Group will be public and the SWG solicits contributions and feedback from OGC members and non-OGC members to the extent that is supported by the OGC Technical Committee Policies and Procedures.
157 | 
158 | The OGC GeoZarr SWG will collaborate on Standard development using a public GitHub repository and a Gitter channel. Development of the Standard will include the use of Issues and other project tools in GitHub.
159 | 
160 | === Similar or Applicable Standards Work (OGC and Elsewhere)
161 | 
162 | * The OGC endorsed a community standard of Zarr V2.0 (https://zarr.readthedocs.io/en/stable/spec/v2.html) in June 2022.
163 | 
164 | * This SWG is closely related to the newly announced [Geodatacube SWG](https://www.ogc.org/press-release/ogc-forms-new-geodatacube-standards-working-group/). Essentially, Geodatacube will specify a server API while GeoZarr can define a standard Cloud-native format for a serverless datacube. Therefore, close coordination between these SWGs seems needed.
165 | 
166 | * The XCube project has potential synergies with the GeoZarr specification as it already relies and complies with CF conventions: 
167 | 
168 |   * xcube Dataset Convention: https://github.com/dcs4cop/xcube/blob/master/docs/source/cubespec.md
169 | 
170 |   * xcube Multi-Resolution Datasets: https://github.com/dcs4cop/xcube/blob/master/docs/source/mldatasets.md
171 | 
172 | === Details of first meeting
173 | 
174 | The first meeting of the SWG will occur within four weeks of approval of the SWG charter.
175 | 
176 | === Projected on-going meeting schedule
177 | 
178 | The work of this SWG will be carried out primarily on GitHub and via email, web conferences / calls, and at face-to-face sessions at OGC Member Meetings as agreed to by the SWG members. The web conferences / calls will be scheduled as needed and posted to the OGC portal. Voting on OGC GeoZarr Conventions content will be limited to SWG members only.
179 | 
180 | === Supporters of this Charter
181 | 
182 | The following people support this proposal and are committed to the Charter and projected meeting schedule. These members are known as SWG Founding or Charter members. The charter members agree to the SoW and IPR terms as defined in this charter. The charter members have voting rights beginning the day the SWG is officially formed. Charter Members are shown on the public SWG page.
183 | 
184 | |===
185 | |Name |Organization
186 | 
187 | |Christophe Noel | Spacebel
188 | |Brianna R. Pagán | NASA GES DISC
189 | |Alexey N. Shiklomanov | NASA Goddard Space Flight Center
190 | |Tyler A. Erickson | VorGeo
191 | |David Blodgett | U.S. Geological Survey
192 | |===
193 | 
194 | === Conveners
195 | 
196 | xxx
197 | 
198 | [bibliography]
199 | == References
200 | 
201 | - [[[gj,1]]] IETF: IETF RFC 7946, The GeoJSON Format, 2016
202 | [[[gj,2]]] Zarr Enhancement Proposal 4 preparation, https://github.com/zarr-developers/zeps/pull/28
203 | 
204 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 | Attribution 4.0 International
  2 | 
  3 | =======================================================================
  4 | 
  5 | Creative Commons Corporation ("Creative Commons") is not a law firm and
  6 | does not provide legal services or legal advice. Distribution of
  7 | Creative Commons public licenses does not create a lawyer-client or
  8 | other relationship. Creative Commons makes its licenses and related
  9 | information available on an "as-is" basis. Creative Commons gives no
 10 | warranties regarding its licenses, any material licensed under their
 11 | terms and conditions, or any related information. Creative Commons
 12 | disclaims all liability for damages resulting from their use to the
 13 | fullest extent possible.
 14 | 
 15 | Using Creative Commons Public Licenses
 16 | 
 17 | Creative Commons public licenses provide a standard set of terms and
 18 | conditions that creators and other rights holders may use to share
 19 | original works of authorship and other material subject to copyright
 20 | and certain other rights specified in the public license below. The
 21 | following considerations are for informational purposes only, are not
 22 | exhaustive, and do not form part of our licenses.
 23 | 
 24 |      Considerations for licensors: Our public licenses are
 25 |      intended for use by those authorized to give the public
 26 |      permission to use material in ways otherwise restricted by
 27 |      copyright and certain other rights. Our licenses are
 28 |      irrevocable. Licensors should read and understand the terms
 29 |      and conditions of the license they choose before applying it.
 30 |      Licensors should also secure all rights necessary before
 31 |      applying our licenses so that the public can reuse the
 32 |      material as expected. Licensors should clearly mark any
 33 |      material not subject to the license. This includes other CC-
 34 |      licensed material, or material used under an exception or
 35 |      limitation to copyright. More considerations for licensors:
 36 |     wiki.creativecommons.org/Considerations_for_licensors
 37 | 
 38 |      Considerations for the public: By using one of our public
 39 |      licenses, a licensor grants the public permission to use the
 40 |      licensed material under specified terms and conditions. If
 41 |      the licensor's permission is not necessary for any reason--for
 42 |      example, because of any applicable exception or limitation to
 43 |      copyright--then that use is not regulated by the license. Our
 44 |      licenses grant only permissions under copyright and certain
 45 |      other rights that a licensor has authority to grant. Use of
 46 |      the licensed material may still be restricted for other
 47 |      reasons, including because others have copyright or other
 48 |      rights in the material. A licensor may make special requests,
 49 |      such as asking that all changes be marked or described.
 50 |      Although not required by our licenses, you are encouraged to
 51 |      respect those requests where reasonable. More considerations
 52 |      for the public:
 53 |     wiki.creativecommons.org/Considerations_for_licensees
 54 | 
 55 | =======================================================================
 56 | 
 57 | Creative Commons Attribution 4.0 International Public License
 58 | 
 59 | By exercising the Licensed Rights (defined below), You accept and agree
 60 | to be bound by the terms and conditions of this Creative Commons
 61 | Attribution 4.0 International Public License ("Public License"). To the
 62 | extent this Public License may be interpreted as a contract, You are
 63 | granted the Licensed Rights in consideration of Your acceptance of
 64 | these terms and conditions, and the Licensor grants You such rights in
 65 | consideration of benefits the Licensor receives from making the
 66 | Licensed Material available under these terms and conditions.
 67 | 
 68 | 
 69 | Section 1 -- Definitions.
 70 | 
 71 |   a. Adapted Material means material subject to Copyright and Similar
 72 |      Rights that is derived from or based upon the Licensed Material
 73 |      and in which the Licensed Material is translated, altered,
 74 |      arranged, transformed, or otherwise modified in a manner requiring
 75 |      permission under the Copyright and Similar Rights held by the
 76 |      Licensor. For purposes of this Public License, where the Licensed
 77 |      Material is a musical work, performance, or sound recording,
 78 |      Adapted Material is always produced where the Licensed Material is
 79 |      synched in timed relation with a moving image.
 80 | 
 81 |   b. Adapter's License means the license You apply to Your Copyright
 82 |      and Similar Rights in Your contributions to Adapted Material in
 83 |      accordance with the terms and conditions of this Public License.
 84 | 
 85 |   c. Copyright and Similar Rights means copyright and/or similar rights
 86 |      closely related to copyright including, without limitation,
 87 |      performance, broadcast, sound recording, and Sui Generis Database
 88 |      Rights, without regard to how the rights are labeled or
 89 |      categorized. For purposes of this Public License, the rights
 90 |      specified in Section 2(b)(1)-(2) are not Copyright and Similar
 91 |      Rights.
 92 | 
 93 |   d. Effective Technological Measures means those measures that, in the
 94 |      absence of proper authority, may not be circumvented under laws
 95 |      fulfilling obligations under Article 11 of the WIPO Copyright
 96 |      Treaty adopted on December 20, 1996, and/or similar international
 97 |      agreements.
 98 | 
 99 |   e. Exceptions and Limitations means fair use, fair dealing, and/or
100 |      any other exception or limitation to Copyright and Similar Rights
101 |      that applies to Your use of the Licensed Material.
102 | 
103 |   f. Licensed Material means the artistic or literary work, database,
104 |      or other material to which the Licensor applied this Public
105 |      License.
106 | 
107 |   g. Licensed Rights means the rights granted to You subject to the
108 |      terms and conditions of this Public License, which are limited to
109 |      all Copyright and Similar Rights that apply to Your use of the
110 |      Licensed Material and that the Licensor has authority to license.
111 | 
112 |   h. Licensor means the individual(s) or entity(ies) granting rights
113 |      under this Public License.
114 | 
115 |   i. Share means to provide material to the public by any means or
116 |      process that requires permission under the Licensed Rights, such
117 |      as reproduction, public display, public performance, distribution,
118 |      dissemination, communication, or importation, and to make material
119 |      available to the public including in ways that members of the
120 |      public may access the material from a place and at a time
121 |      individually chosen by them.
122 | 
123 |   j. Sui Generis Database Rights means rights other than copyright
124 |      resulting from Directive 96/9/EC of the European Parliament and of
125 |      the Council of 11 March 1996 on the legal protection of databases,
126 |      as amended and/or succeeded, as well as other essentially
127 |      equivalent rights anywhere in the world.
128 | 
129 |   k. You means the individual or entity exercising the Licensed Rights
130 |      under this Public License. Your has a corresponding meaning.
131 | 
132 | 
133 | Section 2 -- Scope.
134 | 
135 |   a. License grant.
136 | 
137 |        1. Subject to the terms and conditions of this Public License,
138 |           the Licensor hereby grants You a worldwide, royalty-free,
139 |           non-sublicensable, non-exclusive, irrevocable license to
140 |           exercise the Licensed Rights in the Licensed Material to:
141 | 
142 |             a. reproduce and Share the Licensed Material, in whole or
143 |                in part; and
144 | 
145 |             b. produce, reproduce, and Share Adapted Material.
146 | 
147 |        2. Exceptions and Limitations. For the avoidance of doubt, where
148 |           Exceptions and Limitations apply to Your use, this Public
149 |           License does not apply, and You do not need to comply with
150 |           its terms and conditions.
151 | 
152 |        3. Term. The term of this Public License is specified in Section
153 |           6(a).
154 | 
155 |        4. Media and formats; technical modifications allowed. The
156 |           Licensor authorizes You to exercise the Licensed Rights in
157 |           all media and formats whether now known or hereafter created,
158 |           and to make technical modifications necessary to do so. The
159 |           Licensor waives and/or agrees not to assert any right or
160 |           authority to forbid You from making technical modifications
161 |           necessary to exercise the Licensed Rights, including
162 |           technical modifications necessary to circumvent Effective
163 |           Technological Measures. For purposes of this Public License,
164 |           simply making modifications authorized by this Section 2(a)
165 |           (4) never produces Adapted Material.
166 | 
167 |        5. Downstream recipients.
168 | 
169 |             a. Offer from the Licensor -- Licensed Material. Every
170 |                recipient of the Licensed Material automatically
171 |                receives an offer from the Licensor to exercise the
172 |                Licensed Rights under the terms and conditions of this
173 |                Public License.
174 | 
175 |             b. No downstream restrictions. You may not offer or impose
176 |                any additional or different terms or conditions on, or
177 |                apply any Effective Technological Measures to, the
178 |                Licensed Material if doing so restricts exercise of the
179 |                Licensed Rights by any recipient of the Licensed
180 |                Material.
181 | 
182 |        6. No endorsement. Nothing in this Public License constitutes or
183 |           may be construed as permission to assert or imply that You
184 |           are, or that Your use of the Licensed Material is, connected
185 |           with, or sponsored, endorsed, or granted official status by,
186 |           the Licensor or others designated to receive attribution as
187 |           provided in Section 3(a)(1)(A)(i).
188 | 
189 |   b. Other rights.
190 | 
191 |        1. Moral rights, such as the right of integrity, are not
192 |           licensed under this Public License, nor are publicity,
193 |           privacy, and/or other similar personality rights; however, to
194 |           the extent possible, the Licensor waives and/or agrees not to
195 |           assert any such rights held by the Licensor to the limited
196 |           extent necessary to allow You to exercise the Licensed
197 |           Rights, but not otherwise.
198 | 
199 |        2. Patent and trademark rights are not licensed under this
200 |           Public License.
201 | 
202 |        3. To the extent possible, the Licensor waives any right to
203 |           collect royalties from You for the exercise of the Licensed
204 |           Rights, whether directly or through a collecting society
205 |           under any voluntary or waivable statutory or compulsory
206 |           licensing scheme. In all other cases the Licensor expressly
207 |           reserves any right to collect such royalties.
208 | 
209 | 
210 | Section 3 -- License Conditions.
211 | 
212 | Your exercise of the Licensed Rights is expressly made subject to the
213 | following conditions.
214 | 
215 |   a. Attribution.
216 | 
217 |        1. If You Share the Licensed Material (including in modified
218 |           form), You must:
219 | 
220 |             a. retain the following if it is supplied by the Licensor
221 |                with the Licensed Material:
222 | 
223 |                  i. identification of the creator(s) of the Licensed
224 |                     Material and any others designated to receive
225 |                     attribution, in any reasonable manner requested by
226 |                     the Licensor (including by pseudonym if
227 |                     designated);
228 | 
229 |                 ii. a copyright notice;
230 | 
231 |                iii. a notice that refers to this Public License;
232 | 
233 |                 iv. a notice that refers to the disclaimer of
234 |                     warranties;
235 | 
236 |                  v. a URI or hyperlink to the Licensed Material to the
237 |                     extent reasonably practicable;
238 | 
239 |             b. indicate if You modified the Licensed Material and
240 |                retain an indication of any previous modifications; and
241 | 
242 |             c. indicate the Licensed Material is licensed under this
243 |                Public License, and include the text of, or the URI or
244 |                hyperlink to, this Public License.
245 | 
246 |        2. You may satisfy the conditions in Section 3(a)(1) in any
247 |           reasonable manner based on the medium, means, and context in
248 |           which You Share the Licensed Material. For example, it may be
249 |           reasonable to satisfy the conditions by providing a URI or
250 |           hyperlink to a resource that includes the required
251 |           information.
252 | 
253 |        3. If requested by the Licensor, You must remove any of the
254 |           information required by Section 3(a)(1)(A) to the extent
255 |           reasonably practicable.
256 | 
257 |        4. If You Share Adapted Material You produce, the Adapter's
258 |           License You apply must not prevent recipients of the Adapted
259 |           Material from complying with this Public License.
260 | 
261 | 
262 | Section 4 -- Sui Generis Database Rights.
263 | 
264 | Where the Licensed Rights include Sui Generis Database Rights that
265 | apply to Your use of the Licensed Material:
266 | 
267 |   a. for the avoidance of doubt, Section 2(a)(1) grants You the right
268 |      to extract, reuse, reproduce, and Share all or a substantial
269 |      portion of the contents of the database;
270 | 
271 |   b. if You include all or a substantial portion of the database
272 |      contents in a database in which You have Sui Generis Database
273 |      Rights, then the database in which You have Sui Generis Database
274 |      Rights (but not its individual contents) is Adapted Material; and
275 | 
276 |   c. You must comply with the conditions in Section 3(a) if You Share
277 |      all or a substantial portion of the contents of the database.
278 | 
279 | For the avoidance of doubt, this Section 4 supplements and does not
280 | replace Your obligations under this Public License where the Licensed
281 | Rights include other Copyright and Similar Rights.
282 | 
283 | 
284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability.
285 | 
286 |   a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
287 |      EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
288 |      AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
289 |      ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
290 |      IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
291 |      WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
292 |      PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
293 |      ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
294 |      KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
295 |      ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
296 | 
297 |   b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
298 |      TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
299 |      NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
300 |      INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
301 |      COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
302 |      USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
303 |      ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
304 |      DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
305 |      IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
306 | 
307 |   c. The disclaimer of warranties and limitation of liability provided
308 |      above shall be interpreted in a manner that, to the extent
309 |      possible, most closely approximates an absolute disclaimer and
310 |      waiver of all liability.
311 | 
312 | 
313 | Section 6 -- Term and Termination.
314 | 
315 |   a. This Public License applies for the term of the Copyright and
316 |      Similar Rights licensed here. However, if You fail to comply with
317 |      this Public License, then Your rights under this Public License
318 |      terminate automatically.
319 | 
320 |   b. Where Your right to use the Licensed Material has terminated under
321 |      Section 6(a), it reinstates:
322 | 
323 |        1. automatically as of the date the violation is cured, provided
324 |           it is cured within 30 days of Your discovery of the
325 |           violation; or
326 | 
327 |        2. upon express reinstatement by the Licensor.
328 | 
329 |      For the avoidance of doubt, this Section 6(b) does not affect any
330 |      right the Licensor may have to seek remedies for Your violations
331 |      of this Public License.
332 | 
333 |   c. For the avoidance of doubt, the Licensor may also offer the
334 |      Licensed Material under separate terms or conditions or stop
335 |      distributing the Licensed Material at any time; however, doing so
336 |      will not terminate this Public License.
337 | 
338 |   d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
339 |      License.
340 | 
341 | 
342 | Section 7 -- Other Terms and Conditions.
343 | 
344 |   a. The Licensor shall not be bound by any additional or different
345 |      terms or conditions communicated by You unless expressly agreed.
346 | 
347 |   b. Any arrangements, understandings, or agreements regarding the
348 |      Licensed Material not stated herein are separate from and
349 |      independent of the terms and conditions of this Public License.
350 | 
351 | 
352 | Section 8 -- Interpretation.
353 | 
354 |   a. For the avoidance of doubt, this Public License does not, and
355 |      shall not be interpreted to, reduce, limit, restrict, or impose
356 |      conditions on any use of the Licensed Material that could lawfully
357 |      be made without permission under this Public License.
358 | 
359 |   b. To the extent possible, if any provision of this Public License is
360 |      deemed unenforceable, it shall be automatically reformed to the
361 |      minimum extent necessary to make it enforceable. If the provision
362 |      cannot be reformed, it shall be severed from this Public License
363 |      without affecting the enforceability of the remaining terms and
364 |      conditions.
365 | 
366 |   c. No term or condition of this Public License will be waived and no
367 |      failure to comply consented to unless expressly agreed to by the
368 |      Licensor.
369 | 
370 |   d. Nothing in this Public License constitutes or may be interpreted
371 |      as a limitation upon, or waiver of, any privileges and immunities
372 |      that apply to the Licensor or You, including from the legal
373 |      processes of any jurisdiction or authority.
374 | 
375 | 
376 | =======================================================================
377 | 
378 | Creative Commons is not a party to its public
379 | licenses. Notwithstanding, Creative Commons may elect to apply one of
380 | its public licenses to material it publishes and in those instances
381 | will be considered the “Licensor.” The text of the Creative Commons
382 | public licenses is dedicated to the public domain under the CC0 Public
383 | Domain Dedication. Except for the limited purpose of indicating that
384 | material is shared under a Creative Commons public license or as
385 | otherwise permitted by the Creative Commons policies published at
386 | creativecommons.org/policies, Creative Commons does not authorize the
387 | use of the trademark "Creative Commons" or any other trademark or logo
388 | of Creative Commons without its prior written consent including,
389 | without limitation, in connection with any unauthorized modifications
390 | to any of its public licenses or any other arrangements,
391 | understandings, or agreements concerning use of licensed material. For
392 | the avoidance of doubt, this paragraph does not form part of the
393 | public licenses.
394 | 
395 | Creative Commons may be contacted at creativecommons.org.
396 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # GeoZarr-Spec
 2 | 
 3 | GeoZarr Spec aims to provide a geospatial extension to the Zarr specification. Zarr specifies a protocol and format used for storing Zarr arrays, while the present extension defines **conventions** and recommendations for storing **multidimensional georeferenced grid** of geospatial observations (including rasters). 
 4 | 
 5 | The latest Editor's Draft version of OGC GeoZarr Specifications found here in [HTML](https://zarr.dev/geozarr-spec/documents/standard/template/geozarr-spec.html) or [PDF](https://zarr.dev/geozarr-spec/documents/standard/template/geozarr-spec.pdf)
 6 | 
 7 | The following writings aim to introduce the fundamental concepts of geospatial data models and outline the context and motivation underpinning the development of GeoZarr:
 8 | 
 9 | - [Structure Of GeoSpatial Data Systems](https://medium.com/@christophe.noel/structure-of-geospatial-data-ystems-4033d672c222?source=your_stories_page)
10 | - [Geospatial Data Storage Model](https://medium.com/@christophe.noel/geospatial-data-storage-model-d7c3fb895031?source=your_stories_page)
11 | - [Geospatial Data Model Encoding](https://medium.com/@christophe.noel/geospatial-data-model-encoding-1699f4cd5fb9?source=your_stories_page)
12 | - [Geospatial Ecosystems — Scientific vs GIS Communities](https://medium.com/@christophe.noel/geospatial-ecosystems-scientific-vs-gis-communities-324b340bee1a?source=your_stories_page)
13 | - [Motivation for a GeoZarr Unified EO Data Model](https://medium.com/@christophe.noel/motivation-for-a-geozarr-unified-eo-data-model-926dd2bec07a?source=your_stories_page)
14 | 
15 | 
16 | # Meetings Information
17 | The GeoZarr SWG meets monthly with an agenda and notes kept [here](https://hackmd.io/@briannapagan/geozarr-spec-swg).
18 | 
19 | To receive updates about meetings and current efforts, join the Google group by navigating to [https://groups.google.com/u/2/g/geozarr](https://groups.google.com/u/2/g/geozarr) and click "Join this group". 
20 | 
21 | ## Status
22 | 
23 | This specification early drafts (<=v0.4) were created initially by [Spacebel](https://www.spacebel.com/) for the [European Space Agency](https://esa.int) under the [General Support Technology Programme](http://www.esa.int/Enabling_Support/Space_Engineering_Technology/Shaping_the_Future/About_the_General_Support_Technology_Programme_GSTP).
24 | 
25 | **Update 2023-01-20** - This spec is transitioning to community-based development in anticipation of submission as an OGC standard. It has been moved to the `zarr-developers` GitHub organization. Brianna Pagan ([@briannapagan](https://github.com/briannapagan)) has volunteered to coordinate the community development process.
26 | Feedback from users and implementers will be solicited from the community and incorporated into future drafts.
27 | Information about how to get involved in this process will be announced soon/
28 | 
29 | ## Changelog
30 | 
31 | ### v0.4 
32 | 
33 | * Added visual portrayals and symbology (instead of quicklook)
34 | * Specified default multiscale non-projection (pseudo 'Plate Carree')
35 | 
36 | ### v0.3
37 | 
38 | * Refined multiscales metadata (crs and level attributes)
39 | 
40 | ### v0.2
41 | 
42 | * Specified multiscales zoom level str
43 | 
44 | ## Document and Resources
45 | 
46 | Specification [Document](geozarr-spec.md)
47 | 
48 | Demonstration Videos ([Youtube channel](https://youtube.com/playlist?list=PLzPGC4s5HQOPdeLoK1MXK6gEa1x2Az8Dn)):
49 | - Project Presentation (at WGISS-53) [GeoZarr Data Store - Context of the ESA GSTP project](https://youtu.be/NYhh66EstnY)
50 | - Project Presentation (at DAP) [Hyperspectral Data Store and Access Project](https://youtu.be/CfmPppVR-o4)
51 | - Demo: [GeoZarr Visual Portrayals and OpenLayers extension](https://youtu.be/IKURmv6CVGU)
52 | - Demo: [GeoZarr Fast Time Series Plotting](https://youtu.be/Nt1URJqW71o)
53 | - Demo: [GeoZarr Compute and plot NDWI index at runtime](https://youtu.be/UP0DjphdZgM)
54 | - Demo: [GeoZarr Catalogue Integration](https://youtu.be/Nlbo3FJH8lo)
55 | - Demo: [GeoZarr Serverless Visualisation and Pixel-Based Access](https://youtu.be/sKlejJcPKqQ)
56 | - Comparison: [GeoZarr vs COG Performances](https://youtu.be/KGC8mLqlsCs)
57 | - Advanced applications: soon
58 | 
59 | OpenLayers extension prototype: https://github.com/spacebel/geozarr-openlayers 
60 | 
61 | 
62 | 
63 | ## License
64 | 
65 | (CC BY 4.0) : Content in this repository is licensed under a Creative Commons Attribution 4.0 International  license. Licensees may copy, distribute, display, perform and make derivative works and remixes based on it only if they give the author or licensor the credits (attribution). You can find the complete text of this license at http://creativecommons.org/licenses/by/4.0/.
66 | 
67 | GeoZarr was created initially by [Spacebel](https://www.spacebel.com/) for the [European Space Agency](https://esa.int) under the [General Support Technology Programme](http://www.esa.int/Enabling_Support/Space_Engineering_Technology/Shaping_the_Future/About_the_General_Support_Technology_Programme_GSTP).
68 | 


--------------------------------------------------------------------------------
/geozarr-interop-table.md:
--------------------------------------------------------------------------------
 1 | ## GeoZarr Store Support (current spec)
 2 | 
 3 | | Tool | Can write | Can read local storage | Can read HTTP | Can read S3 | Can read Azure Blob | Can read GCS |
 4 | | -------- | ------- | ------- | ------- | ------- | ------- | ------- |
 5 | | GDAL | ？ |  |  |  |  |  |
 6 | | QGIS| ⚠️ | ⚠️ |  | ✅* |  |  |
 7 | | ArcGIS | ✅ | ✅ | | ✅ |  | ✅ |
 8 | | NetCDF Python | ？ | ✅ |  |  |  |  |
 9 | | NCO | ✅ | ✅ |  |  |  |  |
10 | | Panoply | n/a | 🚫 |  |  |  |  |
11 | | Xarray | ✅ | ✅ |  |  |  |  |
12 | 
13 | ## GeoZarr Tool Interoperability (current spec)
14 | 
15 | |Reader →  Writer ↓| GDAL | QGIS | ArcGIS | NetCDF Python | NCO | Panoply | Xarray |
16 | | -------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- |
17 | | GDAL |  |  |  |  |  | n/a |  |
18 | | QGIS |  |  |  |  |  | n/a |  |
19 | | ArcGIS |  |  |  |  |  | n/a | ✅ |
20 | | NetCDF |  |  |  |  |  | n/a |  |
21 | | NCO |  |  |  |  |  | n/a | ✅ |
22 | | Panoply |  |  |  |  |  | n/a |  |
23 | | Xarray | ✅* | ✅ | ✅ | ✅ | ✅ | n/a | ✅ |
24 | 
25 | ## Sample data
26 | netcdf like data (Written with Xarray): http://tinyurl.com/GLDAS-NOAH025-3H
27 | 
28 | https://beta.source.coop/zarr/geozarr-tests/
29 | 
30 | https://github.com/zarr-developers/geozarr-spec/issues/36
31 | 
32 | ## Tools
33 | 
34 | ### GDAL (3.8.3) 
35 | 
36 | 
37 | ### QGIS (3.34.3)
38 | With GDAL (3.8.1) 
39 | 
40 | Can read from local storage, but can't read the CRS.
41 | 
42 | Can read from S3, but extremely slowly.
43 | 
44 | Can write, but with incorrect nodata value and doesn't write multiple variables to a file. 
45 | 
46 | ### ArcGIS (3.2.1) 
47 | 
48 | ### NetCDF Python Library (1.6.2)
49 | Should be able to read from S3, but depends upon configuring the NetCDF C library with [the NCZarr implementation](https://docs.unidata.ucar.edu/nug/current/nczarr_head.html) to read from S3. Attempting to read from S3 triggered this message: `s3 scheme requires that netCDF be configured with –enable-nczarr-s3 option `.
50 | 
51 | ### NCO (5.1.9)
52 | Ticket: https://github.com/zarr-developers/geozarr-spec/issues/40
53 | 
54 | Should be able to read from S3, but depends upon configuring the NetCDF C library with [the NCZarr implementation](https://docs.unidata.ucar.edu/nug/current/nczarr_head.html) to read from S3. Attempting to read from S3 triggered this message: `s3 scheme requires that netCDF be configured with –enable-nczarr-s3 option `.
55 | 
56 | ### Panoply (5.2.9)
57 | 
58 | ### Xarray (2024.1.1)
59 | Can read and write, but only if using GDAL <3.6 or no GDAL. Does not work with GDAL 3.8.
60 | 


--------------------------------------------------------------------------------
/geozarr-spec.md:
--------------------------------------------------------------------------------
  1 | # GeoZarr-spec 0.4
  2 | 
  3 | This document aims to provides a geospatial extension to the Zarr specification (v2). Zarr specifies a protocol and format used for storing Zarr arrays, while the present extension defines **conventions** and recommendations for storing **multidimensional georeferenced grid** of geospatial observations (including rasters). 
  4 | 
  5 | The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
  6 | 
  7 | ## Status
  8 | 
  9 | This specification is an early draft developed in the frame of an European Space Agency (ESA) GSTP. Through the optional General Support Technology Programme (GSTP) ESA, Participating States and Industry work together to convert promising engineering concepts into a broad spectrum of usable products.
 10 | 
 11 | [Change Log](https://github.com/christophenoel/geozarr-spec/wiki)
 12 | 
 13 | ## GeoZarr Classes
 14 | 
 15 | GeoZarr is restricted to geospatial data which conforms to the conceptual class of Dataset as defined below.
 16 | 
 17 | ### GeoZarr DataArray
 18 | 
 19 | A GeoZarr DataArray variable is a **Zarr Array** that provides values of a measured or observed **geospatial phenomena** (possibly indirectly computed using processing). For example, it might provide reflectance values of a captured satellite scene, or it may describe average vegetation index (NDVI) values for defined period of times.
 20 | 
 21 | GeoZarr DataArray variable MUST include the attribute **\_ARRAY_DIMENSIONS which list the dimension names** (this property was first introduced by xarray library).
 22 | 
 23 | 
 24 | ```
 25 | "_ARRAY_DIMENSIONS": [
 26 |         "lat",
 27 |         "lon"
 28 |     ]
 29 | ```    
 30 |     
 31 | ### GeoZarr Coordinates
 32 | 
 33 | GeoZarr Coordinates variable is either a one dimensional **Zarr Array** or an empty **Zarr Array** containing a **grid_mapping** which includes a **GeoTransform**. In both cases, the coordinates **index a dimension** of a GeoZarr DataArray (e.g latitude, longitude, time, wavelength).
 34 | 
 35 | GeoZarr Coordinates variable MUST include the attribute **\_ARRAY_DIMENSIONS equal to the Zarr array name** (e.g. latitude for the latitude Zarr Array).
 36 | 
 37 | ### GeoZarr Auxiliary Data
 38 | 
 39 | GeoZarr Auxiliary variable is empty, one dimensional or multidimensional **Zarr Array** providing auxiliary information.
 40 | 
 41 | GeoZarr Auxiliary variable MUST include the attribute **\_ARRAY_DIMENSIONS set as an empty array**.
 42 | 
 43 | ### GeoZarr Dataset
 44 | 
 45 | GeoZarr Dataset is a root **Zarr Group** which contains a **set of DataArray variables** (observed data), **Coordinates variables**, Auxiliary variables, and optionally children Datasets (located in children Zarr Groups). Dataset MUST contain a **consistent** set of data for which the DataArray variables have aligned dimensions, and share the same coordinates grid using a common spatial projection.
 46 | 
 47 | If multiple Array Variables share heterogeneous dimensions or coordinates, a primary homogeneous set of variables MUST be located at root level, and the other sets declared in children datasets.
 48 | 
 49 | 
 50 | ## GeoZarr Metadata
 51 | 
 52 | GeoZarr Arrays and Coordinates Variables MUST include [Climate and Forecast (CF)](http://cfconventions.org/) attributes (in the .attrs object). The variables MUST include at least:
 53 | 
 54 | * standard_name for all variables
 55 | * grid_mapping (coordinates reference system) for all array variables
 56 | 
 57 | ### Standard Name
 58 | 
 59 | A CF **standard name** is an attribute which identifies the physical quantity of a variable ([table](https://cfconventions.org/Data/cf-standard-names/78/build/cf-standard-name-table.html)). 
 60 | 
 61 | The quantity may describe the observed phenomenon for:
 62 | * a DataArray variable (for example 'surface_bidirectional_reflectance' for optical sensor data)
 63 | * a Coordinate variable
 64 | * an Auxiliary variable
 65 | 
 66 | The following standard names are recommended to describe coordinates variables for dimensions of DataArrays:
 67 | * grid_latitude, grid_longitude (spatial coordinates as degrees)
 68 | * projection_x_coordinate, projection_y_coordinates (spatial coordinates as per projection)
 69 | * sensor_band_identifier (multisptrectal band identifier)
 70 | * radiation_wavelength (hyperspectral wave length)
 71 | * altitude
 72 | * time
 73 | 
 74 | ### Coordinate Reference System
 75 | 
 76 | The **grid_mapping** CF variable defined by the DataArray variable defines the coordinate reference system (CRS) used for the horizontal spatial coordinate values. The grid_mapping value indicates the auxiliary variable that holds all the CF attributes describing the CRS. 
 77 | 
 78 | In GeoZarr, the grid_mapping variable can contain a **GeoTransform** attribute [adopted from the GDAL Raster Data Model](https://gdal.org/user/raster_data_model.html#affine-geotransform). A GeoTransform is six values: `"X_offset X0 X1 Y_offset Y0 Y1 "` encoded as a space delimited string to ensure interoperability with existing software. `X_offset` and `Y_offset` are the grid origin. `X0` and `Y0` are the grid spacing per column. `X1` and `Y1` are the grid spacing per row. In the case of north up, axis aligned images, `X1 = Y0 = 0` and `X0` is pixel width, `Y1` is pixel height, and `X_offset, Y_offset)` is the top left corner of the top left pixel of the raster. The following equations can be used to derive georeferenced cell centers for rows and columns starting at zero. 
 79 | 
 80 | ```
 81 | X_georeference = X_offset + (row + 0.5) * X1 + (column + 0.5) * X0
 82 | Y_georeference = Y_offset + (row + 0.5) * Y1 + (column + 0.5) * Y0 
 83 | ```
 84 | 
 85 | ### Other CF Properties
 86 | 
 87 | All other CF conventions are recommended, in particular the attributes below:
 88 | 
 89 | * add_offset
 90 | * scale_factor
 91 | * units (as per [UDUNITS v2](https://www.unidata.ucar.edu/software/udunits/udunits-2.2.28/udunits2.html))
 92 | 
 93 | ## Multiscales
 94 | 
 95 | A GeoZarr Dataset variable might include multiscales for a set of DataArray variables.  Also known as "overviews", multiscales provide resampled copies of the original data at a coarser resolution. Multiscales of the original data thus always hold less detail. Common use cases for multiscales are fast rendering for visualization purposes and analyzing data at multiple resolutions. 
 96 | 
 97 | ### Multiscales Encoding 
 98 | 
 99 |  Multiscales MUST be encoded in children groups. Data at all scales MUST use the same coordinate reference system and must follow ONE common zoom level strategy. The zoom level strategy is modelled in close alignment to the [OGC Two Dimensional Tile Matrix Set](https://docs.ogc.org/is/17-083r4/17-083r4.html) version 2 and the [Tiled Asset STAC extension](https://github.com/stac-extensions/tiled-assets). Each zoom level is described by a Matrix defining the number, layout, origin and pixel size of included tiles. These tiles MUST correspond to the chunk layout along the two spatial dimensions listed in `_ARRAY_DIMENSIONS` of a given group.
100 |  
101 | * Multiscale group name is the zoom level identifier (e.g. '0').
102 | * Multiscale group contains all DataArrays generated for this specific zoom level. 
103 | * Multiscale chunking is RECOMMENDED to be 256 pixels or 512 pixels for the two spatial dimensions listed in `_ARRAY_DIMENSIONS`.
104 | 
105 | ### Multiscales Metadata
106 | 
107 | If implemented, each DataArray MUST define the 'multiscales' metadata attribute which includes the following fields:
108 | * `tile_matrix_set`
109 | * `tile_matrix_set_limits` (optional)
110 | * `resampling_method`
111 | 
112 | 
113 | #### Tile Matrix Set
114 | Tile Matrix Set can be: 
115 | * the name of a well know tile matrix set. Well known Tile Matrix Sets are listed [here](https://schemas.opengis.net/tms/2.0/json/examples/tilematrixset/).
116 | * the URI of a JSON document describing the Tile Matrix Set following the OGC standard.
117 | * a JSON object describing the Tile Matrix Set following the OGC standard (CamelCase!).
118 | 
119 | Within the Tile Matrix Set
120 | * the Tile Matrix identifier for each zoom level MUST be the relative path to the Zarr group which holds the DataArray variable 
121 | * zoom levels MUST be provided from lowest to highest resolutions
122 | * the `supportedCRS` attribute of the Tile Matrix Set MUST match the crs information defined under **grid_mapping**.
123 | * the tile layout for each Matrix MUST correspond to the chunk layout along the two spatial dimensions listed in `_ARRAY_DIMENSIONS` of the corresponding group.
124 | 
125 | 
126 | #### Tile Matrix Set Limits
127 | Tile Matrix Sets may describe a larger spatial extent and more resolutions than used in the given dataset.
128 | In that case, users MAY specify [Tile Matrix Set Limits](https://docs.ogc.org/is/17-083r4/17-083r4.html#toc21) as described in the OGC standard to define the minimum and a maximum limits of the indices for each TileMatrix that contains actual data. However, the notation for tile matrix set does not the JSON encoding as described in the OGC standard but follows the STAC Tile Asset encoding for better readability.
129 | 
130 | If used, Tile Matrix Set Limits
131 | * MUST list all included zoom levels
132 | * MAY list the min and max rows and columns for each zoom level. If omitted, it is assumed that the entire spatial extent is covered (resulting in higher chunk count of the DataArray).
133 | 
134 | #### Resampling Method
135 | Resampling Method specifies which resampling method is used for generating multiscales. It MUST be one of the following string values. Resampling method MUST be the same across all zoom levels:
136 | * nearest
137 | * bilinear
138 | * cubic
139 | * cubic_spline
140 | * lanczos
141 | * average
142 | * mode
143 | * gauss
144 | * max
145 | * min
146 | * med
147 | * q1
148 | * q3
149 | * sum
150 | * rms
151 | 
152 | ### Multiscale examples
153 | #### Using Well Known Name reference
154 | 
155 | ```diff
156 | (mandatory items in red, optional items in green)
157 | +{
158 | +  "multiscales":
159 | -       { 
160 | -           "tile_matrix_set": "WebMercatorQuad",
161 | -           "resampling_method": "nearest",
162 | -       }
163 | +}
164 | ```
165 | #### Using a URI
166 | 
167 | ```diff
168 | (mandatory items in red, optional items in green)
169 | +{
170 | +  "multiscales":
171 | -       { 
172 | -           "tile_matrix_set": "https://schemas.opengis.net/tms/2.0/json/examples/tilematrixset/WebMercatorQuad.json",
173 | -           "resampling_method": "nearest",
174 | -       }
175 | +}
176 | ```
177 | 
178 | #### Using a JSON object
179 | 
180 | ```diff
181 | (mandatory items in red, optional items in green)
182 | +{
183 | +  "multiscales":
184 | -       { 
185 | -           "tile_matrix_set": {
186 | -               "id": "WebMercatorQuad",
187 | -               "title": "Google Maps Compatible for the World",
188 | -               "uri": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
189 | -               "crs": "http://www.opengis.net/def/crs/EPSG/0/3857",
190 | -               "orderedAxes": [
191 | -                   "X",
192 | -                   "Y"
193 | -               ],
194 | -               "wellKnownScaleSet": "http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible",
195 | -               "tileMatrices": [
196 | -               {
197 | -               "id": "0",
198 | -               "scaleDenominator": 559082264.028717,
199 | -               "cellSize": 156543.033928041,
200 | -               "pointOfOrigin": [
201 | -                   -20037508.3427892,
202 | -                   20037508.3427892
203 | -               ],
204 | -               "tileWidth": 256,
205 | -               "tileHeight": 256,
206 | -               "matrixWidth": 1,
207 | -               "matrixHeight": 1
208 | -               },
209 | -               {
210 | -               "id": "1",
211 | -               "scaleDenominator": 279541132.014358,
212 | -               "cellSize": 78271.5169640204,
213 | -               "pointOfOrigin": [
214 | -                   -20037508.3427892,
215 | -                   20037508.3427892
216 | -               ],
217 | -               "tileWidth": 256,
218 | -               "tileHeight": 256,
219 | -               "matrixWidth": 2,
220 | -               "matrixHeight": 2
221 | -               },
222 | -           }
223 | -           "resampling_method": "nearest",
224 | -       }
225 | +}
226 | ```
227 | #### Setting limits
228 | 
229 | ```diff
230 | (mandatory items in red, optional items in green)
231 | +{
232 | +  "multiscales":
233 | -       { 
234 | -           "tile_matrix_set": "WebMercatorQuad",
235 | +           "tile_matrix_limits: {
236 | -                "0": {},
237 | -                "1": {
238 | +                    "min_tile_col": 0,
239 | +                    "max_tile_col": 0,
240 | +                    "min_tile_row": 0,
241 | +                    "max_tile_row": 0
242 | -                },
243 | -                "2": {
244 | +                    "min_tile_col": 1,
245 | +                    "max_tile_col": 1,
246 | +                    "min_tile_row": 2,
247 | +                    "max_tile_row": 2
248 | -                }
249 | -        },
250 | -           "resampling_method": "nearest",
251 | -       }
252 | +}
253 | ```
254 | 
255 | 
256 | ## Portrayals and Symbology
257 | 
258 | A GeoZarr Dataset variable might define a set of visual portrayals of the geospatial data and define an adequate symbology. The symbology model is based on a simplified schema based on OGC Symbology Encoding Implementation Specification https://www.ogc.org/standards/symbol.
259 | 
260 | * Each portrayal defines a name and a symbology
261 | * Attribute 'channel-selection' MUST define either the RGB channels, or the grey channels to be represented.
262 | * Channel values MUST specify the relative path to the data, and optionally include the group(s), array and index (which can use positional and label-based indexing (see: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html).
263 | * If grey channel is specified, the 'color-map' MAY define the mapping of palette-type raster colors or fixed-numeric pixel values to colors.
264 | 
265 | ```diff
266 | (mandatory items in red, optional items in green)
267 | +{
268 | +  "portrayals": [
269 | -    "name": {
270 | -    "symbology": {
271 | -      "channel-selection": {
272 | +        "red":"B4"
273 | +        "green":"data[3]"
274 | +        "blue":"data['420']"
275 | +        "grey":"data[2]"
276 | -      "colorMap": [
277 | -        "color-map-entry": {
278 | -          "color": "#000000",
279 | +          "label": "0"
280 | -          "quantity": "0" },
281 | -        "color-map-entry": {
282 | -          "color": "#d73027",
283 | +          "label": "50"
284 | -          "quantity": "0.5" }
285 | +         ]
286 | +    }    
287 | +  ]    
288 | +}    
289 | ```
290 | 
291 | ## Rechunking
292 | 
293 | GeoZarr DataArrray MUST specify the paths to the rechunked instance of the data. These duplicates of the data enable optimizing queries on specific dimensions to improve performances (e.g. for requesting time series).
294 | 
295 | The attribute rechunking list the path the the various instances of the data. The corresponding Zarr metadata provides along the rechunked array provides the chunk size and shape.
296 | 
297 | ```diff
298 | (mandatory items in red, optional items in green)
299 | +  "rechunking": [
300 | -    {
301 | -      "path": "rechunk1"
302 | -    },
303 | -    {
304 | -      "path": "rechunk2"
305 | -    }
306 | +  ]
307 | ```
308 | 
309 | ## Use Cases
310 | 
311 | ### Multispectral Data
312 | 
313 | If the optical sensor captures spectral bands for different resolution, it is RECOMMENDED to hold the highest resolution dataset in the root group, and provide the other resolutions in children groups.
314 | 
315 | The spectral band SHOULD be represented as a dimension (not as an array neither a group). For identifying the band it is RECOMMENDED to either:
316 | * Use the STAC Band common name (see https://github.com/stac-extensions/eo/blob/main/README.md#common-band-names)
317 | * Use the mission specific identifier
318 | 
319 | ### Hyperspectral Data
320 | 
321 | The wavelength SHOULD be represented as a dimension.
322 | 
323 | ### Time Series
324 | 
325 | For level 3+ products, time SHOULD be represented as a dimension. 
326 | When the scene temporal instances are not sharing a common coordinate grid , it is RECOMMENDED to project (interpolate) the scenes in a standard geometry.
327 | 
328 | ## License
329 | 
330 | (CC BY 4.0) : Content in this repository is licensed under a Creative Commons Attribution 4.0 International  license. Licensees may copy, distribute, display, perform and make derivative works and remixes based on it only if they give the author or licensor the credits (attribution). You can find the complete text of this license at http://creativecommons.org/licenses/by/4.0/.
331 | 
332 | GeoZarr documentation by Christophe Noël from Spacebel, supported by ScanWorld and other contributors.
333 | 


--------------------------------------------------------------------------------
/geozarr_swg_charter.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en">
  3 | <head>
  4 | <meta charset="utf-8">
  5 | <meta http-equiv="X-UA-Compatible" content="IE=edge">
  6 | <meta name="viewport" content="width=device-width, initial-scale=1.0">
  7 | <meta name="generator" content="Asciidoctor 2.0.18">
  8 | <title>OGC GeoZarr Standards Working Group Charter</title>
  9 | <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
 10 | <style>
 11 | /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
 12 | /* Uncomment the following line when using as a custom stylesheet */
 13 | /* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
 14 | html{font-family:sans-serif;-webkit-text-size-adjust:100%}
 15 | a{background:none}
 16 | a:focus{outline:thin dotted}
 17 | a:active,a:hover{outline:0}
 18 | h1{font-size:2em;margin:.67em 0}
 19 | b,strong{font-weight:bold}
 20 | abbr{font-size:.9em}
 21 | abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
 22 | dfn{font-style:italic}
 23 | hr{height:0}
 24 | mark{background:#ff0;color:#000}
 25 | code,kbd,pre,samp{font-family:monospace;font-size:1em}
 26 | pre{white-space:pre-wrap}
 27 | q{quotes:"\201C" "\201D" "\2018" "\2019"}
 28 | small{font-size:80%}
 29 | sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
 30 | sup{top:-.5em}
 31 | sub{bottom:-.25em}
 32 | img{border:0}
 33 | svg:not(:root){overflow:hidden}
 34 | figure{margin:0}
 35 | audio,video{display:inline-block}
 36 | audio:not([controls]){display:none;height:0}
 37 | fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
 38 | legend{border:0;padding:0}
 39 | button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
 40 | button,input{line-height:normal}
 41 | button,select{text-transform:none}
 42 | button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
 43 | button[disabled],html input[disabled]{cursor:default}
 44 | input[type=checkbox],input[type=radio]{padding:0}
 45 | button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
 46 | textarea{overflow:auto;vertical-align:top}
 47 | table{border-collapse:collapse;border-spacing:0}
 48 | *,::before,::after{box-sizing:border-box}
 49 | html,body{font-size:100%}
 50 | body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
 51 | a:hover{cursor:pointer}
 52 | img,object,embed{max-width:100%;height:auto}
 53 | object,embed{height:100%}
 54 | img{-ms-interpolation-mode:bicubic}
 55 | .left{float:left!important}
 56 | .right{float:right!important}
 57 | .text-left{text-align:left!important}
 58 | .text-right{text-align:right!important}
 59 | .text-center{text-align:center!important}
 60 | .text-justify{text-align:justify!important}
 61 | .hide{display:none}
 62 | img,object,svg{display:inline-block;vertical-align:middle}
 63 | textarea{height:auto;min-height:50px}
 64 | select{width:100%}
 65 | .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
 66 | div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
 67 | a{color:#2156a5;text-decoration:underline;line-height:inherit}
 68 | a:hover,a:focus{color:#1d4b8f}
 69 | a img{border:0}
 70 | p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
 71 | p aside{font-size:.875em;line-height:1.35;font-style:italic}
 72 | h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
 73 | h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
 74 | h1{font-size:2.125em}
 75 | h2{font-size:1.6875em}
 76 | h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
 77 | h4,h5{font-size:1.125em}
 78 | h6{font-size:1em}
 79 | hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
 80 | em,i{font-style:italic;line-height:inherit}
 81 | strong,b{font-weight:bold;line-height:inherit}
 82 | small{font-size:60%;line-height:inherit}
 83 | code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
 84 | ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
 85 | ul,ol{margin-left:1.5em}
 86 | ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
 87 | ul.circle{list-style-type:circle}
 88 | ul.disc{list-style-type:disc}
 89 | ul.square{list-style-type:square}
 90 | ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
 91 | ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
 92 | dl dt{margin-bottom:.3125em;font-weight:bold}
 93 | dl dd{margin-bottom:1.25em}
 94 | blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
 95 | blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
 96 | @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
 97 | h1{font-size:2.75em}
 98 | h2{font-size:2.3125em}
 99 | h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
100 | h4{font-size:1.4375em}}
101 | table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
102 | table thead,table tfoot{background:#f7f8f7}
103 | table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
104 | table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
105 | table tr.even,table tr.alt{background:#f8f8f7}
106 | table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
107 | h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
108 | h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
109 | .center{margin-left:auto;margin-right:auto}
110 | .stretch{width:100%}
111 | .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
112 | .clearfix::after,.float-group::after{clear:both}
113 | :not(pre).nobreak{word-wrap:normal}
114 | :not(pre).nowrap{white-space:nowrap}
115 | :not(pre).pre-wrap{white-space:pre-wrap}
116 | :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
117 | pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
118 | pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
119 | pre>code{display:block}
120 | pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
121 | em em{font-style:normal}
122 | strong strong{font-weight:400}
123 | .keyseq{color:rgba(51,51,51,.8)}
124 | kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
125 | .keyseq kbd:first-child{margin-left:0}
126 | .keyseq kbd:last-child{margin-right:0}
127 | .menuseq,.menuref{color:#000}
128 | .menuseq b:not(.caret),.menuref{font-weight:inherit}
129 | .menuseq{word-spacing:-.02em}
130 | .menuseq b.caret{font-size:1.25em;line-height:.8}
131 | .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
132 | b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
133 | b.button::before{content:"[";padding:0 3px 0 2px}
134 | b.button::after{content:"]";padding:0 2px 0 3px}
135 | p a>code:hover{color:rgba(0,0,0,.9)}
136 | #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
137 | #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
138 | #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
139 | #content{margin-top:1.25em}
140 | #content::before{content:none}
141 | #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
142 | #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
143 | #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
144 | #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
145 | #header .details span:first-child{margin-left:-.125em}
146 | #header .details span.email a{color:rgba(0,0,0,.85)}
147 | #header .details br{display:none}
148 | #header .details br+span::before{content:"\00a0\2013\00a0"}
149 | #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
150 | #header .details br+span#revremark::before{content:"\00a0|\00a0"}
151 | #header #revnumber{text-transform:capitalize}
152 | #header #revnumber::after{content:"\00a0"}
153 | #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
154 | #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
155 | #toc>ul{margin-left:.125em}
156 | #toc ul.sectlevel0>li>a{font-style:italic}
157 | #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
158 | #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
159 | #toc li{line-height:1.3334;margin-top:.3334em}
160 | #toc a{text-decoration:none}
161 | #toc a:active{text-decoration:underline}
162 | #toctitle{color:#7a2518;font-size:1.2em}
163 | @media screen and (min-width:768px){#toctitle{font-size:1.375em}
164 | body.toc2{padding-left:15em;padding-right:0}
165 | #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
166 | #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
167 | #toc.toc2>ul{font-size:.9em;margin-bottom:0}
168 | #toc.toc2 ul ul{margin-left:0;padding-left:1em}
169 | #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
170 | body.toc2.toc-right{padding-left:0;padding-right:15em}
171 | body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
172 | @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
173 | #toc.toc2{width:20em}
174 | #toc.toc2 #toctitle{font-size:1.375em}
175 | #toc.toc2>ul{font-size:.95em}
176 | #toc.toc2 ul ul{padding-left:1.25em}
177 | body.toc2.toc-right{padding-left:0;padding-right:20em}}
178 | #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
179 | #content #toc>:first-child{margin-top:0}
180 | #content #toc>:last-child{margin-bottom:0}
181 | #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
182 | #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
183 | #content{margin-bottom:.625em}
184 | .sect1{padding-bottom:.625em}
185 | @media screen and (min-width:768px){#content{margin-bottom:1.25em}
186 | .sect1{padding-bottom:1.25em}}
187 | .sect1:last-child{padding-bottom:0}
188 | .sect1+.sect1{border-top:1px solid #e7e7e9}
189 | #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
190 | #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
191 | #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
192 | #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
193 | #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
194 | details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
195 | details{margin-left:1.25rem}
196 | details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
197 | details>summary::-webkit-details-marker{display:none}
198 | details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
199 | details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
200 | details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
201 | .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
202 | table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
203 | .paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
204 | .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
205 | .admonitionblock>table td.icon{text-align:center;width:80px}
206 | .admonitionblock>table td.icon img{max-width:none}
207 | .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
208 | .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
209 | .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
210 | .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
211 | .exampleblock>.content>:first-child{margin-top:0}
212 | .exampleblock>.content>:last-child{margin-bottom:0}
213 | .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
214 | .sidebarblock>:first-child{margin-top:0}
215 | .sidebarblock>:last-child{margin-bottom:0}
216 | .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
217 | .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
218 | .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
219 | @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
220 | @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
221 | .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
222 | .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
223 | .listingblock>.content{position:relative}
224 | .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
225 | .listingblock:hover code[data-lang]::before{display:block}
226 | .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
227 | .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
228 | .listingblock pre.highlightjs{padding:0}
229 | .listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
230 | .listingblock pre.prettyprint{border-width:0}
231 | .prettyprint{background:#f7f7f8}
232 | pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
233 | pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
234 | pre.prettyprint li code[data-lang]::before{opacity:1}
235 | pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
236 | table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
237 | table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
238 | table.linenotable td.code{padding-left:.75em}
239 | table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
240 | pre.pygments span.linenos{display:inline-block;margin-right:.75em}
241 | .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
242 | .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
243 | .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
244 | .quoteblock blockquote{margin:0;padding:0;border:0}
245 | .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
246 | .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
247 | .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
248 | .verseblock{margin:0 1em 1.25em}
249 | .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
250 | .verseblock pre strong{font-weight:400}
251 | .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
252 | .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
253 | .quoteblock .attribution br,.verseblock .attribution br{display:none}
254 | .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
255 | .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
256 | .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
257 | .quoteblock.abstract{margin:0 1em 1.25em;display:block}
258 | .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
259 | .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
260 | .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
261 | .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
262 | .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
263 | p.tableblock:last-child{margin-bottom:0}
264 | td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
265 | td.tableblock>.content>:last-child{margin-bottom:-1.25em}
266 | table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
267 | table.grid-all>*>tr>*{border-width:1px}
268 | table.grid-cols>*>tr>*{border-width:0 1px}
269 | table.grid-rows>*>tr>*{border-width:1px 0}
270 | table.frame-all{border-width:1px}
271 | table.frame-ends{border-width:1px 0}
272 | table.frame-sides{border-width:0 1px}
273 | table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
274 | table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
275 | table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
276 | table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
277 | table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
278 | th.halign-left,td.halign-left{text-align:left}
279 | th.halign-right,td.halign-right{text-align:right}
280 | th.halign-center,td.halign-center{text-align:center}
281 | th.valign-top,td.valign-top{vertical-align:top}
282 | th.valign-bottom,td.valign-bottom{vertical-align:bottom}
283 | th.valign-middle,td.valign-middle{vertical-align:middle}
284 | table thead th,table tfoot th{font-weight:bold}
285 | tbody tr th{background:#f7f8f7}
286 | tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
287 | p.tableblock>code:only-child{background:none;padding:0}
288 | p.tableblock{font-size:1em}
289 | ol{margin-left:1.75em}
290 | ul li ol{margin-left:1.5em}
291 | dl dd{margin-left:1.125em}
292 | dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
293 | li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
294 | ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
295 | ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
296 | ul.unstyled,ol.unstyled{margin-left:0}
297 | li>p:empty:only-child::before{content:"";display:inline-block}
298 | ul.checklist>li>p:first-child{margin-left:-1em}
299 | ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
300 | ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
301 | ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
302 | ul.inline>li{margin-left:1.25em}
303 | .unstyled dl dt{font-weight:400;font-style:normal}
304 | ol.arabic{list-style-type:decimal}
305 | ol.decimal{list-style-type:decimal-leading-zero}
306 | ol.loweralpha{list-style-type:lower-alpha}
307 | ol.upperalpha{list-style-type:upper-alpha}
308 | ol.lowerroman{list-style-type:lower-roman}
309 | ol.upperroman{list-style-type:upper-roman}
310 | ol.lowergreek{list-style-type:lower-greek}
311 | .hdlist>table,.colist>table{border:0;background:none}
312 | .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
313 | td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
314 | td.hdlist1{font-weight:bold;padding-bottom:1.25em}
315 | td.hdlist2{word-wrap:anywhere}
316 | .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
317 | .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
318 | .colist td:not([class]):first-child img{max-width:none}
319 | .colist td:not([class]):last-child{padding:.25em 0}
320 | .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
321 | .imageblock.left{margin:.25em .625em 1.25em 0}
322 | .imageblock.right{margin:.25em 0 1.25em .625em}
323 | .imageblock>.title{margin-bottom:0}
324 | .imageblock.thumb,.imageblock.th{border-width:6px}
325 | .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
326 | .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
327 | .image.left{margin-right:.625em}
328 | .image.right{margin-left:.625em}
329 | a.image{text-decoration:none;display:inline-block}
330 | a.image object{pointer-events:none}
331 | sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
332 | sup.footnote a,sup.footnoteref a{text-decoration:none}
333 | sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
334 | #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
335 | #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
336 | #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
337 | #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
338 | #footnotes .footnote:last-of-type{margin-bottom:0}
339 | #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
340 | div.unbreakable{page-break-inside:avoid}
341 | .big{font-size:larger}
342 | .small{font-size:smaller}
343 | .underline{text-decoration:underline}
344 | .overline{text-decoration:overline}
345 | .line-through{text-decoration:line-through}
346 | .aqua{color:#00bfbf}
347 | .aqua-background{background:#00fafa}
348 | .black{color:#000}
349 | .black-background{background:#000}
350 | .blue{color:#0000bf}
351 | .blue-background{background:#0000fa}
352 | .fuchsia{color:#bf00bf}
353 | .fuchsia-background{background:#fa00fa}
354 | .gray{color:#606060}
355 | .gray-background{background:#7d7d7d}
356 | .green{color:#006000}
357 | .green-background{background:#007d00}
358 | .lime{color:#00bf00}
359 | .lime-background{background:#00fa00}
360 | .maroon{color:#600000}
361 | .maroon-background{background:#7d0000}
362 | .navy{color:#000060}
363 | .navy-background{background:#00007d}
364 | .olive{color:#606000}
365 | .olive-background{background:#7d7d00}
366 | .purple{color:#600060}
367 | .purple-background{background:#7d007d}
368 | .red{color:#bf0000}
369 | .red-background{background:#fa0000}
370 | .silver{color:#909090}
371 | .silver-background{background:#bcbcbc}
372 | .teal{color:#006060}
373 | .teal-background{background:#007d7d}
374 | .white{color:#bfbfbf}
375 | .white-background{background:#fafafa}
376 | .yellow{color:#bfbf00}
377 | .yellow-background{background:#fafa00}
378 | span.icon>.fa{cursor:default}
379 | a span.icon>.fa{cursor:inherit}
380 | .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
381 | .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
382 | .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
383 | .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
384 | .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
385 | .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
386 | .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
387 | .conum[data-value] *{color:#fff!important}
388 | .conum[data-value]+b{display:none}
389 | .conum[data-value]::after{content:attr(data-value)}
390 | pre .conum[data-value]{position:relative;top:-.125em}
391 | b.conum *{color:inherit!important}
392 | .conum:not([data-value]):empty{display:none}
393 | dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
394 | h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
395 | p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
396 | p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem}
397 | p{margin-bottom:1.25rem}
398 | .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
399 | .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
400 | .print-only{display:none!important}
401 | @page{margin:1.25cm .75cm}
402 | @media print{*{box-shadow:none!important;text-shadow:none!important}
403 | html{font-size:80%}
404 | a{color:inherit!important;text-decoration:underline!important}
405 | a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
406 | a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
407 | abbr[title]{border-bottom:1px dotted}
408 | abbr[title]::after{content:" (" attr(title) ")"}
409 | pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
410 | thead{display:table-header-group}
411 | svg{max-width:100%}
412 | p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
413 | h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
414 | #header,#content,#footnotes,#footer{max-width:none}
415 | #toc,.sidebarblock,.exampleblock>.content{background:none!important}
416 | #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
417 | body.book #header{text-align:center}
418 | body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
419 | body.book #header .details{border:0!important;display:block;padding:0!important}
420 | body.book #header .details span:first-child{margin-left:0!important}
421 | body.book #header .details br{display:block}
422 | body.book #header .details br+span::before{content:none!important}
423 | body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
424 | body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
425 | .listingblock code[data-lang]::before{display:block}
426 | #footer{padding:0 .9375em}
427 | .hide-on-print{display:none!important}
428 | .print-only{display:block!important}
429 | .hide-for-print{display:none!important}
430 | .show-for-print{display:inherit!important}}
431 | @media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
432 | .sect1{padding:0!important}
433 | .sect1+.sect1{border:0}
434 | #footer{background:none}
435 | #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
436 | @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
437 | </style>
438 | </head>
439 | <body class="book">
440 | <div id="header">
441 | </div>
442 | <div id="content">
443 | <div id="preamble">
444 | <div class="sectionbody">
445 | <div style="page-break-after: always;"></div>
446 | <table class="tableblock frame-none grid-none stretch">
447 | <colgroup>
448 | <col style="width: 100%;">
449 | </colgroup>
450 | <tbody>
451 | <tr>
452 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"></td>
453 | </tr>
454 | <tr>
455 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"><p class="tableblock"><strong class="big">Open Geospatial Consortium</strong></p></td>
456 | </tr>
457 | <tr>
458 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Submission Date: 2023-05-01</p></td>
459 | </tr>
460 | <tr>
461 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Approval Date: 2023-12-04</p></td>
462 | </tr>
463 | <tr>
464 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Internal reference number of this OGC&#174; document: 23-046</p></td>
465 | </tr>
466 | <tr>
467 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Category: OGC&#174; Standards Working Group Charter</p></td>
468 | </tr>
469 | <tr>
470 | <td class="tableblock halign-right valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Authors: Christophe Noel, Brianna R. Pagán</p></td>
471 | </tr>
472 | </tbody>
473 | </table>
474 | <table class="tableblock frame-none grid-all stretch">
475 | <colgroup>
476 | <col style="width: 100%;">
477 | </colgroup>
478 | <tbody>
479 | <tr>
480 | <td class="tableblock halign-center valign-top" style="background-color: #FFFFFF;"><p class="tableblock"><strong class="big">OGC GeoZarr Standards Working Group Charter</strong></p></td>
481 | </tr>
482 | </tbody>
483 | </table>
484 | <table class="tableblock frame-none grid-none stretch">
485 | <colgroup>
486 | <col style="width: 100%;">
487 | </colgroup>
488 | <tbody>
489 | <tr>
490 | <td class="tableblock halign-center valign-top" style="background-color: #FFFFFF;"><p class="tableblock"><strong>Copyright notice</strong></p></td>
491 | </tr>
492 | <tr>
493 | <td class="tableblock halign-center valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Copyright &#169; 2023 Open Geospatial Consortium</p></td>
494 | </tr>
495 | <tr>
496 | <td class="tableblock halign-center valign-top" style="background-color: #FFFFFF;"><p class="tableblock">To obtain additional rights of use, visit <a href="http://www.opengeospatial.org/legal/" class="bare">http://www.opengeospatial.org/legal/</a></p></td>
497 | </tr>
498 | </tbody>
499 | </table>
500 | <div style="page-break-after: always;"></div>
501 | <div class="paragraph">
502 | <p>To: OGC members &amp; interested parties</p>
503 | </div>
504 | <div class="paragraph">
505 | <p>A new OGC Standards Working Group (SWG) is being formed. The OGC members listed below have proposed the OGC GeoZarr SWG.  The SWG proposal provided in this document meets the requirements of the OGC Technical Committee (TC) Policies and Procedures.</p>
506 | </div>
507 | <div class="paragraph">
508 | <p>The SWG name, statement of purpose, scope, list of deliverables, audience, and language specified in the proposal will constitute the SWG&#8217;s official charter. Technical discussions may occur no sooner than the SWG&#8217;s first meeting.</p>
509 | </div>
510 | <div class="paragraph">
511 | <p>This SWG will operate under the OGC IPR Policy. The eligibility requirements for becoming a participant in the SWG at the first meeting (see details below) are that:</p>
512 | </div>
513 | <div class="ulist">
514 | <ul>
515 | <li>
516 | <p>You must be an employee of an OGC member organization or an individual
517 | member of OGC;</p>
518 | </li>
519 | <li>
520 | <p>The OGC member must have signed the OGC Membership agreement;</p>
521 | </li>
522 | <li>
523 | <p>You must notify the SWG chair of your intent to participate to the first meeting. Members may do so by logging onto the OGC Portal and navigating to the Observer page and clicking on the link for the SWG they wish to join and;</p>
524 | </li>
525 | <li>
526 | <p>You must attend meetings of the SWG. The first meeting of this SWG is at the time and date fixed below. Attendance may be by teleconference.</p>
527 | </li>
528 | </ul>
529 | </div>
530 | <div class="paragraph">
531 | <p>Of course, participants also may join the SWG at any time. The OGC and the SWG welcomes all interested parties.</p>
532 | </div>
533 | <div class="paragraph">
534 | <p>Non-OGC members who wish to participate may contact us about joining the OGC. In addition, the public may access some of the resources maintained for each SWG: the SWG public description, the SWG Charter, Change Requests, and public comments, which will be linked from the SWG’s page.</p>
535 | </div>
536 | <div class="paragraph">
537 | <p>Please feel free to forward this announcement to any other appropriate lists. The OGC is an open standards organization; we encourage your feedback.</p>
538 | </div>
539 | </div>
540 | </div>
541 | <div class="sect1">
542 | <h2 id="_purpose_of_the_standards_working_group"><a class="anchor" href="#_purpose_of_the_standards_working_group"></a>1. Purpose of the Standards Working Group</h2>
543 | <div class="sectionbody">
544 | <div class="paragraph">
545 | <p>The GeoZarr Standard Working Group (SWG) is chartered to develop a Zarr encoding for geospatial gridded data in the form of Zarr conventions (based on the approach described in the draft Zarr Enhancement Proposal 4).  Zarr specifies a protocol and format used for storing Zarr arrays, while GeoZarr defines <strong>conventions</strong> and recommendations for storing <strong>multidimensional georeferenced grid</strong> of geospatial observations (including rasters). If appropriate, the GeoZarr SWG may also contribute to the Climate and Forecast (CF) conventions (e.g. alternative CRS encoding) by proposing changes based on the [CF community governance process](<a href="https://cfconventions.org/governance.html" class="bare">https://cfconventions.org/governance.html</a>).</p>
546 | </div>
547 | </div>
548 | </div>
549 | <div class="sect1">
550 | <h2 id="_business_value_proposition"><a class="anchor" href="#_business_value_proposition"></a>2. Business Value Proposition</h2>
551 | <div class="sectionbody">
552 | <div class="paragraph">
553 | <p>In the geospatial world, new cloud-native data formats are emerging. Zarr is a generic data format for n-dimensional arrays that enables access to data in compressed chunks of the original array and has become increasingly popular to use for geospatial purposes. Zarr facilitates portability and interoperability on both object stores and hard disks. In June 2022, the OGC endorsed a community standard of Zarr V2.0 (<a href="https://zarr.readthedocs.io/en/stable/spec/v2.html" class="bare">https://zarr.readthedocs.io/en/stable/spec/v2.html</a>). The purpose of this charter is to adopt a more explicit GeoZarr as an OGC Standard which would provide guidance to standardize the approach for encoding various aspects of geospatial data in zarrs.</p>
554 | </div>
555 | </div>
556 | </div>
557 | <div class="sect1">
558 | <h2 id="_scope_of_work"><a class="anchor" href="#_scope_of_work"></a>3. Scope of Work</h2>
559 | <div class="sectionbody">
560 | <div class="paragraph">
561 | <p>The goal of the GeoZarr specification is to establish flexible and inclusive conventions for the Zarr cloud-native format, specifically designed to meet the diverse requirements within the geospatial domain. These conventions aim to provide a clear and standardized framework for organizing and describing data, ensuring unambiguous representation.</p>
562 | </div>
563 | <div class="paragraph">
564 | <p>In addition to the encoding geospatial data and metadata using Zarr, the specification will aim to to provide a multidimensional alternative to the two-dimensional Cloud-Optimized GeoTiff format which has gained popularity due to its serverless capabilities. These capabilities allow for inherent support of traditionally server-based functions, including visualization (similar to OGC API Maps), data subset access (analogous to OGC API Coverages), and symbology (equivalent to OGC API Styles). These aspects are planned to be incorporated as optional profiles (e.g. conformance classes).</p>
565 | </div>
566 | <div class="paragraph">
567 | <p>The objectives of GeoZarr conventions includes:</p>
568 | </div>
569 | <div class="olist arabic">
570 | <ol class="arabic">
571 | <li>
572 | <p>Compatibility: Ensuring easy compatibility with popular mapping and data analysis tools such as GDAL, Xarray, ArcGIS, QGIS, and other visualisation tools, enabling seamless integration into existing workflows.</p>
573 | </li>
574 | <li>
575 | <p>Dimensions: Supporting multidimensional data, such as hyperspectral and altitude information, to address diverse geospatial data requirements.</p>
576 | </li>
577 | <li>
578 | <p>Data Discovery: Providing metadata for discovering, accessing, and retrieving the data, including composite products made of multiple data arrays.</p>
579 | </li>
580 | <li>
581 | <p>Mixing Data: Facilitating the combination of different types of geospatial data, including satellite images, elevation maps, and weather models, to create comprehensive and informative datasets.</p>
582 | </li>
583 | <li>
584 | <p>Flexibilty: Allowing scientists and researchers to work with diverse data types and projections in their preferred software and programming languages, promoting flexibility and adaptability in geospatial data processing and analysis.</p>
585 | </li>
586 | </ol>
587 | </div>
588 | <div class="paragraph">
589 | <p>Specifically, the convention should provide guidance to standardize the approach for encoding various aspects of geospatial data, including, for example the following list of potential conformance classes:</p>
590 | </div>
591 | <div class="ulist">
592 | <ul>
593 | <li>
594 | <p>Multiple related variables with heterogeneous coordinates (e.g., children or linked datasets)</p>
595 | </li>
596 | <li>
597 | <p>Multiple resolutions of the data, possibly leveraging multiscale array representations</p>
598 | </li>
599 | <li>
600 | <p>Data subsets that are only available at certain resolutions</p>
601 | </li>
602 | <li>
603 | <p>Multi-dimensional optimizations (spatial chunking scheme, temporal chunking scheme)</p>
604 | </li>
605 | <li>
606 | <p>Supporting typical Earth observation (EO) products (for example, how to encode multispectral bands)</p>
607 | </li>
608 | <li>
609 | <p>Accessing the symbology of the corresponding data</p>
610 | </li>
611 | </ul>
612 | </div>
613 | <div class="paragraph">
614 | <p>Part of the effort of this working group is to determine what should be kept as a part of the GeoZarr core requirements, and what aspects of geospatial data should be kept as separate conformance classes, which may or may not be applicable to specific sub-domains of the geospatial community.</p>
615 | </div>
616 | <div class="sect2">
617 | <h3 id="_statement_of_relationship_of_planned_work_to_the_current_ogc_standards_baseline"><a class="anchor" href="#_statement_of_relationship_of_planned_work_to_the_current_ogc_standards_baseline"></a>3.1. Statement of relationship of planned work to the current OGC standards baseline</h3>
618 | <div class="paragraph">
619 | <p>As the existing draft GeoZarr metadata utilizes Climate and Forecast (CF) attributes, there is an expected relationship with the OGC CF-netCDF Data Model Extension Standard and the OGC netCDF SWG. If necessary, any adjustments or enhancements required for the GeoZarr specification will be considered as a proposal to improve CF conventions as well.
620 | There are strong connections to other OGC raster / array container standards, specifically NetCDF, HDF5, and GeoTiff. The GeoZarr SWG should seek to leverage existing metadata conventions wherever possible.</p>
621 | </div>
622 | <div class="paragraph">
623 | <p>As a chunked storage format, there is potentially a strong connection to the <code>OGC API - Tiles</code> standard. Map tiles could essentially be mapped 1:1 to an appropriately defined multiscale Zarr array.</p>
624 | </div>
625 | </div>
626 | <div class="sect2">
627 | <h3 id="_what_is_out_of_scope"><a class="anchor" href="#_what_is_out_of_scope"></a>3.2. What is Out of Scope?</h3>
628 | <div class="paragraph">
629 | <p>In early conversations around creating a draft GeoZarr specification, concerns arose multiple times around the CF encoding of CRS which may pose issues, see <a href="https://github.com/zarr-developers/geozarr-spec/issues/20" class="bare">https://github.com/zarr-developers/geozarr-spec/issues/20</a>. While these concerns will be discussed and suggestions created for potentially updating CF conventions, if resolutions cannot be made with the GeoZarr specification, we consider out of scope waiting on any subsequent updates to CF conventions to reflect these suggestions.</p>
630 | </div>
631 | </div>
632 | <div class="sect2">
633 | <h3 id="_specific_existing_work_used_as_starting_point"><a class="anchor" href="#_specific_existing_work_used_as_starting_point"></a>3.3. Specific Existing Work Used as Starting Point</h3>
634 | <div class="ulist">
635 | <ul>
636 | <li>
637 | <p>GeoZarr draft specification: <a href="https://github.com/zarr-developers/geozarr-spec/" class="bare">https://github.com/zarr-developers/geozarr-spec/</a></p>
638 | </li>
639 | </ul>
640 | </div>
641 | </div>
642 | <div class="sect2">
643 | <h3 id="_is_this_a_persistent_swg"><a class="anchor" href="#_is_this_a_persistent_swg"></a>3.4. Is This a Persistent SWG</h3>
644 | <div class="paragraph">
645 | <p>[x] YES</p>
646 | </div>
647 | <div class="paragraph">
648 | <p>[ ] NO</p>
649 | </div>
650 | </div>
651 | <div class="sect2">
652 | <h3 id="_when_can_the_swg_be_inactivated"><a class="anchor" href="#_when_can_the_swg_be_inactivated"></a>3.5. When can the SWG be Inactivated</h3>
653 | <div class="paragraph">
654 | <p>The SWG can be inactivated once the SWG identifies no new tasks for the SWG and there are no open Change Requests.</p>
655 | </div>
656 | </div>
657 | </div>
658 | </div>
659 | <div class="sect1">
660 | <h2 id="_description_of_deliverables"><a class="anchor" href="#_description_of_deliverables"></a>4. Description of deliverables</h2>
661 | <div class="sectionbody">
662 | <div class="paragraph">
663 | <p>The GeoZarr SWG will deliver a candidate Standard and associated developer resources.</p>
664 | </div>
665 | <div class="paragraph">
666 | <p>The SWG expects to have a candidate Standard ready for OGC Architecture Board (OAB) review and public comment within nine months of creation of the SWG. Because example implementations will be developed at the same time the candidate Standard is formalized, reference implementations that fully use GeoZarr should be documented at the same time the candidate Standard goes to vote.</p>
667 | </div>
668 | <div class="sect2">
669 | <h3 id="_initial_deliverables"><a class="anchor" href="#_initial_deliverables"></a>4.1. Initial Deliverables</h3>
670 | <div class="paragraph">
671 | <p>The following deliverables will be the initial results of work of the SWG.</p>
672 | </div>
673 | <div class="ulist">
674 | <ul>
675 | <li>
676 | <p>OGC GeoZarr Standard</p>
677 | </li>
678 | <li>
679 | <p>GeoZarr developer resources</p>
680 | </li>
681 | </ul>
682 | </div>
683 | <div class="paragraph">
684 | <p>The targeted start date for this SWG immediately upon approval of the SWG charter.</p>
685 | </div>
686 | </div>
687 | <div class="sect2">
688 | <h3 id="_additional_swg_tasks"><a class="anchor" href="#_additional_swg_tasks"></a>4.2. Additional SWG Tasks</h3>
689 | <div class="paragraph">
690 | <p>No specific additional tasks are currently planned for the SWG.</p>
691 | </div>
692 | </div>
693 | </div>
694 | </div>
695 | <div class="sect1">
696 | <h2 id="_ipr_policy_for_this_swg"><a class="anchor" href="#_ipr_policy_for_this_swg"></a>5. IPR Policy for this SWG</h2>
697 | <div class="sectionbody">
698 | <div class="paragraph">
699 | <p>[x] RAND-Royalty Free</p>
700 | </div>
701 | <div class="paragraph">
702 | <p>[ ] RAND for fee</p>
703 | </div>
704 | </div>
705 | </div>
706 | <div class="sect1">
707 | <h2 id="_anticipated_audience_participants"><a class="anchor" href="#_anticipated_audience_participants"></a>6. Anticipated Audience / Participants</h2>
708 | <div class="sectionbody">
709 | <div class="paragraph">
710 | <p>This SWG will develop a Standard for general use in the geospatial community and suitable for data exchange beyond this community. Geospatial data providers and software implementers will be interested in assisting with the development of this Standard as well as the output of the SWG.</p>
711 | </div>
712 | </div>
713 | </div>
714 | <div class="sect1">
715 | <h2 id="_domain_working_group_endorsement"><a class="anchor" href="#_domain_working_group_endorsement"></a>7. Domain Working Group Endorsement</h2>
716 | <div class="sectionbody">
717 | <div class="paragraph">
718 | <p>The SWG convenors will discuss the charter with potentially interested Domain Working Groups (DWGs) at the first opportunity.</p>
719 | </div>
720 | </div>
721 | </div>
722 | <div class="sect1">
723 | <h2 id="_other_informative_information_about_the_work_of_this_swg"><a class="anchor" href="#_other_informative_information_about_the_work_of_this_swg"></a>8. Other informative information about the work of this SWG</h2>
724 | <div class="sectionbody">
725 | <div class="sect2">
726 | <h3 id="_collaboration"><a class="anchor" href="#_collaboration"></a>8.1. Collaboration</h3>
727 | <div class="paragraph">
728 | <p>All work in the Standards Working Group will be public and the SWG solicits contributions and feedback from OGC members and non-OGC members to the extent that is supported by the OGC Technical Committee Policies and Procedures.</p>
729 | </div>
730 | <div class="paragraph">
731 | <p>The OGC GeoZarr SWG will collaborate on Standard development using a public GitHub repository and a Gitter channel. Development of the Standard will include the use of Issues and other project tools in GitHub.</p>
732 | </div>
733 | </div>
734 | <div class="sect2">
735 | <h3 id="_similar_or_applicable_standards_work_ogc_and_elsewhere"><a class="anchor" href="#_similar_or_applicable_standards_work_ogc_and_elsewhere"></a>8.2. Similar or Applicable Standards Work (OGC and Elsewhere)</h3>
736 | <div class="ulist">
737 | <ul>
738 | <li>
739 | <p>The OGC endorsed a community standard of Zarr V2.0 (<a href="https://zarr.readthedocs.io/en/stable/spec/v2.html" class="bare">https://zarr.readthedocs.io/en/stable/spec/v2.html</a>) in June 2022.</p>
740 | </li>
741 | <li>
742 | <p>This SWG is closely related to the newly announced [Geodatacube SWG](<a href="https://www.ogc.org/press-release/ogc-forms-new-geodatacube-standards-working-group/" class="bare">https://www.ogc.org/press-release/ogc-forms-new-geodatacube-standards-working-group/</a>). Essentially, Geodatacube will specify a server API while GeoZarr can define a standard Cloud-native format for a serverless datacube. Therefore, close coordination between these SWGs seems needed.</p>
743 | </li>
744 | <li>
745 | <p>The XCube project has potential synergies with the GeoZarr specification as it already relies and complies with CF conventions:</p>
746 | </li>
747 | <li>
748 | <p>xcube Dataset Convention: <a href="https://github.com/dcs4cop/xcube/blob/master/docs/source/cubespec.md" class="bare">https://github.com/dcs4cop/xcube/blob/master/docs/source/cubespec.md</a></p>
749 | </li>
750 | <li>
751 | <p>xcube Multi-Resolution Datasets: <a href="https://github.com/dcs4cop/xcube/blob/master/docs/source/mldatasets.md" class="bare">https://github.com/dcs4cop/xcube/blob/master/docs/source/mldatasets.md</a></p>
752 | </li>
753 | </ul>
754 | </div>
755 | </div>
756 | <div class="sect2">
757 | <h3 id="_details_of_first_meeting"><a class="anchor" href="#_details_of_first_meeting"></a>8.3. Details of first meeting</h3>
758 | <div class="paragraph">
759 | <p>The first meeting of the SWG will occur within four weeks of approval of the SWG charter.</p>
760 | </div>
761 | </div>
762 | <div class="sect2">
763 | <h3 id="_projected_on_going_meeting_schedule"><a class="anchor" href="#_projected_on_going_meeting_schedule"></a>8.4. Projected on-going meeting schedule</h3>
764 | <div class="paragraph">
765 | <p>The work of this SWG will be carried out primarily on GitHub and via email, web conferences / calls, and at face-to-face sessions at OGC Member Meetings as agreed to by the SWG members. The web conferences / calls will be scheduled as needed and posted to the OGC portal. Voting on OGC GeoZarr Conventions content will be limited to SWG members only.</p>
766 | </div>
767 | </div>
768 | <div class="sect2">
769 | <h3 id="_supporters_of_this_charter"><a class="anchor" href="#_supporters_of_this_charter"></a>8.5. Supporters of this Charter</h3>
770 | <div class="paragraph">
771 | <p>The following people support this proposal and are committed to the Charter and projected meeting schedule. These members are known as SWG Founding or Charter members. The charter members agree to the SoW and IPR terms as defined in this charter. The charter members have voting rights beginning the day the SWG is officially formed. Charter Members are shown on the public SWG page.</p>
772 | </div>
773 | <table class="tableblock frame-all grid-all stretch">
774 | <colgroup>
775 | <col style="width: 50%;">
776 | <col style="width: 50%;">
777 | </colgroup>
778 | <thead>
779 | <tr>
780 | <th class="tableblock halign-left valign-top" style="background-color: #FFFFFF;">Name</th>
781 | <th class="tableblock halign-left valign-top" style="background-color: #FFFFFF;">Organization</th>
782 | </tr>
783 | </thead>
784 | <tbody>
785 | <tr>
786 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Christophe Noel</p></td>
787 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Spacebel</p></td>
788 | </tr>
789 | <tr>
790 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Brianna R. Pagán</p></td>
791 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">NASA GES DISC</p></td>
792 | </tr>
793 | <tr>
794 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Alexey N. Shiklomanov</p></td>
795 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">NASA Goddard Space Flight Center</p></td>
796 | </tr>
797 | <tr>
798 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">Tyler A. Erickson</p></td>
799 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">VorGeo</p></td>
800 | </tr>
801 | <tr>
802 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">David Blodgett</p></td>
803 | <td class="tableblock halign-left valign-top" style="background-color: #FFFFFF;"><p class="tableblock">U.S. Geological Survey</p></td>
804 | </tr>
805 | </tbody>
806 | </table>
807 | </div>
808 | <div class="sect2">
809 | <h3 id="_conveners"><a class="anchor" href="#_conveners"></a>8.6. Conveners</h3>
810 | <div class="paragraph">
811 | <p>xxx</p>
812 | </div>
813 | </div>
814 | </div>
815 | </div>
816 | <div class="sect1">
817 | <h2 id="_references"><a class="anchor" href="#_references"></a>References</h2>
818 | <div class="sectionbody">
819 | <div class="ulist bibliography">
820 | <ul class="bibliography">
821 | <li>
822 | <p><a id="gj"></a>[1] IETF: IETF RFC 7946, The GeoJSON Format, 2016
823 | [<a id="gj"></a>] Zarr Enhancement Proposal 4 preparation, <a href="https://github.com/zarr-developers/zeps/pull/28" class="bare">https://github.com/zarr-developers/zeps/pull/28</a></p>
824 | </li>
825 | </ul>
826 | </div>
827 | </div>
828 | </div>
829 | </div>
830 | <div id="footer">
831 | <div id="footer-text">
832 | Last updated 2023-12-19 15:48:15 -0700
833 | </div>
834 | </div>
835 | </body>
836 | </html>


--------------------------------------------------------------------------------
/standard/README.md:
--------------------------------------------------------------------------------
 1 | # Standard template
 2 | 
 3 | OGC uses [Metanorma](https://www.metanorma.org) software for creating Standards documents.
 4 | 
 5 | You can compile documents using either a local installation of Metanorma or optionally a docker-containerized instance of Metanorma.
 6 | 
 7 | ## Using Metanorma from a local installation
 8 | 
 9 | ### Pre-requisite
10 | 
11 | Confirm that you have Metanorma installed locally on your operating system. If you do not have Metanorma installed, follow the steps at the [Metanorma website](https://www.metanorma.org/install/) to install it.
12 | 
13 | ### Getting the Templates
14 | 
15 | **Step 1**. Obtain the template for a Draft OGC Standard from the `template` sub-folder.
16 | 
17 | ### Editing a Draft OGC Standard for compilation with Metanorma
18 | 
19 | Now that you have obtained a copy of the template, you can edit the document. The following steps assume that you have read the **authoring guidelines** are at https://www.metanorma.org/author/ogc/authoring-guide/
20 | 
21 | **Step 2**. Next, edit the asciidoc file `document.adoc` by filling the document properties: `docsubtype`, `status`, `abbrev`, `edition` (i.e. version of the document), `docnumber` (OGC Document Number), `keywords`, `fullname` (of the editors).
22 | 
23 | **Step 3**. Ensure that the `doctype` property is set to `standard`.
24 | 
25 | Refer to the authoring guidelines for the complete list of document properties.
26 | 
27 | NOTE: If there are multiple editors, the names of the editors are listed in the sequence `fullname`, `fullname_2`, `fullname_3`,...
28 | 
29 | ### Compiling a Draft OGC Standard with a local Metanorma instance
30 | 
31 | To convert the draft document from asciidoc format to HTML and PDF formats, we use the metanorma software to **compile** the document.
32 | 
33 | **Step 4**. From the folder containing the `document.adoc` file, run the following command.
34 | 
35 | `metanorma compile --agree-to-terms -t ogc -x xml,html,doc document.adoc`
36 | 
37 | NOTE: You need to add this option to retrieve licensed fonts  `--agree-to-terms`
38 | 
39 | ## Using Metanorma from within Docker
40 | 
41 | ### Pre-requisite
42 | 
43 | Confirm that you have docker installed on your operating system. If you do not have docker installed, follow the steps at the [Get Docker page](https://docs.docker.com/get-docker/) to install it.
44 | 
45 | ### Creating a copy of the template
46 | 
47 | The template for Standards documents is organized as a folder of asciidoc files, with nested folders for sections, abstract tests, requirements and other resources.
48 | 
49 | To create a copy of the template, follow these steps.
50 | 
51 | **Step 1**. Pull the latest version of the Metanorma image on to your local docker installation.
52 | 
53 | `docker pull metanorma/metanorma:latest`
54 | 
55 | **Step 2**.  Generate a copy of the template for OGC Standards by running the following command from a terminal (i.e. from the command prompt).
56 | 
57 | `docker run --rm -v "$(pwd)":/metanorma metanorma/metanorma  metanorma new -d standard -t ogc  -l https://github.com/metanorma/metanorma-templates-ogc folder_for_standard`
58 | 
59 | NOTE: The `-d standard -t ogc` flags instruct metanorma that the template is for OGC Standards.
60 | 
61 | NOTE: The `folder_for_standard` value can be replaced with whatever you would like to be the name of the folder that contains the copy of the template.
62 | 
63 | ### Editing a Draft OGC Standard for compilation with Metanorma
64 | 
65 | Now that you have generated a copy of the template, you can edit the document. The following steps assume that you have read the **authoring guidelines** are at https://www.metanorma.org/author/ogc/authoring-guide/
66 | 
67 | **Step 3**. Next, edit the asciidoc file `document.adoc` by filling the document properties: `docsubtype`, `status`, `abbrev`, `edition` (i.e. version of the standard), `docnumber` (OGC Document Number), `keywords`, `fullname` (of the editors).
68 | 
69 | **Step 4**. Ensure that the `doctype` property is set to `standard`.
70 | 
71 | Refer to the authoring guidelines for the complete list of document properties.
72 | 
73 | NOTE: If there are multiple editors, the names of the editors are listed in the sequence `fullname`, `fullname_2`, `fullname_3`,...
74 | 
75 | ### Compiling a Draft OGC Standard with a docker-containerized Metanorma instance
76 | 
77 | To convert the draft standard from asciidoc format to HTML and PDF formats, we use the metanorma software to **compile** the document.
78 | 
79 | **Step 5**. From the folder containing the `document.adoc` file, run the following command.
80 | 
81 | `docker run -v "$(pwd)":/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts  metanorma/metanorma  metanorma compile --agree-to-terms -t ogc -x xml,html,doc document.adoc`
82 | 
83 | NOTE: You need to add this option to retrieve licensed fonts  `--agree-to-terms`
84 | 


--------------------------------------------------------------------------------
/standard/template/.github/workflows/docker.yml:
--------------------------------------------------------------------------------
 1 | # Auto-generated by Cimas: Do not edit it manually!
 2 | # See https://github.com/metanorma/cimas
 3 | name: docker
 4 | 
 5 | on:
 6 |   push:
 7 |     branches: [ master, main ]
 8 |   pull_request:
 9 |     paths-ignore:
10 |       - .gitlab-ci.yml
11 |       - .github/workflows/test.yml
12 |       - .github/workflows/generate.yml
13 |   repository_dispatch:
14 |     types: [ metanorma/metanorma-docker ]
15 | 
16 | jobs:
17 |   test-docker:
18 |     runs-on: ubuntu-latest
19 |     container: docker://metanorma/mn
20 |     steps:
21 |       - uses: actions/checkout@v2
22 |         with:
23 |           token: ${{ secrets.METANORMA_CI_PAT_TOKEN || github.token }}
24 |           submodules: true
25 | 
26 |       - uses: actions/cache@v2
27 |         with:
28 |           path: /config/fonts
29 |           key: fontist-docker
30 |           restore-keys: fontist-docker
31 | 
32 |       - uses: actions/cache@v2
33 |         with:
34 |           path: ~/.metanorma-ietf-workgroup-cache.json
35 |           key: metanorma-ietf-workgroup-cache
36 |           restore-keys: metanorma-ietf-workgroup-cache
37 | 
38 |       - uses: metanorma/metanorma-build-scripts/gh-rubygems-setup-action@master
39 |         with:
40 |           token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}
41 | 
42 |       - run: |
43 |           curl -L --retry 3 https://raw.githubusercontent.com/metanorma/metanorma-build-scripts/master/gemfile-to-bundle-add.sh | bash
44 | 
45 |       - uses: actions-mn/cli/site-gen@main
46 |         with:
47 |           agree-to-terms: true
48 | 
49 |       - uses: actions/upload-artifact@master
50 |         with:
51 |           name: site
52 |           path: site
53 | 
54 |   deploy-gh-pages:
55 |     if: github.ref == 'refs/heads/master'
56 |     runs-on: ubuntu-latest
57 |     needs: test-docker
58 |     steps:
59 |       - uses: actions/checkout@v2
60 | 
61 |       - uses: actions/download-artifact@v1
62 |         with:
63 |           name: site
64 | 
65 |       - uses: peaceiris/actions-gh-pages@v3
66 |         with:
67 |           github_token: ${{ github.token }}
68 |           publish_dir: ./site
69 |           force_orphan: true
70 |           user_name: ${{ github.actor }}
71 |           user_email: ${{ format('{0}@users.noreply.github.com', github.actor) }}
72 |           commit_message: "${{ format('Deploy to GitHub Pages: {0}', github.sha) }}"
73 | 
74 |       - uses: kolpav/purge-artifacts-action@v1
75 |         with:
76 |           token: ${{ github.token }}
77 |           expire-in: 0
78 | 


--------------------------------------------------------------------------------
/standard/template/.github/workflows/generate.yml:
--------------------------------------------------------------------------------
 1 | # Auto-generated by Cimas: Do not edit it manually!
 2 | # See https://github.com/metanorma/cimas
 3 | name: generate
 4 | 
 5 | on:
 6 |   push:
 7 |     branches: [ master, main ]
 8 |   pull_request:
 9 |     paths-ignore:
10 |       - .gitlab-ci.yml
11 |       - .github/workflows/test.yml
12 |       - .github/workflows/docker.yml
13 |   workflow_dispatch:
14 | 
15 | jobs:
16 |   test-linux:
17 |     name: Test on ${{ matrix.os }}
18 |     runs-on: ${{ matrix.os }}
19 |     strategy:
20 |       fail-fast: false
21 |       matrix:
22 |         os: [ ubuntu-latest, windows-latest, macos-latest ]
23 |     steps:
24 |       - uses: actions/checkout@v2
25 |         with:
26 |           token: ${{ secrets.METANORMA_CI_PAT_TOKEN || github.token }}
27 |           submodules: true
28 | 
29 |       - uses: actions/cache@v2
30 |         with:
31 |           path: ~/.cache/xml2rfc
32 |           key: xml2rfc
33 |           restore-keys: xml2rfc
34 | 
35 |       - uses: actions/cache@v2
36 |         with:
37 |           path: ~/.fontist
38 |           key: fontist-${{ runner.os }}
39 |           restore-keys: fontist-${{ runner.os }}
40 | 
41 |       - uses: actions/cache@v2
42 |         with:
43 |           path: ~/.metanorma-ietf-workgroup-cache.json
44 |           key: metanorma-ietf-workgroup-cache
45 |           restore-keys: metanorma-ietf-workgroup-cache
46 | 
47 |       - if: matrix.os == 'windows-latest'
48 |         run: rm Gemfile
49 | 
50 |       - uses: actions-mn/setup@master
51 | 
52 |       - uses: actions-mn/cli/site-gen@main
53 |         with:
54 |           agree-to-terms: true
55 | 


--------------------------------------------------------------------------------
/standard/template/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | .swp
3 | .tmp.xml
4 | 
5 | # Deploy key
6 | deploy_key
7 | 


--------------------------------------------------------------------------------
/standard/template/.gitlab-ci.yml:
--------------------------------------------------------------------------------
 1 | # Auto-generated by Cimas: Do not edit it manually!
 2 | # See https://github.com/metanorma/cimas
 3 | image:
 4 |   name: metanorma/mn
 5 |   entrypoint: [ "" ]
 6 | 
 7 | cache:
 8 |   paths:
 9 | 
10 | stages:
11 |   - build
12 |   - deploy
13 | 
14 | 
15 | build:
16 |   stage: build
17 |   script:
18 |     # We need to do this to install mscorefonts
19 |     - curl -Ls -o yq https://github.com/mikefarah/yq/releases/download/3.3.0/yq_linux_amd64
20 |     - chmod +x yq && mv yq /usr/bin
21 |     - yq
22 |     - apt-add-repository -y contrib && apt-get update
23 |     - echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections
24 |     - apt-get install -y ttf-mscorefonts-installer
25 |     - curl -Ls https://raw.githubusercontent.com/metanorma/vista-fonts-installer/master/vista-fonts-installer.sh | bash
26 |     - curl -L --retry 3 https://raw.githubusercontent.com/metanorma/metanorma-build-scripts/master/gemfile-to-bundle-add.sh | bash
27 |     - bundle install
28 |     - metanorma site generate sources --output-dir public
29 | 
30 |   artifacts:
31 |     paths:
32 |       - public
33 | 
34 | pages:
35 |   dependencies:
36 |     - build
37 |   stage: deploy
38 |   script:
39 |     - >
40 |       'curl --location --output artifacts.zip --header
41 |       "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=build"'
42 |   artifacts:
43 |     paths:
44 |       - public
45 |   only:
46 |     - master
47 | 


--------------------------------------------------------------------------------
/standard/template/Gemfile:
--------------------------------------------------------------------------------
1 | source "https://rubygems.org"
2 | 
3 | gem "metanorma-cli"
4 | gem "relaton-cli"
5 | 


--------------------------------------------------------------------------------
/standard/template/Makefile:
--------------------------------------------------------------------------------
  1 | # Auto-generated by Cimas: Do not edit it manually!
  2 | # See https://github.com/metanorma/cimas
  3 | #!make
  4 | SHELL := /bin/bash
  5 | # Ensure the xml2rfc cache directory exists locally
  6 | IGNORE := $(shell mkdir -p $(HOME)/.cache/xml2rfc)
  7 | 
  8 | SRC := $(shell yq r metanorma.yml metanorma.source.files | cut -c 3-)
  9 | 
 10 | ifeq ($(SRC),null)
 11 | SRC :=
 12 | endif
 13 | ifeq ($(SRC),ll)
 14 | SRC :=
 15 | endif
 16 | 
 17 | ifeq ($(SRC),)
 18 | BUILT := $(shell yq r metanorma.yml metanorma.source.built_targets | cut -d ':' -f 1 | tr -s '\n' ' ')
 19 | 
 20 | ifeq ($(BUILT),null)
 21 | SRC :=
 22 | endif
 23 | ifeq ($(BUILT),ll)
 24 | SRC :=
 25 | endif
 26 | 
 27 | ifeq ($(BUILT),)
 28 | SRC := $(filter-out README.adoc, $(wildcard sources/*.adoc))
 29 | else
 30 | XML := $(patsubst sources/%,documents/%,$(BUILT))
 31 | endif
 32 | endif
 33 | 
 34 | FORMATS := $(shell yq r metanorma.yml metanorma.formats | tr -d '[:space:]' | tr -s '-' ' ')
 35 | ifeq ($(FORMATS),)
 36 | FORMAT_MARKER := mn-output-
 37 | FORMATS := $(shell grep "$(FORMAT_MARKER)" $(SRC) | cut -f 2 -d " " | tr "," "\\n" | sort | uniq | tr "\\n" " ")
 38 | endif
 39 | 
 40 | XML  ?= $(patsubst sources/%,documents/%,$(patsubst %.adoc,%.xml,$(SRC)))
 41 | HTML := $(patsubst %.xml,%.html,$(XML))
 42 | 
 43 | ifdef METANORMA_DOCKER
 44 |   PREFIX_CMD := echo "Running via docker..."; docker run -v "$$(pwd)":/metanorma/ $(METANORMA_DOCKER)
 45 | else
 46 |   ifdef SKIP_BUNDLE
 47 |     PREFIX_CMD := echo "Running locally...";
 48 |   else
 49 |     PREFIX_CMD := echo "Running locally via bundle ..."; bundle exec
 50 |   endif
 51 | endif
 52 | 
 53 | _OUT_FILES := $(foreach FORMAT,$(FORMATS),$(shell echo $(FORMAT) | tr '[:lower:]' '[:upper:]'))
 54 | OUT_FILES  := $(foreach F,$(_OUT_FILES),$($F))
 55 | 
 56 | define print_vars
 57 | 	$(info "src $(SRC)")
 58 | 	$(info "xml $(XML)")
 59 | 	$(info "formats $(FORMATS)")
 60 | endef
 61 | 
 62 | all: documents.html
 63 | 	$(call print_vars)
 64 | 
 65 | documents:
 66 | 	mkdir -p $@
 67 | 
 68 | documents/%.html: documents/%.xml | documents
 69 | 	${PREFIX_CMD} metanorma $<
 70 | 
 71 | documents/%.xml: sources/%.xml | documents
 72 | 	mkdir -p $(dir $@)
 73 | 	mv $< $@
 74 | 
 75 | # Build canonical XML output
 76 | # If XML file is provided, copy it over
 77 | # Otherwise, build the xml using adoc
 78 | sources/%.xml: | bundle
 79 | 	BUILT_TARGET="$(shell yq r metanorma.yml metanorma.source.built_targets[$@])"; \
 80 | 	if [ "$$BUILT_TARGET" = "" ] || [ "$$BUILT_TARGET" = "null" ]; then \
 81 | 		BUILT_TARGET=$@; \
 82 | 		$(PREFIX_CMD) metanorma -x xml "$${BUILT_TARGET//xml/adoc}"; \
 83 | 	else \
 84 | 		if [ -f "$$BUILT_TARGET" ] && [ "$${BUILT_TARGET##*.}" == "xml" ]; then \
 85 | 			cp "$$BUILT_TARGET" $@; \
 86 | 		else \
 87 | 			$(PREFIX_CMD) metanorma -x xml $$BUILT_TARGET; \
 88 | 			cp "$${BUILT_TARGET//adoc/xml}" $@; \
 89 | 		fi \
 90 | 	fi
 91 | 
 92 | documents.rxl: $(XML) $(HTML)
 93 | 	${PREFIX_CMD} relaton concatenate \
 94 | 	  -t "$(shell yq r metanorma.yml relaton.collection.name)" \
 95 | 		-g "$(shell yq r metanorma.yml relaton.collection.organization)" \
 96 | 		documents $@
 97 | 
 98 | documents.html: documents.rxl
 99 | 	$(PREFIX_CMD) relaton xml2html documents.rxl
100 | 
101 | %.adoc:
102 | 
103 | define FORMAT_TASKS
104 | OUT_FILES-$(FORMAT) := $($(shell echo $(FORMAT) | tr '[:lower:]' '[:upper:]'))
105 | 
106 | open-$(FORMAT):
107 | 	open $$(OUT_FILES-$(FORMAT))
108 | 
109 | clean-$(FORMAT):
110 | 	rm -f $$(OUT_FILES-$(FORMAT))
111 | 
112 | $(FORMAT): clean-$(FORMAT) $$(OUT_FILES-$(FORMAT))
113 | 
114 | .PHONY: clean-$(FORMAT)
115 | 
116 | endef
117 | 
118 | $(foreach FORMAT,$(FORMATS),$(eval $(FORMAT_TASKS)))
119 | 
120 | open: open-html
121 | 
122 | clean:
123 | 	rm -rf documents documents.{html,rxl} published *_images $(OUT_FILES)
124 | 
125 | bundle:
126 | ifndef METANORMA_DOCKER
127 | ifndef SKIP_BUNDLE
128 | 	bundle install --jobs 4 --retry 3
129 | endif
130 | endif
131 | 	$(call print_vars)
132 | 
133 | .PHONY: bundle all open clean
134 | 
135 | #
136 | # Watch-related jobs
137 | #
138 | 
139 | .PHONY: watch serve watch-serve
140 | 
141 | NODE_BINS          := onchange live-serve run-p
142 | NODE_BIN_DIR       := node_modules/.bin
143 | NODE_PACKAGE_PATHS := $(foreach PACKAGE_NAME,$(NODE_BINS),$(NODE_BIN_DIR)/$(PACKAGE_NAME))
144 | 
145 | $(NODE_PACKAGE_PATHS): package.json
146 | 	npm i
147 | 
148 | watch: $(NODE_BIN_DIR)/onchange
149 | 	make all
150 | 	$< $(ALL_SRC) -- make all
151 | 
152 | define WATCH_TASKS
153 | watch-$(FORMAT): $(NODE_BIN_DIR)/onchange
154 | 	make $(FORMAT)
155 | 	$$< $$(SRC_$(FORMAT)) -- make $(FORMAT)
156 | 
157 | .PHONY: watch-$(FORMAT)
158 | endef
159 | 
160 | $(foreach FORMAT,$(FORMATS),$(eval $(WATCH_TASKS)))
161 | 
162 | serve: $(NODE_BIN_DIR)/live-server revealjs-css reveal.js
163 | 	export PORT=$${PORT:-8123} ; \
164 | 	port=$${PORT} ; \
165 | 	for html in $(HTML); do \
166 | 		$< --entry-file=$$html --port=$${port} --ignore="*.html,*.xml,Makefile,Gemfile.*,package.*.json" --wait=1000 & \
167 | 		port=$$(( port++ )) ;\
168 | 	done
169 | 
170 | watch-serve: $(NODE_BIN_DIR)/run-p
171 | 	$< watch serve
172 | 
173 | #
174 | # Deploy jobs
175 | #
176 | 
177 | publish: published
178 | 
179 | published: documents.html
180 | 	mkdir -p $@ && \
181 | 	cp -a documents $@/ && \
182 | 	cp $< $@/index.html;
183 | 
184 | #
185 | # PDF
186 | #
187 | 
188 | PDFTEXT := $(patsubst %.pdf,%.txt,$(subst /pdfs,/text,$(wildcard reference-docs/pdfs/*.pdf)))
189 | 
190 | pdf2text: $(PDFTEXT)
191 | 
192 | reference-docs/text:
193 | 	mkdir -p $@
194 | 
195 | reference-docs/text/%.txt: reference-docs/pdfs/%.pdf | reference-docs/text
196 | 	ps2ascii "$<" "$@"
197 | 


--------------------------------------------------------------------------------
/standard/template/Makefile.win:
--------------------------------------------------------------------------------
  1 | # Auto-generated by Cimas: Do not edit it manually!
  2 | # See https://github.com/metanorma/cimas
  3 | #!make
  4 | SHELL := cmd
  5 | # Ensure the xml2rfc cache directory exists locally
  6 | IGNORE := $(shell md $(USERPROFILE)\.cache\xml2rfc)
  7 | 
  8 | SRC := $(shell yq r metanorma.yml metanorma.source.files | cut -c 3-)
  9 | 
 10 | ifeq ($(SRC),null)
 11 | SRC :=
 12 | endif
 13 | ifeq ($(SRC),ll)
 14 | SRC :=
 15 | endif
 16 | 
 17 | ifeq ($(SRC),)
 18 | BUILT := $(subst ${ },${\n},$(shell yq r metanorma.yml metanorma.source.built_targets | cut -d ":" -f 1))
 19 | 
 20 | ifeq ($(BUILT),null)
 21 | BUILT :=
 22 | SRC :=
 23 | endif
 24 | ifeq ($(BUILT),ll)
 25 | BUILT :=
 26 | SRC :=
 27 | endif
 28 | ifeq ($(BUILT),)
 29 | SRC :=
 30 | endif
 31 | 
 32 | ifeq ($(BUILT),)
 33 | SRC := $(filter-out README.adoc, $(wildcard sources/*.adoc))
 34 | else
 35 | XML := $(patsubst sources/%,documents/%,$(BUILT))
 36 | endif
 37 | endif
 38 | 
 39 | FORMATS := $(subst -,${ },$(strip $(shell yq r metanorma.yml metanorma.formats)))
 40 | ifeq ($(FORMATS),null)
 41 | FORMATS :=
 42 | endif
 43 | ifeq ($(FORMATS),)
 44 | FORMAT_MARKER := mn-output-
 45 | FORMATS := $(subst ${\n},${ },$(shell grep "$(FORMAT_MARKER)" $(SRC) | cut -f 2 -d " " | tr "," "\n" | sort | uniq))
 46 | endif
 47 | 
 48 | XML  ?= $(patsubst sources/%,documents/%,$(patsubst %.adoc,%.xml,$(SRC)))
 49 | HTML := $(patsubst %.xml,%.html,$(XML))
 50 | 
 51 | ifdef METANORMA_DOCKER
 52 |   PREFIX_CMD := echo "Running via docker..." & docker run -v "$$(pwd)":/metanorma/ $(METANORMA_DOCKER)
 53 | else
 54 |   ifdef SKIP_BUNDLE
 55 |     PREFIX_CMD := echo "Running locally..." &
 56 |   else
 57 |     PREFIX_CMD := echo "Running locally via bundle ..." & bundle exec
 58 |   endif
 59 | endif
 60 | 
 61 | _OUT_FILES := $(foreach FORMAT,$(FORMATS),$(shell echo $(FORMAT) | tr '[:lower:]' '[:upper:]'))
 62 | OUT_FILES  := $(foreach F,$(_OUT_FILES),$($F))
 63 | 
 64 | define print_vars
 65 | 	$(info "src $(SRC)")
 66 | 	$(info "xml $(XML)")
 67 | 	$(info "formats $(FORMATS)")
 68 | endef
 69 | 
 70 | all: documents.html
 71 | 	$(call print_vars)
 72 | 
 73 | documents:
 74 | 	setlocal enableextensions & md $@ & endlocal
 75 | 
 76 | documents/%.html: documents/%.xml | documents
 77 | 	${PREFIX_CMD} metanorma $<
 78 | 
 79 | documents/%.xml: sources/%.xml | documents
 80 | 	if not exist "$(subst /,\,$(dir $@))" md "$(subst /,\,$(dir $@))"
 81 | 	move "$(subst /,\,$<)" "$(subst /,\,$@)"
 82 | 
 83 | # Build canonical XML output
 84 | # If XML file is provided, copy it over
 85 | # Otherwise, build the xml using adoc
 86 | sources/%.xml: | bundle
 87 | 	$(eval BUILT_TARGET := $(subst /,\,$(shell yq r metanorma.yml metanorma.source.built_targets[$@])))
 88 | 	$(eval BUILT_TARGET_EMPTY := $(if $(filter $(or $(BUILT_TARGET),null),null ll),true,false))
 89 | 	if "$(BUILT_TARGET_EMPTY)" == "true" ( \
 90 | 		$(PREFIX_CMD) metanorma -x xml "$(subst xml,adoc,$@)" \
 91 | 	) else ( \
 92 | 		if exist "$(BUILT_TARGET)" ( \
 93 | 			if "$(suffix $(BUILT_TARGET))" == ".xml" ( \
 94 | 				copy "$(BUILT_TARGET)" "$(subst /,\,$@)" \
 95 | 			) else ( \
 96 | 				$(PREFIX_CMD) metanorma $(BUILT_TARGET) & \
 97 | 				copy "$(subst adoc,xml,$(BUILT_TARGET))" "$(subst /,\,$@)" \
 98 | 			) \
 99 | 		) else ( \
100 | 			$(PREFIX_CMD) metanorma $(BUILT_TARGET) & \
101 | 			copy "$(subst adoc,xml,$(BUILT_TARGET))" "$(subst /,\,$@)" \
102 | 		) \
103 | 	)
104 | 
105 | documents.rxl: $(XML) $(HTML)
106 | 	${PREFIX_CMD} relaton concatenate \
107 | 		-t "$(shell yq r metanorma.yml relaton.collection.name)" \
108 | 		-g "$(shell yq r metanorma.yml relaton.collection.organization)" \
109 | 		documents $@
110 | 
111 | documents.html: documents.rxl
112 | 	$(PREFIX_CMD) relaton xml2html documents.rxl
113 | 
114 | %.adoc:
115 | 
116 | define FORMAT_TASKS
117 | OUT_FILES-$(FORMAT) := $($(shell echo $(FORMAT) | tr '[:lower:]' '[:upper:]'))
118 | 
119 | open-$(FORMAT):
120 | 	"$$(OUT_FILES-$(FORMAT))"
121 | 
122 | clean-$(FORMAT):
123 | 	del /q $$(OUT_FILES-$(FORMAT))
124 | 
125 | $(FORMAT): clean-$(FORMAT) $$(OUT_FILES-$(FORMAT))
126 | 
127 | .PHONY: clean-$(FORMAT)
128 | 
129 | endef
130 | 
131 | $(foreach FORMAT,$(FORMATS),$(eval $(FORMAT_TASKS)))
132 | 
133 | open: open-html
134 | 
135 | clean:
136 | 	rm -rf $(OUT_FILES)
137 | 	del /q documents published
138 | 	del /q *_images
139 | 	del /q documents.*
140 | 
141 | bundle:
142 | ifndef METANORMA_DOCKER
143 | ifndef SKIP_BUNDLE
144 | 	bundle install --jobs 4 --retry 3
145 | endif
146 | endif
147 | 	$(call print_vars)
148 | 
149 | .PHONY: bundle all open clean
150 | 
151 | #
152 | # Watch-related jobs
153 | #
154 | 
155 | .PHONY: watch serve watch-serve
156 | 
157 | NODE_BINS          := onchange live-serve run-p
158 | NODE_BIN_DIR       := node_modules/.bin
159 | NODE_PACKAGE_PATHS := $(foreach PACKAGE_NAME,$(NODE_BINS),$(NODE_BIN_DIR)/$(PACKAGE_NAME))
160 | 
161 | $(NODE_PACKAGE_PATHS): package.json
162 | 	npm i
163 | 
164 | watch: $(NODE_BIN_DIR)/onchange
165 | 	make all
166 | 	$< $(ALL_SRC) -- make all
167 | 
168 | define WATCH_TASKS
169 | watch-$(FORMAT): $(NODE_BIN_DIR)/onchange
170 | 	make $(FORMAT)
171 | 	$$< $$(SRC_$(FORMAT)) -- make $(FORMAT)
172 | 
173 | .PHONY: watch-$(FORMAT)
174 | endef
175 | 
176 | $(foreach FORMAT,$(FORMATS),$(eval $(WATCH_TASKS)))
177 | 
178 | ifndef PORT
179 | override PORT = 8123
180 | endif
181 | 
182 | serve: $(NODE_BIN_DIR)/live-server revealjs-css reveal.js
183 | 	set port=$(PORT) & \
184 | 	for /r %%html in $(HTML) do ( \
185 | 		$< --entry-file=%%html --port=%port% --ignore="*.html,*.xml,Makefile,Gemfile.*,package.*.json" --wait=1000 & \
186 | 		set /A port=%port%+1 \
187 | 	)
188 | 
189 | watch-serve: $(NODE_BIN_DIR)/run-p
190 | 	$< watch serve
191 | 
192 | #
193 | # Deploy jobs
194 | #
195 | 
196 | publish: published
197 | 
198 | published: documents.html
199 | 	setlocal enableextensions & md $@ & endlocal
200 | 	copy documents $@/
201 | 	copy $< $@/index.html
202 | 	if exist "source\images" xcopy /E source\images $@
203 | 
204 | #
205 | # PDF
206 | #
207 | 
208 | PDFTEXT := $(patsubst %.pdf,%.txt,$(subst /pdfs,/text,$(wildcard reference-docs/pdfs/*.pdf)))
209 | 
210 | pdf2text: $(PDFTEXT)
211 | 
212 | reference-docs/text:
213 | 	md $@
214 | 
215 | reference-docs/text/%.txt: reference-docs/pdfs/%.pdf | reference-docs/text
216 | 	ps2ascii "$<" "$@"
217 | 


--------------------------------------------------------------------------------
/standard/template/README.adoc:
--------------------------------------------------------------------------------
 1 | = Standard template in Metanorma
 2 | 
 3 | == Content
 4 | 
 5 | This repository contains the content for an OGC standard.
 6 | 
 7 | * `document.adoc` - the main standard document with references to all sections
 8 | * remaining ``adoc``s - each section of the standard document is in a separate document: follow directions in each document to populate
 9 | * `figures` - figures go here
10 | * `images` - Image files for graphics go here. Image files for figures go in the `figures` directory. Only place in here images not used in figures (e.g., as parts of tables, as logos, etc.)
11 | * `requirements` - directory for requirements and requirement classes to be referenced in `clause_7_normative_text.adoc`
12 | * `code` - sample code to accompany the standard, if desired
13 | * `abstract_tests` - the Abstract Test Suite comprising one test for every requirement, optional
14 | * `UML` - UML diagrams, if applicable
15 | 
16 | == Building
17 | 
18 | Run `make`.
19 | 


--------------------------------------------------------------------------------
/standard/template/UML/README.adoc:
--------------------------------------------------------------------------------
1 | Store UML content in this directory. Feel free to use any organizational scheme that you like.
2 | 
3 | Figures derived from UML diagrams should be placed in the "figures" folder.
4 | 


--------------------------------------------------------------------------------
/standard/template/abstract_tests/ATS_class_example1.adoc:
--------------------------------------------------------------------------------
 1 | [[ats_example1]]
 2 | [conformance_class_example1]
 3 | ====
 4 | [%metadata]
 5 | label:: http://www.opengis.net/spec/name-of-standard/1.0/conf/example1
 6 | subject:: Requirements Class "example1"
 7 | classification:: Target Type:Web API
 8 | ====
 9 | 
10 | ==== Example 1
11 | 
12 | include::./ATS_test_example1.adoc[]
13 | 
14 | ==== Example 2
15 | 
16 | include::./ATS_test_example2.adoc[]
17 | 


--------------------------------------------------------------------------------
/standard/template/abstract_tests/ATS_test_example1.adoc:
--------------------------------------------------------------------------------
 1 | [[ats_core_api-definition-op]]
 2 | [abstract_test]
 3 | ====
 4 | [%metadata]
 5 | label:: /conf/core/api-definition-op
 6 | subject:: /req/req-class-a/req-name-1
 7 | test-purpose:: Validate that the API Definition document can be retrieved from the expected location.
 8 | 
 9 | [.component,class=test method]
10 | =====
11 | [.component,class=step]
12 | --
13 | Construct a path for the API Definition document that ends with `/api`.
14 | --
15 | 
16 | [.component,class=step]
17 | --
18 | Issue a HTTP GET request on that path
19 | --
20 | 
21 | [.component,class=step]
22 | --
23 | Validate the contents of the returned document using test <<ats_core_api-definition-success,/conf/core/api-definition-success>>.
24 | --
25 | =====
26 | ====
27 | 


--------------------------------------------------------------------------------
/standard/template/abstract_tests/ATS_test_example2.adoc:
--------------------------------------------------------------------------------
 1 | [[ats_core_http]]
 2 | [abstract_test]
 3 | ====
 4 | [%metadata]
 5 | label:: /conf/core/http
 6 | subject:: /req/req-class-a/req-name-2
 7 | test-purpose:: Validate that the resource paths advertised through the API conform with HTTP 1.1 and, where appropriate, TLS.
 8 | 
 9 | [.component,class=test method]
10 | =====
11 | [.component,class=step]
12 | --
13 | All compliance tests SHALL be configured to use the HTTP 1.1 protocol exclusively.
14 | --
15 | 
16 | [.component,class=step]
17 | --
18 | For APIs which support HTTPS, all compliance tests SHALL be configured to use <<rfc2818,HTTP over TLS>> (RFC 2818) with their HTTP 1.1 protocol.
19 | --
20 | =====
21 | ====
22 | 


--------------------------------------------------------------------------------
/standard/template/abstract_tests/README.adoc:
--------------------------------------------------------------------------------
1 | This folder contains the Abstract Test Suite.
2 | 
3 | The test is expressed according to this pattern:
4 | 
5 | NOTE: for each test, there should be a corresponding requirement in the "requirements" folder.
6 | 


--------------------------------------------------------------------------------
/standard/template/code/README.adoc:
--------------------------------------------------------------------------------
1 | Sample code may be stored in this folder, organized as you see fit
2 | 


--------------------------------------------------------------------------------
/standard/template/document.adoc:
--------------------------------------------------------------------------------
 1 | = OGC (add title text)
 2 | :doctype: standard
 3 | :encoding: utf-8
 4 | :lang: en
 5 | :status: draft
 6 | :committee: technical
 7 | :draft: 3.0
 8 | :external-id: http://www.opengis.net/doc/{doc-type}/{standard}/{m.n}
 9 | :docnumber: YY-999
10 | :received-date: 2029-03-30
11 | :issued-date: 2029-03-30
12 | :published-date: 2029-03-30
13 | :fullname: Editor One
14 | :fullname_2: Editor Two
15 | :docsubtype: Interface
16 | :keywords: ogcdoc, OGC document, API, openapi, html
17 | :submitting-organizations: Organization One; Organization Two
18 | :mn-document-class: ogc
19 | :mn-output-extensions: xml,html,doc,pdf
20 | :local-cache-only:
21 | :data-uri-image:
22 | :pdf-uri: ./document.pdf
23 | :xml-uri: ./document.xml
24 | :doc-uri: ./document.doc
25 | :edition: 1.0
26 | 
27 | ////
28 | Make sure to complete each included document
29 | ////
30 | include::sections/clause_0_front_material.adoc[]
31 | 
32 | include::sections/clause_1_scope.adoc[]
33 | 
34 | include::sections/clause_2_conformance.adoc[]
35 | 
36 | include::sections/clause_3_references.adoc[]
37 | 
38 | include::sections/clause_4_terms_and_definitions.adoc[]
39 | 
40 | include::sections/clause_5_conventions.adoc[]
41 | 
42 | include::sections/clause_6_informative_text.adoc[]
43 | 
44 | include::sections/clause_7_normative_text.adoc[]
45 | 
46 | include::sections/clause_8_media_types.adoc[]
47 | 
48 | ////
49 | add or remove annexes after "A" as necessary
50 | ////
51 | include::sections/annex-a.adoc[]
52 | 
53 | include::sections/annex-n.adoc[]
54 | 
55 | ////
56 | Revision History should be the last annex before the Bibliography
57 | Bibliography should be the last annex
58 | ////
59 | include::sections/annex-history.adoc[]
60 | 
61 | include::sections/annex-bibliography.adoc[]
62 | 


--------------------------------------------------------------------------------
/standard/template/figures/README.adoc:
--------------------------------------------------------------------------------
1 | Figures go here.
2 | 
3 | Each figure is a separate file with the naming convention:
4 | 
5 | "FIGn.xxx" where "n" is a number with leading zeroes appropriate for the total number of figures and "xxx" is the appropriate extension for the file type.


--------------------------------------------------------------------------------
/standard/template/images/README.adoc:
--------------------------------------------------------------------------------
1 | Image files for graphics go here. Image files for figures go in the "figures" directory. Only place in here images not used in figures (e.g., as parts of tables, as logos, etc.)
2 | 
3 | Each graphic is a separate file with the naming convention:
4 | 
5 | "GRPn.xxx" where "n" is a sequential number with leading zeroes appropriate for the total number of graphics and "xxx" is the appropriate extension for the file type.
6 | 


--------------------------------------------------------------------------------
/standard/template/metanorma.yml:
--------------------------------------------------------------------------------
1 | ---
2 | metanorma:
3 |   deploy:
4 |     email: "ci@metanorma.org"
5 | 


--------------------------------------------------------------------------------
/standard/template/requirements/README.adoc:
--------------------------------------------------------------------------------
 1 | This folder contains requirements description.
 2 | 
 3 | Each file is a single requirement. The naming convention for these files is:
 4 | 
 5 | "REQn.adoc" where "n" corresponds to the requirement number. Numbers should have preceding zeros appropriate for the total number of requirements in the project (e.g., the first requirement could be REQ001 if less than 1000 requirements are anticipated).
 6 | 
 7 | The requirement files are integrated into the main document as links.
 8 | 
 9 | The requirement is expressed according to this pattern:
10 | 
11 | NOTE: for each requirement, there should be a corresponding Abstract Test in the "abstract_tests" folder.
12 | 
13 | NOTE: sample code may reference one or more requirements and should state which requirements are included in the code by adding the following line to the Extended Description:
14 | 
15 | "#REQS: reqnum1,reqnum2,...reqnumn"
16 | 


--------------------------------------------------------------------------------
/standard/template/requirements/requirement001.adoc:
--------------------------------------------------------------------------------
1 | [requirement,type="general",id="/req/req-class-a/req-name-1",label="/req/req-class-a/req-name-1",obligation="requirement"]
2 | ====
3 | 
4 | Requirement 'shall' statement
5 | 
6 | ====
7 | 


--------------------------------------------------------------------------------
/standard/template/requirements/requirement002.adoc:
--------------------------------------------------------------------------------
 1 | [[req_core_process-execute-input-inline-object]]
 2 | [requirement]
 3 | ====
 4 | [%metadata]
 5 | label:: /req/req-class-a/req-name-2
 6 | [.component,class=conditions]
 7 | --
 8 | . The process input value is specified in-line in an execute request.
 9 | . The process input is defined as an object according to its schema.
10 | --
11 | 
12 | [.component,class=part]
13 | --
14 | The server SHALL support process input values encoded as qualified values.
15 | --
16 | 
17 | [.component,class=part]
18 | --
19 | The value of the `value` key SHALL be an _object_ instance.
20 | --
21 | ====
22 | 


--------------------------------------------------------------------------------
/standard/template/requirements/requirements_class.adoc:
--------------------------------------------------------------------------------
 1 | ////
 2 | [cols="1,4",width="90%"]
 3 | |===
 4 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 5 | 2+|http://www.opengis.net/spec/ABCD/m.n/req/req-class-a {set:cellbgcolor:#FFFFFF}
 6 | |Target type |Token
 7 | |Dependency |http://www.example.org/req/blah
 8 | |Dependency |urn:iso:ts:iso:19139:clause:6
 9 | |*Requirement 1* {set:cellbgcolor:#CACCCE} |http://www.opengis.net/spec/ABCD/m.n/req/req-class-a/req-name-1 +
10 | requirement description {set:cellbgcolor:#FFFFFF}
11 | |*Requirement 2* {set:cellbgcolor:#CACCCE} |http://www.opengis.net/spec/ABCD/m.n/req/req-class-a/req-name-2 +
12 | requirement description {set:cellbgcolor:#FFFFFF}
13 | 
14 | |*Requirement 3* {set:cellbgcolor:#CACCCE} |http://www.opengis.net/spec/ABCD/m.n/req/req-class-a/req-name-3 +
15 | requirement description
16 | {set:cellbgcolor:#FFFFFF}
17 | |===
18 | ////
19 | 
20 | 
21 | [requirement,type="class",id="http://www.opengis.net/spec/ABCD/m.n/req/req-class-a",obligation="requirement"]
22 | ====
23 | 
24 | Requirements Class
25 | 
26 | [dependency]
27 | --
28 | * http://www.example.org/req/blah
29 | * urn:iso:ts:iso:19139:clause:6
30 | --
31 | 
32 | [requirement,type="general",label="/req/req-class-a/req-name-1"]
33 | ======
34 | 
35 | ======
36 | 
37 | [requirement,type="general",label="/req/req-class-a/req-name-2"]
38 | ======
39 | 
40 | ======
41 | 
42 | ====
43 | 


--------------------------------------------------------------------------------
/standard/template/sections/annex-a.adoc:
--------------------------------------------------------------------------------
 1 | [appendix]
 2 | == Conformance Class Abstract Test Suite (Normative)
 3 | 
 4 | [NOTE]
 5 | Ensure that there is a conformance class for each requirements class and a test for each requirement (identified by requirement name and number)
 6 | 
 7 | === Conformance Class A
 8 | 
 9 | include::../abstract_tests/ATS_class_example1.adoc[]
10 | 


--------------------------------------------------------------------------------
/standard/template/sections/annex-bibliography.adoc:
--------------------------------------------------------------------------------
 1 | [bibliography]
 2 | [[Bibliography]]
 3 | == Bibliography
 4 | 
 5 | [NOTE]
 6 | .Example Bibliography (Delete this note).
 7 | ===============================================
 8 | The TC has approved Springer LNCS as the official document citation type.
 9 | 
10 | Springer LNCS is widely used in technical and computer science journals and other publications
11 | 
12 | * For citations in the text please use square brackets and consecutive numbers: [1], [2], [3]
13 | 
14 | – Actual References:
15 | 
16 | [n] Journal: Author Surname, A.: Title. Publication Title. Volume number, Issue number, Pages Used (Year Published)
17 | 
18 | [n] Web: Author Surname, A.: Title, http://Website-Url
19 | 
20 | ===============================================
21 | 
22 | * [[[OGC2015,OGCTB12]]], _OGC: OGC Testbed 12 Annex B: Architecture_ (2015).
23 | 


--------------------------------------------------------------------------------
/standard/template/sections/annex-history.adoc:
--------------------------------------------------------------------------------
1 | [appendix]
2 | == Revision History
3 | 
4 | [width="90%",options="header"]
5 | |===
6 | |Date |Release |Editor | Primary clauses modified |Description
7 | |2016-04-28 |0.1 |G. Editor |all |initial version
8 | |===
9 | 


--------------------------------------------------------------------------------
/standard/template/sections/annex-n.adoc:
--------------------------------------------------------------------------------
1 | [appendix,obligation="informative"]
2 | == Title
3 | 
4 | [NOTE]
5 | Place other Annex material in sequential annexes beginning with "B" and leave final two annexes for the Revision History and Bibliography
6 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_0_front_material.adoc:
--------------------------------------------------------------------------------
 1 | .Preface
 2 | 
 3 | [NOTE]
 4 | ====
 5 | 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.
 6 | ====
 7 | 
 8 | ////
 9 | *OGC Declaration*
10 | ////
11 | 
12 | 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.
13 | 
14 | 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.
15 | 
16 | ////
17 | NOTE: Uncomment ISO section if necessary
18 | 
19 | *ISO Declaration*
20 | 
21 | 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.
22 | 
23 | International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.
24 | 
25 | 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.
26 | 
27 | 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.
28 | ////
29 | 
30 | [abstract]
31 | == Abstract
32 | 
33 | <Insert Abstract Text here>
34 | 
35 | 
36 | 
37 | == Preface
38 | 
39 | [NOTE]
40 | ====
41 | 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. >
42 | 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.
43 | 
44 | 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.
45 | ====
46 | 
47 | == Security considerations
48 | 
49 | //If no security considerations have been made for this Standard, use the following text.
50 | 
51 | No security considerations have been made for this Standard.
52 | 
53 | ////
54 | If security considerations have been made for this Standard, follow the examples found in IANA or IETF documents. Please see the following example.
55 | “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.
56 | 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.
57 | 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....”
58 | ////
59 | 
60 | 
61 | 
62 | == Submitters
63 | 
64 | All questions regarding this submission should be directed to the editor or the submitters:
65 | 
66 | |===
67 | |*Name* |*Affiliation*
68 | | |
69 | |===
70 | 
71 | == Contributors
72 | 
73 | //This clause is optional.
74 | 
75 | Additional contributors to this Standard include the following:
76 | 
77 | Individual name(s), Organization
78 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_1_scope.adoc:
--------------------------------------------------------------------------------
1 | == Scope
2 | [NOTE]
3 | ====
4 | Insert Scope text here. Give the subject of the document and the aspects of that scope covered by the document.
5 | ====
6 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_2_conformance.adoc:
--------------------------------------------------------------------------------
 1 | == Conformance
 2 | This standard defines XXXX.
 3 | 
 4 | Requirements for N standardization target types are considered:
 5 | 
 6 | * AAAA
 7 | * BBBB
 8 | 
 9 | Conformance with this standard 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 OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.
10 | 
11 | In order to conform to this OGC® interface standard, a software implementation shall choose to implement:
12 | 
13 | * Any one of the conformance levels specified in Annex A (normative).
14 | * Any one of the Distributed Computing Platform profiles specified in Annexes TBD through TBD (normative).
15 | 
16 | All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified.
17 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_3_references.adoc:
--------------------------------------------------------------------------------
 1 | [bibliography]
 2 | == References
 3 | 
 4 | 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.
 5 | 
 6 | [NOTE]
 7 | ====
 8 | Insert References here. If there are no references, leave this section empty.
 9 | 
10 | References are to follow the Springer LNCS style, with the exception that optional information may be appended to references: DOIs are added after the date and web resource references may include an access date at the end of the reference in parentheses. See examples from Springer and OGC below.
11 | ====
12 | 
13 | * [[[Smith81,Identification of Common Molecular Subsequences]]],
14 | _Identification of Common Molecular Subsequences_.
15 | Smith, T.F., Waterman, M.S., J. Mol. Biol. 147, 195–197 (1981)
16 | 
17 | * [[[May06,ZIB Structure Prediction Pipeline]]],
18 | _ZIB Structure Prediction Pipeline: Composing a Complex Biological Workflow through Web Services_.
19 | May, P., Ehrlich, H.C., Steinke, T. In: Nagel, W.E., Walter,
20 | W.V., Lehner, W. (eds.) Euro-Par 2006. LNCS, vol. 4128, pp. 1148–1158. Springer,
21 | Heidelberg (2006)
22 | 
23 | * [[[Grid,The Grid]]], _The Grid: Blueprint for a New Computing Infrastructure._,
24 | Foster, I., Kesselman, C.. Morgan Kaufmann, San Francisco (1999).
25 | 
26 | * [[[Czajkowski01,Grid Information Services for Distributed Resource Sharing]]],
27 | _Grid Information Services for Distributed Resource Sharing._
28 | Czajkowski, K., Fitzgerald, S., Foster, I., Kesselman, C. In: 10th IEEE International Symposium on High
29 | Performance Distributed Computing, pp. 181–184. IEEE Press, New York (2001)
30 | 
31 | * [[[Foster02,The Physiology of the Grid]]],
32 | _The Physiology of the Grid: an Open Grid Services Architecture for Distributed Systems Integration._
33 | Foster, I., Kesselman, C., Nick, J., Tuecke, S. Technical report, Global Grid Forum (2002)
34 | 
35 | * [[[NCBI,NCBI]]], _National Center for Biotechnology Information_, http://www.ncbi.nlm.nih.gov
36 | 
37 | * [[[ISO19101-1,ISO 19101-1:2014]]], Geographic information -- Reference model -- Part 1: Fundamentals
38 | 
39 | * [[[ISO19115-1,ISO 19115-1:2014]]], _Geographic information -- Metadata -- Part 1: Fundamentals_
40 | 
41 | * [[[ISO19157,ISO 19157:2013]]], _Geographic information -- Data quality_
42 | 
43 | * [[[ISO19139,ISO 19139:2007]]], _Geographic information -- Metadata -- XML schema implementation_
44 | 
45 | * [[[ISO19115-3,ISO 19115-3]]], _Geographic information -- Metadata -- Part 3: XML schemas_ (2016)
46 | 
47 | * [[[OGC15-097,OGC 15-097]]], _OGC Geospatial User Feedback Standard: Conceptual Model_ (2016)
48 | 
49 | * [[[OGC12-019,OGC 12-019]]], _OGC City Geography Markup Language (CityGML) Encoding Standard_ (2012)
50 | 
51 | * [[[OGC14-005r3,OGC 14-005r3]]], _OGC IndoorGML_ (2014)
52 | 
53 | * [[[OGC06121r9,OGC 06-121r9]]], _OGC Web Service Common Implementation Specification_, April 7, 2010. http://portal.opengeospatial.org/files/?artifact_id=38867


--------------------------------------------------------------------------------
/standard/template/sections/clause_4_terms_and_definitions.adoc:
--------------------------------------------------------------------------------
 1 | == Terms and definitions
 2 | 
 3 | This document uses the terms defined in Sub-clause 5.3 of <<OGC06-121r9>>, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word "`shall`" (not "`must`") is the verb form used to indicate a requirement to be strictly followed to conform to this standard.
 4 | 
 5 | For the purposes of this document, the following additional terms and definitions apply.
 6 | 
 7 | === example term
 8 | 
 9 | term used for exemplary purposes
10 | 
11 | [.source]
12 | <<ISO19101-1>>
13 | 
14 | NOTE: An example note.
15 | 
16 | [example]
17 | Here's an example of an example term.
18 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_5_conventions.adoc:
--------------------------------------------------------------------------------
 1 | == Conventions
 2 | 
 3 | This sections provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.
 4 | 
 5 | === Identifiers
 6 | The normative provisions in this standard are denoted by the URI
 7 | 
 8 | `http://www.opengis.net/spec/{standard}/{m.n}`
 9 | 
10 | All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.
11 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_6_informative_text.adoc:
--------------------------------------------------------------------------------
 1 | [obligation=informative]
 2 | == Clauses not containing normative material
 3 | 
 4 | Paragraph
 5 | 
 6 | === Clauses not containing normative material sub-clause 1
 7 | 
 8 | Paragraph
 9 | 
10 | === Clauses not containing normative material sub-clause 2
11 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_7_annex_mapping.adoc.adoc:
--------------------------------------------------------------------------------
  1 | == GeoZarr format requirements
  2 | 
  3 | TIP: This is a very preliminary draft. The content is primarily for demonstrating the purpose of the proposed sections. The main focus should be on the table of contents.
  4 | 
  5 | A GeoZarr data format is a regular Zarr hierarchy that represents geospatial coverages such as granules, scenes series, mosaics or any spatio temporal asset (as per STAC specification).
  6 | 
  7 | === Overview and Definitions 
  8 | 
  9 | The OGC Abstract Topic 6 [OGC 07-011] standard defines all geographic object as a feature, with coverage being a special type for any digital geospatial information representing space and time varying phenomena. The ISO 19123 standard provides a formal definition for coverages: a "feature acting as a function that returns values from its range for any direct position within its spatiotemporal domain". 
 10 | 
 11 | GeoZarr, like many array-oriented geospatial data formats (e.g., NetCDF, GeoTIFF), primarily supports *Rectified Grid Coverages*. Rectified Grid Coverage is a type of grid coverage that aligns with a coordinate reference system, ensuring that each cell or grid point corresponds precisely to a specific geographic location. 
 12 | 
 13 | The base terminology in the scope of this specification includes the following terms:
 14 | 
 15 | - A *GeoZarr Instance* (or GeoZarr) is a hierarchy of objects including attributes and arrays describing geospatial information.
 16 | - A *GeoZarr Data Variable* is the arrray and attributes that define the values of a n-D coverage (i.e. a Rectified Grid Coverage)
 17 | - A *GeoZarr Coordinate Variable* is the array (might be empty) and attributes  that define a coordinate dimension of a n-D coverage
 18 | - A *GeoZarr Auxiliary Variable* is the array (might be empty) and attributes that define other type of information
 19 | - A *GeoZarr Dataset* is a self-describing collection of n-D coverages defined by a set of values, coordinates and attributes (similar to a NetCDF dataset).
 20 | 
 21 | Unlike some popular geospatial data formats, GeoZarr is not limited to 2D rasters and extends to multiple dimensions, including time, altitude, wavelength, and others. Additionally, the order of these dimensions is not fixed, allowing for optimizations in data analysis.
 22 | 
 23 | A Dataset (referenced as an asset in a STAC item) facilitates the discovery and handling of the coverages by clients, such as web maps, and supports advanced capabilities such as pyramiding. However,GeoZarr also flexible and adaptable enough to accommodate other types of information: the specification aim to ensure that a transformation to GeoZarr from a source format can be reverted back to the original format.
 24 | 
 25 | === Underlying GeoZarr Requirements
 26 | 
 27 | The requirement class GeoZarr Core is mandatory for all GeoZarr instances and must be specified at the root level with the `conformsTo` attribute.
 28 | 
 29 | Some requirement classes are optional and define specific type of assets to facilitate standard interpretation by clients, such as a the requirement class Dataset. These optional requirement classes must be specified at the appropriate level within the hierarchy, using the conformsTo attribute to indicate adherence to the respective requirement class.
 30 | 
 31 | TIP: maybe list possible requirements classes and purpose
 32 | 
 33 | ==== Requirement Class GeoZarr Core
 34 | 
 35 | The base requirement class is designed to be flexible, facilitating conversion from any data source and support most source formats..
 36 | 
 37 | [[req_geozarr-core]]
 38 | [cols="1,4",width="90%"]
 39 | |===
 40 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 41 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/geozarr-core {set:cellbgcolor:#FFFFFF}
 42 | |Target type | Zarr Encoder
 43 | |Dependency | TBD
 44 | |===
 45 | 
 46 | ===== Structure
 47 | 
 48 | A GeoZarr instance must consist of any Zarr tree structure with a root that is always a Zarr group, include the attribute conformsTo set to the GeoZarr requirement class in the root group, and allow any number of hierarchical levels within the groups.
 49 | 
 50 | [width="90%",cols="2,6"]
 51 | |===
 52 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr/structure
 53 | | A {set:cellbgcolor:#EEEEEE} | A GeoZarr instance (or GeoZarr) must consist of a Zarr tree structure.
 54 | | B {set:cellbgcolor:#EEEEEE} | The GeoZarr root must always be a Zarr group.
 55 | | C {set:cellbgcolor:#EEEEEE} | The root group must include the attribute `conformsTo` set to the GeoZarr requirement class.
 56 | | D {set:cellbgcolor:#EEEEEE} | The GeoZarr instance may have any number of levels within the hierarchy.
 57 | |===
 58 | 
 59 | ===== Variables
 60 | 
 61 | A variable represents an array of values of the same type in a Zarr array. A variable can describe coverage values, their coordinates, or any auxiliary data (i.e., additional information to the coverage). These different types of variables are defined further in the specification.
 62 | 
 63 | [width="90%",cols="2,6"]
 64 | |===
 65 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr/variable
 66 | | A {set:cellbgcolor:#EEEEEE} | A variable represents an array of values of the same type and is stored in Zarr arrays.
 67 | |===
 68 | 
 69 | 
 70 | ===== Attributes
 71 | 
 72 | GeoZarr attributes are used to store ancillary data or metadata at any level of the hierarchy. This information can pertain to variables, coordinates, spatio-temporal assets, or any other relevant purpose.
 73 | 
 74 | [width="90%",cols="2,6"]
 75 | |===
 76 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr/attributes
 77 | | A {set:cellbgcolor:#EEEEEE} | GeoZarr attributes are used to store ancillary data or metadata at any level of the hierarchy.
 78 | | B {set:cellbgcolor:#EEEEEE} | GeoZarr attributes must be encoded as Zarr attributes.
 79 | |===
 80 | 
 81 | ==== Requirement Class GeoZarr Dataset
 82 | 
 83 | [[req_geozarr-dataset]]
 84 | [cols="1,4",width="90%"]
 85 | |===
 86 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 87 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/geozarr-dataset {set:cellbgcolor:#FFFFFF}
 88 | |Target type | Zarr Encoder
 89 | |Dependency | TBD
 90 | |===
 91 | 
 92 | ===== Notion of Dataset
 93 | 
 94 | GeoZarr defines flexible conventions to encode content from various source formats, including geospatial arrays (raster), non-geospatial arrays, and hierarchical structures.
 95 | 
 96 | GeoZarr emphasizes Rectified Grid Coverages, which can be easily discovered, interpreted, and displayed on a map. A coverage is spatial data organized in a regular grid, where each cell holds a value representing a specific geographic area. Examples include 2D Rasters, Raster Time Series, and Geo-Datacubes (with dimensions like time, light spectrum, altitude, etc.).
 97 | 
 98 | A GeoZarr Dataset, consists of a collection of coverage defined by data variables, their common coordinates, and some attributes which together form a self describing dataset and represent a geospatial phenomenon in the data hierarchy.  GeoZarr defines the structure and necessary metadata for understanding this dataset, such as an index of available variables, the projection used, and the coordinates describing the dimensions of these variables.
 99 | 
100 | The purpose of a GeoZarr Dataset is to maximize compatibility and facilitate the seamless mapping of diverse source formats into a standardized, easily interpretable structure.
101 | 
102 | **Figure 1: GeoZarr Dataset Abstract Representation**
103 | 
104 | ```mermaid
105 | classDiagram
106 |     class Dataset {
107 |         +attributes
108 |     }
109 |     class DataVariable {
110 |         +values
111 |         +attributes
112 |     }
113 |     class CoordinateVariable {
114 |         +coordinates
115 |         +attributes
116 |     }
117 |     class AuxiliaryVariable {
118 |         +data
119 |         +attributes
120 |     }
121 | 
122 |     Dataset --> "1..*" DataVariable : includes
123 |     Dataset --> "1..*" CoordinateVariable : includes
124 |     Dataset --> "0..*" AuxiliaryVariable : includes
125 |     CoordinateVariable --> DataVariable : coordinates
126 | ```
127 | 
128 | ===== Dataset Structure
129 | 
130 | A GeoZarr may include Dataset Groups which consists in n-D variables observed by a sensor (temperature, humidity, elevation). These variables are defined by geospatial coordinates and optional extra dimensions (time, altitude, etc.).
131 | 
132 | [width="90%",cols="2,6"]
133 | |===
134 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/group
135 | | A {set:cellbgcolor:#EEEEEE} | A Dataset must be represented by a Zarr group.
136 | | B {set:cellbgcolor:#EEEEEE} | The Zarr group must include the attribute `conformsTo` set to the Dataset requirement class.
137 | | C {set:cellbgcolor:#EEEEEE} | Coordinates, attributes, and any additional information must be represented in the Zarr group or children Zarr objects (see furhter equirements)
138 | |===
139 | 
140 | [width="90%",cols="2,6"]
141 | |===
142 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/coordinate-variable
143 | | A {set:cellbgcolor:#EEEEEE} | Each coordinate variable must include the Climate and Forecast (CF) standard name in the `standard_name` attribute of the Zarr array.
144 | |===
145 | 
146 | [width="90%",cols="2,6"]
147 | |===
148 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/data-variable-coordinates
149 | | A {set:cellbgcolor:#EEEEEE} | Data Variables (coverages) in a dataset should share a common set of coordinates and coordinate reference system.
150 | |===
151 | 
152 | 
153 | **Hierarchy of Zarr Elements**
154 | 
155 | ```mermaid
156 | classDiagram
157 |     class ZarrGroup {
158 |         +attrs (attributes)
159 |     }
160 |     class ZarrArray {
161 |         +attrs (attributes)
162 |     }
163 |     
164 |     ZarrGroup <|-- Dataset : maps to
165 |     ZarrArray <|-- Coordinate : maps to
166 |     ZarrArray <|-- DataVariable : maps to
167 | 
168 |     class Dataset {
169 |     }
170 |     class Coordinate {
171 |     }
172 |     class DataVariable {
173 |     }
174 | 
175 |     Dataset --> ZarrGroup
176 |     ZarrGroup --> "1..*" ZarrArray : contains
177 |     Coordinate --> ZarrArray
178 |     DataVariable --> ZarrArray
179 | ```
180 | 
181 | Below is a representation of a Zarr structure for an abstract Dataset with a single data variable.
182 | 
183 | ```
184 | GeoZarr_Dataset/
185 | ├── .zgroup
186 | ├── attrs.json
187 | ├── data_variable/
188 | │   ├── .zarray
189 | │   ├── attrs.json
190 | │   └── data (chunks)
191 | ├── latitude/
192 | │   ├── .zarray
193 | │   ├── attrs.json
194 | │   └── data (chunks)
195 | ├── longitude/
196 | │   ├── .zarray
197 | │   ├── attrs.json
198 | │   └── data (chunks)
199 | └── time/
200 |     ├── .zarray
201 |     ├── attrs.json
202 |     └── data (chunks)
203 | ```
204 | 
205 | INFO: a coordinate is not necessary a list of positions (labelled coordinates) but might be encoded in different ways further defined.
206 | 
207 | NOTE: We may require or recommend that a Dataset is restricted to a single data variable or to variable with consistent coordinates (otherwise the group is a mess). We might specify also an attribute for a index of variables.
208 | 
209 | 
210 | ===== Data Variables
211 | 
212 | TIP: Defines the requirements for the variables in a dataset (how to specify dimensions and relationship with the coordinates sibling)
213 | 
214 | A Data Variable holds the data values of the observed geospatial phenomena. A variable has a name, type,any dimension, attributes and values.
215 | 
216 | TBD: can/should a data variable have dimensions which are not coordinates
217 | 
218 | [width="90%",cols="2,6"]
219 | |===
220 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/data-variable
221 | | A {set:cellbgcolor:#EEEEEE} | Each data variable (values of a rectified grid coverage) must be stored as a child Zarr array within the dataset group.
222 | | B {set:cellbgcolor:#EEEEEE} | The child Zarr array must include the attribute `_ARRAY_DIMENSIONS` which lists the dimension names.
223 | | C {set:cellbgcolor:#EEEEEE} | For each dimension listed in `_ARRAY_DIMENSIONS`, there must be a corresponding coordinate variable in the dataset group.
224 | |===
225 | 
226 | Each data variable must:
227 | - Be stored as a child Zarr array within the dataset group.
228 | - Include the attribute `_ARRAY_DIMENSIONS` listing the dimension names.
229 | - Have a corresponding coordinate variable for each dimension listed in `_ARRAY_DIMENSIONS` within the dataset group.
230 | 
231 | 
232 | ===== Coordinates
233 | 
234 | TIP: Defines the requirement for the data coordinates and reference to the requirement classes for the different encoding of data coordinate.
235 | 
236 | [width="90%",cols="2,6"]
237 | |===
238 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/coordinate-variable
239 | | A {set:cellbgcolor:#EEEEEE} | Each coordinate variable (representing the positions of one dimension of a data variable) must be represented in a child Zarr array within the dataset group.
240 | | B {set:cellbgcolor:#EEEEEE} | The Zarr array variables must be named with the same name as the dimension of the data variable they represent.
241 | |===
242 | 
243 | Each coordinate variable must:
244 | - Be represented in a child Zarr array within the dataset group.
245 | - Be named with the same name as the dimension of the data variable it represents.
246 | 
247 | [width="90%",cols="2,6"]
248 | |===
249 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/coordinate-variable
250 | | A {set:cellbgcolor:#EEEEEE} | Each coordinate variable must include the Climate and Forecast (CF) standard name in the `standard_name` attribute of the Zarr array.
251 | |===
252 | 
253 | Each coordinate variable should:
254 | - Include the Climate and Forecast (CF) standard name in the `standard_name` attribute of the Zarr array.
255 | 
256 | 
257 | === Coordinates
258 | 
259 | 
260 | ==== Coordinate Types
261 | 
262 | TIP: Defines what are the requirement in GeoZarr related to latitude, longitude, time, etc. metadata such as does it impose to use CF standard names for qualifying the coordinate (or another convention from GDAL)
263 | 
264 | ==== Geospatial Coordinate Encodings
265 | 
266 | There are multiple types of encoding for coordinates, each serving different purposes and applications in geospatial data processing. Some common examples include:
267 | 
268 | * Geospatial Control Points (labeled Coordinates) : each data point or grid cell is explicitly assigned a coordinate value, which can be used to directly map and reference spatial data. 
269 | * Affine Transforms (Coordinate Origin and Step):  this involves defining a starting point (origin) and a regular interval (step) between points. This method is commonly used in grid-based data where the position of each cell is calculated based on its distance from the origin.
270 | 
271 | Proposed encoding:
272 | - 2D array (the nominal encoding applied by xarray)
273 | - origin/offset:
274 | - COARDS :
275 | 
276 | ===== Requirements Class Geospatial_Control_Points
277 | 
278 | Geospatial Control Points (GCPs), also known as Labeled Coordinates, are specific geographic locations with known coordinates. These points serve as reference markers to accurately align and georeference spatial data in mapping and GIS applications, ensuring that the data corresponds correctly to real-world locations.
279 | 
280 | [[req_geozarr-coordinate-labelled]]
281 | [cols="1,4",width="90%"]
282 | |===
283 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
284 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-labelled {set:cellbgcolor:#FFFFFF}
285 | |Target type | Dataset Coordinate
286 | |Dependency | TBD
287 | |===
288 | 
289 | 
290 | ===== Requirements Class CoordinateOriginOffset
291 | 
292 | TIP: It is not supported yet in the model, but this seems relevant to be added.
293 | 
294 | [[req_geozarr-coordinate-oo]]
295 | [cols="1,4",width="90%"]
296 | |===
297 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
298 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-oo {set:cellbgcolor:#FFFFFF}
299 | |Target type | Dataset Coordinate
300 | |Dependency | TBD
301 | |===
302 | 
303 | To accurately represent the spatial dimensions of the dataset, each coordinate type origin offset must be defined in a child Zarr array within the dataset. This array must contain the triplet of values: origin, offset, and end, to describe the coordinate's range and intervals. Additionally, the coordinate variable must include a CF standard name in the `standard_name` attribute, specifically for latitude or longitude.
304 | 
305 | [width="90%",cols="2,6"]
306 | |===
307 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/coordinate-variable
308 | | A {set:cellbgcolor:#EEEEEE} | A coordinate type origin offset should be represented in a child Zarr array of the dataset.
309 | | B {set:cellbgcolor:#EEEEEE} | The coordinate variable must define in the array the triplet of values: origin, offset, end.
310 | | C {set:cellbgcolor:#EEEEEE} | The coordinate variable must provide a standard name (CF) for latitude or longitude in the `standard_name` attribute.
311 | |===
312 | 
313 |  To enhance clarity and interoperability, it is recommended that each coordinate variable link to the `grid_mapping` variable, which describes the CRS applicable to this coordinate.
314 | 
315 | [width="90%",cols="2,6"]
316 | |===
317 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/coordinate-variable
318 | | A {set:cellbgcolor:#EEEEEE} | The coordinate variable should link to the `grid_mapping` variable defined to describe the CRS that applies to this coordinate.
319 | |===
320 | 
321 | The coordinate variable should:
322 | - Link to the `grid_mapping` variable defined to describe the CRS that applies to this coordinate.
323 | 
324 | 
325 | ===== Requirements Class CoordinateVector
326 | 
327 | TIP: please add the definition
328 | 
329 | [[req_geozarr-coordinate-vector]]
330 | [cols="1,4",width="90%"]
331 | |===
332 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
333 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-vector {set:cellbgcolor:#FFFFFF}
334 | |Target type | TBD
335 | |Dependency | TBD
336 | |===
337 | 
338 | 
339 | ==== Coordinates Reference System Encodings
340 | 
341 | TIP: any consideration with projections and affine transformations ?
342 | 
343 | [width="90%",cols="2,6"]
344 | |===
345 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/data-variable-coordinates
346 | | A {set:cellbgcolor:#EEEEEE} | The coordinate reference system (CRS) must be indicated for each data variable (coverage).
347 | | B {set:cellbgcolor:#EEEEEE} | The CRS should be represented in a child Zarr array of the dataset (auxiliary variable).
348 | | C {set:cellbgcolor:#EEEEEE} | The CRS variable name should be referenced in the data variable (coverage) in the `grid_mapping` attribute.
349 | | D {set:cellbgcolor:#EEEEEE} | The CRS should be described in the attributes of the CRS variable using CF conventions properties.
350 | |===
351 | 
352 | Each data variable (coverage) must:
353 | - Indicate the coordinate reference system used.
354 | - Reference the CRS variable name in the `grid_mapping` attribute.
355 | 
356 | The CRS should:
357 | - Be represented in a child Zarr array of the dataset (auxiliary variable).
358 | - Be described in the attributes of the CRS variable using CF conventions properties.
359 | 
360 | While it is recommended that all coverages in a dataset share the same set of coordinates and coordinate reference system to ensure consistency and ease of use, explicitly indicating the coordinate reference system for each data variable is necessary to avoid any ambiguity and to support interoperability when integrating data from diverse sources.
361 | 
362 | TBD explain the grid_mapping and required properties
363 | 
364 | 
365 | === Tiling and Pyramiding
366 | 
367 | TIP: equivalent to GeoTiff (https://docs.ogc.org/is/21-026/21-026.html). GeoZarr should specify if and how tiling might be applied for three-dimensional and higher-dimensional data (for example, order of dimensions might be critical)
368 | 
369 | ==== Requirements Class Tiling
370 | 
371 | [[req_geozarr-tiling]]
372 | [cols="1,4",width="90%"]
373 | |===
374 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
375 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/tiling {set:cellbgcolor:#FFFFFF}
376 | |Target type | Dataset
377 | |Dependency | TBD
378 | |===
379 | 
380 | 
381 | Tiling is a strategy for optimising chunking in GeoZarr. With tiling, access to a specific area or two-dimensional bounding box is much quicker, as the relevant data is stored closer together in the file, reducing the number of bytes that need to be read compared to the strips approach.
382 | 
383 | ==== Requirements Class Pyramiding
384 | 
385 | Pyramiding is useful when the client wants to quickly render an image of the entire area or a large portion of the area represented in the file. Instead of downloading every pixel, the software can request a smaller, pre-created, lower-resolution version.
386 | 
387 | [[req_geozarr-coordinate-pyramiding]]
388 | [cols="1,4",width="90%"]
389 | |===
390 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
391 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-piramidiing {set:cellbgcolor:#FFFFFF}
392 | |Target type | Dataset
393 | |Dependency | TBD
394 | |===
395 | 
396 | 
397 | ==== Requirements Class Map Rendering
398 | 
399 | TIP: in addition to traditional 2D formats, some conventions might be needed to faciltiate the rendering of time series or N-D arrays on map tools. For example, how the bands / layers of the array are referenced, etc.
400 | 
401 | 
402 | ==== Requirement
403 | 
404 | === Referencing in STAC
405 | 
406 | TIP: might be useful to describe or provide extension for referencing GeoZarr assets (e.g. dataset) in STAC Items.
407 | 
408 | == Annex B: Mappings with other formats
409 | 
410 | TIP: Provides the mappings for information purpose to show how source formats can preserve information from any data source.
411 | 
412 | To maximize compatibility with various source formats, GeoZarr preserves as much metadata and structure as possible from these formats.
413 | 
414 | NOTE: In particular, if relevant information which cannot be encoded in GeoZarr is identified, the specification might be extended.
415 | 
416 | === Mappings with CF
417 | 
418 | 
419 | === Mappings with GeoTiff
420 | 
421 | To map a GeoTIFF to the GeoZarr structure, we need to carefully translate the data arrays, coordinate variables, and metadata (such as the CRS) into the appropriate GeoZarr elements. 
422 | 
423 | GeoZarr is structured as a single GeoZarr dataset at the root, encapsulating all necessary components to represent the geospatial data and metadata effectively.
424 | 
425 | - GeoTIFF Data Array to GeoZarr Data Variable: In the case of a single band, the data variable represents a 2D raster with latitude and longitude dimensions. If there are multiple bands, they might be mapped to positions within a band dimension, with coordinates providing the wavelength and standard names indicating the units of measure for those coordinates.
426 | - GeoTIFF Coordinates to GeoZarr Coordinate Variables: Latitude and longitude coordinates are extracted and stored as GeoZarr Coordinate Variables.
427 | - GeoTIFF Metadata to GeoZarr Attributes: Metadata from the GeoTIFF (such as CRS and transform) are stored in the attributes of the GeoZarr Data Varaible. The CRS is translated to an auxiliary variable, referenced from the GeoZarr Data Variable in the grid_mapping attribute.
428 | - GeoZarr Dataset Group for Organizing: All the data variables and coordinate variables are organized within a GeoZarr Dataset Group, ensuring a coherent structure. This group is the root of the GeoZarr hierarchy, making it a self-contained and self-describing dataset.
429 | 
430 | 
431 | === Mappings with GDAL entities
432 | 
433 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_7_format_requirements.adoc:
--------------------------------------------------------------------------------
 1 | == GeoZarr format requirements
 2 | 
 3 | TIP: This is a very preliminary draft. The content is primarily for demonstrating the purpose of the proposed sections. The main focus should be on the table of contents.
 4 | 
 5 | include::clause_7a_format_overview.adoc[]
 6 | 
 7 | === Underlying GeoZarr Requirements
 8 | 
 9 | The requirement class GeoZarr Core is mandatory for all GeoZarr instances and must be specified at the root level with the `conformsTo` attribute.
10 | 
11 | Some requirement classes are optional and define specific type of assets to facilitate standard interpretation by clients, such as a the requirement class Dataset. These optional requirement classes must be specified at the appropriate level within the hierarchy, using the conformsTo attribute to indicate adherence to the respective requirement class.
12 | 
13 | TIP: maybe list possible requirements classes and purpose
14 | 
15 | include::clause_7b_format_core.adoc[]
16 | 
17 | include::clause_7c_format_coordinates.adoc[]
18 | 
19 | include::clause_7d_format_pyramiding.adoc[]
20 | 
21 | include::clause_7e_format_dataset_types.adoc[]
22 | 
23 | include::clause_7_annex_mapping.adoc.adoc[]


--------------------------------------------------------------------------------
/standard/template/sections/clause_7a_format_overview.adoc:
--------------------------------------------------------------------------------
 1 | A GeoZarr data format is a regular Zarr hierarchy that represents geospatial coverages such as granules, scenes series, mosaics or any spatio temporal asset (as per STAC specification).
 2 | 
 3 | === Overview and Definitions 
 4 | 
 5 | The OGC Abstract Topic 6 [OGC 07-011] standard defines all geographic object as a feature, with coverage being a special type for any digital geospatial information representing space and time varying phenomena. The ISO 19123 standard provides a formal definition for coverages: a "feature acting as a function that returns values from its range for any direct position within its spatiotemporal domain". 
 6 | 
 7 | GeoZarr, like many array-oriented geospatial data formats (e.g., NetCDF, GeoTIFF), primarily supports *Rectified Grid Coverages*. Rectified Grid Coverage is a type of grid coverage that aligns with a coordinate reference system, ensuring that each cell or grid point corresponds precisely to a specific geographic location. 
 8 | 
 9 | The base terminology in the scope of this specification includes the following terms:
10 | 
11 | - A *GeoZarr Instance* (or GeoZarr) is a hierarchy of objects including attributes and arrays describing geospatial information.
12 | - A *GeoZarr Data Variable* is the arrray and attributes that define the values of a n-D coverage (i.e. a Rectified Grid Coverage)
13 | - A *GeoZarr Coordinate Variable* is the array (might be empty) and attributes  that define a coordinate dimension of a n-D coverage
14 | - A *GeoZarr Auxiliary Variable* is the array (might be empty) and attributes that define other type of information
15 | - A *GeoZarr Dataset* is a self-describing collection of n-D coverages defined by a set of values, coordinates and attributes (similar to a NetCDF dataset).
16 | 
17 | Unlike some popular geospatial data formats, GeoZarr is not limited to 2D rasters and extends to multiple dimensions, including time, altitude, wavelength, and others. Additionally, the order of these dimensions is not fixed, allowing for optimizations in data analysis.
18 | 
19 | A Dataset (referenced as an asset in a STAC item) facilitates the discovery and handling of the coverages by clients, such as web maps, and supports advanced capabilities such as pyramiding. However,GeoZarr also flexible and adaptable enough to accommodate other types of information: the specification aim to ensure that a transformation to GeoZarr from a source format can be reverted back to the original format.
20 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_7b_format_core.adoc:
--------------------------------------------------------------------------------
  1 | ==== Requirement Class GeoZarr Core
  2 | 
  3 | The base requirement class is designed to be flexible, facilitating conversion from any data source and support most source formats..
  4 | 
  5 | [[req_geozarr-core]]
  6 | [cols="1,4",width="90%"]
  7 | |===
  8 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
  9 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/geozarr-core {set:cellbgcolor:#FFFFFF}
 10 | |Target type | Zarr Encoder
 11 | |Dependency | TBD
 12 | |===
 13 | 
 14 | ===== Structure
 15 | 
 16 | A GeoZarr instance must consist of any Zarr tree structure with a root that is always a Zarr group, include the attribute conformsTo set to the GeoZarr requirement class in the root group, and allow any number of hierarchical levels within the groups.
 17 | 
 18 | [width="90%",cols="2,6"]
 19 | |===
 20 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr/structure
 21 | | A {set:cellbgcolor:#EEEEEE} | A GeoZarr instance (or GeoZarr) must consist of a Zarr tree structure.
 22 | | B {set:cellbgcolor:#EEEEEE} | The GeoZarr root must always be a Zarr group.
 23 | | C {set:cellbgcolor:#EEEEEE} | The root group must include the attribute `conformsTo` set to the GeoZarr requirement class.
 24 | | D {set:cellbgcolor:#EEEEEE} | The GeoZarr instance may have any number of levels within the hierarchy.
 25 | |===
 26 | 
 27 | ===== Variables
 28 | 
 29 | A variable represents an array of values of the same type in a Zarr array. A variable can describe coverage values, their coordinates, or any auxiliary data (i.e., additional information to the coverage). These different types of variables are defined further in the specification.
 30 | 
 31 | [width="90%",cols="2,6"]
 32 | |===
 33 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr/variable
 34 | | A {set:cellbgcolor:#EEEEEE} | A variable represents an array of values of the same type and is stored in Zarr arrays.
 35 | |===
 36 | 
 37 | 
 38 | ===== Attributes
 39 | 
 40 | GeoZarr attributes are used to store ancillary data or metadata at any level of the hierarchy. This information can pertain to variables, coordinates, spatio-temporal assets, or any other relevant purpose.
 41 | 
 42 | [width="90%",cols="2,6"]
 43 | |===
 44 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr/attributes
 45 | | A {set:cellbgcolor:#EEEEEE} | GeoZarr attributes are used to store ancillary data or metadata at any level of the hierarchy.
 46 | | B {set:cellbgcolor:#EEEEEE} | GeoZarr attributes must be encoded as Zarr attributes.
 47 | |===
 48 | 
 49 | ==== Requirement Class GeoZarr Dataset
 50 | 
 51 | [[req_geozarr-dataset]]
 52 | [cols="1,4",width="90%"]
 53 | |===
 54 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 55 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/geozarr-dataset {set:cellbgcolor:#FFFFFF}
 56 | |Target type | Zarr Encoder
 57 | |Dependency | TBD
 58 | |===
 59 | 
 60 | ===== Notion of Dataset
 61 | 
 62 | GeoZarr defines flexible conventions to encode content from various source formats, including geospatial arrays (raster), non-geospatial arrays, and hierarchical structures.
 63 | 
 64 | GeoZarr emphasizes Rectified Grid Coverages, which can be easily discovered, interpreted, and displayed on a map. A coverage is spatial data organized in a regular grid, where each cell holds a value representing a specific geographic area. Examples include 2D Rasters, Raster Time Series, and Geo-Datacubes (with dimensions like time, light spectrum, altitude, etc.).
 65 | 
 66 | A GeoZarr Dataset, consists of a collection of coverage defined by data variables, their common coordinates, and some attributes which together form a self describing dataset and represent a geospatial phenomenon in the data hierarchy.  GeoZarr defines the structure and necessary metadata for understanding this dataset, such as an index of available variables, the projection used, and the coordinates describing the dimensions of these variables.
 67 | 
 68 | The purpose of a GeoZarr Dataset is to maximize compatibility and facilitate the seamless mapping of diverse source formats into a standardized, easily interpretable structure.
 69 | 
 70 | **Figure 1: GeoZarr Dataset Abstract Representation**
 71 | 
 72 | ```mermaid
 73 | classDiagram
 74 |     class Dataset {
 75 |         +attributes
 76 |     }
 77 |     class DataVariable {
 78 |         +values
 79 |         +attributes
 80 |     }
 81 |     class CoordinateVariable {
 82 |         +coordinates
 83 |         +attributes
 84 |     }
 85 |     class AuxiliaryVariable {
 86 |         +data
 87 |         +attributes
 88 |     }
 89 | 
 90 |     Dataset --> "1..*" DataVariable : includes
 91 |     Dataset --> "1..*" CoordinateVariable : includes
 92 |     Dataset --> "0..*" AuxiliaryVariable : includes
 93 |     CoordinateVariable --> DataVariable : coordinates
 94 | ```
 95 | 
 96 | ===== Dataset Structure
 97 | 
 98 | A GeoZarr may include Dataset Groups which consists in n-D variables observed by a sensor (temperature, humidity, elevation). These variables are defined by geospatial coordinates and optional extra dimensions (time, altitude, etc.).
 99 | 
100 | [width="90%",cols="2,6"]
101 | |===
102 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/group
103 | | A {set:cellbgcolor:#EEEEEE} | A Dataset must be represented by a Zarr group.
104 | | B {set:cellbgcolor:#EEEEEE} | The Zarr group must include the attribute `conformsTo` set to the Dataset requirement class.
105 | | C {set:cellbgcolor:#EEEEEE} | Coordinates, attributes, and any additional information must be represented in the Zarr group or children Zarr objects (see furhter equirements)
106 | |===
107 | 
108 | [width="90%",cols="2,6"]
109 | |===
110 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/coordinate-variable
111 | | A {set:cellbgcolor:#EEEEEE} | Each coordinate variable must include the Climate and Forecast (CF) standard name in the `standard_name` attribute of the Zarr array.
112 | |===
113 | 
114 | [width="90%",cols="2,6"]
115 | |===
116 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/data-variable-coordinates
117 | | A {set:cellbgcolor:#EEEEEE} | Data Variables (coverages) in a dataset should share a common set of coordinates and coordinate reference system.
118 | |===
119 | 
120 | 
121 | **Hierarchy of Zarr Elements**
122 | 
123 | ```mermaid
124 | classDiagram
125 |     class ZarrGroup {
126 |         +attrs (attributes)
127 |     }
128 |     class ZarrArray {
129 |         +attrs (attributes)
130 |     }
131 |     
132 |     ZarrGroup <|-- Dataset : maps to
133 |     ZarrArray <|-- Coordinate : maps to
134 |     ZarrArray <|-- DataVariable : maps to
135 | 
136 |     class Dataset {
137 |     }
138 |     class Coordinate {
139 |     }
140 |     class DataVariable {
141 |     }
142 | 
143 |     Dataset --> ZarrGroup
144 |     ZarrGroup --> "1..*" ZarrArray : contains
145 |     Coordinate --> ZarrArray
146 |     DataVariable --> ZarrArray
147 | ```
148 | 
149 | Below is a representation of a Zarr structure for an abstract Dataset with a single data variable.
150 | 
151 | ```
152 | GeoZarr_Dataset/
153 | ├── .zgroup
154 | ├── attrs.json
155 | ├── data_variable/
156 | │   ├── .zarray
157 | │   ├── attrs.json
158 | │   └── data (chunks)
159 | ├── latitude/
160 | │   ├── .zarray
161 | │   ├── attrs.json
162 | │   └── data (chunks)
163 | ├── longitude/
164 | │   ├── .zarray
165 | │   ├── attrs.json
166 | │   └── data (chunks)
167 | └── time/
168 |     ├── .zarray
169 |     ├── attrs.json
170 |     └── data (chunks)
171 | ```
172 | 
173 | INFO: a coordinate is not necessary a list of positions (labelled coordinates) but might be encoded in different ways further defined.
174 | 
175 | NOTE: We may require or recommend that a Dataset is restricted to a single data variable or to variable with consistent coordinates (otherwise the group is a mess). We might specify also an attribute for a index of variables.
176 | 
177 | 
178 | ===== Data Variables
179 | 
180 | TIP: Defines the requirements for the variables in a dataset (how to specify dimensions and relationship with the coordinates sibling)
181 | 
182 | A Data Variable holds the data values of the observed geospatial phenomena. A variable has a name, type,any dimension, attributes and values.
183 | 
184 | TBD: can/should a data variable have dimensions which are not coordinates
185 | 
186 | [width="90%",cols="2,6"]
187 | |===
188 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/data-variable
189 | | A {set:cellbgcolor:#EEEEEE} | Each data variable (values of a rectified grid coverage) must be stored as a child Zarr array within the dataset group.
190 | | B {set:cellbgcolor:#EEEEEE} | The child Zarr array must include the attribute `_ARRAY_DIMENSIONS` which lists the dimension names.
191 | | C {set:cellbgcolor:#EEEEEE} | For each dimension listed in `_ARRAY_DIMENSIONS`, there must be a corresponding coordinate variable in the dataset group.
192 | |===
193 | 
194 | Each data variable must:
195 | - Be stored as a child Zarr array within the dataset group.
196 | - Include the attribute `_ARRAY_DIMENSIONS` listing the dimension names.
197 | - Have a corresponding coordinate variable for each dimension listed in `_ARRAY_DIMENSIONS` within the dataset group.
198 | 
199 | 
200 | ===== Coordinates
201 | 
202 | TIP: Defines the requirement for the data coordinates and reference to the requirement classes for the different encoding of data coordinate.
203 | 
204 | [width="90%",cols="2,6"]
205 | |===
206 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/coordinate-variable
207 | | A {set:cellbgcolor:#EEEEEE} | Each coordinate variable (representing the positions of one dimension of a data variable) must be represented in a child Zarr array within the dataset group.
208 | | B {set:cellbgcolor:#EEEEEE} | The Zarr array variables must be named with the same name as the dimension of the data variable they represent.
209 | |===
210 | 
211 | Each coordinate variable must:
212 | - Be represented in a child Zarr array within the dataset group.
213 | - Be named with the same name as the dimension of the data variable it represents.
214 | 
215 | [width="90%",cols="2,6"]
216 | |===
217 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/coordinate-variable
218 | | A {set:cellbgcolor:#EEEEEE} | Each coordinate variable must include the Climate and Forecast (CF) standard name in the `standard_name` attribute of the Zarr array.
219 | |===
220 | 
221 | Each coordinate variable should:
222 | - Include the Climate and Forecast (CF) standard name in the `standard_name` attribute of the Zarr array.
223 | 
224 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_7c_format_coordinates.adoc:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | 
  4 | === Coordinates
  5 | 
  6 | 
  7 | ==== Coordinate Types
  8 | 
  9 | TIP: Defines what are the requirement in GeoZarr related to latitude, longitude, time, etc. metadata such as does it impose to use CF standard names for qualifying the coordinate (or another convention from GDAL)
 10 | 
 11 | ==== Geospatial Coordinate Encodings
 12 | 
 13 | There are multiple types of encoding for coordinates, each serving different purposes and applications in geospatial data processing. Some common examples include:
 14 | 
 15 | * Geospatial Control Points (labeled Coordinates) : each data point or grid cell is explicitly assigned a coordinate value, which can be used to directly map and reference spatial data. 
 16 | * Affine Transforms (Coordinate Origin and Step):  this involves defining a starting point (origin) and a regular interval (step) between points. This method is commonly used in grid-based data where the position of each cell is calculated based on its distance from the origin.
 17 | 
 18 | Proposed encoding:
 19 | 
 20 | - 2D array (the nominal encoding applied by xarray)
 21 | - origin/offset:
 22 | - COARDS :
 23 | 
 24 | ===== Requirements Class Geospatial_Control_Points
 25 | 
 26 | Geospatial Control Points (GCPs), also known as Labeled Coordinates, are specific geographic locations with known coordinates. These points serve as reference markers to accurately align and georeference spatial data in mapping and GIS applications, ensuring that the data corresponds correctly to real-world locations.
 27 | 
 28 | [[req_geozarr-coordinate-labelled]]
 29 | [cols="1,4",width="90%"]
 30 | |===
 31 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 32 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-labelled {set:cellbgcolor:#FFFFFF}
 33 | |Target type | Dataset Coordinate
 34 | |Dependency | TBD
 35 | |===
 36 | 
 37 | 
 38 | ===== Requirements Class CoordinateOriginOffset
 39 | 
 40 | TIP: It is not supported yet in the model, but this seems relevant to be added.
 41 | 
 42 | [[req_geozarr-coordinate-oo]]
 43 | [cols="1,4",width="90%"]
 44 | |===
 45 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 46 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-oo {set:cellbgcolor:#FFFFFF}
 47 | |Target type | Dataset Coordinate
 48 | |Dependency | TBD
 49 | |===
 50 | 
 51 | To accurately represent the spatial dimensions of the dataset, each coordinate type origin offset must be defined in a child Zarr array within the dataset. This array must contain the triplet of values: origin, offset, and end, to describe the coordinate's range and intervals. Additionally, the coordinate variable must include a CF standard name in the `standard_name` attribute, specifically for latitude or longitude.
 52 | 
 53 | [width="90%",cols="2,6"]
 54 | |===
 55 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/coordinate-variable
 56 | | A {set:cellbgcolor:#EEEEEE} | A coordinate type origin offset should be represented in a child Zarr array of the dataset.
 57 | | B {set:cellbgcolor:#EEEEEE} | The coordinate variable must define in the array the triplet of values: origin, offset, end.
 58 | | C {set:cellbgcolor:#EEEEEE} | The coordinate variable must provide a standard name (CF) for latitude or longitude in the `standard_name` attribute.
 59 | |===
 60 | 
 61 |  To enhance clarity and interoperability, it is recommended that each coordinate variable link to the `grid_mapping` variable, which describes the CRS applicable to this coordinate.
 62 | 
 63 | [width="90%",cols="2,6"]
 64 | |===
 65 | |*Recommendation {counter:rec-id}* {set:cellbgcolor:#CACCCE}|/rec/geozarr-dataset/coordinate-variable
 66 | | A {set:cellbgcolor:#EEEEEE} | The coordinate variable should link to the `grid_mapping` variable defined to describe the CRS that applies to this coordinate.
 67 | |===
 68 | 
 69 | The coordinate variable should:
 70 | - Link to the `grid_mapping` variable defined to describe the CRS that applies to this coordinate.
 71 | 
 72 | 
 73 | ===== Requirements Class CoordinateVector
 74 | 
 75 | TIP: please add the definition
 76 | 
 77 | [[req_geozarr-coordinate-vector]]
 78 | [cols="1,4",width="90%"]
 79 | |===
 80 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 81 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-vector {set:cellbgcolor:#FFFFFF}
 82 | |Target type | TBD
 83 | |Dependency | TBD
 84 | |===
 85 | 
 86 | 
 87 | ==== Coordinates Reference System Encodings
 88 | 
 89 | TIP: any consideration with projections and affine transformations ?
 90 | 
 91 | [width="90%",cols="2,6"]
 92 | |===
 93 | |*Requirement {counter:req-id}* {set:cellbgcolor:#CACCCE}|/req/geozarr-dataset/data-variable-coordinates
 94 | | A {set:cellbgcolor:#EEEEEE} | The coordinate reference system (CRS) must be indicated for each data variable (coverage).
 95 | | B {set:cellbgcolor:#EEEEEE} | The CRS should be represented in a child Zarr array of the dataset (auxiliary variable).
 96 | | C {set:cellbgcolor:#EEEEEE} | The CRS variable name should be referenced in the data variable (coverage) in the `grid_mapping` attribute.
 97 | | D {set:cellbgcolor:#EEEEEE} | The CRS should be described in the attributes of the CRS variable using CF conventions properties.
 98 | |===
 99 | 
100 | Each data variable (coverage) must:
101 | - Indicate the coordinate reference system used.
102 | - Reference the CRS variable name in the `grid_mapping` attribute.
103 | 
104 | The CRS should:
105 | - Be represented in a child Zarr array of the dataset (auxiliary variable).
106 | - Be described in the attributes of the CRS variable using CF conventions properties.
107 | 
108 | While it is recommended that all coverages in a dataset share the same set of coordinates and coordinate reference system to ensure consistency and ease of use, explicitly indicating the coordinate reference system for each data variable is necessary to avoid any ambiguity and to support interoperability when integrating data from diverse sources.
109 | 
110 | TBD explain the grid_mapping and required properties
111 | 
112 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_7d_format_pyramiding.adoc:
--------------------------------------------------------------------------------
  1 | 
  2 | === Tiling and Pyramiding
  3 | 
  4 | TIP: equivalent to GeoTiff (https://docs.ogc.org/is/21-026/21-026.html). GeoZarr should specify if and how tiling might be applied for three-dimensional and higher-dimensional data (for example, order of dimensions might be critical)
  5 | 
  6 | ==== Requirements Class Tiling
  7 | 
  8 | [[req_geozarr-tiling]]
  9 | [cols="1,4",width="90%"]
 10 | |===
 11 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 12 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/tiling {set:cellbgcolor:#FFFFFF}
 13 | |Target type | Dataset
 14 | |Dependency | TBD
 15 | |===
 16 | 
 17 | 
 18 | A GeoZarr Dataset variable might include multiscales for a set of DataArray variables.  Also known as "overviews", multiscales provide resampled copies of the original data at a coarser resolution. Multiscales of the original data thus always hold less detail. Common use cases for multiscales are fast rendering for visualization purposes and analyzing data at multiple resolutions.
 19 | 
 20 | Tiling is a strategy for optimising chunking in GeoZarr. With tiling, access to a specific area or two-dimensional bounding box is much quicker, as the relevant data is stored closer together in the file, reducing the number of bytes that need to be read compared to the strips approach.
 21 | 
 22 | ==== Requirements Class Pyramiding
 23 | 
 24 | Pyramiding is useful when the client wants to quickly render an image of the entire area or a large portion of the area represented in the file. Instead of downloading every pixel, the software can request a smaller, pre-created, lower-resolution version.
 25 | 
 26 | [[req_geozarr-coordinate-pyramiding]]
 27 | [cols="1,4",width="90%"]
 28 | |===
 29 | 2+|*Requirements Class* {set:cellbgcolor:#CACCCE}
 30 | 2+|http://www.opengis.net/spec/GeoZarr/1.0/req/coordinate-piramidiing {set:cellbgcolor:#FFFFFF}
 31 | |Target type | Dataset
 32 | |Dependency | TBD
 33 | |===
 34 | 
 35 | 
 36 | ==== Requirements Class Map Rendering
 37 | 
 38 | TIP: in addition to traditional 2D formats, some conventions might be needed to faciltiate the rendering of time series or N-D arrays on map tools. For example, how the bands / layers of the array are referenced, etc.
 39 | 
 40 | ==== Draft Text
 41 | 
 42 | ===== Multiscales Encoding 
 43 | 
 44 |  Multiscales MUST be encoded in children groups. Data at all scales MUST use the same coordinate reference system and must follow ONE common zoom level strategy. The zoom level strategy is modelled in close alignment to the [OGC Two Dimensional Tile Matrix Set](https://docs.ogc.org/is/17-083r4/17-083r4.html) version 2 and the [Tiled Asset STAC extension](https://github.com/stac-extensions/tiled-assets). Each zoom level is described by a Matrix defining the number, layout, origin and pixel size of included tiles. These tiles MUST correspond to the chunk layout along the two spatial dimensions listed in `_ARRAY_DIMENSIONS` of a given group.
 45 | 
 46 | * Multiscale group name is the zoom level identifier (e.g. '0').
 47 | * Multiscale group contains all DataArrays generated for this specific zoom level.
 48 | * Multiscale chunking is RECOMMENDED to be 256 pixels or 512 pixels for the two spatial dimensions listed in `_ARRAY_DIMENSIONS`.
 49 | 
 50 | ===== Multiscales Metadata
 51 | 
 52 | If implemented, each DataArray MUST define the 'multiscales' metadata attribute which includes the following fields:
 53 | * `tile_matrix_set`
 54 | * `tile_matrix_set_limits` (optional)
 55 | * `resampling_method`
 56 | 
 57 | 
 58 | ====== Tile Matrix Set
 59 | Tile Matrix Set can be:
 60 | * the name of a well know tile matrix set. Well known Tile Matrix Sets are listed [here](https://schemas.opengis.net/tms/2.0/json/examples/tilematrixset/).
 61 | * the URI of a JSON document describing the Tile Matrix Set following the OGC standard.
 62 | * a JSON object describing the Tile Matrix Set following the OGC standard (CamelCase!).
 63 | 
 64 | Within the Tile Matrix Set
 65 | * the Tile Matrix identifier for each zoom level MUST be the relative path to the Zarr group which holds the DataArray variable
 66 | * zoom levels MUST be provided from lowest to highest resolutions
 67 | * the `supportedCRS` attribute of the Tile Matrix Set MUST match the crs information defined under **grid_mapping**.
 68 | * the tile layout for each Matrix MUST correspond to the chunk layout along the two spatial dimensions listed in `_ARRAY_DIMENSIONS` of the corresponding group.
 69 | 
 70 | 
 71 | ====== Tile Matrix Set Limits
 72 | Tile Matrix Sets may describe a larger spatial extent and more resolutions than used in the given dataset.
 73 | In that case, users MAY specify [Tile Matrix Set Limits](https://docs.ogc.org/is/17-083r4/17-083r4.html#toc21) as described in the OGC standard to define the minimum and a maximum limits of the indices for each TileMatrix that contains actual data. However, the notation for tile matrix set does not the JSON encoding as described in the OGC standard but follows the STAC Tile Asset encoding for better readability.
 74 | 
 75 | If used, Tile Matrix Set Limits
 76 | * MUST list all included zoom levels
 77 | * MAY list the min and max rows and columns for each zoom level. If omitted, it is assumed that the entire spatial extent is covered (resulting in higher chunk count of the DataArray).
 78 | 
 79 | ====== Resampling Method
 80 | Resampling Method specifies which resampling method is used for generating multiscales. It MUST be one of the following string values. Resampling method MUST be the same across all zoom levels:
 81 | * nearest
 82 | * bilinear
 83 | * cubic
 84 | * cubic_spline
 85 | * lanczos
 86 | * average
 87 | * mode
 88 | * gauss
 89 | * max
 90 | * min
 91 | * med
 92 | * q1
 93 | * q3
 94 | * sum
 95 | * rms
 96 | 
 97 | ===== Multiscale examples
 98 | =====# Using Well Known Name reference
 99 | 
100 | ```diff
101 | (mandatory items in red, optional items in green)
102 | +{
103 | +  "multiscales":
104 | -       { 
105 | -           "tile_matrix_set": "WebMercatorQuad",
106 | -           "resampling_method": "nearest",
107 | -       }
108 | +}
109 | ```
110 | =====# Using a URI
111 | 
112 | ```diff
113 | (mandatory items in red, optional items in green)
114 | +{
115 | +  "multiscales":
116 | -       { 
117 | -           "tile_matrix_set": "https://schemas.opengis.net/tms/2.0/json/examples/tilematrixset/WebMercatorQuad.json",
118 | -           "resampling_method": "nearest",
119 | -       }
120 | +}
121 | ```
122 | 
123 | ====== Using a JSON object
124 | 
125 | ```diff
126 | (mandatory items in red, optional items in green)
127 | +{
128 | +  "multiscales":
129 | -       { 
130 | -           "tile_matrix_set": {
131 | -               "id": "WebMercatorQuad",
132 | -               "title": "Google Maps Compatible for the World",
133 | -               "uri": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
134 | -               "crs": "http://www.opengis.net/def/crs/EPSG/0/3857",
135 | -               "orderedAxes": [
136 | -                   "X",
137 | -                   "Y"
138 | -               ],
139 | -               "wellKnownScaleSet": "http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible",
140 | -               "tileMatrices": [
141 | -               {
142 | -               "id": "0",
143 | -               "scaleDenominator": 559082264.028717,
144 | -               "cellSize": 156543.033928041,
145 | -               "pointOfOrigin": [
146 | -                   -20037508.3427892,
147 | -                   20037508.3427892
148 | -               ],
149 | -               "tileWidth": 256,
150 | -               "tileHeight": 256,
151 | -               "matrixWidth": 1,
152 | -               "matrixHeight": 1
153 | -               },
154 | -               {
155 | -               "id": "1",
156 | -               "scaleDenominator": 279541132.014358,
157 | -               "cellSize": 78271.5169640204,
158 | -               "pointOfOrigin": [
159 | -                   -20037508.3427892,
160 | -                   20037508.3427892
161 | -               ],
162 | -               "tileWidth": 256,
163 | -               "tileHeight": 256,
164 | -               "matrixWidth": 2,
165 | -               "matrixHeight": 2
166 | -               },
167 | -           }
168 | -           "resampling_method": "nearest",
169 | -       }
170 | +}
171 | ```
172 | =====# Setting limits
173 | 
174 | ```diff
175 | (mandatory items in red, optional items in green)
176 | +{
177 | +  "multiscales":
178 | -       { 
179 | -           "tile_matrix_set": "WebMercatorQuad",
180 | +           "tile_matrix_limits: {
181 | -                "0": {},
182 | -                "1": {
183 | +                    "min_tile_col": 0,
184 | +                    "max_tile_col": 0,
185 | +                    "min_tile_row": 0,
186 | +                    "max_tile_row": 0
187 | -                },
188 | -                "2": {
189 | +                    "min_tile_col": 1,
190 | +                    "max_tile_col": 1,
191 | +                    "min_tile_row": 2,
192 | +                    "max_tile_row": 2
193 | -                }
194 | -        },
195 | -           "resampling_method": "nearest",
196 | -       }
197 | +}
198 | ```
199 | 
200 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_7e_format_dataset_types.adoc:
--------------------------------------------------------------------------------
 1 | == Supported Dataset Types
 2 | 
 3 | TIP: To be done
 4 | 
 5 | 
 6 | This section outlines the specific dataset types supported within this specification, along with additional requirements for each type. Each dataset type has requirements related to data format, metadata, and any unique processing needs.
 7 | 
 8 | === 1. 2D Raster RGB Data
 9 | 
10 | - **Description**: Two-dimensional raster images with RGB channels, primarily for visualisation.
11 | - **Data Format**: Supported formats include `GeoTIFF` and `PNG`.
12 | - **Resolution Requirements**: Minimum resolution of 10m per pixel.
13 | - **Metadata Requirements**:
14 | - RGB Channel Mapping.
15 | - Spatial reference and bounding box.
16 | - **Additional Processing**:
17 | - Multiscale overview generation to support fast rendering at various zoom levels.
18 | 
19 | === 2. 2D Multispectral Data
20 | 
21 | - **Description**: Multiband data that includes spectral information beyond RGB, useful for environmental and remote sensing applications.
22 | - **Data Format**: Supported formats include `NetCDF` and `GeoTIFF` with multiple bands.
23 | - **Band Information**:
24 | - Supported bands, such as Blue, Green, Red, NIR.
25 | - Wavelength range or specifications per band.
26 | - **Metadata Requirements**:
27 | - Spectral resolution and sensor-specific information.
28 | - Spatial reference, bounding box, and temporal extent if time-indexed.
29 | - **Additional Processing**:
30 | - Generation of multiscale overviews.
31 | - Band normalization or calibration to standardize across datasets.
32 | 
33 | === 3. 3D Time Series
34 | 
35 | - **Description**: Multidimensional datasets incorporating spatial (X, Y) and temporal (Z) dimensions for tracking changes over time.
36 | - **Data Format**: Supported formats include `Zarr` and `NetCDF`.
37 | - **Temporal Resolution**: Required intervals, such as daily, weekly, or monthly.
38 | - **Metadata Requirements**:
39 | - Temporal indexing, ideally in ISO 8601 format.
40 | - Spatial reference and bounding box.
41 | - Data provenance, if applicable.
42 | - **Additional Processing**:
43 | - Support for multiscale pyramids to enable fast access and visualization over time.
44 | - Aggregation or summarization of data for efficient handling.
45 | 
46 | 


--------------------------------------------------------------------------------
/standard/template/sections/clause_8_media_types.adoc:
--------------------------------------------------------------------------------
1 | == Media Types for any data encoding(s)
2 | 
3 | A section describing the MIME-types to be used is mandatory for any standard involving data encodings. If no suitable MIME type exists in http://www.iana.org/assignments/media-types/index.html then this section may be used to define a new MIME type for registration with IANA.
4 | 


--------------------------------------------------------------------------------