[x3d-public] candidate geoSystem correction to JSON schema

John Carlson yottzumm at gmail.com
Mon May 22 15:36:55 PDT 2017


Thanks again for your good work.  We’ll see if we can write a code generator for the Schema(Jeff is a bit indisposed).  I trust that this is being incorporated into the Object Model?

John

Sent from Mail for Windows 10

From: Roy Walmsley
Sent: Monday, May 22, 2017 6:12 PM
To: 'John Carlson'; 'Don Brutzman'
Cc: 'X3D Graphics public mailing list'
Subject: RE: [x3d-public] candidate geoSystem correction to JSON schema

John,


Agreed, the problem was the “N”. However, the JSON schema was not conforming to the requirements of the standard for the geoSystem field, and so needed fixing. While it does not solve the “N” problem, I believe it does now conform to the standard for this field.

Roy

From: John Carlson [mailto:yottzumm at gmail.com] 
Sent: 22 May 2017 22:57
To: Roy Walmsley <roy.walmsley at ntlworld.com>; 'Don Brutzman' <brutzman at nps.edu>
Cc: 'X3D Graphics public mailing list' <x3d-public at web3d.org>
Subject: RE: [x3d-public] candidate geoSystem correction to JSON schema

Roy, I think you may be doing a lot of unnecessary work, but thanks for it.  The problem was the “N,” I believe.

John

Sent from Mail for Windows 10

From: Roy Walmsley
Sent: Monday, May 22, 2017 5:51 PM
To: 'John Carlson'; 'Don Brutzman'
Cc: 'X3D Graphics public mailing list'
Subject: RE: [x3d-public] candidate geoSystem correction to JSON schema

Hi,

Following my earlier posting concerning the geoSystem field of geospatial nodes, and the JSON schema for validation, I have now updated the JSON schema file x3d-3.3-JSONSchema.json and committed it to SourceForge. The revision number is 25271.

I tested this new version of the schema with a sample JSON file containing one example of all the legal ordering possibilities. The file listing was:

