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

Methods

flyToCoo

flyToCoo(coords: Coords, opts?: AnimationOptions): 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?: AnimationOptions): 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?: AnimationOptions): 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: CameraArray,
    opts?: AnimationOptions & {
        isJump?: boolean;
        limitZoom?: boolean;
        margin?: [number, number];
        omniIndex?: number;
        prevView?: CameraArray;
        progress?: number;
    },
): Promise<void>
Animates the camera smoothly to a target viewport.
Parameters
- view: CameraArray
  The target viewport as a View [x0, y0, width, height].
- opts: AnimationOptions & {
      isJump?: boolean;
      limitZoom?: boolean;
      margin?: [number, number];
      omniIndex?: number;
      prevView?: CameraArray;
      progress?: number;
  } = {}
  Optional animation settings.
  - OptionalisJump?: boolean
    
    If true, performs a "jump" animation (zooms out then in).
  - OptionallimitZoom?: boolean
    
    If true, respects the image's maximum zoom limit during animation.
  - Optionalmargin?: [number, number]
    
    If provided, adds a margin to the view.
  - OptionalomniIndex?: number
    
    For Omni objects: the target image frame index to animate to.
  - OptionalprevView?: CameraArray
    
    Base the progress override on this starting view.
  - Optionalprogress?: number
    
    Set the starting animation progress percentage (0-1).
Returns Promise<void>
A Promise that resolves when the animation completes, or rejects if aborted.

getCoo

getCoo(
    x: number,
    y: number,
    absolute?: boolean,
    noLimit?: boolean,
): 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?].

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: number,
    y: number,
    scale?: number,
    radius?: number,
    rotX?: number,
    rotY?: number,
    rotZ?: number,
    transY?: number,
    scaleX?: number,
    scaleY?: number,
    noCorrectNorth?: boolean,
): 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.
- OptionalnoCorrectNorth: boolean
Returns Float32Array
The resulting 4x4 matrix as a Float32Array.

getMinScale

getMinScale(): number

Gets the minimum allowed camera zoom scale.

Returns number

getOmniRotation

getOmniRotation(): number

[Omni] Gets the current rotation angle in radians based on the active frame index.

Returns number

getOmniXY

getOmniXY(x: number, y: number, z: number): 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.

getScale

getScale(): number

Gets the current camera zoom scale.

Returns number

getView

getView(): CameraArray

Gets the current image view rectangle [x0, y0, width, height].

Returns CameraArray

getViewRaw

getViewRaw(): Float64Array

Gets the current image view rectangle [x0, y0, width, height] relative to the image (0-1).

Returns Float64Array
The live Float64Array buffer from the engine.

getXY

getXY(
    x: number,
    y: number,
    abs?: boolean,
    radius?: number,
    rotation?: number,
    noTrueNorth?: boolean,
): 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

Checks if the camera is zoomed in to the maximum allowed scale or beyond.

Returns boolean

isZoomedOut

isZoomedOut(full?: boolean): boolean
Checks if the camera is fully zoomed out.
Parameters
- full: boolean = false
Returns boolean

pan

pan(
    x: number,
    y: number,
    duration?: number,
    opts?: { noLimit?: boolean; render?: boolean },
): 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).
Returns void

pause

pause(): void

Pauses the current camera animation.

Returns void

resume

resume(): void

Resumes a previously paused camera animation and triggers a render.

Returns void

set360RangeLimit

set360RangeLimit(xPerc?: number, yPerc?: number): void
Sets horizontal and vertical pan limits for 360 images as percentages of the full sphere.
Parameters
- xPerc: number = 0
  Horizontal limit percentage (0-100).
- yPerc: number = 0
  Vertical limit percentage (0-100).
Returns void

setArea

setArea(
v: CameraArray,
opts?: { direct?: boolean; noDispatch?: boolean; noRender?: boolean },
): void
Sets the rendering area for this image within the main canvas. Used for grid/embed layout effects. Animates by default.
Parameters
- v: CameraArray
  The target area rectangle [x0, y0, width, height] relative to the main canvas (0-1).
- opts: { direct?: boolean; noDispatch?: boolean; noRender?: boolean } = {}
  Options for setting the area.
Returns void

setCoo

setCoo(x: number, y: number, scale?: number): 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).
- Optionalscale: number
  The target scale (optional, defaults to current scale).
Returns void

setCoverLimit

setCoverLimit(b: boolean): 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: number, pitch?: number): void
Sets the viewing direction (yaw/pitch) in 360 mode.
Parameters
- yaw: number
  The target yaw in radians.
- Optionalpitch: number
  The target pitch in radians (defaults to current pitch).
Returns void

setLimit

setLimit(v: CameraArray): void
Sets a rectangular limit for camera navigation within the image.
Parameters
- v: CameraArray
  The viewport limit [x, y, width, height] in image-relative coordinates.
Returns void

setMinScale

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

setMinScreenSize

setMinScreenSize(s: number): void
Sets the minimum screen size ratio that the image must occupy, restricting zoom-out.
Parameters
- s: number
Returns void

setRotation

setRotation(rotX?: number, rotY?: number, rotZ?: number): 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: number): void
Sets the camera zoom scale instantly.
Parameters
- s: number
Returns void

setView

setView(
view: CameraArray,
opts?: { correctNorth?: boolean; noLimit?: boolean; noRender?: boolean },
): void
Sets the camera view instantly to the specified viewport.
Parameters
- view: CameraArray
  The target viewport as a View [x0, y0, width, height].
- opts: { correctNorth?: boolean; noLimit?: boolean; noRender?: boolean } = {}
  Options for setting the view.
  - 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 render after setting the view.
Returns void

stop

stop(): void

Stops any ongoing camera animation immediately.

Returns void

zoom

zoom(
    delta: number,
    duration?: number,
    x?: number,
    y?: number,
    _speed?: number,
    noLimit?: boolean,
): 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).
- Optionalx: number
  Screen pixel X-coordinate for zoom focus (optional, defaults to center).
- Optionaly: number
  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?: number, duration?: number, speed?: number): 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?: number, duration?: number, speed?: number): 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

Methods

Methods

flyToCoo

Parameters

Returns Promise<void>

flyToCoverView

Parameters

Returns Promise<void>

flyToFullView

Parameters

Returns Promise<void>

flyToView

Parameters

OptionalisJump?: boolean

OptionallimitZoom?: boolean

Optionalmargin?: [number, number]

OptionalomniIndex?: number

OptionalprevView?: CameraArray

Optionalprogress?: number

Returns Promise<void>

getCoo

Parameters

Returns Float64Array

getCoverScale

Returns number

getDirection

Returns number

getMatrix

Parameters

Returns Float32Array

getMinScale

Returns number

getOmniRotation

Returns number

getOmniXY

Parameters

Returns Float64Array

getPitch

Returns number

getScale

Returns number

getView

Returns CameraArray

getViewRaw

Returns Float64Array

getXY

Parameters

Returns Float64Array

isZoomedIn

Returns boolean

isZoomedOut

Parameters

Returns boolean

pan

Parameters

Returns void

pause

Returns void

resume

Returns void

set360RangeLimit

Parameters

Returns void

setArea

Parameters

Returns void

setCoo

Parameters

Returns void

setCoverLimit

Parameters

Returns void

setDirection

Parameters

Returns void

setLimit

Parameters

`Optional`isJump?: boolean

`Optional`limitZoom?: boolean

`Optional`margin?: [number, number]

`Optional`omniIndex?: number

`Optional`prevView?: CameraArray

`Optional`progress?: number

`Optional`correctNorth?: boolean

`Optional`noLimit?: boolean

`Optional`noRender?: boolean