@smarterplan/ngx-smarterplan-core 1.4.19 → 1.4.21

package/lib/helpers.service.d.ts

@@ -22,6 +22,21 @@ export interface ThreeJsAlignment {
     };
     scale?: number;
 }
+/**
+ * Where a POI placed in a Three.js model says it was placed, or null for any other POI.
+ *
+ * `frame` is 'model' when its coordinates are in that model's own space - it was placed before the
+ * model was calibrated - rather than in the space tags share with the other visits.
+ */
+export declare function getThreeJsPoiOrigin(poi: {
+    metadata?: string | null;
+} | null | undefined): {
+    captureID: string;
+    frame: "model" | null;
+} | null;
+/** Which of a model's own axes points up, for a model whose file has it the other way. */
+export type ThreeJsModelUp = "x" | "y" | "z" | "-x" | "-y" | "-z";
+export declare const THREEJS_MODEL_UP_OPTIONS: ThreeJsModelUp[];
 /** Where the camera starts when a Three.js visit is opened. */
 export interface ThreeJsPlacement {
     cameraPosition?: {
@@ -35,6 +50,8 @@ export interface ThreeJsPlacement {
         z: number;
     };
     alignment?: ThreeJsAlignment;
+    /** Set once someone has chosen the vertical axis by hand; absent means "work it out". */
+    up?: ThreeJsModelUp;
 }
 /**
  * Parses the placement stored in a Three.js capture's metadata, or null when there is none.

package/lib/services/matterport-object3d.service.d.ts

@@ -1,4 +1,5 @@
-import { IObject3D, PoiType, POI, DbObjectType } from '../types.service';
+import { Subject } from 'rxjs';
+import { IObject3D, PoiType, POI, DbObjectType, GizmoMode, GizmoSnap, Object3DBoundingBox, Object3DTransform, Object3DTransformChange, Point3D } from '../types.service';
 import * as i0 from "@angular/core";
 export declare class MatterportObject3DService {
     dictionnaryObjects3D: Map<string, any>;
@@ -9,22 +10,141 @@ export declare class MatterportObject3DService {
     azimuthalCrown: any;
     threeJSScene: any;
     noLightForObjects: boolean;
+    /** Max time (ms) to wait for a model to be loaded by the SDK */
+    loadTimeoutMs: number;
+    /** Max distance (m) an object can travel from where a translate drag started */
+    maxDragDistance: number;
+    /** Max vertical travel (m, up and down) during a translate drag, so an object cannot jump to another floor */
+    maxDragHeight: number;
+    /** Emits on every gizmo change and on setObject3DTransform */
+    readonly object3DTransformChanged$: Subject<Object3DTransformChange>;
+    /** Security camera animators by object uuid (`securityCameraAnimator` stays the last loaded one) */
+    securityCameraAnimators: Map<string, any>;
+    private viewFrustumVisible;
+    private lastSecurityCameraUuid;
+    /** Loader component of each model (outputs.objectRoot is set once loaded) */
+    private loaderComponents;
+    private gizmos;
+    private activeGizmoUuid;
+    private gizmoSnap;
+    /** Sweeps disabled by setNavigationLocked(true), re-enabled on unlock */
+    private sweepsDisabledByLock;
+    /** Sweeps re-enabled by the last unlock (the SDK may still report them disabled for a moment) */
+    private sweepsEnabledByUnlock;
+    private readonly tmpBox;
     constructor();
     init3DObjectViewer(sdk: any): Promise<void>;
-    add3DObject(sdk: any, obj: IObject3D, mode?: 'translate' | 'rotate'): Promise<any>;
+    /** SDK loader component name for a model format, null when the format is not supported */
+    private getLoaderComponentName;
+    /** Resolves once the loader component has produced its objectRoot, rejects after `timeoutMs` */
+    private waitForModelLoaded;
+    /**
+     * Adds a 3D model to the scene.
+     * The promise resolves with the three.js object once the model is actually loaded, and rejects
+     * (after cleaning the scene) when the format is unknown or the load times out.
+     * The position / rotation / scale of `obj` are applied to the model origin, as stored in DB.
+     */
+    add3DObject(sdk: any, obj: IObject3D, mode?: GizmoMode): Promise<any>;
+    /**
+     * Removes a 3D object for good: detaches its gizmo, stops its scene object and forgets it.
+     */
     deleteObject3D(uuid: string): Promise<void>;
     getObject3DModelNodeFromDictionnary(uuid: string): any;
     toggleObjectVisibility(objectId: any): void;
     isObjectVisible(objectId: any): boolean;
+    /** Shows / hides a model (used by the placement preview) */
+    setObject3DVisible(uuid: string, visible: boolean): void;
+    /** Enables / disables the pointer collider of a model (disabled while it follows the cursor) */
+    setObject3DColliderEnabled(uuid: string, enabled: boolean): void;
+    /**
+     * Moves the camera next to a 3D object by creating a temporary tag on the object centre.
+     * @returns false when the object is unknown or no tag could be reached
+     */
     pointCameraTo3DObject(sdk: any, objectId: any, createTagCallback: (tagType: PoiType, object: DbObjectType, poi: POI) => Promise<any>, goToTagCallback: (sid: string) => Promise<any>, deleteLastTagCallback: () => void, getTagFromElementId: (id: string) => {
         tag: string;
         sweep: string;
-    }): Promise<void>;
+    }): Promise<boolean>;
     getSceneNodeFromObject3DId(uuid: string): any;
     displayAzimutalCrown(poseCamera: any): Promise<void>;
