MapCamera - @magiclane/maps-sdk API Reference

MapCamera class

Map camera class.

This class should not be instantiated directly. Instead, use the GemView.camera getter to obtain an instance.

Controls the map view camera. It lets clients save and restore the camera state, read the current orientation and position, and set position or orientation either directly (quaternion/3D position) or via higher‑level camera transforms (absolute camera placement, target‑centered or target‑relative setups).

It also provides helpers to compute a camera position and orientation for a given geographic target and heading/pitch/roll or distance parameters, returning a typed position+orientation result together with an operation status.

Common uses are persisting/ restoring view state, programmatically placing the camera around a point or object, and generating camera matrices for custom actors or animations.

Maps & 3D Scene

Signature:

export declare class MapCamera

Remarks

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the MapCamera class.

Properties

Property	Modifiers	Type	Description
cameraOrientation		Point3d	Sets the camera orientation, with respect to the surface of the focused sphere and current camera position, using heading in degrees (0=N, 90=E, 180=S, 270=W).
cameraPosition		Coordinates	Sets the camera's longitude, latitude position in degrees, with respect to the surface of the focused sphere, altitude in meters above the sphere (sea level), oriented toward the center of the sphere, north up.
cameraState		Uint8Array	Saves the current state of the camera into a binary format.
mapId	`readonly`	number
orientation		Point4d	Retrieves the current orientation of the camera.
pointerId	`readonly`	number \| bigint
position		Point3d	Retrieves the current position of the camera.

Methods

Method	Modifiers	Description
generatePositionAndOrientation(targetCoords)		Generates a position at longitude, latitude in degrees, with respect to the surface of the focused sphere, altitude in meters above the sphere (sea level), oriented toward the center of the sphere, north up. The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.
generatePositionAndOrientationHPR(targetCoords, headingPitchRollDeg)		Generates a position at longitude, latitude in degrees, with respect to the surface of the focused sphere, altitude in meters above the sphere (sea level), oriented toward the specified heading, pitch, and roll. The heading is 0 deg=North with respect to the focused sphere, 90 deg=East, 180 deg=South, 270 deg or -90 deg=west. Pitch is 0 deg=the object (or camera) forward vector looking toward the center of the focused sphere, 90 deg=looking at horizon. Roll is a rotation about the forward vector, positive deg to the left and negative deg to the right. The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.
generatePositionAndOrientationRelativeToCenteredTarget(targetCoords, targetHeadingPitchRollDeg, cameraHeadingPitchDegDistanceMeters)		Generates a position and orientation relative to, and oriented toward/centered on, a target position which is relative to the focused sphere (orientation relative to target). The target has the specified orientation where heading in degrees (0=N, 90=E, 180=S, 270=W) is with respect to the surface of the focused sphere, pitch in degrees (0=the target forward vector is oriented to the center of the focused sphere, 90=the target forward vector is oriented toward the horizon), and roll in degrees about the target forward vector, positive to the left and negative to the right. The generated orientation is toward, and with respect to, the target position, where heading in degrees (0=in the direction of the target heading, 90=looking at the target from its right/starboard side, 180=looking at the target from the front, 270=looking at the target from its left/port side). Pitch in degrees (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is the plane containing the target forward and right vectors, 180=looking at the target from below). The roll is always 0, so the horizon is level. The generated position is at the specified distance in meters from the target center. The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.
generatePositionAndOrientationRelativeToTarget(targetCoords, targetHeadingPitchRollDeg, cameraHeadingPitchDegDistanceMeters, cameraHeadingPitchRollDeg)		Generates a position and orientation relative to a target position, looking in any direction relative to the direction toward the target, all in the coordinate system of the focused target. This function is the same as generatePositionAndOrientationRelativeToCenteredTarget, except the orientation can be in a direction other than centered on the target. The orientation is centered on the target when the 4th parameter, the camera/observer heading, pitch, roll = 0, 0, 0. A nonzero heading, in degrees, specifies a rotation about the observer/camera up axis, going through the observer/camera position. A nonzero pitch, in degrees, specifies a rotation about the observer/camera right axis, going through the observer/camera position. A nonzero roll, in degrees, specifies a rotation about the observer/camera forward vector.
generatePositionAndOrientationTargetCentered(targetCoords, cameraHeadingPitchDegDistanceMeters)		Generates a position and orientation relative to, and oriented toward/centered on, a target position which is relative to the focused sphere (orientation relative to sphere). The specified target position is at lon,lat in degrees, with respect to surface of the focused sphere, altitude in meters above sphere (sea level). The target position does not have an orientation, so it can be considered a point. The generated orientation is toward the target position, where heading in degrees (0=N, 90=E, 180=S, 270=W) is with respect to the surface of the focused sphere, so heading 0 is looking at the target toward the north, from a position south of the target (the generated position is at 180 degrees as seen from the target). Pitch in degrees (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is the plane containing the target forward and right vectors). The roll is always 0, so the horizon is level. The generated position is at the specified distance in meters from the target center. The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.
setCameraRelativeToCenteredTarget(targetCoords, targetHeadingPitchRollDeg, cameraHeadingPitchDegDistanceMeters)		Sets the camera to look toward a target position, all in the coordinate system of the focused target. Target coordinates are lon, lat position in degrees, with respect to the focused sphere surface, altitude in meters above the sphere. The camera is centered on the target, at the specified distance in meters from the target, heading (0=looking at the target from behind it, in the direction of the target's heading, 90=looking at the target from its right/starboard side, 180=looking at the target from the front, 270=looking at the target from its left/port side) with respect to the focused target, and pitch (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is the plane containing the target forward and right vectors, 180=looking at the target from below). The roll is always 0, so the horizon is level.
setCameraRelativeToTarget(targetCoords, targetHeadingPitchRollDeg, cameraHeadingPitchDegDistanceMeters, cameraHeadingPitchRollDeg)		Sets the camera relative to a target position, looking in any direction relative to the direction toward the target, all in the coordinate system of the focused target. This function is the same as setCameraRelativeToCenteredTarget, except the camera can be oriented in a direction other than centered on the target. The camera is centered on the target when the 4th parameter, the camera/observer heading, pitch, roll = 0, 0, 0. A nonzero heading, in degrees, specifies a rotation about the observer/camera up axis, going through the observer/camera position. A nonzero pitch, in degrees, specifies a rotation about the observer/camera right axis, going through the observer/camera position. A nonzero roll, in degrees, specifies a rotation about the observer/camera forward vector.
setCameraTargetCentered(coords, pos)		Sets the camera to look toward a target position, all in the coordinate system of the focused sphere. Target coordinates are longitude, latitude position in degrees, with respect to the focused sphere surface, altitude in meters above the sphere (sea level). The camera is centered on the target, at the specified distance in meters from the target, heading (0=N, 90=E, 180=S, 270=W) with respect to the focused sphere, and pitch (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is the plane containing the target forward and right vectors). The roll is always 0, so the horizon is level.