@smarterplan/ngx-smarterplan-core 1.4.15 → 1.4.17

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

@@ -0,0 +1,521 @@
+import { NgZone } from '@angular/core';
+import { Subject } from 'rxjs';
+import { ThreeJsAlignment } from '../helpers.service';
+import { PoiType } from '../types.service';
+import * as i0 from "@angular/core";
+/**
+ * A tag to draw in the Three.js scene, mirroring a Mattertag.
+ *
+ * Positions are in the model's own coordinate space - the same numbers stored in POI.coordinate -
+ * not scene space. The service reparents tags under the model so they inherit the centering and
+ * scaling applied at load, which means callers never deal with that transform.
+ */
+export interface ThreeJsTag {
+    /** The tagged element's id (POI.elementID), used to update or remove the tag later. */
+    id: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Drives both the click route and type filtering, so it travels with the tag. */
+    poiType?: PoiType | null;
+    /** Shown on hover. A marker with no identity is just a dot on a wall. */
+    label?: string | null;
+    /** Icon drawn on the tag. Falls back to a plain disc when absent or it fails to load. */
+    iconUrl?: string | null;
+    /** Tint for the fallback disc, as a CSS colour. */
+    color?: string;
+}
+/** What a click on a tag reports: enough to route to the element's detail page. */
+export interface ThreeJsTagClick {
+    elementId: string;
+    poiType: PoiType | null;
+}
+/**
+ * A spot picked on the model for a new tag.
+ *
+ * Both vectors are in the model's own coordinate space, which is what POI.coordinate stores. Scene
+ * coordinates deliberately never leave this service: the model is scaled to a fixed size on load, so
+ * a scene-space position would silently mean somewhere else the moment the .glb is re-exported.
+ */
+export interface ThreeJsTagPlacement {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Surface normal at the picked point - Matterport stores the same thing in POI.metadata. */
+    normal: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** What the placement was armed for, so the caller knows which creation form to open. */
+    poiType?: PoiType | null;
+}
+/** One tag seen in both spaces: where it is stored, and where it really sits on the model. */
+export interface ThreeJsAlignmentPair {
+    source: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/**
+ * Solves the transform that maps stored tag coordinates onto the loaded model.
+ *
+ * Takes exactly the correspondences a person can produce by hand: three tags, each pointed at twice
+ * - once where it currently sits, once where it belongs. That is the minimum that pins down all
+ * three parts of the answer. One pair fixes only translation; two leave the rotation about the line
+ * between them free; three resolve it.
+ *
+ * Returns null when the points are collinear or degenerate, because a wrong alignment applied
+ * silently is worse than none.
+ */
+export declare function solveThreeJsAlignment(pairs: ThreeJsAlignmentPair[]): ThreeJsAlignment | null;
+export interface ObjAdded {
+    id: string;
+    name: string;
+    file: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export declare class ThreeJsService {
+    private ngZone;
+    private scene;
+    private camera;
+    private renderer;
+    private controls;
+    private animationFrameId;
+    private raycaster;
+    private mouse;
+    private isDraggingCamera;
+    private isDraggingTimer;
+    private clickableObjects;
+    objectHovered$: Subject<{
+        id: string;
+        event: MouseEvent;
+    }>;
+    objectClicked$: Subject<string>;
+    /** Emits when the user clicks a tag, mirroring Matterport's tag click. */
+    tagClicked$: Subject<ThreeJsTagClick>;
+    /** Emits a tag's label while the pointer is over it, and null when it leaves. */
+    tagHovered$: Subject<{
+        label: string;
+        event: MouseEvent;
+    }>;
+    private tagGroup;
+    private tagSprites;
+    private canvasResizeObserver?;
+    /** Aborts the in-flight model download. Parsing cannot be interrupted, only not started. */
+    private loadAbortController?;
+    private modelRoot?;
+    /** True while the next click on the model places a tag instead of orbiting. */
+    private placingTag;
+    /** What the armed placement is for, echoed back when the spot is picked. */
+    private placementPoiType;
+    /** Position and normal of the last placed tag, in model space, awaiting commit to a POI. */
+    private pendingTagPlacement;
+    /** Pointer position waiting for a preview pick, coalesced to one per frame. */
+    private pendingPreviewEvent;
+    /**
+     * Layer carrying the model alone, so the depth pick can render it without the tags.
+     *
+     * Layers are tested per object at render time and children are traversed regardless of whether
+     * their parent passed, so marking the model's own meshes is enough - no re-parenting.
+     */
+    private static readonly PICK_LAYER;
+    /** Cache Storage bucket holding downloaded models, and how many to keep. */
+    private static readonly MODEL_CACHE;
+    private static readonly MODEL_CACHE_SIZE;
+    private pickTarget?;
+    private pickCamera?;
+    private pickDepthMaterial?;
+    private readonly pickPixel;
+    /** Emits once a tag is dropped on the model, so the UI can confirm and persist it. */
+    tagPlaced$: Subject<ThreeJsTagPlacement>;
+    /** Emits when the calibration walkthrough is abandoned, so the panel driving it can close. */
+    alignmentCancelled$: Subject<void>;
+    /** Translucent marker shown under the cursor while placing. */
+    private placementPreview?;
+    private aligning;
+    private alignmentPairs;
+    private alignmentSource;
+    /** Drives the alignment walkthrough's UI: how many pairs are done and what it wants next. */
+    alignmentProgress$: Subject<{
+        pairs: number;
+        awaiting: 'tag' | 'point' | null;
+        tagId?: string;
+    }>;
+    /** In-flight camera move started by goToTag, advanced by the render loop. */
+    private cameraTween;
+    /** Emits true while a heavy OBJ file is being parsed (in a worker, when available), false once done. */
+    modelLoading$: Subject<boolean>;
+    /**
+     * Download progress for GLB models, as a 0-1 fraction, or null when the total size is unknown.
+     *
+     * A null means the server did not send Content-Length (chunked responses, some proxies) and no
+     * percentage can be derived; show an indeterminate indicator rather than guessing at one.
+     */
+    modelLoadProgress$: Subject<number>;
+    /**
+     * Emits when a load actually stopped short, which is not the same as asking it to.
+     *
+     * cancelModelLoad() can arrive after parse() has taken the main thread, and parse cannot be
+     * interrupted - the model finishes loading regardless. Only this tells the UI which of the two
+     * happened, so it does not offer to reload something that is already on screen.
+     */
+    modelLoadCancelled$: Subject<void>;
+    private objParserWorker?;
+    private objParserPendingRequests;
+    constructor(ngZone: NgZone);
+    /**
+     * Registers a Web Worker used to parse heavy .obj files off the main thread.
+     * Must be instantiated by the consuming app (e.g. `new Worker(new URL('./obj-parser.worker', import.meta.url))`),
+     * since a library packaged with ng-packagr cannot bundle worker files itself.
+     * When no worker is provided, loadObjModel falls back to parsing on the main thread.
+     */
+    setObjParserWorker(worker: Worker): void;
+    private requestObjParseInWorker;
+    /** Rebuilds a THREE.Mesh from the raw typed arrays sent back by the parser worker. */
+    private meshFromParsedData;
+    init(canvas: HTMLCanvasElement): void;
+    /**
+     * Path (served by the app) holding basis_transcoder.js/.wasm, which KTX2Loader needs to turn
+     * Basis Universal textures into whatever compressed format the local GPU actually supports.
+     */
+    private ktx2TranscoderPath;
+    /** Overrides where the Basis transcoder files are served from. */
+    setKtx2TranscoderPath(path: string): void;
+    /**
+     * Loads a base 3D model in GLTF/GLB format - the preferred format for large models.
+     * Unlike .obj, geometry arrives as binary typed arrays (no text parsing to offload to a worker)
+     * and stays indexed, so far less data reaches the GPU. KTX2 textures are supported too: they
+     * stay compressed in VRAM instead of being decoded to raw pixels like JPEG/PNG.
+     */
+    loadGLTFModel(url: string, cameraPosition?: {
+        x: number;
+        y: number;
+        z: number;
+    }, rotation?: {
+        x: number;
+        y: number;
+        z: number;
+    }, cacheKey?: string): void;
+    /**
+     * Stops the model download in progress, if any.
+     *
+     * Only the download can be interrupted: parse() runs synchronously and holds the main thread until
+     * it finishes, so once it has begun there is nothing to cancel. In practice the download is the
+     * long part, which is where someone reaches for this.
+     */
+    cancelModelLoad(): void;
+    /**
+     * Abandons the load in progress without reporting it as cancelled.
+     *
+     * Dropping the controller is what makes the difference: onError treats an abort as user-initiated
+     * only while the controller that aborted is still the current one. Tearing down or rebuilding the
+     * scene is not something the person asked for, so it must not surface as "loading cancelled".
+     */
+    private discardCurrentLoad;
+    /**
+     * Resolves once the browser has painted at least one frame.
+     *
+     * A requestAnimationFrame callback runs *before* that frame is painted, so a single one is not
+     * enough to guarantee pending DOM changes are on screen; the second fires after the first frame
+     * has gone out. Falls back to a timeout where rAF isn't available (SSR, tests).
+     */
+    private afterNextPaint;
+    /**
+     * Downloads a file, reporting progress on modelLoadProgress$ as it arrives.
+     *
+     * GLTFLoader.load() would report progress through XHR, but this path deliberately uses fetch() +
+     * parse() instead (see loadGLTFModel for why), so progress is read off the response stream here.
+     * That is also the more useful number: on a model of this size the download dominates, and the
+     * stream reports it as it happens rather than in one jump at the end.
+     */
+    private fetchWithProgress;
+    /**
+     * The model store, or null where the browser will not give us one.
+     *
+     * Cache Storage needs a secure context, so it is absent over plain http and in some embedded
+     * webviews. Every caller treats that as a miss - caching is an optimisation, never a requirement.
+     */
+    private openModelCache;
+    /**
+     * A cached copy of this model, if one was stored.
+     *
+     * Keyed by the S3 key rather than the URL it is fetched from: that URL is signed, so it carries a
+     * fresh signature and expiry every time and would never match twice. The browser's own HTTP cache
+     * misses for the same reason, which is why this exists at all.
+     */
+    private readModelFromCache;
+    /** Stores a model for next time, evicting the oldest once a few are held. */
+    private writeModelToCache;
+    /** Cache Storage keys on a URL, so the S3 key is expressed as one. It is never requested. */
+    private modelCacheUrl;
+    /**
+     * Fits the camera's clipping planes to how big the model actually is.
+     *
+     * Depth precision depends on the far/near ratio, and the fixed 0.1 / 10000 the camera starts with
+     * is a ratio of 100000 for a model only ~10 units across. That wastes most of the depth buffer on
+     * empty space and lets nearly coincident surfaces - which captured meshes have everywhere -
+     * flicker against each other.
+     */
+    private adjustClippingPlanes;
+    /**
+     * Swaps the PBR materials GLTFLoader builds for the plain Phong ones the .obj path produces.
+     *
+     * MeshStandardMaterial keeps a specular reflection even at metalness 0, since every dielectric
+     * reflects some light, and Fresnel drives that reflection towards white as a surface turns away
+     * from the viewer. On an aerial view of a facade most surfaces sit at exactly those grazing
+     * angles, which paints white highlights over window frames and roof edges - the same model
+     * loaded as .obj never shows them, because MTLLoader builds Phong materials and OBJLoader zeroes
+     * their specular when the .mtl declares Ns 0.
+     *
+     * Captured models carry their lighting in the texture and want no specular response at all, so
+     * matching the .obj path here is both the fix and the more faithful choice.
+     */
+    private convertToPhongMaterials;
+    /**
+     * Renders every material double-sided.
+     *
+     * Reality capture meshes routinely contain triangles with reversed winding - an artefact of the
+     * reconstruction, not of the file. With the default FrontSide those triangles are culled, leaving
+     * scattered holes that show the scene background through the model. Against a light background
+     * they read as white specks with no discernible pattern.
+     *
+     * Drawing both sides costs a little fill rate but is what makes captured geometry render as
+     * solid; other viewers of this kind of content do the same unconditionally.
+     */
+    private forceDoubleSidedMaterials;
+    /**
+     * Computes real vertex normals for any geometry that arrived without them.
+     *
+     * A glTF without a NORMAL attribute is spec-compliant, and GLTFLoader handles it by switching the
+     * material to flatShading, which makes the shader derive the normal per pixel from screen-space
+     * derivatives. That derivation collapses on the degenerate, needle-thin triangles that reality
+     * capture meshes are full of: the face has almost no area, the derived normal is meaningless, and
+     * lighting blows those fragments out to white specks - densest exactly where fine detail is.
+     *
+     * Computing normals from the geometry instead is robust to those triangles, since a degenerate
+     * face contributes almost nothing to the average and its neighbours dominate.
+     */
+    private ensureVertexNormals;
+    /**
+     * Configures how every texture in a model is sampled: maximum anisotropy, and no mipmapping.
+     *
+     * Photogrammetry atlases pack their UV islands with unused gutter pixels between them. Mipmapping
+     * averages neighbouring pixels at each level, so those gutters bleed further into the islands the
+     * smaller the level gets - and viewing the whole model at once uses the smallest levels, painting
+     * bright gutter pixels over the edges of fine detail. Sampling the full-resolution image avoids
+     * that, at the cost of some shimmer on minified surfaces.
+     *
+     * Note that anisotropy only takes effect while mipmapping is on, so with the settings below it is
+     * inert; it is set anyway so the sampling stays correct for anyone who re-enables mipmaps here.
+     */
+    private tuneTextureSampling;
+    /**
+     * Loads an OBJ model with MTL.
+     * The heavy text-parsing step runs in a Web Worker when one has been registered via
+     * setObjParserWorker (see there for why the app, not this library, provides it); this keeps
+     * the main thread free while large architecture models (millions of vertices) are parsed.
+     * Falls back to parsing on the main thread otherwise.
+     */
+    loadObjModel(mtlUrl: string, objUrl: string, cameraPosition?: {
+        x: number;
+        y: number;
+        z: number;
+    }, rotation?: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    /** Centers, scales and adds a loaded object to the scene, then frames the camera on it. */
+    private placeLoadedObjectInScene;
+    /**
+     * Keeps the drawing buffer and camera matched to the canvas as it is resized.
+     *
+     * renderer.setSize() writes explicit pixel width/height into the canvas's style, overriding the
+     * 100%/100% it starts with. Without this, the canvas keeps whatever size it had at startup: hiding
+     * the top menu grows the container, the canvas does not follow, and the strip that opens up shows
+     * the page behind it instead of the scene.
+     *
+     * The parent is observed rather than the canvas, because resizing the canvas is what this reacts
+     * to - watching the element we resize would retrigger the observer.
+     */
+    private observeCanvasResize;
+    /**
+     * Starts the alignment walkthrough: pick a tag, then click where it really is, three times.
+     *
+     * Existing tags are the correspondences - they already carry the stored coordinate, so the person
+     * only has to supply the matching spot on the model. No new records are written; nothing is
+     * applied until solveAlignmentFromPairs() succeeds.
+     */
+    startTagAlignment(): void;
+    cancelTagAlignment(): void;
+    isAligningTags(): boolean;
+    /**
+     * Whether the pointer should be showing the placement ghost.
+     *
+     * True while placing a tag, and while calibrating once a tag has been picked - that second click
+     * is the same question ("where on the model?") and deserves the same aiming aid. Not true for the
+     * first half of a pair, which is a click on a tag, not on the model.
+     */
+    private isPreviewingPlacement;
+    /** Whether a tag is currently registered for this element. */
+    hasTag(elementId: string): boolean;
+    /**
+     * Solves and applies the alignment collected so far, returning it so the caller can persist it.
+     *
+     * Returns null when the three tags turn out to be collinear, in which case nothing is applied and
+     * the walkthrough stays open for the person to pick a better third point.
+     */
+    solveAlignmentFromPairs(): ThreeJsAlignment | null;
+    /** Handles a click while the alignment walkthrough is running. */
+    private handleAlignmentClick;
+    /** Arms tag placement: the next click on the model drops a tag instead of being ignored. */
+    startTagPlacement(poiType?: PoiType | null): void;
+    /** Leaves placement mode without placing anything. */
+    cancelTagPlacement(): void;
+    /**
+     * Shows a translucent tag under the cursor while placing, so the spot is visible before commiting.
+     *
+     * Matterport does this with a tag that follows the pointer; the equivalent here is a preview
+     * sprite that gets removed the moment the real tag takes its place.
+     */
+    private updatePlacementPreview;
+    /**
+     * The point under the cursor, read from the depth buffer instead of raycast, in tag space.
+     *
+     * A raycast walks every triangle of the mesh it hits: on a captured model that is millions of
+     * them, tens of milliseconds, every time the pointer moves. Coalescing to one per frame did not
+     * help, because the cost is the pick itself - it simply became one slow frame instead of several.
+     *
+     * Rendering the model's depth into a single pixel under the cursor answers the same question on
+     * the GPU in constant time, whatever the model's size. The camera's view offset is what narrows
+     * the whole image down to that one pixel, so the value read back is the depth the cursor is over.
+     *
+     * Used for the ghost only. The click that actually places a tag still raycasts: it is one pick,
+     * its cost does not matter, and it yields the surface normal, which depth alone cannot give.
+     */
+    private pickPointOnGpu;
+    private removePlacementPreview;
+    /** Shows or hides one tag, leaving it registered so it can be brought back without reloading. */
+    setTagVisibility(elementId: string, visible: boolean): void;
+    /**
+     * Shows only tags of the given types, hiding the rest.
+     *
+     * Passing null shows everything - the "no filter" state, distinct from an empty array, which is a
+     * filter that happens to match nothing.
+     */
+    setVisibleTagTypes(types: PoiType[] | null): void;
+    /**
+     * Moves the camera to look at a tag, mirroring Matterport's goToTag.
+     *
+     * Animated rather than teleported: jumping the camera loses the viewer's sense of where they were
+     * relative to the model. The approach distance follows the model's size so it frames sensibly
+     * whatever the units are.
+     */
+    goToTag(elementId: string): void;
+    /** Advances the camera animation started by goToTag, if one is running. */
+    private stepCameraTween;
+    isPlacingTag(): boolean;
+    /** The spot picked by the last placement, for whoever commits it to a POI. */
+    getPendingTagPlacement(): ThreeJsTagPlacement | null;
+    /**
+     * Raycasts a click against the model's geometry and returns the hit, in world space.
+     *
+     * Returns null when the click missed, which is a normal outcome - the user clicked the sky - and
+     * leaves whatever mode is armed still armed, so they can simply try again.
+     */
+    private raycastModel;
+    /**
+     * Turns a click into a point on the model, in the frame tag coordinates are persisted in.
+     *
+     * That frame is the tag group's, not the model's. A stored coordinate is read back as a sprite
+     * position inside that group, so a coordinate captured in any other frame comes back displaced by
+     * exactly however far the alignment moves the group. The two frames agree only while the
+     * alignment is identity, which is why this stayed invisible until a model was calibrated.
+     */
+    private pickPlacementOnModel;
+    /**
+     * Where the user says a tag really belongs, in the space the solved alignment maps onto.
+     *
+     * setTagAlignment writes the solution to the tag group's own transform, which is expressed
+     * relative to its parent - so the target has to be in the parent's frame. Measuring it in the
+     * group's own frame instead would fold the current alignment into the answer, making each
+     * calibration depend on the one before it.
+     */
+    private pickAlignmentTarget;
+    /**
+     * Sets the transform mapping captured tag coordinates onto this model's space.
+     *
+     * Every tag comes from the same source space, so this is one transform on the group rather than
+     * per-tag maths - which also means it applies retroactively to tags already placed, and can be
+     * adjusted live while someone dials the numbers in.
+     *
+     * Passing null resets to identity, i.e. tag coordinates are already in model space.
+     */
+    setTagAlignment(alignment: ThreeJsAlignment | null): void;
+    /**
+     * Adds a tag, or moves/restyles the one already registered for this element.
+     *
+     * Upsert rather than a declarative "here is the full list" call, because tags arrive per type
+     * (equipment, then tickets, then measurements...) from separate subscriptions - replacing the set
+     * on each of those would wipe the types that came before.
+     */
+    upsertTag(tag: ThreeJsTag): void;
+    /** Removes the tag registered for an element, if there is one. */
+    removeTag(elementId: string): void;
+    /** Removes every tag from the scene. */
+    clearTags(): void;
+    /** Loads an icon into an existing tag, leaving the fallback disc in place if it fails. */
+    private applyTagIcon;
+    /** Draws the default tag marker: a filled disc with a white ring, so it reads on any background. */
+    private createTagTexture;
+    /**
+     * Sizes a tag relative to the model.
+     *
+     * A sprite inherits the model's scale and the alignment's, so a fixed size would come out tiny on
+     * a large model and huge on a small one. Dividing by the group's world scale keeps tags the same
+     * size on screen whatever the model's units are.
+     */
+    private scaleTagForModel;
+    /**
+     * Adds secondary interactive objects (e.g., POIs, sensors) to the scene.
+     */
+    updateObjsToScene(objsAdded: ObjAdded[]): void;
+    private onMouseMove;
+    private onMouseClick;
+    /**
+     * Escape cancels whatever the pointer is currently committed to.
+     *
+     * Emits through the same subjects the explicit Cancel buttons use, so the UI driving them follows
+     * along instead of being left showing a mode that is no longer armed.
+     */
+    private onKeyDown;
+    private animate;
+    destroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThreeJsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThreeJsService>;
+}