-    attachGizmoControlTo3DObject(sdk: any, modelNode: any, sceneObject: any, mode: 'translate' | 'rotate' | 'scale', visible: boolean, isNewObject: boolean): Promise<any>;
+    private toPoint;
+    /**
+     * Geometry of the model itself (the loader output): the node also holds the helpers added by other
+     * components, like the view frustum of a security camera, which must not count in its size.
+     */
+    private modelRoot;
+    /** World-space bounding box of the model, null when unknown or when nothing is loaded yet */
+    getObject3DBoundingBox(uuid: string): Object3DBoundingBox | null;
+    /**
+     * Real dimensions of the model in meters (width x, height y, depth z), scale included but not
+     * its rotation: the world bounding box of a rotated object is larger than the object itself.
+     */
+    getObject3DDimensions(uuid: string): Point3D | null;
+    /**
+     * Uniform scale so that the largest bounding box dimension equals `targetSizeMeters`.
+     * The node position is untouched, so call placeObject3DOnSurface afterwards.
+     * @returns the new scale, null when the object is unknown / not loaded / `targetSizeMeters` invalid
+     */
+    normalizeObject3DSize(uuid: string, targetSizeMeters: number): Point3D | null;
+    /**
+     * Places the model on a surface point without touching its pivot: the node position is
+     * adjusted so that the bounding box bottom-center lies on `point`.
+     * - floor (normal pointing up, or no normal): bottom-center on the point
+     * - wall (mostly horizontal normal): model turned around Y so its +Z faces away from the wall,
+     *   and pushed along the normal by half its depth so it does not cut the wall
+     * - ceiling (normal pointing down): the model hangs, top-center on the point
+     * @returns the new transform, null when the object is unknown or not loaded
+     */
+    /**
+     * @param frontYawOffset rotation (radians, around Y) that turns the front of the model toward its +Z
+     *                       axis, for models whose front is another axis (e.g. -PI/2 when it is +X)
+     */
+    placeObject3DOnSurface(uuid: string, point: Point3D, normal?: Point3D, frontYawOffset?: number): Object3DTransform | null;
+    getObject3DTransform(uuid: string): Object3DTransform | null;
+    /** Applies a (partial) transform. Rotation is in radians. */
+    setObject3DTransform(uuid: string, transform: Partial<Object3DTransform>): boolean;
+    private emitTransformChanged;
+    /** Creates the mp.transformControls node of a model and wires it (events, snap) */
+    private createGizmo;
+    /** Keeps a translate drag within maxDragDistance / maxDragHeight of where it started, then notifies */
+    private onGizmoObjectChange;
+    private applySnap;
+    /**
+     * Shows the transform gizmo on an object (any previous gizmo is detached first).
+     * Re-attaching to the object that already has the gizmo only changes its mode.
+     */
+    attachGizmo(uuid: string, mode: GizmoMode, sdk?: any): Promise<boolean>;
+    /** Switches the active gizmo between translate / rotate / scale without re-attaching it */
+    setGizmoMode(mode: GizmoMode): void;
+    /** Really removes the gizmo from the scene (default: the active one) */
+    detachGizmo(uuid?: string): void;
+    isGizmoAttached(uuid?: string): boolean;
+    /** Snap steps for all gizmos (null / missing value = no snap) */
+    setGizmoSnap(snap: GizmoSnap | null): void;
+    setGizmoMaxDragDistance(maxDistance: number, maxHeight?: number): void;
+    /**
+     * Prevents camera navigation to other sweeps while a gizmo is edited.
+     * The SDK has no "freeze camera" switch, so every enabled sweep except the current one is
+     * disabled (Sweep.disable); exactly those sweeps are re-enabled on unlock. Sweeps already
+     * disabled (forbidden sweeps, edit mode) are never touched, and `keepDisabled` lists sweeps
+     * that must stay disabled on unlock.
+     * @returns false when the lock could not be applied (SDK without Sweep.disable, unknown current sweep)
+     */
+    setNavigationLocked(sdk: any, locked: boolean, sweepCollection?: Record<string, any> | null, currentSweepId?: string | null, keepDisabled?: string[]): Promise<boolean>;
+    isNavigationLocked(): boolean;
+    /** Sweeps currently disabled by the navigation lock */
+    getSweepsDisabledByLock(): string[];
+    /**
+     * Legacy API: attaches a gizmo to a model node. Prefer attachGizmo(uuid, mode).
+     */
+    attachGizmoControlTo3DObject(sdk: any, modelNode: any, sceneObject: any, mode: GizmoMode, visible: boolean, isNewObject: boolean): Promise<any>;
+    /** Removes the gizmo of the last added / edited object */
     removeGizmoFromLastObject(): void;
