rename screenPosition to canvasPosition (#3932)

* rename screenPosition to canvasPosition

* fixed broken link

* fixed type declaration

Author: elalish

packages/model-viewer/src/features/annotation.ts

@@ -30,15 +30,15 @@ const worldToModel = new Matrix4();
 const worldToModelNormal = new Matrix3();
 
 export declare type HotspotData = {
-  readonly position: Vector3D;
-  readonly normal: Vector3D;
-  readonly screenPosition: Vector3D;
-  readonly facingCamera: boolean;
+  position: Vector3D,
+  normal: Vector3D,
+  canvasPosition: Vector3D,
+  facingCamera: boolean,
 }
 
 export declare interface AnnotationInterface {
   updateHotspot(config: HotspotConfiguration): void;
-  queryHotspot(name: string): HotspotData | null;
+  queryHotspot(name: string): HotspotData|null;
   positionAndNormalFromPoint(pixelX: number, pixelY: number):
       {position: Vector3D, normal: Vector3D, uv: Vector2D|null}|null
 }
@@ -136,7 +136,7 @@ export const AnnotationMixin = <T extends Constructor<ModelViewerElementBase>>(
      * This method returns in-scene data about a requested hotspot including
      * its position in screen (canvas) space and its current visibility.
      */
-    queryHotspot(name: string): HotspotData | null {
+    queryHotspot(name: string): HotspotData|null {
       const hotspot = this[$hotspotMap].get(name);
       if (hotspot == null) {
         return null;
@@ -159,18 +159,15 @@ export const AnnotationMixin = <T extends Constructor<ModelViewerElementBase>>(
       vector.x = (vector.x * widthHalf) + widthHalf;
       vector.y = -(vector.y * heightHalf) + heightHalf;
 
-      const screenPosition = toVector3D(
-        new Vector3(
-          vector.x,
-          vector.y,
-          vector.z
-        ));
+      const canvasPosition =
+          toVector3D(new Vector3(vector.x, vector.y, vector.z));
 
-      if (!Number.isFinite(screenPosition.x) || !Number.isFinite(screenPosition.y)) {
+      if (!Number.isFinite(canvasPosition.x) ||
+          !Number.isFinite(canvasPosition.y)) {
         return null;
       }
 
-      return {position, normal, screenPosition, facingCamera};
+      return {position, normal, canvasPosition, facingCamera};
     }
 
     /**

packages/model-viewer/src/test/features/annotation-spec.ts

@@ -97,18 +97,22 @@ suite('Annotation', () => {
     });
 
     test('querying it returns valid data', () => {
-
-      // to test querying, place hotspot in the center and verify the screen position is 
-      // half the default width and height (300 x 150) with a depth value of ~1.
-      const defaultDimensions = { width: 300, height: 150 };
-      element.updateHotspot({ name: 'hotspot-1', position: `0m 0m 0m`});
+      // to test querying, place hotspot in the center and verify the screen
+      // position is half the default width and height (300 x 150) with a depth
+      // value of ~1.
+      const defaultDimensions = {width: 300, height: 150};
+      element.updateHotspot({name: 'hotspot-1', position: `0m 0m 0m`});
 
       const hotspotData = element.queryHotspot('hotspot-1');
 
-      expect(hotspotData?.screenPosition.x).to.be.closeTo(defaultDimensions.width / 2, 0.0001);
-      expect(hotspotData?.screenPosition.y).to.be.closeTo(defaultDimensions.height / 2, 0.0001);
-      expect(hotspotData?.position.toString()).to.equal(toVector3D(new Vector3(0, 0, 0)).toString());
-      expect(hotspotData?.normal.toString()).to.equal(toVector3D(new Vector3(0, 0, -1)).toString());
+      expect(hotspotData?.canvasPosition.x)
+          .to.be.closeTo(defaultDimensions.width / 2, 0.0001);
+      expect(hotspotData?.canvasPosition.y)
+          .to.be.closeTo(defaultDimensions.height / 2, 0.0001);
+      expect(hotspotData?.position.toString())
+          .to.equal(toVector3D(new Vector3(0, 0, 0)).toString());
+      expect(hotspotData?.normal.toString())
+          .to.equal(toVector3D(new Vector3(0, 0, -1)).toString());
       expect(hotspotData?.facingCamera).to.be.true;
     });
 

packages/modelviewer.dev/data/docs.json

@@ -766,9 +766,9 @@
       {
         "name": "queryHotspot(name)",
         "htmlName": "queryHotspot",
-        "description": "Returns information about the current state of the hotspot corresponding to the hotspot name given as a read-only snapshot: The position, normal, screen (canvas) position and current visibility. The screen position is represented as a Vector3 with z as the OpenGL depth information. The function returns null if no hotspot is found.",
+        "description": "Returns information about the current state of the hotspot corresponding to the hotspot name as a snapshot: the position, normal, canvasPosition, and facingCamera. The canvas position is represented as a Vector3D with z as the OpenGL depth information. The function returns null if no hotspot is found.",
         "links": [
-          "<a href=\"../examples/annotations/#overlays\"><span class='attribute'>custom overlays</span> example</a>"
+          "<a href=\"../examples/annotations/#dimensions\"><span class='attribute'>dimension lines</span> example</a>"
         ]
       },
       {

packages/modelviewer.dev/examples/annotations/index.html

@@ -136,9 +136,10 @@ <h4 id="intro"><span class="font-medium">Show Dimensions. </span></h4>
           <p>
             Hotspots can be queried to build custom overlays in screen space.
             For example, by using an SVG canvas and updating the line nodes we
-            can draw rudimentary dimensions lines. Note that this kind of
-            extended functionality cannot support occlusion in the 3D scene as
-            it is drawn on top.
+            can draw rudimentary dimension lines. Note that this kind of
+            extended functionality cannot support occlusion in the 3D scene, but
+            you can cause it to draw behind the model by setting its CSS z-index
+            to a negative value.
           </p>
           <p>
             By using WebXR mode, this markup works equally well in AR. Note that
@@ -279,10 +280,10 @@ <h4 id="intro"><span class="font-medium">Show Dimensions. </span></h4>
     // update svg
     function drawLine(svgLine, dotHotspot1, dotHotspot2, dimensionHotspot) {
       if (dotHotspot1 && dotHotspot1) {
-        svgLine.setAttribute('x1', dotHotspot1.screenPosition.x);
-        svgLine.setAttribute('y1', dotHotspot1.screenPosition.y);
-        svgLine.setAttribute('x2', dotHotspot2.screenPosition.x);
-        svgLine.setAttribute('y2', dotHotspot2.screenPosition.y);
+        svgLine.setAttribute('x1', dotHotspot1.canvasPosition.x);
+        svgLine.setAttribute('y1', dotHotspot1.canvasPosition.y);
+        svgLine.setAttribute('x2', dotHotspot2.canvasPosition.x);
+        svgLine.setAttribute('y2', dotHotspot2.canvasPosition.y);
 
         // use provided optional hotspot to tie visibility of this svg line to
         if (dimensionHotspot && !dimensionHotspot.facingCamera) {