{ "X3D": {
    "@profile":"Immersive",
    "@version":"3.3",
    "@xsd:noNamespaceSchemaLocation":"http://www.web3d.org/specifications/x3d-3.3.xsd",
    "encoding": "UTF-8",
    "Scene": {
        "-children":[
        {"GeoViewpoint": {"@geoSystem": ["GD"]}},
        {"GeoViewpoint": {"@geoSystem": ["GDC"]}},
        {"GeoViewpoint": {"@geoSystem": ["GD","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["GDC","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["GD","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["GDC","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["GD","AM","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["GDC","AM","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["GD","WGS84","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["GDC","WGS84","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","S"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","S","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","S","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","AM","S"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","AM","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","WGS84","S"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","WGS84","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","S","AM","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","S","WGS84","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","AM","S","WGS84"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","AM","WGS84","S"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","WGS84","S","AM"]}},
        {"GeoViewpoint": {"@geoSystem": ["UTM","Z1","WGS84","AM","S"]}},
        {"GeoViewpoint": {"@geoSystem": ["GC"]}},
        {"GeoViewpoint": {"@geoSystem": ["GCC"]}}
      ]
    }
  }
}

This file successfully validated against the new version of the JSON schema.

For the record, the variable ordering of the optional arguments for the UTM spatial reference frame was accomplished with five additional subschemas. The full validation of the geoSystem field required, in total, nine subschemas.

All the best,

Roy

From: x3d-public [mailto:x3d-public-bounces at web3d.org] On Behalf Of Roy Walmsley
Sent: 22 May 2017 17:03
To: 'John Carlson' <yottzumm at gmail.com>; 'Don Brutzman' <brutzman at nps.edu>
Cc: 'X3D Graphics public mailing list' <x3d-public at web3d.org>
Subject: Re: [x3d-public] candidate geoSystem correction to JSON schema

Hi,

Let us look at the geoSystem field in detail. The relevant clause is ISO/IEC 19775-1 25.2.3 Specifying a spatial reference frame (see http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geodata.html#Specifyingaspatialreference). The first paragraph of this clause reads:

“All the X3D nodes that allow inclusion of geographic coordinates support a field called geoSystem. This field is used to specify the particular spatial reference frame that will be used for the geospatial coordinates in that node. This is an MFString field that can include a number of arguments to fully designate the spatial reference frame. Each argument appears in a separate string within the MFString array. Argument matching is case sensitive. Optional arguments may appear in any order. The following values are supported.”

What does this tell us? And what doesn’t it tell us? Here goes:
• geoSystem is an MFString field
• It specifies the particular spatial reference frame
• It says that three values are supported, namely “GD”, “UTM” and “GC”
• It says the optional arguments may appear in any order
• It does not specifically state that any arguments are mandatory

The subsequent three bullet points list the supported values. We’ll look at each of them in turn, in a moment. First, we should refer to clause 25.2.2 Spatial reference frames (see http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geodata.html#Spatialreferenceframes). Table 25.2 lists the same three supported spatial reference frames. However, the first sentence of the text in the paragraph immediately following Table 25.2 reads as follows:

“The code GDC shall be synonymous to GD and the code GCC shall be synonymous to GC.”

We have to take account of the synonyms.

One further point is from the last paragraph of 25.2.3, which reads:

“If no geoSystem field is specified, the default value is [ "GD", "WE" ].”

So, I started the JSON schema definition for this field with the presumed requirement that the first string value is required, and must be one of the supported values, or synonyms. Since, as we shall see, that the three spatial reference frame types have rather different additional arguments, I decided to take the “oneOf” approach, dealing with each type separately. Let’s take the first type, “GD”, which has the synonym  “GDC”. The first bullet point in 25.2.3 reads:

“"GD" - Geodetic spatial reference frame (latitude/longitude). An optional argument may be used to specify the ellipsoid using one of the ellipsoid codes that are defined in Table 25.3. If no ellipsoid is specified, then "WE" is assumed (i.e., the WGS84 ellipsoid). An optional "WGS84" string can be specified if you wish all elevations to relative to the WGS84 geoid (i.e., mean sea level) (see Table 25.4); otherwise, all elevations will be relative to the ellipsoid. An example spatial reference frame definition of this format is [ "GD", "WD" ], for a geodetic spatial reference frame based upon the WGS72 ellipsoid with all elevations being relative to that ellipsoid.”
And this tell us:
• There is an optional argument to specify one of the ellipsoids from Table 25.3.
• An optional “WGS84” can be specified if all elevations are to be relative to the WGS84 geoid.

Here’s my JSON schema expanded to show this spatial reference frame type:



Does it conform? Let’s see:
• The array is constrained to contain from one to three strings
• The first string in the array, which is required has two enumerations, namely “GD” and “GDC”, so the synonym is present.
• The second string in the array, which is optional, is an enumeration for all 23 of the supported earth ellipsoids from table 25.3.
• The third string in the array, which is also optional, can only take the value “WGS84”
• The array fails to allow for the optional arguments to appear in any order

No, it does not conform. However, this can be rectifies fairly easily, by adding an additional subschema, whereby the optional “WGS84” is the second string, and the list of 23 supported earth geoids. Now, this section consists of two subschemas, as follows:



Now, let’s turn to the second supported spatial reference frame type. This is “UTM”. The second bullet point of 25.2.3 reads:

“"UTM" - Universal Transverse Mercator. One further required argument must be supplied for UTM in order to specify the zone number (1..60). This is given in the form "Z<n>", where <n> is the zone number. An optional argument of "S" may be supplied in order to specify that the coordinates are in the southern hemisphere (otherwise, northern hemisphere will be assumed). A further optional argument may be used to specify the ellipsoid using one of the ellipsoid codes that are defined in Table 25.3. If no ellipsoid is specified, then "WE" is assumed (i.e., the WGS84 ellipsoid). An optional "WGS84" string can be specified if you wish all elevations to relative to the WGS84 geoid (i.e., mean sea level (see Table 25.4)); otherwise, all elevations will be relative to the ellipsoid. An example spatial reference frame definition of this format is [ "UTM", "Z10", "S", "GD" ], for a southern hemisphere UTM spatial reference frame in zone 10 with all elevations being with respect to mean sea level.”

The salient points are:
• The second string is a required argument, and must be a zone number of the form “z<N>”, where the “<n>” is the zone number, from one to sixty, inclusive. 
• An optional argument “S” may be supplied to indicate southern hemisphere. Note that the use of an “N” is not permitted.
• A further optional argument to specify one of the ellipsoids from Table 25.3.
• An optional “WGS84” can be specified if all elevations are to be relative to the WGS84 geoid.

Here’s my JSON schema expanded to show this spatial reference frame type:



Does it conform? Let’s see:
• The array is constrained to contain from one to five strings. This fails because the second string is required.
• The first string in the array can only take the value UTM.
• The second string in the array, which is optional, can take any one of the 60 zone number values.
• The third string in the array, which is optional, can only take the value “S”.
• The fourth string in the array, which is optional, is an enumeration for all 23 of the supported earth ellipsoids from table 25.3.
• The fifth string in the array, which is also optional, can only take the value “WGS84”
• The array fails to allow for the optional arguments to appear in any order.

So this fails on two counts. The first failure, not making the zone number required, is easy to fix. The array constraints should be changed to contain from two to five strings. The second failure, the appearance of the optional arguments in any order, could be fixed in a similar manner to the first case above, introducing additional subschemas. For this instance, as many as nine might be required. This would take careful consideration of all possible combinations, bearing in mind that any, or even all, of the three optional arguments could be absent. I will try to solve this problem at a later date.

Finally let’s consider the third case. The final bullet point from 25.2.3 reads:

“"GC" - Earth-fixed Geocentric with respect to the WGS84 ellipsoid. No additional arguments are supported. An example spatial reference frame definition of this format is [ "GC" ].”

This is straightforward, since no additional arguments are supported. The only consideration required is the synonym. Here is the expanded JSON schema for this:


Now we see that only one string is permitted in the array, and it has the two possible values “GC” and “GCC” as required. This conforms to the requirements.

Before closing this discussion I should point out that the lack of support for an optional “N” value for the UTM reference frame has been raised before. This is covered in Mantis issue 938 (see http://www.web3d.org/member-only/mantis/view.php?id=938). Candidate resolutions have been proposed, but none firmly decided upon. This means that those geospatial examples in the archive, such as Squaw LOD 029 (http://www.web3d.org/x3d/content/examples/Basic/Geospatial/SquawLOD029Index.html) do not conform to V3.3. In fact, this particular example is against V3.0 of the standard. However, the wording is technically identical, therefore this does not conform to V3.0 either.

Since neither the DTD nor the XML schema have sufficient expressive power to validate the individual string values, these errors have probably not been picked up before. I don’t know what level of checking is built into the current version of the schematron. I did run this particular example on the X3D validator, and it passed all tests. The development of the JSON schema, with this very strong validation capability, has now exposed these issues.

All the best,

Roy



From: John Carlson [mailto:yottzumm at gmail.com] 
Sent: 21 May 2017 02:29
To: Don Brutzman <brutzman at nps.edu>; Roy Walmsley <roy.walmsley at ntlworld.com>
Cc: X3D Graphics public mailing list <x3d-public at web3d.org>
Subject: RE: [x3d-public] candidate geoSystem correction to JSON schema

Don, try this Schema.  These are my modifications.  Note that I don’t have some of the required @name fields yet in this schema.  They will need to be added.  Also, are IMPORTs up to date?

Will provide an update when ready.

Thanks,

John

Sent from Mail for Windows 10

From: Don Brutzman
Sent: Saturday, May 20, 2017 8:57 PM
To: Roy Walmsley
Cc: X3D Graphics public mailing list
Subject: [x3d-public] candidate geoSystem correction to JSON schema

JSON Schema sayeth

"@geoSystem": {
                "description": "Attempts to validate all possible combinations",
                "oneOf": [
                                {
                                                "type": "array",
                                                "minItems": 1,
                                                "maxItems": 3,
                                                "items": [
                                                                {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                                "GD",
                                                                                                "GDC"
                                                                                ],
                                                                                "default": "GD"
                                                                },

while in X3D abstract specification:

25.2.2 Spatial reference frames
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geodata.html#Spatialreferenceframes

Table 25.2 — Supported spatial reference frames

lists GD GC UTM and is followed by special cases GDC and GCC.

Suggest adding enumeration values for "GC", "GCC", "UTM"

However I do see other entries further down for "UTM" and default "GD" (though GD is not also listed there as an enum value).

Example scene for testing is Squaw.x3d with Squaw.json including

                "@geoSystem":["UTM","Z10","N"],

Also Mars.x3d and Mars.json with recent updates at

                http://www.web3d.org/x3d/content/examples/Basic/Geospatial/

Not quite sure how you are handling things there, hope you can sort it out OK.  TIA.

all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman

_______________________________________________
x3d-public mailing list
x3d-public at web3d.org
http://web3d.org/mailman/listinfo/x3d-public_web3d.org



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170522/e03c6e7f/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 28593 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170522/e03c6e7f/attachment-0004.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image002.png
Type: image/png
Size: 35481 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170522/e03c6e7f/attachment-0005.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 26686 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170522/e03c6e7f/attachment-0006.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image004.png
Type: image/png
Size: 19029 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170522/e03c6e7f/attachment-0007.png>


More information about the x3d-public mailing list