Document side-by-side examples of JSON used in each demo

[JulieWinchester]

Aleph: https://gist.github.com/JulieWinchester/cb475ae63d0f564fa2868701f17f90e6 Model Viewer: https://gist.github.com/JulieWinchester/bf34bdc567590b64e0adc4119ad07c76 Voyager: https://gist.github.com/JulieWinchester/6529d1ff0fcbac0d15efdd183882a773 X3D: https://gist.github.com/JulieWinchester/9607f88f2150afe0d0f147bff5bd2e9f

[JulieWinchester]

Documentation and comparison of viewer demo JSON examples

Aleph

• Confirmed Y up, right-handed
• Annotation position coordinates are included.
  • Position coordinates are specified relative to world space origin. In the specific Aleph demo implementation, the astronaut model’s origin is placed at the viewer’s world space origin, and therefore in this specific case the annotation coordinates are also relative to the model origin as well.
  • Coordinate values and ordering are functionally identical to Model Viewer and X3D
  • Coordinate values are specified as a string with three values, with values split by space separators
• Annotation normal coordinates are included.
  • Normal coordinates specify a unit-length vector which, unlike other demos, seems to have no effect at all on either annotation point or label display.
  • Coordinate values and ordering are functionally identical to Aleph and X3D.
  • Coordinate values are specified as a string with three values split by space separators.
• Other notes:
  • Default view target is center of model, and entire model is encompassed. It is not possible to translate the model out of the initial view frame using the demo.
  • Model is placed such that its coordinate origin matches the world space origin. This causes the provided annotation coordinates to also be relative to model origin.

Model Viewer:

• Confirmed Y up, right-handed
• Annotation position coordinates are included.
  • Position coordinates are specified relative to model coordinate space (https://modelviewer.dev/examples/annotations/index.html).
  • Coordinate values and ordering are functionally identical to Aleph and X3D.
  • Coordinate values are specified as a string with three values split by space separators.
• Annotation “normal” coordinates are included.
  • Normal coordinates specify a unit-length vector that determines whether to display the annotation label - show when normal is toward the camera view, hide when normal is away from the camera view.
  • Vector magnitude does not matter, only direction.
  • Coordinate values and ordering are functionally identical to Aleph and X3D.
  • Coordinate values are specified as a string with three values split by space separators.
  • Unlike some other demos, the normal vector does not affect the placement of the annotation label at all.
• Have not yet investigated normals deeply
• Viewer Notes:
  • Default view target is center of model, and entire model is encompassed. It is not possible to translate the model out of the initial view frame using the demo.

X3D:

• Confirmed Y up, right-handed
• Annotation position coordinates are included.
  • Position coordinates are specified relative to a “frame” space coordinate origin, which has been off-set from world space (see Other notes). The model is also placed relative to this frame space. Therefore, both the model and the annotations are specified using independent coordinate sets, but in practice, the annotation position coordinates are effectively “relative” to the model’s local origin. This would of course stop being the case if the model were to be transformed relative to the frame space.
  • Coordinate values and ordering are functionally identical to Aleph and Model Viewer.
  • Coordinate values are specified as an array with three elements.
• Annotation normal coordinates are included.
  • Normal coordinates specify a near-unit-length vector that determines the placement of the “anchor” of an annotation label. The vector seems to be near unit-length and not unit-length exactly due to rounding off individual coordinates at 3 significant digits compared to Aleph and Model Viewer demos.
  • The magnitude of the vector determines the length of a connector bar between the position coordinate and the label anchor. The direction of the vector is the direction of the connector bar, and affects the directional placement of the label anchor.
  • Coordinate values and ordering are functionally identical to Aleph and X3D.
  • Coordinate values are specified as an array of three elements.
  • The vector described is not normalized to unit length - in other words, annotation label connector distance can be modified.
  • Unlike other demos, the normal vector is not used for determining annotation point or label display. Points and labels are always displayed.
• Other notes:
  • Default view is centered on world space coordinate origin. In other words, it is possible to translate the model out of the initial view frame using the demo.
  • In this demo, the viewer establishes a relative “frame” space with world space coordinate origin at (0, -1, 0). Since the model “stands atop” coordinate origin and is roughly 2 units tall, this places the center of the model at world space (0, 0, 0) and makes the approximate center of the model the target for the view camera. Annotations are placed relative to the frame space coordinate origin, which is the same as the model origin.

Voyager:

• Confirmed Y up, right-handed
• Annotation position coordinates are included.
  • Position coordinates are specified relative to world space origin.
  • Coordinate ordering is identical to Aleph, Model Viewer, and X3D.
  • Coordinate values are specified as an array with three elements.
  • Coordinate values seem quite different from other demos, but this is only because of them being specified with world-space positions matching to a transformed model (see Other Notes). Adding the annotation coordinates to the reverse of the model translation gives (0.0142194, 1.7889915, 0.3438864) for the visor annotation, and (0.5040075, 0.9569079, 0.127869) for the glove annotation. These are close (though not identical) to coordinate values in the other demos.
• Annotation direction coordinates are included.
  • Direction coordinates specify a unit-length vector that determines the directional placement of an annotation label (relative to the position coordinate, which the label points at) as well as the normal direction for determination of whether to display the annotation label.
  • Only the direction of the vector seems to matter, not the magnitude. The distance from the annotation position to the label seems fixed, and is not affected by the magnitude of this vector.
  • Coordinate values are specified as an array of three elements.
  • Values are close (but not identical) to normal coordinates specified by other demos.
• Other notes:
  • In the specific demo implementation, the model is itself translated with (0, -1.0054235, 0.0061665).
  • This is the only demo JSON with configurable cameras, lights, etc.
  • It is possible to modify this demo, removing the translation from the astronaut model and using the same annotation position and direction coordinates that other demos use. It seems equivalent to original Voyager demo is more directly comparable to the other demos.