Various Typos

[mmccool]

I did a close read of the spec (version 21-056r5) and noticed some typos that you probably want to fix. I have some more general comments but in this issue I will focus on things that I'm pretty sure are just editorial mistakes:

• [x] p9, "fsuch" -> "such"
• [x] p10, "shall choose to implement one of the eight" -> "shall choose to implement one or more of the eight" (ok, this one is not really a typo, just that when I first read it sounded like it meant "one and only one" which is not the intended meaning)
• [x] p12, two references to JSON Schema version 9 (2 and 14). Is this intended?
• [x] p13 "[ref]" -> missing reference to UML spec, which did not seem to appear in the list on p12
• [x] p15, in definition of "frame graph": "This is by design, even though... and the same inner frame." I read this sentence over and over and could not find the verb or parse the meaning. I suspect a word is missing somewhere, or perhaps a comma between "single transforms" and "between" (then "transforms" is the verb? Anyhow, confusing)
• [x] p15, "Inter-pose duration": there seem to be missing words at the end of this definition.
• [x] p16, end of section 4.2: there is a long paragraph written in the first person, using "I", starting with "I know from my...". Who is "I"?
• [x] p17, "valid time": "instants" is at the start of a sentence and should be capitalized.
• [x] p26, "package.The" a space seems to be missing.
• [x] p31, Figure 13, "IntergirtyCheck" -> "IntegrityCheck". Actually, both appear in different classes, but only the latter is correct. If this figure is generated from a UML spec, it's possible the error appears in the normative UML file.
• [x] p57, in American English, which most SW specs use, "modelling" should be "modeling". I know, it looks weird to me too, but apparently that's the American spelling. In the "description" of the example
• [x] p85: Abstract Test 11 and 16. Names include the word "quaternion", but description is for YPR. In fact there does not seem to be a test for YPR. I suspect there needs to be two separate tests, one for quaternions (for instance, to check that they are "close enough" to unit norm) and one for YPR.
• [x] p88, Abstract Test 27, "GeoPoseduration" -> "GeoPoseDuration" (I assume)
• [x] p94, "XXX". Exciting, but surprising to see in a specification! I assume this is a blank that was not filled in. Not sure if the last bit in this sentence is also an unfilled blank or is supposed to be a template, pls clarify.
• [x] p98, "Annex D", seems incomplete. Maybe just replace with a reference if you don't have time for a writeup.
• [x] p99, E.1: "inegral" -> "integral" E.2 would also be a good place to mention 64-bit integers are needed for time (see below).

Other comments that are not technically typos, but places where clarity could be improved:

• [x] a 64-bit integer is needed for Unix time to avoid overflow (which would have already happened since you are using ms) but "long" is used in the spec. Technically JSON implementations are supposed to support ints of arbitrary length but I would not build a house on that. I think it would be safer to use something like "uint64_t" or at least add a comment somewhere on page 28 saying that a 64-bit integer (signed is ok) is the minimum or something like that. Abstract Test 17 should probably do some sanity checking to make sure that round-trip encoding/decoding works.
• [x] p33. Inconsistent use of "real number", no clarity on whether signs are used. For example, I assume degrees used for YPR are also (signed) real numbers. Stating lat and long are signed would also be useful, because I know in some specs "EW" and "NS" are used (and stating for clarity which side is positive would also be helpful if you want to be totally clear).
• [x] p36, "as close to 1.0 as the real number representation allows". What representation? IEEE single precision? IEEE double precision? As an implementer, I would probably not trust the JSON encoding and would just renormalize quaternions before using them anyway...
• [x] p33. What unit is "h" in? I could not find it anywhere. I'm assuming meters, but others might assume feet. I think buried later in the spec there is a formal reference but putting the unit in the definition on p33 would be helpful (and perhaps the reference)
• [x] p59 and onwards: I was surprised to see a bunch of "parameters" packed into a string in the examples without definitions of where they came from, and by the fact they were inconsistent in naming with the rest of the spec (e.g. "rotation" instead of "angles" or "quaternion".) It was only much later in the spec I realized these were parameters defined in other standards. Mentioning this earlier would be helpful.
• [x] p69: the "integrityCheck" is a SHA-256 checksum, not "just" a string. A little bit more detail in the definition would be helpful, even just a comment/description if you can't provide a formal type. Also a description of how the checksum is computed would be helpful: is it on the raw string? After conversion to JCS form? Do you leave out the checksum object, or use an empty string for it? Etc.

[3DXScape]

Added to the public review comments. These are very insightful. Combining in workflow with the other open Public Review Comments.

[cperey]

This is the PDF with comments and feedback from Michael (handwritten comments via reMarkable) Michael McCool's feedback to draft GeoPose standard.pdf

[3DXScape]

The note on page 16 was a note to myself regarding more detail for a later better treatment of transition model. I copied it here to prserve the info and deleted it from the document:

[NOTE] Poses always represent the position and orientation of a real or virtual physical entity. There is temporal continuity of pose for any such entity. On the other hand, there is no condition on consecutive poses in a sequence. There are two causes. First, the poses themselves may be representative of a physical object only at the instant assigned to the pose. Consider a service that provides a sequence of predicted timed poses of a camera that would observe a satellite flare (specular reflection of sunlight) for a specific satellite at a specific earth location. Poses between the member poses of the sequence are meaningless. Second, the sampling of poses may not support computation of intermediate poses. Consider poses that are sampled at a rate much slower than the rate of change of the pose of an underlying externally controlled (such as an airplane controlled by a pilot) physical entity. The sampled poses do not constrain or otherwise provide computational control for estimating intermediate poses. Alternatively, the provider of the sequence may declare via metadata whether it is possible and/or reasonable to compute intermediate poses. The provider is in a position to know this information, which may be binary: "none" => the data do not support the computation of intermediate poses or "interpolate" => the data do support the computation of intermediate poses - though the method is not prescribed. These are the two values in the enumeration in the LM TransitionModel datatype. I know from my experience with the "fair fight" issue in distributed simulations that there are a lot of possibilities in defining how to interpolate and these are themselves as complex as GeoPose. That's why I suggest postponing definition of more comprehensive metadata to a later version but leaving this as an enumeration that we can expand to include additional possibilities beyond the binary "none" and "interpolate".

[3DXScape]

p 57 modelling is generated by code - will change if feasible p 85 - all of the quaternion tests had the same problem p 94 Already gone 64-bit time value - this is a typo 64-bit was intended and fixed as such now