@micrio/client 5.3.9 → 5.4.0

package/micrio.min.d.ts

@@ -4,7 +4,7 @@ declare module '@micrio/client' {
 	 * Defines the current version of the Micrio library.
 	 * This constant is used internally and exposed statically via `HTMLMicrioElement.VERSION`.
 	 */
-	export const VERSION = "5.3.9";
+	export const VERSION = "5.4.0";
 	/**
 	 * Loads an image texture asynchronously. Adds the request to the queue
 	 * and returns a Promise that resolves with the TextureBitmap or rejects on error.
@@ -33,6 +33,7 @@ declare module '@micrio/client' {
 	 * @returns Formatted time string (e.g., "1:23", "1:05:09", "-0:15").
 	 */
 	export function parseTime(s: number): string;
+	export const isLegacyViews: (i: Models.ImageInfo.ImageInfo) => boolean;
 	/**
 	 * Decodes a character from a Micrio ID into its numeric value (used for V4 short IDs).
 	 * @private
@@ -40,7 +41,7 @@ declare module '@micrio/client' {
 	export const getIdVal: (a: string) => number;
 	/** Checks if an ID likely belongs to the V5 format (6 or 7 characters). */
 	export const idIsV5: (id: string) => boolean;
-	/** Clamps a view rectangle [x0, y0, x1, y1] to the image bounds [0, 0, 1, 1]. */
+	/** Clamps a view rectangle the image bounds [0, 0, 1, 1]. */
 	export const limitView: (v: Models.Camera.View) => Models.Camera.View;
 	/**
 	 * Calculates the 3D vector and navigation parameters between two images in a 360 space.
@@ -63,6 +64,22 @@ declare module '@micrio/client' {
 	 * @returns True if native HLS support is detected.
 	 */
 	export const hasNativeHLS: (video?: HTMLMediaElement) => boolean;
+	export const View: {
+		/** Casts a legacy view array ([x0, y0, x1, y1]) to [x0,y0,width,height]. */
+		fromLegacy: (v?: Models.Camera.ViewRect | Models.Camera.View) => Models.Camera.View | undefined;
+		toCenterJSON: (v: Models.Camera.View) => {
+			centerX: number;
+			centerY: number;
+			width: number;
+			height: number;
+		};
+		rectToCenterJSON: (v: Models.Camera.View) => {
+			centerX: number;
+			centerY: number;
+			width: number;
+			height: number;
+		};
+	};
 	/**
 	 * Defines various enums used throughout the Micrio application,
 	 * primarily for standardizing action types and option values.
@@ -120,25 +137,37 @@ declare module '@micrio/client' {
 	export class Camera {
 		/** Current center screen coordinates [x, y] and scale [z]. For 360, also includes [yaw, pitch]. For Omni, also includes [frameIndex]. */
 		readonly center: Models.Camera.Coords;
+		/** CORRECT view: [x0, y0, width, height] */
+		private readonly view;
+		/**
+		 * Gets the current image view rectangle.
+		 * @returns A copy of the current screen viewport array, or undefined if not initialized.
+		 */
+		getView: () => Models.Camera.View;
+		/**
+		 * Gets the current image view rectangle [centerX, centerY, width, height] relative to the image (0-1).
+		 * @returns A copy of the current screen viewport array, or undefined if not initialized.
+		 */
+		getViewRaw: () => Float64Array;
 		/**
 		 * Gets the current image view rectangle [x0, y0, x1, y1] relative to the image (0-1).
 		 * @returns A copy of the current screen viewport array, or undefined if not initialized.
 		 */
-		getView: () => Models.Camera.View | undefined;
+		getViewLegacy: () => Models.Camera.ViewRect | undefined;
 		/**
-		 * Sets the camera view instantly to the specified rectangle.
-		 * @param v The target viewport rectangle [x0, y0, x1, y1].
+		 * Sets the camera view instantly to the specified viewport.
+		 * @param view The target viewport as either a View [x0, y0, x1, y1] or View {centerX, centerY, width, height}.
 		 * @param opts Options for setting the view.
 		 */
-		setView(v: Models.Camera.View, opts?: {
+		setView(view: Models.Camera.View, opts?: {
 			/** If true, allows setting a view outside the normal image boundaries. */
 			noLimit?: boolean;
 			/** If true (for 360), corrects the view based on the `trueNorth` setting. */
 			correctNorth?: boolean;
 			/** If true, prevents triggering a Wasm render after setting the view. */
 			noRender?: boolean;
-			/** If provided, interprets `v` relative to this sub-area instead of the full image. */
-			area?: Models.Camera.View;
+			/** If provided, interprets `view` relative to this sub-area instead of the full image. */
+			area?: Models.Camera.ViewRect;
 		}): void;
 		/**
 		 * Gets the relative image coordinates [x, y, scale, depth, yaw?, pitch?] corresponding to a screen coordinate.
@@ -185,7 +214,7 @@ declare module '@micrio/client' {
 		 * @param scaleY Optional non-uniform Y scaling.
 		 * @returns The resulting 4x4 matrix as a Float32Array.
 		 */
-		getMatrix(x: number, y: number, scale?: number, radius?: number, rotX?: number, rotY?: number, rotZ?: number, transY?: number, scaleX?: number, scaleY?: number): Float32Array;
+		getMatrix(x: number, y: number, scale?: number, radius?: number, rotX?: number, rotY?: number, rotZ?: number, transY?: number, scaleX?: number, scaleY?: number, noCorrectNorth?: boolean): Float32Array;
 		/**
 		 * Sets the camera zoom scale instantly.
 		 * @param s The target scale.
@@ -221,7 +250,7 @@ declare module '@micrio/client' {
 		 * Sets a rectangular limit for camera navigation within the image.
 		 * @param l The viewport limit rectangle [x0, y0, x1, y1].
 		*/
-		setLimit(l: Models.Camera.View): void;
+		setLimit(v: Models.Camera.ViewRect): void;
 		/**
 		 * Sets whether the camera view should be limited to always cover the viewport.
 		 * @param b If true, limits the view to cover the screen.
@@ -236,12 +265,12 @@ declare module '@micrio/client' {
 		*/
 		set360RangeLimit(xPerc?: number, yPerc?: number): void;
 		/**
-		 * Animates the camera smoothly to a target view rectangle.
-		 * @param view The target viewport rectangle [x0, y0, x1, y1].
+		 * Animates the camera smoothly to a target viewport.
+		 * @param view The target viewport as either a View [x0, y0, x1, y1] or View {centerX, centerY, width, height}.
 		 * @param opts Optional animation settings.
 		 * @returns A Promise that resolves when the animation completes, or rejects if aborted.
 		 */
-		flyToView: (view: Models.Camera.View, opts?: Models.Camera.AnimationOptions & {
+		flyToView: (view: Models.Camera.ViewRect | Models.Camera.View, opts?: Models.Camera.AnimationOptions & {
 			/** Set the starting animation progress percentage (0-1). */
 			progress?: number;
 			/** Base the progress override on this starting view. */
@@ -253,9 +282,11 @@ declare module '@micrio/client' {
 			/** If true (for 360), ignores the `trueNorth` correction. */
 			noTrueNorth?: boolean;
 			/** If provided, interprets `view` relative to this sub-area. */
-			area?: Models.Camera.View;
+			area?: Models.Camera.ViewRect;
 			/** If true, respects the image's maximum zoom limit during animation. */
 			limitZoom?: boolean;
+			/** If provided, adds a margin to the view. */
+			margin?: [number, number];
 		}) => Promise<void>;
 		/**
 		 * Animates the camera to a view showing the entire image (minimum zoom).
@@ -343,7 +374,7 @@ declare module '@micrio/client' {
 		 * @param v The target area rectangle [x0, y0, x1, y1] relative to the main canvas (0-1).
 		 * @param opts Options for setting the area.
 		 */
-		setArea(v: Models.Camera.View, opts?: {
+		setArea(v: Models.Camera.ViewRect, opts?: {
 			/** If true, sets the area instantly without animation. */
 			direct?: boolean;
 			/** If true, prevents dispatching view updates during the animation. */
@@ -549,7 +580,7 @@ declare module '@micrio/client' {
 		*/
 		class Image {
 			private image;
-			/** Writable Svelte store holding the current viewport [x0, y0, x1, y1] of this image. */
+			/** Writable Svelte store holding the current viewport [centerX, centerY, width, height] of this image. */
 			readonly view: Writable<Models.Camera.View | undefined>;
 			/** Getter for the current value of the {@link view} store. */
 			get $view(): Models.Camera.View | undefined;
@@ -579,7 +610,7 @@ declare module '@micrio/client' {
 		private attr;
 		opts: {
 			/** Optional sub area [x0, y0, x1, y1] defining placement within a parent canvas (for embeds/galleries). */
-			area?: Models.Camera.View;
+			area?: Models.Camera.ViewRect;
 			/** For split screen, the primary image this one is secondary to. */
 			secondaryTo?: MicrioImage;
 			/** If true, passively follows the view changes of the primary split-screen image. */
@@ -628,7 +659,7 @@ declare module '@micrio/client' {
 		/** Stores an error message if loading failed. */
 		error: string | undefined;
 		/** Svelte Writable store holding the calculated pixel viewport [left, top, width, height] of this image within the main canvas. */
-		readonly viewport: Writable<Models.Camera.View>;
+		readonly viewport: Writable<Models.Camera.ViewRect>;
 		/** Array of child {@link MicrioImage} instances embedded within this image. */
 		readonly embeds: MicrioImage[];
 		/** Grid controller instance, if this image is a grid container. */
@@ -642,7 +673,7 @@ declare module '@micrio/client' {
 		 * @param opts Embedding options (opacity, fit, etc.).
 		 * @returns The newly created embedded {@link MicrioImage} instance.
 		 */
-		addEmbed(info: Partial<Models.ImageInfo.ImageInfo>, area: Models.Camera.View, opts?: Models.Embeds.EmbedOptions): MicrioImage;
+		addEmbed(info: Partial<Models.ImageInfo.ImageInfo>, area: Models.Camera.ViewRect, opts?: Models.Embeds.EmbedOptions): MicrioImage;
 		/** Gets the HTMLMediaElement associated with a video embed ID. */
 		getEmbedMediaElement(id: string): HTMLMediaElement | undefined;
 		/** Fades in the image smoothly or instantly. */
@@ -793,7 +824,7 @@ declare module '@micrio/client' {
 		*/
 		enlarge(idx: number, width: number, height?: number): Promise<MicrioImage[]>;
 		/** Get the relative in-grid viewport of the image */
-		getRelativeView(image: MicrioImage, view: Models.Camera.View): Models.Camera.View;
+		getRelativeView(image: MicrioImage, view: Models.Camera.ViewRect): Models.Camera.ViewRect;
 	}
 	/**
 	 * Video tour controller. Manages playback and camera animation for video tours
@@ -905,9 +936,11 @@ declare module '@micrio/client' {
 				/** The Micrio version this image was created in
 				 * @default autoloaded
 				*/
-				version: number;
+				version: string;
 				/** Created date */
 				created?: number;
+				/** Has new viewport model, optimized for 360 images */
+				viewsWH?: boolean;
 				/** For V5+: published revisions per language */
 				revision?: RevisionType;
 				/** The original image width
@@ -973,7 +1006,7 @@ declare module '@micrio/client' {
 			}
 			/** Micrio image settings, which is on load included as {@link ImageInfo}`.settings`. */
 			type Settings = {
-				/** The starting viewport (`[x0,y0,x1,y1]`) */
+				/** The starting viewport */
 				view?: Camera.View;
 				/** Restrict navigation to this viewport (`[x0,y0,x1,y1]`) */
 				restrict?: Camera.View;
@@ -1635,6 +1668,8 @@ declare module '@micrio/client' {
 				keepMarkers?: boolean;
 				/** Don't disable user navigation when running */
 				keepInteraction?: boolean;
+				/** The tour is a direct outside instance using legacy [x0,y0,x1,y1] viewports */
+				isLegacy?: boolean;
 				/** Current running tour instance */
 				instance?: VideoTourInstance;
 			};
@@ -1901,7 +1936,7 @@ declare module '@micrio/client' {
 				baseTileIdx: number;
 				ptr: number;
 				opts: {
-					area: Camera.View;
+					area: Camera.ViewRect;
 				};
 			}
 		}
@@ -1912,8 +1947,8 @@ declare module '@micrio/client' {
 			/** Virtual ImageInfo extension to support grid logic */
 			interface GridImage extends Partial<ImageInfo.ImageInfo> {
 				size: [number, number?];
-				area?: Camera.View;
-				view?: Camera.View;
+				area?: Camera.ViewRect;
+				view?: Camera.ViewRect;
 			}
 			interface GridHistory {
 				layout: string;
@@ -1922,7 +1957,7 @@ declare module '@micrio/client' {
 			}
 			interface GridImageOptions {
 				view?: Camera.View;
-				area?: Camera.View;
+				area?: Camera.ViewRect;
 				size?: number[];
 			}
 			interface FocusOptions {
@@ -1984,7 +2019,9 @@ declare module '@micrio/client' {
 			hooked?: boolean;
 		}
 		namespace Camera {
-			/** A viewport rectangle */
+			/** A viewport rectangle [x0,y0,x1,y1] */
+			type ViewRect = number[] | Float64Array;
+			/** An area definition [x0,y0,width,height] */
 			type View = number[] | Float64Array;
 			/** Coordinate tuple, [x, y, scale] */
 			type Coords = [number, number, number?] | Float64Array;
@@ -2519,7 +2556,7 @@ declare module '@micrio/client' {
 			splitTo?: MicrioImage;
 			/** If true, opens the split-screen view passively (doesn't take focus). */
 			isPassive?: boolean;
-			/** An optional starting view `[x0, y0, x1, y1]` to apply immediately. */
+			/** An optional starting view to apply immediately. */
 			startView?: Models.Camera.View;
 			/** For 360 transitions, provides the direction vector from the previous image. */
 			vector?: Models.Camera.Vector;