reearth.camera
The reearth.camera
namespace provides a comprehensive set of functionalities for managing and interacting with the camera within the reearth
environment.
Properties
position
This property provides the current position and orientation of the camera within reearth
. It gives a comprehensive information about the camera’s geographical location, altitude, and angular orientation. This information is important for understanding or logging the camera’s viewpoint.
Syntax
reearth.camera.position: CameraPosition | undefined;
Return Value
Type CameraPosition
An object with detailed position and orientation data if the camera position is defined.
Type undefined
Indicates that the camera position is not currently available.
Example
// Example 1: Retrieve the current camera positionconst currentPosition = reearth.camera.position;
// Check if the position is availableif (currentPosition) { console.log("Latitude:", currentPosition.lat); console.log("Longitude:", currentPosition.lng); console.log("Height:", currentPosition.height); console.log("Heading:", currentPosition.heading); console.log("Pitch:", currentPosition.pitch); console.log("Roll:", currentPosition.roll);} else { console.log("Camera position is undefined.");}
fov
This represents the camera’s field of view (FOV) in reearth
, and defines the extent of the observable world seen at any given moment. This parameter is crucial for adjusting how broad or narrow the camera’s perspective is.
Please note that FOV is only available when the camera is in perspective mode.
Syntax
reearth.camera.fov: number | undefined
Return Value
Type number | undefined
A numeric value representing the field of view of the camera in radians. The field of view can significantly affect how content is perceived in a 3D space, with higher values providing a wider perspective, and lower values providing a more focused, zoomed-in view.
If the field of view is undefined, it indicates that the camera’s FOV is either not set or unavailable under current conditions.
Example
// Example 1: Access and log the camera's current field of viewconst cameraFov = reearth.camera.fov;
if (cameraFov !== undefined) { console.log("Current Camera FOV (radians):", cameraFov);} else { console.log("Camera FOV is undefined.");}
// Example 2: Adjust based on FOV// Check and adjust the camera's field of view if too wideconst cameraFov = reearth.camera.fov;
if (cameraFov !== undefined && cameraFov > 1) { console.log("Camera FOV is wide. Consider reducing for a more focused view.");} else if (cameraFov !== undefined) { console.log("Camera FOV is optimal for current view.");}
aspectRatio
This property represents the width-to-height ratio of the camera’s viewport in the reearth
environment. This ratio affects how content is displayed within the camera’s view, ensuring that objects are rendered without distortion based on the dimensions of the viewport.
Syntax
reearth.camera.aspectRatio: number | undefined
Return Value
Type number | undefined
A numeric value representing the aspect ratio of the camera’s viewport, defined as the width divided by the height. For example, a typical widescreen monitor might have an aspect ratio of 16:9, represented as approximately 1.78, while a square aspect ratio would be 1:1 (1.0). The aspect ratio influences how objects appear in the view, with wider aspect ratios providing more horizontal view and taller aspect ratios offering more vertical view.
Example
// Example 1: Access and log the camera's current aspect ratioconst cameraAspectRatio = reearth.camera.aspectRatio;
if (cameraAspectRatio !== undefined) { console.log("Current Camera Aspect Ratio:", cameraAspectRatio);} else { console.log("Camera aspect ratio is undefined.");}
// Example 2: Adjust camera view based on aspect ratioconst cameraAspectRatio = reearth.camera.aspectRatio;
if (cameraAspectRatio !== undefined && cameraAspectRatio > 1.8) { console.log( "Camera aspect ratio is very wide. Consider adjusting the view for better composition." );} else if (cameraAspectRatio !== undefined) { console.log("Camera aspect ratio is within a normal range.");}
viewport
This property represents the geographic boundaries currently visible in the camera’s view. It returns a GeoRect object defining the western, southern, eastern, and northern extents of the camera’s visible area, which can be useful for understanding the camera’s field of view in geographic coordinates.
Syntax
reearth.camera.viewport: GeoRect | undefined
Return Value
Type GeoRect | undefined
An object describing the geographic boundaries of the current viewport.
If the viewport is undefined, it indicates that the camera’s current geographic boundaries are not set or cannot be retrieved, which might occur in scenarios where the camera is not focused on a geographic region.
Example
// Example 1: Access and log the current geographic boundaries of the viewportconst viewportBounds = reearth.camera.viewport;
if (viewportBounds) { console.log("Viewport bounds:"); console.log("West:", viewportBounds.west); console.log("South:", viewportBounds.south); console.log("East:", viewportBounds.east); console.log("North:", viewportBounds.north);} else { console.log("Viewport is undefined.");}
// Example 2: Check viewport and suggest adjustmentsconst viewportBounds = reearth.camera.viewport;
if (viewportBounds) { console.log("Current Viewport:", viewportBounds);
// Check if viewport extends too far west or east if (viewportBounds.west < -180 || viewportBounds.east > 180) { console.log( "Viewport extends beyond global bounds. Consider adjusting the camera." ); } else { console.log("Viewport is within normal geographic bounds."); }} else { console.log("Viewport is undefined.");}
Methods
flyTo
This method smoothly moves the camera to a specified destination with optional controls for animation duration, easing, and field of view (FOV). This function is useful for guiding the camera to specific locations or layers in the scene, allowing for smooth transitions and custom animations.
Syntax
reearth.camera.flyTo( destination: LayerId | CameraPosition, options?: CameraMoveOptions & { fov?: number }) => void;
Parameters
destination
Specifies the target destination for the camera. It can be a LayerId (string) to focus on a specific layer or a CameraPosition object specifying the precise geographic and orientation parameters.
Type: LayerId | CameraPosition
LayerId
: A string that represents the ID of a specific layer that the camera should move to.
CameraPosition
: An object defining the camera’s latitude, longitude, height, and orientation.
options
Optional
An optional object that provides control over the movement animation and field of view.
Type: CameraMoveOptions & { fov?: number }
CameraMoveOptions:
An object that provides control over the movement animation
fov?: number:
Specifies the field of view (in radians) for the destination. Adjusts the camera’s FOV as part of the transition.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Fly to specified coordinates with a 3-second animationreearth.camera.flyTo( { lat: 35.6895, lng: 139.6917, height: 500 }, // Tokyo coordinates { duration: 3 } // 3-second animation duration);
// Example 2: Fly to a layer instantly without animationconst layerId = "layer123";reearth.camera.flyTo(layerId, { withoutAnimation: true });
// Example 3: Fly to coordinates with a 4-second animation, custom FOV, and easing functionreearth.camera.flyTo( { lat: 48.8566, // Latitude for Paris lng: 2.3522, // Longitude for Paris height: 1500, // Altitude in meters heading: 0.785, // Heading in radians (45 degrees clockwise) pitch: -0.523, // Pitch in radians (30 degrees downward) roll: 0, // No roll }, { duration: 4, // Set animation duration to 4 seconds withoutAnimation: false, // Ensure animation is enabled fov: 0.8, // Set field of view to 0.8 radians easing: (t) => t * t, // Custom easing for a slower start });
flyToBoundingBox
This smoothly moves the camera to focus on a specified geographic bounding box, with optional parameters for animation, orientation, and distance. This method is useful for zooming out to show a region or zooming in to highlight specific areas within the viewport.
Syntax
reearth.camera.flyToBoundingBox( boundingBox: GeoRect, options?: CameraMoveOptions & { heading?: number; pitch?: number; range?: number; }) => void;
Parameters
boundingBox
Type: GeoRect
An object that defines the geographic boundaries of the target area
options
Optional
An object to control animation, orientation, and zoom level.
Type:
CameraMoveOptions & { heading?: number; pitch?: number; range?: number;}
heading?: number;
The direction the camera faces in radians, where 0 points north. Positive values rotate clockwise.
pitch?: number;
The vertical angle of the camera, in radians. Negative values tilt downward.
range?: number;
The distance from the center of the bounding box to the camera, in meters. This controls the zoom level.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Fly to a bounding box with a 2-second animationreearth.camera.flyToBoundingBox( { west: -74.1, south: 40.7, east: -73.9, north: 40.8 }, // New York City area { duration: 2 } // 2-second animation duration);
// Example 2: Fly to a bounding box without animationreearth.camera.flyToBoundingBox( { west: 139.6, south: 35.6, east: 139.8, north: 35.7 }, // Tokyo area { withoutAnimation: true });
// Example 3: Fly to a bounding box with full parameters in usereearth.camera.flyToBoundingBox( { west: -122.55, // Western boundary of San Francisco area south: 37.7, // Southern boundary east: -122.35, // Eastern boundary north: 37.85, // Northern boundary }, { duration: 5, // Set animation duration to 5 seconds withoutAnimation: false, // Enable animation easing: (t) => t * t, // Custom easing for a slower start heading: 0.785, // Set heading to 0.785 radians (45 degrees clockwise) pitch: -0.523, // Tilt downward to -0.523 radians (30 degrees) range: 4000, // Set camera distance to 4000 meters from the center });
zoomIn
This method moves the camera closer to the scene by reducing the camera’s altitude. The zoom effect can be customized with optional animation settings such as duration and easing. This method is useful for providing a more detailed view of objects or areas in the scene.
Syntax
reearth.camera.zoomIn: (amount: number, options?: CameraMoveOptions) => void;
Parameters
amount
Type: number
Specifies the zoom level. A positive value moves the camera closer to the scene by reducing the altitude, larger values result in greater zoom level. Negative values would theoretically move the camra further away.
options
Optional
An object to control the animation of the zoom operation.
Type:CameraMoveOptions
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Zooming in on the current view by a factor with animationreearth.camera.zoomIn(2, { duration: 3, easing: (t) => t * (2 - t), // Quadratic easing in-out});
// Example 2: Instant zoom in without animationreearth.camera.zoomIn(100, { withoutAnimation: true,});
// Example 4: Zoom in with animation and custom easing functionreearth.camera.zoomIn(500, { duration: 3, // Set animation duration to 3 seconds withoutAnimation: false, // Enable animation easing: (t) => t * t, // Custom easing function for slower start});
zoomOut
This is used for decreasing the camera’s zoom level relative to its current position by a specified amount, enabling a wider view of the scene.. The zoom effect can be customized with optional animation settings such as duration and easing. This method is useful for providing a broader view of the environment or for transitioning to a wide perspective.
Syntax
reearth.camera.zoomOut(amount: number, options?: CameraMoveOptions) => void;
Parameters
amount
Type: number
Specifies the zoom level. A positive value moves the camera farther from the scene by increasing the altitude. Larger values result in a more significant zoom-out effect.
options
Optional
An object to control the animation of the zoom operation.
Type:CameraMoveOptions
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Zoom out instantlyreearth.camera.zoomOut(10, { withoutAnimation: true });
// Example 2: Zoom out with a custom easing functionreearth.camera.zoomOut(5, { duration: 2, // Set animation duration to 2 seconds easing: (t) => t * t, // Custom easing for a slower start});
// Example 3: Zoom out with a custom easing function and animationreearth.camera.zoomOut(15, { duration: 4, // Animation lasts 4 seconds withoutAnimation: false, // Enable animation easing: (t) => t * (2 - t), // Custom easing for smooth acceleration and deceleration});
lookAt
This adjusts the camera to focus on a specified destination, allowing control over the camera’s orientation, distance, and field of view (FOV). This method is ideal for directing the user’s attention to specific locations or objects within the scene.
Syntax
reearth.camera.lookAt( destination: LookAtDestination, options?: CameraMoveOptions & { fov?: number }) => void;
Parameters
destination
Type: LookAtDestination
An object that pecifies the target location for the camera.
options
Optional
An optional object that provides control over the movement animation and field of view.
Type: CameraMoveOptions & { fov?: number }
CameraMoveOptions:
An object that provides control over the movement animation.
fov?: number:
Specifies the field of view (in radians) for the destination. Adjusts the camera’s FOV as part of the transition.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Focus on specific coordinates with a default animationreearth.camera.lookAt({ lat: 34.0522, // Latitude for Los Angeles lng: -118.2437, // Longitude for Los Angeles height: 1000, // Altitude in meters});
// Example 2: Focus on coordinates with custom heading, pitch, and rangereearth.camera.lookAt( { lat: 51.5074, // Latitude for London lng: -0.1278, // Longitude for London height: 1000, // Altitude in meters heading: 1.57, // Heading in radians (90 degrees clockwise) pitch: -0.785, // Pitch in radians (45 degrees downward) range: 2000, // 2 kilometers from the focus point }, { duration: 3, // Set animation duration to 3 seconds });
// Example 3: Use all destination and options parametersreearth.camera.lookAt( { lat: 35.6895, // Latitude for Tokyo lng: 139.6917, // Longitude for Tokyo height: 500, // Altitude in meters heading: 0.785, // Heading in radians pitch: -0.523, // Pitch in radians range: 1500, // 1.5 kilometers from the focus point radius: 100, // Focus area radius in meters }, { duration: 5, // Animation lasts 5 seconds withoutAnimation: false, // Enable animation easing: (t) => t * t, // Custom easing for a slower start fov: 1.2, // Set field of view to 1.2 radians });
getGlobeIntersection
This calculates the intersection of the camera’s view with the globe’s surface or terrain. It returns the geographic coordinates (latitude, longitude, and height) of the intersection point and optionally calculates the visible area of the viewport. This method is particularly useful for applications that require interaction with the ground or terrain, such as measuring distances or determining visibility.
Syntax
reearth.camera.getGlobeIntersection: (options: Options) => | { center?: LatLngHeight; viewSize?: number; } | undefined;
Parameters
options
An optional object to control the intersection calculation.
Type:
type Options = { withTerrain?: boolean; calcViewSize?: boolean;};
withTerrain?: boolean;
: If true, the function accounts for terrain height when calculating the intersection point. Default is false (flat terrain). If false or omitted, the calculation assumes a flat globe surface.
calcViewSize?: boolean;
: If true, the function calculates the size of the visible area on the ground (view size) from the camera’s perspective in meters. Default is false.
Return Value:
{center?: LatLngHeight; viewSize?: number;} | undefined
The function returns an object if an intersection is found, or undefined if there is no intersection.
center?: LatLngHeight
: The geographic coordinates of the intersection point.
type LatLngHeight = { lat: number; // Latitude of the intersection point in decimal degrees. lng: number; // Longitude of the intersection point in decimal degrees. height: number; // Height of the intersection point above the ground in meters.};
viewSize?: number
: The size of the visible area (in meters) on the ground from the camera’s perspective.
Example
// Example 1: Calculate intersection with terrain and view sizeconst intersection = reearth.camera.getGlobeIntersection({ withTerrain: true, // Enable terrain intersection calcViewSize: true, // Calculate visible area size});
if (intersection) { console.log("Intersection Point:", intersection.center); console.log("View Size (meters):", intersection.viewSize);} else { console.log("No intersection found.");}
// Example 2: Calculate intersection with a flat globe surface and no view size calculationconst intersection = reearth.camera.getGlobeIntersection({ withTerrain: false, // Assume a flat globe surface calcViewSize: false, // Do not calculate the visible area size});
if (intersection && intersection.center) { console.log("Intersection Point:", intersection.center); console.log("Latitude:", intersection.center.lat); console.log("Longitude:", intersection.center.lng); console.log("Height:", intersection.center.height);} else { console.log("No intersection found.");}
// Example 3: Safely handle undefined intersectionconst intersection = reearth.camera.getGlobeIntersection({ withTerrain: true,});
if (!intersection) { console.log("No intersection found. The camera may be above the globe.");} else if (intersection.center) { console.log("Latitude:", intersection.center.lat); console.log("Longitude:", intersection.center.lng); console.log("Height:", intersection.center.height);}
rotateAround
This method enables the camera to rotate around its current focus point by a specified angle in radians. This functionality is useful for exploring a scene while keeping the focus point stationary.
Syntax
reearth.camera.rotateAround(radian: number) => void;
Parameters
radian
Type: number
The angle by which to rotate the camera, measured in radians. Positive values rotate the camera clockwise, and negative values rotate it counterclockwise.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Rotate the camera 1 radian clockwisereearth.camera.rotateAround(1);
// Example 2: Rotate the camera -0.5 radians counterclockwisereearth.camera.rotateAround(-0.5);
rotateRight
This method enables the camera to rotate to the right around its current position by a specified angle in radians, without focusing on any specific external point.
Syntax
reearth.camera.rotateRight(radian: number) => void;
Parameters
radian
Type: number
The angle by which to rotate the camera, measured in radians. Positive values rotate the camera to the right, and negative values rotate it to the left.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Rotate the camera 0.785 radians (45 degrees) to the rightreearth.camera.rotateRight(0.785);
// Example 2: Rotate the camera 1 radian to the right (clockwise)reearth.camera.rotateRight(1);
// Example 3: Rotate the camera -1.57 radians (-90 degrees) to the left (counterclockwise)reearth.camera.rotateRight(-1.57);
orbit
This enables the camera to rotate around the center of the Earth by a specified angle in radians, providing a global perspective. This functionality is particularly useful for quickly exploring the globe from different angles.
Syntax
reearth.camera.orbit(radian: number) => void;
Parameters
radian
Type: number
The angle by which to orbit the camera, measured in radians. Positive values orbit the camera clockwise, and negative values orbit it counterclockwise.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Orbit the camera 2 radians clockwise around the Earthreearth.camera.orbit(2);
// Example 2: Orbit the camera -1 radian counterclockwise around the Earthreearth.camera.orbit(-1);
move
This method allows the camera to move in a specified direction relative to its current position. This method is useful for navigating the scene dynamically, providing precise control over the camera’s movement along different axes.
Syntax
reearth.camera.move( direction: "forward" | "backward" | "up" | "down" | "left" | "right", amount: number) => void;
Parameters
direction
Type: "forward" | "backward" | "up" | "down" | "left" | "right"
forward
: Moves the camera forward (closer to the direction it is facing).
backward
: Moves the camera backward (away from the direction it is facing).
up
: Moves the camera upward along the vertical axis.
down
: Moves the camera downward along the vertical axis.
left
: Moves the camera left along the horizontal axis.
right
: Moves the camera right along the horizontal axis
amount
Type: number
Specifies the distance (in meters) that the camera moves in the chosen direction. A larger value results in a more significant movement.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Move the camera forward by 500 metersreearth.camera.move("forward", 500);
// Example 2: Move the camera upward by 200 metersreearth.camera.move("up", 200);
// Example 3: Move the camera to the left by 100 metersreearth.camera.move("left", 100);
// Example 4: Move the camera backward by 300 metersreearth.camera.move("backward", 300);
setView
This method instantly sets the camera to a specified position and orientation, without animations. This method is ideal for quickly positioning the camera to a specific view with precise control over location, orientation, and field of view (FOV).
Syntax
reearth.camera.setView( view: CameraPosition & { fov?: number }) => void;
Parameters
view
Type: CameraPosition & { fov?: number }
An object defining the camera’s position, orientation, and optional field of view.
fov?: number:
Optional field of view for the camera, measured in radians, controlling the camera’s viewing angle.
Return Value:
None (void)
. The method performs its operation without returning a value.
Example
// Example 1: Set the camera to a specific position with heading, pitch, and rollreearth.camera.setView({ lat: 35.6895, // Latitude for Tokyo lng: 139.6917, // Longitude for Tokyo height: 1000, // Altitude in meters heading: 1.57, // Heading in radians (90 degrees clockwise) pitch: -0.785, // Pitch in radians (45 degrees downward) roll: 0, // No roll});
// Example 2: Set the camera with a custom field of viewreearth.camera.setView({ lat: 48.8566, // Latitude for Paris lng: 2.3522, // Longitude for Paris height: 1500, // Altitude in meters heading: 0.785, // Heading in radians (45 degrees clockwise) pitch: -0.523, // Pitch in radians (30 degrees downward) roll: 0, // No roll fov: 1.2, // Field of view in radians});
// Example 3: Set the camera without heading, pitch, or rollreearth.camera.setView({ lat: 40.7128, // Latitude for New York City lng: -74.006, // Longitude for New York City height: 2000, // Altitude in meters});
Events
move
This event is triggered whenever the camera’s position or orientation changes within the reearth
environment. This event allows users to listen for and respond to camera movements, providing the updated camera position and orientation.
Syntax
reearth.camera.on("move", (camera: CameraPosition) => void): void;
Parameters
camera
Type: CameraPosition
A function that is called whenever the move event occurs. The callback receives the updated camera position as an argument.
Example
// Example 1: Listen for camera movement and log the updated positionreearth.camera.on("move", (camera) => { console.log("Camera moved:"); console.log("Latitude:", camera.lat); console.log("Longitude:", camera.lng); console.log("Height:", camera.height); console.log("Heading:", camera.heading); console.log("Pitch:", camera.pitch); console.log("Roll:", camera.roll);});
// Example 2: Trigger a custom action whenever the camera movesreearth.camera.on("move", (camera) => { if (camera.lat && camera.lng) { console.log(`Camera moved to ${camera.lat}, ${camera.lng}`); }});
References
CameraPosition
An object that contains detailed position and orientation data.
type CameraPosition = { lat?: number; lng?: number; height?: number; heading?: number; pitch?: number; roll?: number;};
lat?: number;
: The latitide where the camera is positioned (in decimal degrees).
lng?: number;
: The longitude where the camera is positioned (in decimal degrees).
height?: number
: The altitude of the camera above the Earth’s surface, determining how high or low the camera is positioned (in meters).
heading?: number;
: The direction the camera is facing. A heading of 0 points north, with the value increasing clockwise (in radians).
pitch?: number;
: Pitch angle, the vertical tilt of the camera. Positive values tilt the view upwards, while negative values tilt it downwards (in radians).
roll?: number;
: Roll angle, the rotation of the camera around its view direction (in radians).
GeoRect
An object describing the geographic boundaries of the current viewport:
type GeoRect = { west: number; south: number; east: number; north: number;};
west: number
: The western boundary of the viewport, in decimal degrees of longitude.
south: number
: The southern boundary of the viewport, in decimal degrees of latitude.
east: number
: The eastern boundary of the viewport, in decimal degrees of longitude.
north: number
: The northern boundary of the viewport, in decimal degrees of latitude.
CameraMoveOptions
An object that provides control over the movement animation.
type CameraMoveOptions = { duration?: number; // in seconds withoutAnimation?: boolean; easing?: (time: number) => number;};
duration?: number;
Specifies the duration of the camera movement in seconds. If omitted, a default duration is used.
withoutAnimation?: boolean;
If set to true, the camera moves instantly to the destination without animation. Default is false (animated).
easing?: (time: number) => number;
A custom easing function for controlling the animation pace, where time is a normalized value between 0 and 1.
LookAtDestination
An object that specifies the target location for the camera.
type LookAtDestination = { lat?: number; lng?: number; height?: number; heading?: number; pitch?: number; range?: number; radius?: number;};
lat?: number
Latitude of the target location in decimal degrees.
lng?: number;
Longitude of the target location in decimal degrees.
height?: number;
Altitude of the target location above sea level in meters.
heading?: number;
Orientation of the camera in radians. (0 = north, positive values rotate clockwise).
pitch?: number;
Vertical tilt of the camera in radians. Negative values tilt downward.
range?: number;
Distance from the camera to the target location in meters.
radius?: number;
Specifies the radius around the target, controlling how far the camera is from the target while looking at it.