Class Camera

Represents the virtual camera used to view a MicrioImage. Provides methods for controlling the viewport (position, zoom, rotation), converting between screen and image coordinates, and managing animations.

Instances are typically accessed via micrioImage.camera.

Author

Marcel Duin marcel@micr.io

Properties

`Readonly`center

center: Coords = ...

Current center screen coordinates [x, y] and scale [z]. For 360, also includes [yaw, pitch]. For Omni, also includes [frameIndex].

Methods

aniIsKinetic

aniIsKinetic(): boolean
Returns true if the camera is currently performing a kinetic pan/zoom (coasting).

Returns boolean

flyToCoo

flyToCoo(coords, opts?): Promise<void>
Animates the camera to center on specific image coordinates and scale.
Parameters
- coords: Coords
  The target coordinates [x, y, scale]. Scale is optional.
- opts: AnimationOptions = {}
  Optional animation settings.
Returns Promise<void>
A Promise that resolves when the animation completes.

flyToCoverView

flyToCoverView(opts?): Promise<void>
Animates the camera to a view where the image covers the viewport.
Parameters
- opts: AnimationOptions = {}
  Optional animation settings.
Returns Promise<void>
A Promise that resolves when the animation completes.

flyToFullView

flyToFullView(opts?): Promise<void>
Animates the camera to a view showing the entire image (minimum zoom).
Parameters
- opts: AnimationOptions = {}
  Optional animation settings.
Returns Promise<void>
A Promise that resolves when the animation completes.

flyToView

flyToView(view, opts?): Promise<void>
Animates the camera smoothly to a target view rectangle.
Parameters
- view: View
  The target viewport rectangle [x0, y0, x1, y1].
- opts: AnimationOptions & {
      area?: View;
      isJump?: boolean;
      limitZoom?: boolean;
      noTrueNorth?: boolean;
      omniIndex?: number;
      prevView?: View;
      progress?: number;
  } = {}
  Optional animation settings.
Returns Promise<void>
A Promise that resolves when the animation completes, or rejects if aborted.

getCoo

getCoo(x, y, absolute?, noLimit?): Float64Array
Gets the relative image coordinates [x, y, scale, depth, yaw?, pitch?] corresponding to a screen coordinate. Rounds the result for cleaner output.
Parameters
- x: number
  The screen X coordinate in pixels.
- y: number
  The screen Y coordinate in pixels.
- absolute: boolean = false
  If true, treats x/y as absolute browser window coordinates.
- noLimit: boolean = false
  If true, allows returning coordinates outside the image bounds (0-1).
Returns Float64Array
A Float64Array containing the relative image coordinates [x, y, scale, depth, yaw?, pitch?].

getCoverLimit

getCoverLimit(): boolean
Gets whether the cover limit is currently enabled.

Returns boolean

getCoverScale

getCoverScale(): number
Gets the scale at which the image fully covers the viewport.

Returns number

getDirection

getDirection(): number
Gets the current viewing direction (yaw) in 360 mode.

Returns number
The current yaw in radians.

getMatrix

getMatrix(x, y, scale?, radius?, rotX?, rotY?, rotZ?, transY?, scaleX?, scaleY?): Float32Array
Calculates a 4x4 transformation matrix for placing an object at specific coordinates with scale and rotation in 360 space. Used for CSS matrix3d.
Parameters
- x: number
  The image X coordinate (0-1).
- y: number
  The image Y coordinate (0-1).
- Optionalscale: number
  The object scale multiplier.
- Optionalradius: number
  The object radius (distance from center, default 10).
- OptionalrotX: number
  The object X rotation in radians.
- OptionalrotY: number
  The object Y rotation in radians.
- OptionalrotZ: number
  The object Z rotation in radians.
- OptionaltransY: number
  Optional Y translation in 3D space.
- OptionalscaleX: number
  Optional non-uniform X scaling.
- OptionalscaleY: number
  Optional non-uniform Y scaling.
Returns Float32Array
The resulting 4x4 matrix as a Float32Array.

getMinScale

getMinScale(): number
Gets the minimum allowed zoom scale for the image.

Returns number
The minimum scale.

getOmniFrame

getOmniFrame(rot?): number
[Omni] Gets the frame index corresponding to a given rotation angle (radians).
Parameters
- Optionalrot: number
Returns number

getOmniRotation

getOmniRotation(): number
[Omni] Gets the current rotation angle in degrees based on the active frame index.

Returns number

getOmniXY

getOmniXY(x, y, z): Float64Array
[Omni] Gets the screen coordinates [x, y, scale, depth] for given 3D object coordinates.
Parameters
- x: number
- y: number
- z: number
Returns Float64Array

getPitch

getPitch(): number
Gets the current viewing pitch in 360 mode.

Returns number
The current pitch in radians.

getQuad