-    toggleViewFrustum(): void;
+    private applyViewFrustum;
+    /** Shows / hides the view frustum of the security camera `uuid` */
+    setViewFrustum(uuid: string, visible: boolean): boolean;
+    isViewFrustumVisible(uuid: string): boolean;
+    /** Toggles the frustum of `uuid`, or of the last loaded security camera when omitted */
+    toggleViewFrustum(uuid?: string): void;
     clear(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<MatterportObject3DService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MatterportObject3DService>;

package/lib/services/matterport.service.d.ts

@@ -1,8 +1,8 @@
-import { NgZone } from '@angular/core';
+import { NgZone, OnDestroy } from '@angular/core';
 import { ActivatedRoute, Router } from '@angular/router';
 import { Subject } from 'rxjs';
 import { MattertagData } from '../mattertagData';
-import { DbObjectType, IObject3D, MattertagActionMode, MatterportView, POI, PoiType, SpModule } from '../types.service';
+import { DbObjectType, GizmoMode, GizmoSnap, IObject3D, MattertagActionMode, MatterportView, Object3DBoundingBox, Object3DPlacementResult, Object3DTransform, Object3DTransformChange, POI, PoiType, Point3D, SpModule } from '../types.service';
 import { BaseTagService } from './tag.service';
 import { BaseVisibilityService } from './baseVisibility.service';
 import { Config } from '../config';
@@ -42,7 +42,7 @@ declare global {
         };
     }
 }
