Choosing the Right Pixel Type

Responding to requirements phrased in the project the range type in coverages has been extended in rasdaman. As this is a new feature it is documented here to ease understanding and use.

Of particular interest are the components:

• field name: the record component name under which range values are known and can be extracted, such as $c.red in WCPS; this must follow the usual syntax conventions of program variable names
• definition: the technical data type (int, float, etc.), expressed through OGC URIs as OGC requires
• description: a human-readable text explaining the meaning
• nil values, as pairs of reason (some text) and a value (taken from the data type definition, see above)
• unit of measure: OGC has no guidance on this; earlier UCUM was used, but it appears inconvenient. In Fairicube QUDT seems preferred - more to come once agreed, stay tuned. This has been clarified in Correct provision of rangeType #8, SWE Common clearly specifies use of UCUM

Note: several of the definitions listed above are incorrect. Please refer to the OGC® SWE Common Data Model Encoding Standard for correct definitions

Importantly, datacubes (as data in general) fall into one of several different categories, as statistics teaches: numerical, categorial and ordinal (not supported now),. SWE Common (upon which the coverage range type relies) supports that halfways, therefore an activity is planned to reflect these categories in a statistically correct way in the OGC/ISO coverage standards.

XML Range Type

In XML, the complete range type structure is as in the following example:

<gmlcov:rangeType>
    <swe:DataRecord>
        <swe:field name="red">
            <swe:Quantity definition="http://www.opengis.net/def/dataType/OGC/0/unsignedByte">
                <swe:label>red</swe:label>
                <swe:description>Band 1 description</swe:description>
                <swe:nilValues>
                    <swe:NilValues>
                        <swe:nilValue reason="I don't know">25</swe:nilValue>
                    </swe:NilValues>
                </swe:nilValues>
                <swe:uom code="10^0"/>
            </swe:Quantity>
        </swe:field>
        <swe:field name="...">...</swe:field>
    </swe:DataRecord>
</gmlcov:rangeType>

Note: the structure presented above, while syntactically correct, is semantically incorrect. Please see the description of rangeType encoding for both Quantities and Categories

Import: How to design the ingredients file

• See official document of rasdaman enterprise https://doc.rasdaman.org/05_geo-services-guide.html#slicer-section
• Setting observationType- Set the output type in GML format of a band in SWE standard. If omitted, then it set to numerical by default. Valid values are: numeric (in GML showed as swe:Quantity) and categorial (in GML showed as swe:Category).
• Setting definition - Metadata definition of the band, typically it is a URL pointing to online registries, ontologies or dictionaries. If omitted, petascope sets the value to the URL corresponding to band’s data type.
• nilValue - Metadata null value of the band; used in case band has only one null value. This setting and nilValues are exclusive, only one can be specified. If default_null_values setting is specified, then nilValue* settings are ignored.
• nilReason - Metadata reason for the null value of the band;
• nilValues - Array of null value objects (used in case the band has more than one null values) with each object contains:
  • value - Metadata null value of the band
  • reason - Metadata reason for the null value of the band This setting and nilValue are exclusive, only one can be specified. If default_null_values setting is specified, then nilValue* settings are ignored.
• uomCode - Set the Unit of measurement (uom) code of the band. Note: only valid for swe:Quantity.

Examples of general_coverage recipe in wcst_import to import a 2D coverage with 2 bands in swe:Quantity and 1 band in swe:Category.

        "slicer": {
          "type": "gdal",
          "bands": [
            {
              "name": "red",
              "identifier": "red",
              "observationType": "numeric",
              "nilValue": 25,
              "nilReason": "The reason for null values are because of some missing pixels",
              "description": "Band 1 description"
            }, {
              "name": "green",
              "identifier": "green",
              "observationType": "categorial",
              "definition": "Band 2 definition which is an attribute",
              "nilValues": [
                  {
                    "reason": "This is an example of null values as a range",
                    "value": "25:35"
                  },
                  
                  {
                    "reason": "This is an example of null values as a value",
                    "value": "57"
                  }
              ]
            }, {
              "name": "blue",
              "identifier": "blue"
            }
          ],
          "axes": {
            "j": {
              "min": "${gdal:maxY}",
              "max": "${gdal:minY}",
              "resolution": "-1"
            },
            "i": {
              "min": "${gdal:minX}",
              "max": "${gdal:maxX}",
              "resolution": "${gdal:resolutionX}"
            }
          }
        }

FC-Specific Metadata

FC has requested further metadata which do not fit the OGC range type definition. These FC-specific metadata go into the metadata bag of the coverage. To this end, a separate schema has been developed with an FC schema location (tbd - see this issue.

See the project schema repository (still to be established) and a concrete example.