HARP-10793: Add styleSetName and category to MapAnchors and removed M…

…apView.worldAnchors (#1610)

@here/harp-examples/src/rendering_globe-atmosphere.ts

@@ -74,9 +74,9 @@ export namespace GlobeAtmosphereExample {
         const ui = new MapControlsUI(mapControls, { zoomLevel: "input" });
         map.canvas.parentElement!.appendChild(ui.domElement);
 
-        const { camera, projection, worldAnchors } = map;
+        const { camera, projection, mapAnchors } = map;
         const updateCallback = () => map.update();
-        const atmosphere = new MapViewAtmosphere(worldAnchors, camera, projection, updateCallback);
+        const atmosphere = new MapViewAtmosphere(mapAnchors, camera, projection, updateCallback);
         atmosphere.lightMode = AtmosphereLightMode.LightDynamic;
 
         const coords = new GeoCoordinates(10.0, -10.0);

@here/harp-examples/src/threejs_add-object.ts

@@ -89,7 +89,7 @@ export namespace ThreejsAddSimpleObject {
 
             // snippet:harp_gl_threejs_add_simple_object_2.ts
             const cube = createPinkCube();
-            cube.geoPosition = geoPosition;
+            cube.anchor = geoPosition;
             mapView.mapAnchors.add(cube);
             // end:harp_gl_threejs_add_simple_object_2.ts
 

@here/harp-mapview/index.ts

@@ -36,6 +36,7 @@ export * from "./lib/ElevationRangeSource";
 export * from "./lib/image/Image";
 export * from "./lib/image/ImageCache";
 export * from "./lib/image/MapViewImageCache";
+export * from "./lib/MapAnchors";
 export * from "./lib/MapView";
 export * from "./lib/MapViewAtmosphere";
 export * from "./lib/MapViewFog";

@here/harp-mapview/lib/MapAnchors.ts

@@ -0,0 +1,154 @@
+/*
+ * Copyright (C) 2017-2020 HERE Europe B.V.
+ * Licensed under Apache 2.0, see full license in LICENSE
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { StylePriority } from "@here/harp-datasource-protocol";
+import {
+    GeoCoordinates,
+    GeoCoordLike,
+    isGeoCoordinatesLike,
+    isVector3Like,
+    Projection,
+    Vector3Like
+} from "@here/harp-geoutils";
+
+import * as THREE from "three";
+
+/**
+ * An interface describing [[THREE.Object3D]]s anchored on given [[GeoCoordinates]].
+ *
+ * Example:
+ * ```typescript
+ * const mesh: MapAnchor<THREE.Mesh> = new THREE.Mesh(geometry, material);
+ * mesh.anchor = new GeoCoordinates(latitude, longitude, altitude);
+ * mapView.mapAnchors.add(mesh);
+ * ```
+ */
+export type MapAnchor<T extends THREE.Object3D = THREE.Object3D> = T & {
+    /**
+     * The position of this [[MapAnchor]] in [[GeoCoordinates]].
+     * @deprecated Use [[anchor]] instead.
+     */
+    geoPosition?: GeoCoordinates;
+
+    /**
+     * The anchor of this Object3D in [[GeoCoordinates]] or world coordinates.
+     */
+    anchor?: GeoCoordLike | Vector3Like;
+
+    /**
+     * Flag defining if the object may be picked.
+     *
+     * @note By default all objects are pickable even if this flag is undefined.
+     */
+    pickable?: boolean;
+
+    /**
+     * The styleSet that owns this map object.
+     *
+     * @remarks
+     * This property is used together with [[Theme.priorities]] to compute the render
+     * order of this map object.
+     */
+    styleSet?: string;
+
+    /**
+     * The category of this style.
+     *
+     * @remarks
+     * This property is used together with [[Theme.priorities]] to compute the render
+     * order of this mao object.
+     */
+    category?: string;
+};
+
+/**
+ * Container holding [[MapAnchor]] objects.
+ */
+export class MapAnchors {
+    private m_anchors: MapAnchor[] = [];
+
+    /**
+     * All currently added [[MapAnchor]]s.
+     */
+    get children() {
+        return this.m_anchors;
+    }
+
+    /**
+     * Add a [[MapAnchor]].
+     * @param mapAnchor [[MapAnchor]] instance to add.
+     */
+    add(mapAnchor: MapAnchor) {
+        this.m_anchors.push(mapAnchor);
+    }
+
+    /**
+     * Remove a [[MapAnchor]].
+     * @param mapAnchor - [[MapAnchor]] instance to remove.
+     *
+     * @note This method is potentially slow when removing a lot of anchors.
+     * [[clear]]ing and [[add]]ing anchors should be considered in that case.
+     */
+    remove(mapAnchor: MapAnchor) {
+        const index = this.m_anchors.findIndex(element => element === mapAnchor);
+        if (index > -1) {
+            this.m_anchors.splice(index, 1);
+        }
+    }
+
+    /**
+     * Remove all [[MapAnchor]]s.
+     */
+    clear() {
+        this.m_anchors.length = 0;
+    }
+
+    /**
+     * Update the map anchors.
+     * @param projection - Current projection
+     * @param cameraPosition - Current camera position
+     * @param rootNode - Node where the objects will be inserted
+     * @param priorities - Optional theme priority list
+     *
+     * @internal
+     * @hidden
+     */
+    update(
+        projection: Projection,
+        cameraPosition: THREE.Vector3,
+        rootNode: THREE.Object3D,
+        priorities?: StylePriority[]
+    ) {
+        const worldPosition = new THREE.Vector3();
+
+        this.m_anchors.forEach((mapAnchor: MapAnchor) => {
+            if (mapAnchor.styleSet !== undefined) {
+                const priority = priorities?.findIndex(
+                    entry =>
+                        entry.group === mapAnchor.styleSet && entry.category === mapAnchor.category
+                );
+
+                if (priority !== undefined && priority !== -1) {
+                    mapAnchor.renderOrder = (priority + 1) * 10;
+                }
+            }
+
+            const anchor =
+                // tslint:disable-next-line: deprecation
+                mapAnchor.geoPosition !== undefined ? mapAnchor.geoPosition : mapAnchor.anchor;
+            if (anchor !== undefined) {
+                if (isVector3Like(anchor)) {
+                    worldPosition.set(anchor.x, anchor.y, anchor.z);
+                } else if (isGeoCoordinatesLike(anchor)) {
+                    projection.projectPoint(anchor, worldPosition);
+                }
+                mapAnchor.position.copy(worldPosition).sub(cameraPosition);
+            }
+
+            rootNode.add(mapAnchor);
+        });
+    }
+}

@here/harp-mapview/lib/MapView.ts

@@ -57,6 +57,7 @@ import { FrustumIntersection } from "./FrustumIntersection";
 import { overlayOnElevation } from "./geometry/overlayOnElevation";
 import { TileGeometryManager } from "./geometry/TileGeometryManager";
 import { MapViewImageCache } from "./image/MapViewImageCache";
+import { MapAnchors } from "./MapAnchors";
 import { MapObjectAdapter } from "./MapObjectAdapter";
 import { MapViewFog } from "./MapViewFog";
 import { PickHandler, PickResult } from "./PickHandler";
@@ -92,57 +93,6 @@ if (isProduction) {
     // In dev: silence logging below log (silences "debug" and "trace" levels).
     LoggerManager.instance.setLogLevelForAll(LogLevel.Log);
 }
-/**
- * An interface describing [[THREE.Object3D]]s anchored on given [[GeoCoordinates]].
- *
- * Example:
- * ```typescript
- * const mesh: MapAnchor<THREE.Mesh> = new THREE.Mesh(geometry, material);
- * mesh.geoPosition = new GeoCoordinates(latitude, longitude, altitude);
- * mapView.mapAnchors.add(mesh);
- * ```
- *
- */
-export type MapAnchor<T extends THREE.Object3D = THREE.Object3D> = T & {
-    /**
-     * The position of this [[MapAnchor]] in [[GeoCoordinates]].
-     */
-    geoPosition?: GeoCoordinates;
-    /**
-     * Flag defining if the object may be picked.
-     *
-     * @note By default all objects are pickable even if this flag is undefined.
-     */
-    pickable?: boolean;
-};
-
-/**
- * An interface describing [[THREE.Object3D]]s anchored on given world coordinates.
- *
- * Example:
- * ```typescript
- * const mesh: WorldAnchor<THREE.Mesh> = new THREE.Mesh(geometry, material);
- * mesh.worldPosition = new Vector3(x, y, z);
- * mesh.pickable = false;
- * mapView.worldAnchors.add(mesh);
- * ```
- * @internal
- */
-export type WorldAnchor<T extends THREE.Object3D = THREE.Object3D> = T & {
-    /**
-     * The position of this [[WorldAnchor]] in world coordinates (and units).
-     *
-     * Word coordinates anchors may be used for objects that has not exact relation to the
-     * place on the Earth globe or map. This may include light sources, special cameras, effects.
-     */
-    worldPosition?: THREE.Vector3;
-    /**
-     * Flag defining if the object may be picked.
-     *
-     * @note By default all objects are pickable even if this flag is undefined.
-     */
-    pickable?: boolean;
-};
 
 export enum MapViewEventNames {
     /** Called before this `MapView` starts to render a new frame. */
@@ -853,8 +803,7 @@ export class MapView extends THREE.EventDispatcher {
     private readonly m_scene: THREE.Scene = new THREE.Scene();
     private readonly m_fog: MapViewFog = new MapViewFog(this.m_scene);
     private readonly m_mapTilesRoot = new THREE.Object3D();
-    private readonly m_mapAnchors = new THREE.Object3D();
-    private readonly m_worldAnchors = new THREE.Object3D();
+    private readonly m_mapAnchors: MapAnchors = new MapAnchors();
 
     private m_animationCount: number = 0;
     private m_animationFrameHandle: number | undefined;
@@ -1808,24 +1757,10 @@ export class MapView extends THREE.EventDispatcher {
      * [[MapAnchor.geoPosition]].
      * Deeper level children can be used to position custom objects relative to the anchor node.
      */
-    get mapAnchors(): THREE.Object3D {
+    get mapAnchors(): MapAnchors {
         return this.m_mapAnchors;
     }
 
-    /**
-     * The root node for user's defined objects that will be positioned by world coordinates.
-     *
-     * This objects are transformed according to camera setup, but are not _attached_ to map
-     * geo position. Such anchors may be used to add custom rendering geometry of effects that are
-     * moving or just positioned in world space, i.e. light source, comet, spaceship, etc.
-     *
-     * @see mapAnchors.
-     * @internal
-     */
-    get worldAnchors(): THREE.Object3D {
-        return this.m_worldAnchors;
-    }
-
     /**
      * The position in world coordinates of the center of the scene.
      */
@@ -3367,19 +3302,12 @@ export class MapView extends THREE.EventDispatcher {
             this.m_initialTextPlacementDone = true;
         }
 
-        this.m_mapAnchors.children.forEach((childObject: MapAnchor) => {
-            if (childObject.geoPosition !== undefined) {
-                this.projection.projectPoint(childObject.geoPosition, childObject.position);
-                childObject.position.sub(this.camera.position);
-            }
-        });
-        this.m_worldAnchors.children.forEach((childObject: WorldAnchor) => {
-            if (childObject.worldPosition !== undefined) {
-                const wp = childObject.worldPosition;
-                childObject.position.set(wp.x, wp.y, wp.z);
-                childObject.position.sub(this.camera.position);
-            }
-        });
+        this.m_mapAnchors.update(
+            this.projection,
+            this.camera.position,
+            this.m_mapTilesRoot,
+            this.m_theme.priorities
+        );
 
         this.m_animatedExtrusionHandler.zoom = this.m_zoomLevel;
 
@@ -4004,8 +3932,6 @@ export class MapView extends THREE.EventDispatcher {
         this.m_renderer.setClearColor(DEFAULT_CLEAR_COLOR);
 
         this.m_scene.add(this.m_mapTilesRoot);
-        this.m_scene.add(this.m_mapAnchors);
-        this.m_scene.add(this.m_worldAnchors);
 
         this.shadowsEnabled = this.m_options.enableShadows ?? false;
     }