-export declare class MatterportService {
+export declare class MatterportService implements OnDestroy {
     private readonly sdkKey;
     private router;
     private activeRoute;
@@ -65,6 +65,18 @@ export declare class MatterportService {
     private isMeasureModeOn;
     private interactionMode;
     private cameraMode;
+    /** Emitted when a placement (tag following the cursor, or 3D object preview) is cancelled by right click or Escape */
+    readonly placementCancelled$: Subject<void>;
+    /** Pending interactive placement of a 3D object (see startObject3DPlacement) */
+    private object3DPlacement;
+    /** Sweeps snapshot taken when navigation is locked (disabled sweeps vanish from Sweep.data) */
+    private lockedSweepsSnapshot;
+    /**
+     * Every sweep seen in Sweep.data. After an unlock the SDK re-emits the re-enabled sweeps little by
+     * little: a lock asked meanwhile must still know all of them (it found nothing to disable).
+     */
+    private knownSweeps;
+    private keydownTargets;
     get mattertagIDs(): Array<string>;
     set mattertagIDs(value: Array<string>);
     get dictionnaryTags(): Map<string, MattertagData>;
@@ -414,15 +426,102 @@ export declare class MatterportService {
     clearAll(): Promise<void>;
     removeForbiddenSweeps(forbiddenSweeps: string[]): Promise<void>;
     init3DObjectViewer(): Promise<void>;
-    add3DObject(obj: IObject3D, mode?: 'translate' | 'rotate'): Promise<any>;
+    /**
+     * Adds a 3D model; resolves once it is loaded, rejects on unknown format or load timeout (~15 s).
+     */
+    add3DObject(obj: IObject3D, mode?: GizmoMode): Promise<any>;
     toggleObjectVisibility(objectId: any): void;
     isObjectVisible(objectId: any): boolean;
-    pointCameraTo3DObject(objectId: any): Promise<void>;
+    /** Moves the camera to the object (centered on its bounding box). Resolves false when the object is unknown. */
+    /**
+     * Moves the camera to the sweep closest to a 3D object and turns it toward the object.
+     * @param visibleArea client X bounds of the part of the viewer not covered by other panels
+     *                    (the lateral menu covers the right of the viewer): the object is centered there.
+     * Falls back to the temporary tag navigation when no sweep can be used.
+     */
+    pointCameraTo3DObject(objectId: any, visibleArea?: {
+        left: number;
+        right: number;
+    }): Promise<boolean>;
     getSceneNodeFromObject3DId(uuid: string): any;
     displayAzimutalCrown(): Promise<void>;
-    attachGizmoControlTo3DObject(modelNode: any, sceneObject: any, mode: 'translate' | 'rotate' | 'scale', visible: boolean, isNewObject: boolean): Promise<any>;
+    attachGizmoControlTo3DObject(modelNode: any, sceneObject: any, mode: GizmoMode, visible: boolean, isNewObject: boolean): Promise<any>;
     removeGizmoFromLastObject(): void;
-    toggleViewFrustum(): void;
+    /** Toggles the frustum of the security camera `uuid` (default: the last loaded one) */
+    toggleViewFrustum(uuid?: string): void;
+    setViewFrustum(uuid: string, visible: boolean): boolean;
+    isViewFrustumVisible(uuid: string): boolean;
+    /** Emits on gizmo changes and on setObject3DTransform / placeObject3DOnSurface / normalizeObject3DSize */
+    get object3DTransformChanged$(): Subject<Object3DTransformChange>;
+    /** World-space bounding box, null when the object is unknown or not loaded */
+    getObject3DBoundingBox(uuid: string): Object3DBoundingBox | null;
+    /** Dimensions of the model in meters, without its rotation */
+    getObject3DDimensions(uuid: string): Point3D | null;
+    /** Uniform scale so the largest dimension equals `targetSizeMeters`; returns the new scale or null */
+    normalizeObject3DSize(uuid: string, targetSizeMeters: number): Point3D | null;
+    /** Moves the object so its bounding box bottom-center (top-center on a ceiling) lies on `point` */
+    placeObject3DOnSurface(uuid: string, point: Point3D, normal?: Point3D, frontYawOffset?: number): Object3DTransform | null;
+    getObject3DTransform(uuid: string): Object3DTransform | null;
+    /** Rotation in radians */
+    setObject3DTransform(uuid: string, transform: Partial<Object3DTransform>): boolean;
+    attachGizmo(uuid: string, mode: GizmoMode): Promise<boolean>;
+    setGizmoMode(mode: GizmoMode): void;
+    detachGizmo(uuid?: string): void;
+    isGizmoAttached(uuid?: string): boolean;
+    /** null disables snapping (default) */
+    setGizmoSnap(snap: GizmoSnap | null): void;
+    /** Limits of a translate drag from its start (default 2 m, +/- 1.5 m vertically) */
+    setGizmoMaxDragDistance(maxDistance: number, maxHeight?: number): void;
+    /**
+     * Locks / unlocks camera navigation to other sweeps while a gizmo is edited: every enabled sweep
+     * except the current one is disabled, and exactly those are re-enabled on unlock.
+     * @returns false when the lock could not be applied (SDK not ready, current sweep unknown)
+     */
+    setNavigationLocked(locked: boolean): Promise<boolean>;
+    isNavigationLocked(): boolean;
+    /**
+     * Makes an already loaded model follow the cursor on the surfaces of the visit.
+     * Left click resolves with the surface point / normal under the cursor (read the object origin
+     * with getObject3DTransform); right click or Escape hides the model and resolves null
+     * (deleting it is up to the caller). Resolves null right away if another interaction is running.
+     */
+    startObject3DPlacement(uuid: string, options?: {
+        frontYawOffset?: number;
+    }): Promise<Object3DPlacementResult | null>;
+    isPlacingObject3D(): boolean;
+    /** Cancels the running object placement (model hidden, promise resolves null) */
+    cancelObject3DPlacement(): void;
+    /**
+     * Drops the object where it is previewed (same as a left click). Touch screens have no hover: each
+     * tap moves the preview, and the app confirms with a button.
+     * @returns false when no surface was pointed yet
+     */
+    confirmObject3DPlacement(): boolean;
+    /** True once the preview stands on a surface (the placement can be confirmed) */
+    hasObject3DPlacementPoint(): boolean;
+    private validateObject3DPlacement;
+    private endObject3DPlacement;
+    private updateObject3DPlacementPreview;
+    /** Token for the pointer trick: truthy while something follows the cursor (tag or 3D object) */
+    private getFollowTarget;
+    /**
+     * Cancels whatever follows the cursor (right click / Escape): the 3D object preview, or the tag.
+     * Emits placementCancelled$ when something was actually running.
+     */
+    private cancelCurrentPlacement;
+    /** Escape cancels any placement. Listens on the page and on the (same-origin) Showcase iframe, which takes the focus on click. */
+    private registerEscapeListener;
+    private removeEscapeListener;
+    ngOnDestroy(): void;
+    /**
+     * Closest enabled sweep to a world position (for instance to re-assign the zone of a moved object).
+     * `sweepId` is the DB-format id (like currentSweep), `sid` the SDK id. null when no sweep is known.
+     */
+    findNearestSweep(position: Point3D): {
+        sweepId: string;
+        sid: string;
+        floorSequence: number | null;
+    } | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<MatterportService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MatterportService>;
 }

package/lib/services/models/base-object.service.d.ts

@@ -17,11 +17,10 @@ export declare class BaseObjectService {
         };
     } | void>;
     /**
-     * The space's 3D visit, or null when it has none.
+     * The 3D visit to show a POI in, or null when the space has none.
      *
-     * Takes the first one the database returns. That is not the space's chosen default - the
-     * default ordering lives in SpaceService, which cannot be injected here. The POI does not record
-     * which capture it was placed in, so with several 3D models this is a guess either way.
+     * The one the POI was placed in, when it says. Older POIs do not, and for those it is the first
+     * 3D visit the database returns - a guess, when the space has several.
      */
     private getThreeJsVisitForSpace;
     updateIconForAllObjects(objects: Ticket[] | Feature[] | Equipment[], tagIcon: string): Promise<POI[]>;

package/lib/services/models/measurement.service.d.ts

@@ -42,6 +42,7 @@ export declare class MeasurementService {
     createMeasurementForSpace(commentInput: Comment, dataMeasurements: {
         measure: any[];
         sweep: string;
+        metadata?: string;
     }, screenshot: any, spaceID: string): Promise<Measurement>;
     getModel3DForMeasurement(measurement: Measurement): Promise<string>;
     getMeasurementsForSpaceForUser(spaceID: string): Promise<Measurement[]>;

package/lib/services/sweep-locator.service.d.ts

@@ -0,0 +1,54 @@
+import { CaptureService } from './models/capture.service';
+import { NavigationService } from './models/navigation.service';
+import * as i0 from "@angular/core";
+interface SweepPosition {
+    sweepID: string;
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Finds the Matterport sweep a point in a space sits closest to.
+ *
+ * A tag placed in Matterport is recorded with the sweep it was placed from, and much of the
+ * Matterport side keys on that: which floor plan draws the tag, which zone it belongs to, which
+ * floor it shows on. A tag placed in the Three.js viewer has no sweep, so it was missing from all
+ * of them. Resolving the nearest one at creation - what the tag copy tool already does for copied
+ * tags - lets every one of those readers work unchanged instead of each growing its own exception.
+ */
+export declare class SweepLocatorService {
+    private captureService;
+    private navigationService;
+    /**
+     * Sweeps sit a few metres apart, so a point on a scanned surface always has one nearby. Anything
+     * further means the coordinates are not in the Matterport capture's space - a model that was
+     * never calibrated - and a sweep picked from that far would file the tag under an arbitrary
+     * floor. Leaving it without one is the honest answer there.
+     */
+    private static readonly MAX_DISTANCE_METRES;
+    /** Sweep positions per space. They only change on import, so one load per session is enough. */
+    private readonly sweepsBySpace;
+    constructor(captureService: CaptureService, navigationService: NavigationService);
+    /**
+     * The sweep nearest to a point, or null when the space has none within reach.
+     *
+     * Never throws: this only refines where a tag is filed, and a tag that cannot be filed is still
+     * better saved without a sweep than not saved at all.
+     */
+    findNearestSweep(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, spaceID: string): Promise<string | null>;
+    /** The sweep closest to a point, or null when none is within reach. */
+    nearestSweep(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, sweeps: SweepPosition[]): string | null;
+    private loadSweeps;
+    private fetchSweeps;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SweepLocatorService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SweepLocatorService>;
+}
+export {};