@openglobus/og 1.0.0-rc29 → 1.0.0-rc30

package/lib/control/entityEditor/EntityEditor.d.ts

@@ -1,20 +1,18 @@
-import { Control, type IControlParams } from "../Control";
-import { EntityEditorScene, type EditModeName } from "./EntityEditorScene";
+import { EntityGizmo, type IEntityGizmoParams } from "../entityGizmo/EntityGizmo";
 import { EntityEditorDialog } from "./EntityEditorDialog";
-import { Entity } from "../../entity/Entity";
 import { Dialog } from "../../ui";
-export interface IEntityEditorParams extends IControlParams {
-    editMode?: EditModeName;
+export interface IEntityEditorParams extends Omit<IEntityGizmoParams, "tools"> {
 }
-export declare class EntityEditor extends Control {
-    protected _entityEditorScene: EntityEditorScene;
+/**
+ * Entity properties editor. Combines the {@link EntityGizmo} on-map transform mechanism
+ * with the "Entity Properties" dialog.
+ * @class
+ * @extends {EntityGizmo}
+ */
+export declare class EntityEditor extends EntityGizmo {
     protected _dialog: EntityEditorDialog;
     constructor(options?: IEntityEditorParams);
     oninit(): void;
-    onactivate(): void;
     ondeactivate(): void;
-    selectEntity(entity: Entity): void;
     positionDialogLeftOf(anchor: Dialog<unknown>): void;
-    unselectEntity(): void;
-    getSelectedEntity(): Entity | null;
 }

package/lib/control/entityEditor/EntityEditorDialog.d.ts

@@ -1,14 +1,14 @@
 import { Dialog, type IDialogParams } from "../../ui/Dialog";
-import { EntityEditorScene } from "./EntityEditorScene";
+import { EntityGizmoScene } from "../entityGizmo/EntityGizmoScene";
 import { Entity } from "../../entity/Entity";
 import { Vec3 } from "../../math/Vec3";
 import { CameraEditorView } from "./CameraEditorView";
 import { EntityEditorView } from "./EntityEditorView";
 import { ProjectorEditorView } from "./ProjectorEditorView";
 interface IEntityEditorDialog extends IDialogParams {
-    model: EntityEditorScene;
+    model: EntityGizmoScene;
 }
-export declare class EntityEditorDialog extends Dialog<EntityEditorScene> {
+export declare class EntityEditorDialog extends Dialog<EntityGizmoScene> {
     protected _entityView: EntityEditorView | null;
     protected _cameraView: CameraEditorView | null;
     protected _projectorView: ProjectorEditorView | null;

package/lib/control/entityEditor/EntityEditorView.d.ts

@@ -4,12 +4,12 @@ import { Input } from "../../ui/Input";
 import { Slider } from "../../ui/Slider";
 import { TitleBarView } from "../../ui/TitleBarView";
 import { View, type IViewParams } from "../../ui/View";
-import { EntityEditorScene } from "./EntityEditorScene";
+import { EntityGizmoScene } from "../entityGizmo/EntityGizmoScene";
 interface IEntityEditorViewParams extends IViewParams {
-    model: EntityEditorScene;
+    model: EntityGizmoScene;
     entity?: Entity;
 }
-export declare class EntityEditorView extends View<EntityEditorScene> {
+export declare class EntityEditorView extends View<EntityGizmoScene> {
     protected _entity: Entity | null;
     protected _titleBarView: TitleBarView;
     protected _bodyEl: HTMLElement | null;

package/lib/control/entityGizmo/EntityGizmo.d.ts

@@ -0,0 +1,103 @@
+import { Control, type IControlParams } from "../Control";
+import { type EventsHandler } from "../../Events";
+import { Entity } from "../../entity/Entity";
+import { EntityGizmoScene, type EditModeName, type GizmoTools, type IGizmoTransformEvent } from "./EntityGizmoScene";
+export interface IEntityGizmoParams extends IControlParams {
+    tools?: GizmoTools;
+    editMode?: EditModeName;
+    autoSelect?: boolean;
+}
+type EntityGizmoEventsList = [
+    "select",
+    "unselect",
+    "transformstart",
+    "transformchange",
+    "transformend",
+    "transformcancel"
+];
+/**
+ * On-map gizmo for translating and rotating entities.
+ * @class
+ * @extends {Control}
+ * @param {IEntityGizmoParams} [options] - Gizmo options:
+ * @param {GizmoTools} [options.tools] - Gizmo tool set, i.e. which handles are shown. `translate`
+ * shows move axes and planes only, `full` adds rotation rings. Orthogonal to `editMode`.
+ * @param {EditModeName} [options.editMode] - Rotation mode. `native` rotates in the entity's own
+ * frame, `yaw` rotates in the local horizon frame. Affects the rotation rings only, so it does
+ * nothing with `tools: "translate"`.
+ * @param {boolean} [options.autoSelect] - When `false`, a left click on a map entity does not
+ * change the gizmo selection, so the host application stays the only source of the selection.
+ * Default is `true`.
+ */
+export declare class EntityGizmo extends Control {
+    events: EventsHandler<EntityGizmoEventsList>;
+    protected _scene: EntityGizmoScene;
+    constructor(options?: IEntityGizmoParams);
+    oninit(): void;
+    onactivate(): void;
+    ondeactivate(): void;
+    onremove(): void;
+    /**
+     * Gizmo tool set: which handles are shown.
+     * @public
+     */
+    get tools(): GizmoTools;
+    set tools(tools: GizmoTools);
+    /**
+     * Rotation mode of the rotation rings. Does nothing with `tools: "translate"`.
+     * @public
+     */
+    get editMode(): EditModeName;
+    set editMode(editMode: EditModeName);
+    /**
+     * When `false`, a left click on a map entity does not change the gizmo selection.
+     * @public
+     */
+    get autoSelect(): boolean;
+    set autoSelect(autoSelect: boolean);
+    /**
+     * Shows the gizmo on the given entity. Activates the control when it is inactive.
+     * Changing the selection cancels any running gesture on the previously selected entity.
+     * @public
+     * @param {Entity} entity - Entity to transform.
+     */
+    selectEntity(entity: Entity): void;
+    /**
+     * Hides the gizmo and drops the selection. Cancels a running gesture.
+     * @public
+     */
+    unselectEntity(): void;
+    /**
+     * Returns the selected entity or `null`.
+     * @public
+     * @returns {Entity | null}
+     */
+    getSelectedEntity(): Entity | null;
+    /**
+     * Returns `true` while a drag gesture is running.
+     * @public
+     * @returns {boolean}
+     */
+    isTransforming(): boolean;
+    /**
+     * Returns the running gesture description or `null`.
+     * @public
+     * @returns {IGizmoTransformEvent | null}
+     */
+    getActiveTransform(): IGizmoTransformEvent | null;
+    /**
+     * Cancels the current gesture and restores the entity transform when possible.
+     * @public
+     * @returns {boolean} Whether a gesture was cancelled.
+     */
+    cancelTransform(): boolean;
+    protected _bindSceneEvents(): void;
+    protected _unbindSceneEvents(): void;
+    protected _onSelect: (entity: Entity) => void;
+    protected _onUnselect: (entity: Entity | null) => void;
+    protected _onTransformStart: (e: IGizmoTransformEvent) => void;
+    protected _onTransformChange: (e: IGizmoTransformEvent) => void;
+    protected _onTransformEnd: (e: IGizmoTransformEvent) => void;
+    protected _onTransformCancel: (e: IGizmoTransformEvent) => void;
+}
+export {};

package/lib/control/{entityEditor/EntityEditorScene.d.ts → entityGizmo/EntityGizmoScene.d.ts}

@@ -12,16 +12,45 @@ import { MovePlaneEntity } from "./MovePlaneEntity";
 import { RotateEntity } from "./RotateEntity";
 import { AxisTrackEntity } from "./AxisTrackEntity";
 import { EntityCollection } from "../../entity/EntityCollection";
-export interface IEntityEditorSceneParams {
+export interface IEntityGizmoSceneParams {
     planet?: Planet;
     name?: string;
     editMode?: EditModeName;
+    tools?: GizmoTools;
+    autoSelect?: boolean;
 }
 export declare const NATIVE_MODE = 0;
 export declare const YAW_MODE = 1;
+/** Rotation mode: the frame the rotation rings are built in and written back through. */
 export type EditMode = typeof NATIVE_MODE | typeof YAW_MODE;
 export type EditModeName = "native" | "yaw";
-type EntityEditorSceneEventsList = [
+/**
+ * Gizmo tool set, i.e. which handles are shown. Orthogonal to the rotation {@link EditModeName}.
+ * `translate` - move axes and planes only.
+ * `full` - move axes, planes and rotation rings.
+ */
+export type GizmoTools = "translate" | "full";
+/** Gizmo handle names. Each handle belongs to exactly one {@link GizmoTransformKind}. */
+export type GizmoTransformHandle = "move_x" | "move_y" | "move_z" | "move_xz" | "move_xy" | "move_zy" | "rotate_pitch" | "rotate_yaw" | "rotate_roll";
+/** Kind of transformation a gesture performs. */
+export type GizmoTransformKind = "translate" | "rotate";
+/** Payload of `transformstart`, `transformchange`, `transformend` and `transformcancel`. */
+export interface IGizmoTransformEvent {
+    entity: Entity;
+    kind: GizmoTransformKind;
+    handle: GizmoTransformHandle;
+}
+interface IGizmoGesture {
+    entity: Entity;
+    handle: GizmoTransformHandle;
+    kind: GizmoTransformKind;
+    started: boolean;
+    cartesian: Vec3;
+    pitch: number;
+    yaw: number;
+    roll: number;
+}
+type EntityGizmoSceneEventsList = [
     "mousemove",
     "mouseenter",
     "mouseleave",
@@ -54,10 +83,20 @@ type EntityEditorSceneEventsList = [
     "pitch",
     "yaw",
     "roll",
-    "scale"
+    "scale",
+    "transformstart",
+    "transformchange",
+    "transformend",
+    "transformcancel"
 ];
-declare class EntityEditorScene extends Scene {
-    events: EventsHandler<EntityEditorSceneEventsList>;
+/**
+ * Scene for translating and rotating entities with a gizmo.
+ * @class
+ * @extends {Scene}
+ * @param {IEntityGizmoSceneParams} [options] - Gizmo scene options.
+ */
+declare class EntityGizmoScene extends Scene {
+    events: EventsHandler<EntityGizmoSceneEventsList>;
     protected _planet: Planet | null;
     protected _startPos: Vec2 | null;
     protected _startClick: Vec2;
@@ -76,15 +115,28 @@ declare class EntityEditorScene extends Scene {
     protected _planeEntity: MovePlaneEntity;
     protected _rotateEntity: RotateEntity;
     protected _axisTrackEntity: AxisTrackEntity;
-    protected _selectedMove: string | null;
+    protected _selectedMove: GizmoTransformHandle | null;
     protected _ops: Record<string, (mouseState: IMouseState) => void>;
     protected _axisTrackVisibility: boolean;
     protected _editMode: EditMode;
-    constructor(options?: IEntityEditorSceneParams);
+    protected _tools: GizmoTools;
+    protected _autoSelect: boolean;
+    protected _visibility: boolean;
+    protected _isActivated: boolean;
+    protected _gesture: IGizmoGesture | null;
+    protected _suspendedNavigation: string[];
+    constructor(options?: IEntityGizmoSceneParams);
     get ellipsoid(): Ellipsoid | undefined;
     get planet(): Planet | null;
     get editMode(): EditMode;
     set editMode(mode: EditMode);
+    /** Gizmo tool set: which handles are shown. */
+    get tools(): GizmoTools;
+    set tools(tools: GizmoTools);
+    /** When `false`, a left click on a map entity does not change the gizmo selection. */
+    get autoSelect(): boolean;
+    set autoSelect(autoSelect: boolean);
+    protected get _rotateEnabled(): boolean;
     bindPlanet(planet: Planet): void;
     protected _parseEditMode(mode: EditModeName | undefined): EditMode;
     init(): void;
@@ -92,36 +144,82 @@ declare class EntityEditorScene extends Scene {
     protected _addAxisLayers(): void;
     protected _onAxisLayerMouseEnter: (e: IMouseState) => void;
     protected _onAxisLayerMouseLeave: (e: IMouseState) => void;
-    protected _navActivate(): void;
-    protected _navDeactivate(): void;
-    protected _onAxisLayerLUp: (e: IMouseState) => void;
+    /**
+     * Suspends the navigation controls that are active right now, so that a drag gesture
+     * does not fight with the camera. The suspended set is remembered and restored by
+     * {@link EntityGizmoScene._navRestore}, which keeps controls that were already
+     * deactivated beforehand deactivated.
+     * @protected
+     */
+    protected _navSuspend(): void;
+    protected _navRestore(): void;
     protected _onAxisLayerLDown: (e: IMouseState) => void;
     protected _onPlaneLayerMouseEnter: (e: IMouseState) => void;
     protected _onPlaneLayerMouseLeave: (e: IMouseState) => void;
-    protected _onPlaneLayerLUp: (e: IMouseState) => void;
     protected _onPlaneLayerLDown: (e: IMouseState) => void;
     protected _onRotateLayerMouseEnter: (e: IMouseState) => void;
     protected _onRotateLayerMouseLeave: (e: IMouseState) => void;
-    protected _onRotateLayerLUp: (e: IMouseState) => void;
     protected _onRotateLayerLDown: (e: IMouseState) => void;
     protected _onMouseMove: (e: IMouseState) => void;
     protected _removeAxisLayers(): void;
     activate(): void;
-    protected deactivate(): void;
+    deactivate(): void;
     protected _setAxisTrackVisibility(visibility: boolean): void;
     setVisibility(visibility: boolean): void;
+    protected _applyVisibility(): void;
     readyToEdit(entity: Entity): boolean;
     select(entity: Entity): void;
     unselect(): void;
     protected _onLclick: (e: IMouseState) => void;
     clear(): void;
     protected _onForwardpass: () => void;
+    /**
+     * Returns `true` when a drag gesture is running right now.
+     * @public
+     */
+    isTransforming(): boolean;
+    /**
+     * Returns the running gesture description or `null`.
+     * @public
+     */
+    getActiveTransform(): IGizmoTransformEvent | null;
+    /**
+     * Cancels the current gesture and restores the entity transform when possible.
+     * @public
+     * @returns {boolean} Whether a gesture was cancelled.
+     */
+    cancelTransform(): boolean;
+    protected _gestureEvent(gesture: IGizmoGesture): IGizmoTransformEvent;
+    protected _beginGesture(handle: GizmoTransformHandle): void;
+    /**
+     * Dispatches `transformstart` right before the very first entity change of the gesture.
+     * @protected
+     */
+    protected _beginChange(): void;
+    protected _afterChange(): void;
+    protected _endGesture(): void;
+    protected _restoreGesture(gesture: IGizmoGesture): void;
+    protected _isEntityAttached(entity: Entity): boolean;
+    protected _bindGestureListeners(): void;
+    protected _unbindGestureListeners(): void;
+    protected _onWindowPointerUp: () => void;
+    protected _onWindowPointerCancel: () => void;
+    protected _onWindowBlur: () => void;
+    protected _onLUp: () => void;
+    protected _onTouchCancel: () => void;
     protected _moveX: (e: IMouseState) => void;
     protected _moveY: (e: IMouseState) => void;
     protected _moveZ: (e: IMouseState) => void;
     protected _moveXZ: (e: IMouseState) => void;
     protected _moveXY: (e: IMouseState) => void;
     protected _moveZY: (e: IMouseState) => void;
+    /**
+     * Applies a new absolute position to the selected entity and emits the gesture events
+     * around the change. The `position` event receives the applied `pos` and the entity.
+     * @protected
+     * @param {Vec3} pos - New absolute cartesian position.
+     */
+    protected _applyPosition(pos: Vec3): void;
     getFrameRotation(cartesian: Vec3): Quat;
     protected _isPlanetEntity(entity: Entity): boolean;
     protected _isYawMode(): boolean;
@@ -140,4 +238,4 @@ declare class EntityEditorScene extends Scene {
     lockView(): void;
     unlockView(): void;
 }
-export { EntityEditorScene };
+export { EntityGizmoScene };

package/lib/control/index.d.ts

@@ -26,6 +26,8 @@ export * from "./selection/Selection";
 export * from "./timeline/TimelineControl";
 export * from "./elevationProfile/ElevationProfileControl";
 export * from "./atmosphere/AtmosphereConfig";
+export * from "./entityGizmo/EntityGizmo";
+export * from "./entityGizmo/EntityGizmoScene";
 export * from "./entityEditor/EntityEditor";
 export * from "./CameraLock";
 export * from "./object3dManager/Object3dManager";

package/lib/index.d.ts

@@ -27,6 +27,10 @@ export type { IDepthCameraParams } from "./control/depthCamera/DepthCamera";
 export { DepthCamera } from "./control/depthCamera/DepthCamera";
 export type { IDepthCameraHandlerParams } from "./control/depthCamera/DepthCameraHandler";
 export { DepthCameraHandler } from "./control/depthCamera/DepthCameraHandler";
+export type { IEntityGizmoParams } from "./control/entityGizmo/EntityGizmo";
+export { EntityGizmo } from "./control/entityGizmo/EntityGizmo";
+export type { EditMode, EditModeName, GizmoTools, GizmoTransformHandle, GizmoTransformKind, IEntityGizmoSceneParams, IGizmoTransformEvent } from "./control/entityGizmo/EntityGizmoScene";
+export { EntityGizmoScene } from "./control/entityGizmo/EntityGizmoScene";
 export { PhongDeferredShading } from "./renderer/PhongDeferredShading";
 export { AtmosphereDeferredShading } from "./renderer/AtmosphereDeferredShading";
 export { WOITPass } from "./renderer/WOITPass";
@@ -60,7 +64,7 @@ import { EarthQuadTreeStrategy, EquiQuadTreeStrategy, QuadTreeStrategy, quadTree
 import { Object3d } from "./Object3d";
 import { Handler, ShaderProgram, Framebuffer, Multisample } from "./webgl/index";
 import { EmptyTerrain, GlobusTerrain, RgbTerrain, BilTerrain, GlobusRgbTerrain, MapterhornTerrain, rgbToHeightByEncoding, rgbToHeightRgb, rgbToHeightTerrarium, resolveRgbToHeightFunc } from "./terrain/index";
-import { MoveAxisEntity } from "./control/entityEditor/MoveAxisEntity";
+import { MoveAxisEntity } from "./control/entityGizmo/MoveAxisEntity";
 import { Gltf } from "./utils/gltf/gltfParser";
 import { Easing } from "./utils/easing";
 import type { EasingFunction } from "./utils/easing";