getQuad(cX, cY, w, h, rotX?, rotY?, rotZ?, scaleX?, scaleY?): Float32Array
Calculates the screen coordinates of the four corners of a transformed quad in 360 space. Used for positioning HTML embeds accurately on the 360 sphere.
Parameters
- cX: number
  The quad center X coordinate (0-1).
- cY: number
  The quad center Y coordinate (0-1).
- w: number
  The quad relative width (0-1).
- h: number
  The quad relative height (0-1).
- rotX: number = 0
  Rotation over X axis (radians).
- rotY: number = 0
  Rotation over Y axis (radians).
- rotZ: number = 0
  Rotation over Z axis (radians).
- scaleX: number = 1
  Horizontal scale multiplier.
- scaleY: number = 1
  Vertical scale multiplier.
Returns Float32Array
A Float32Array containing the screen coordinates [x0,y0, x1,y1, x2,y2, x3,y3].

getScale

getScale(): number
Gets the current camera zoom scale.

Returns number

getView

getView(): View
Gets the current image view rectangle [x0, y0, x1, y1] relative to the image (0-1).

Returns View
A copy of the current screen viewport array, or undefined if not initialized.

getXY

getXY(x, y, abs?, radius?, rotation?, noTrueNorth?): Float64Array
Gets the screen coordinates [x, y, scale, depth] corresponding to relative image coordinates.
Parameters
- x: number
  The image X coordinate (0-1).
- y: number
  The image Y coordinate (0-1).
- abs: boolean = false
  If true, returns absolute browser window coordinates instead of element-relative.
- Optionalradius: number
  Optional offset radius for 360 calculations.
- Optionalrotation: number
  Optional offset rotation (radians) for 360 calculations.
- OptionalnoTrueNorth: boolean
  If true (for 360), ignores the trueNorth correction.
Returns Float64Array
A Float64Array containing the screen coordinates [x, y, scale, depth].

isZoomedIn

isZoomedIn(): boolean
Returns true if the camera is currently zoomed in to its maximum limit.

Returns boolean

isZoomedOut

isZoomedOut(full?): boolean
Returns true if the camera is currently zoomed out to its minimum limit.
Parameters
- full: boolean = false
  If true, checks against the absolute minimum scale (ignoring setMinScreenSize).
Returns boolean

pan

pan(x, y, duration?, opts?): void
Pans the camera view by a relative pixel amount.
Parameters
- x: number
  The horizontal pixel distance to pan.
- y: number
  The vertical pixel distance to pan.
- duration: number = 0
  Animation duration in ms (0 for instant).
- opts: {
  noLimit?: boolean;
  render?: boolean;
  } = {}
  Options: render (force render), noLimit (allow panning outside bounds).
  - OptionalnoLimit?: boolean
  - Optionalrender?: boolean
Returns void

pause

pause(): void
Pauses the current camera animation.

Returns void

resume

resume(): void
Resumes a paused camera animation.

Returns void

set360RangeLimit

set360RangeLimit(xPerc?, yPerc?): void
Limits the horizontal and vertical viewing range for 360 images.
Parameters
- xPerc: number = 0
  The horizontal arc limit as a percentage (0-1, where 1 = 360°). 0 disables horizontal limit.
- yPerc: number = 0
  The vertical arc limit as a percentage (0-1, where 1 = 180°). 0 disables vertical limit.
Returns void

setArea

setArea(v, opts?): void
Sets the rendering area for this image within the main canvas. Used for split-screen and potentially other layout effects. Animates by default.
Parameters
- v: View
  The target area rectangle [x0, y0, x1, y1] relative to the main canvas (0-1).
- opts: {
      direct?: boolean;
      noDispatch?: boolean;
      noRender?: boolean;
  } = {}
  Options for setting the area.
  - Optionaldirect?: boolean
    If true, sets the area instantly without animation.
  - OptionalnoDispatch?: boolean
    If true, prevents dispatching view updates during the animation.
  - OptionalnoRender?: boolean
    If true, prevents triggering a Wasm render after setting the area.
Returns void

setCoo

setCoo(x, y, scale?): void
Sets the center of the screen to the specified image coordinates and scale instantly.
Parameters
- x: number
  The target image X coordinate (0-1).
- y: number
  The target image Y coordinate (0-1).
- scale: number = ...
  The target scale (optional, defaults to current scale).
Returns void

setCoverLimit

setCoverLimit(b): void
Sets whether the camera view should be limited to always cover the viewport.
Parameters
- b: boolean
  If true, limits the view to cover the screen.
Returns void

setDirection

setDirection(yaw, pitch?): void
Sets the viewing direction (yaw and optionally pitch) instantly in 360 mode.
Parameters
- yaw: number
  The target yaw in radians.
- Optionalpitch: number
  Optional target pitch in radians.
Returns void

setLimit

setLimit(l): void
Sets a rectangular limit for camera navigation within the image.
Parameters
- l: View
  The viewport limit rectangle [x0, y0, x1, y1].
Returns void

setMinScale

setMinScale(s): void
Sets the minimum allowed zoom scale.
Parameters
- s: number
  The minimum scale to set.
Returns void

setMinScreenSize

setMinScreenSize(s): void
Sets the minimum screen size the image should occupy when zooming out (0-1). Allows zooming out further than the image boundaries, creating margins. Note: Does not work with albums.
Parameters
- s: number
  The minimum screen size fraction (0-1).
Returns void

setOmniSettings

setOmniSettings(): void
[Omni] Applies Omni-specific camera settings (distance, FoV, angle) to Wasm.

Returns void

setRotation

setRotation(rotX?, rotY?, rotZ?): void
Sets the 3D rotation for an embedded image (used for placing embeds in 360 space).
Parameters
- rotX: number = 0
- rotY: number = 0
- rotZ: number = 0
Returns void

setScale

setScale(s): void
Sets the camera zoom scale instantly.
Parameters
- s: number
  The target scale.
Returns void

setView

setView(v, opts?): void
Sets the camera view instantly to the specified rectangle.
Parameters
- v: View
  The target viewport rectangle [x0, y0, x1, y1].
- opts: {
      area?: View;
      correctNorth?: boolean;
      noLimit?: boolean;
      noRender?: boolean;
  } = {}
  Options for setting the view.
  - Optionalarea?: View
    If provided, interprets v relative to this sub-area instead of the full image.
  - OptionalcorrectNorth?: boolean
    If true (for 360), corrects the view based on the trueNorth setting.
  - OptionalnoLimit?: boolean
    If true, allows setting a view outside the normal image boundaries.
  - OptionalnoRender?: boolean
    If true, prevents triggering a Wasm render after setting the view.
Returns void

stop

stop(): void
Stops any currently running camera animation immediately.

Returns void

zoom

zoom(delta, duration?, x?, y?, speed?, noLimit?): Promise<void>
Performs an animated zoom centered on a specific screen point (or the current center).
Parameters
- delta: number
  The amount to zoom (positive zooms out, negative zooms in).
- duration: number = 0
  Forced duration in ms (0 for instant).
- x: number = undefined
  Screen pixel X-coordinate for zoom focus (optional, defaults to center).
- y: number = undefined
  Screen pixel Y-coordinate for zoom focus (optional, defaults to center).
- speed: number = 1
  Animation speed multiplier (optional).
- noLimit: boolean = false
  If true, allows zooming beyond image boundaries.
Returns Promise<void>
A Promise that resolves when the zoom animation completes.

zoomIn

zoomIn(factor?, duration?, speed?): Promise<void>
Zooms in by a specified factor.
Parameters
- factor: number = 1
  Zoom factor (e.g., 1 = standard zoom step).
- duration: number = 250
  Animation duration in ms.
- speed: number = 1
  Animation speed multiplier.
Returns Promise<void>
A Promise that resolves when the animation completes.

zoomOut

zoomOut(factor?, duration?, speed?): Promise<void>
Zooms out by a specified factor.
Parameters
- factor: number = 1
  Zoom factor (e.g., 1 = standard zoom step).
- duration: number = 250
  Animation duration in ms.
- speed: number = 1
  Animation speed multiplier.
Returns Promise<void>
A Promise that resolves when the animation completes.

Class Camera

Author

Index

Properties

Methods

Properties

Readonlycenter

Methods

aniIsKinetic

Returns boolean

flyToCoo

Parameters

Returns Promise<void>

flyToCoverView

Parameters

Returns Promise<void>

flyToFullView

Parameters

Returns Promise<void>

flyToView

Parameters

Returns Promise<void>

getCoo

Parameters

Returns Float64Array

getCoverLimit

Returns boolean

getCoverScale

Returns number

getDirection

Returns number

getMatrix

Parameters

Returns Float32Array

getMinScale

Returns number

getOmniFrame

Parameters

Returns number

getOmniRotation

Returns number

getOmniXY

Parameters

Returns Float64Array

getPitch

Returns number

getQuad

Parameters

Returns Float32Array

getScale

Returns number

getView

Returns View

getXY

Parameters

Returns Float64Array

isZoomedIn

Returns boolean

isZoomedOut

Parameters

Returns boolean

pan

Parameters

OptionalnoLimit?: boolean

Optionalrender?: boolean

Returns void

pause

Returns void

resume

Returns void

set360RangeLimit

Parameters

Returns void

setArea

Parameters

Optionaldirect?: boolean

OptionalnoDispatch?: boolean

OptionalnoRender?: boolean

Returns void

setCoo

`Readonly`center

`Optional`noLimit?: boolean

`Optional`render?: boolean

`Optional`direct?: boolean

`Optional`noDispatch?: boolean

`Optional`noRender?: boolean

`Optional`area?: View

`Optional`correctNorth?: boolean

`Optional`noLimit?: boolean

`Optional`noRender?: boolean