Namespace: reearth.camera
Description: This method 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 and controlling the viewer’s perspective within a scene.
Syntax: reearth.camera.position: CameraPosition | undefined;
Properties:
// CameraPosition is an object that contains the following options:
CameraPosition = {
/** degrees */ // The latitide where the camera is positioned(north-south)
lat: number;
/** degrees */ // The longitude where the camera is positioned(East-west)
lng: number;
/** meters */ // The altitude of the camera above the Earth's surface, determining how high or low the camera is positioned.
height: number;
/** radians */ // The direction the camera is facing. A heading of 0 points north, with the value increasing clockwise.
heading: number;
/** radians */ // The angle of the camera's view direction relative to the horizon. Positive values tilt the view upwards, while negative values tilt it downwards.
pitch: number;
/** radians */ // The rotation of the camera around its view direction, affecting the level of the horizon in the camera's view.
roll: number;
/** Field of view expressed in radians */ // The camera's field of view, defining the extent of the visible world seen through the camera in the vertical direction.
fov: number;
}
// If the camera's position and orientation cannot be determined, such as before the scene has fully loaded or initialized.
undefined
Example Usage:
// Log the current camera position and orientation
if (reearth.camera.position) {
console.log(`Camera Position:
Latitude: ${reearth.camera.position.lat}
Longitude: ${reearth.camera.position.lng}
Height: ${reearth.camera.position.height}
Heading: ${reearth.camera.position.heading}
Pitch: ${reearth.camera.position.pitch}
Roll: ${reearth.camera.position.roll}
Field of View: ${reearth.camera.position.fov}`);
} else {
console.log("Camera position is undefined.");
}
// Set the camera to a new position and orientation
reearth.camera.position = {
lat: 35.681236, // Latitude in degrees
lng: 139.767125, // Longitude in degrees
height: 1000, // Height in meters
heading: 0.785398163, // Heading in radians (equivalent to 45 degrees)
pitch: -0.523598776, // Pitch in radians (equivalent to -30 degrees)
roll: 0, // Roll in radians
fov: 1.047197551 // FOV in radians (equivalent to 60 degrees)
};
Description: Provides the geographical boundaries of the current camera's viewport within the reearth. This property outlines the visible area from the camera's perspective, defined by the northernmost, southernmost, easternmost, and westernmost limits of the view. This property is particularly useful for understanding which parts of the globe are currently visible to the user.
Syntax: reearth.camera.viewport: Rect | undefined;
Properties:
// Rect is an object that includes the following properties, each representing latitude or longitude boundaries in degrees:
Rect = {
/** degrees */ // The highest latitude of the northern boundary of the viewport
north: number;
/** degrees */ // The lowest latitude of the southern boundary of the viewport
south: number;
/** degrees */ // The furthest longitude of the eastern boundary of the viewport visible to the right of the camera's current view
east: number;
/** degrees */ // The furthest longitude of the western boundary of the viewport visible to the left of the camera's current view
west: number;
}
// Value returns undefines if the camera's viewport cannot be determined or if the property is not supported in the current context.
undefined
Example Usage:
// Check and log the bounds of the current camera viewport
if (reearth.camera.viewport) {
console.log(`Current Viewport Bounds:
North: ${reearth.camera.viewport.north}
South: ${reearth.camera.viewport.south}
East: ${reearth.camera.viewport.east}
West: ${reearth.camera.viewport.west}`);
} else {
console.log("Camera viewport is undefined.");
}
Description: This method allows users to zoom the camera closer to the surface of the Earth by a specified amount. It enhances interactivity by providing control over the camera’s zoom level. It accepts two parameters: amount, which is a number, and options, which provides optional settings through the CameraOptions object.
Syntax: reearth.camera.zoomIn(amount: number, options?: CameraOptions) => void;
Parameters:
// Specifies how much the camera should zoom in.
amount
// Optional parameter. Includes an object that has additional settings to control the zoom action.
options?: CameraOptions = {
/** Expressed in seconds. Default is zero. */ // A longer duration results in a gradual, smoother zoom, while a duration of zero (the default) results in an immediate change.
duration?: number;
/** Easing function. */ // Defines the pace of the zoom action over time. This can be used to implement various effects, such as easing in, easing out, or more complex animation curves.
easing?: (time: number) => number;
// Specifies whether the zoom action should be animated. When set to true, the zoom will transition smoothly according to the duration and easing options. If false, the zoom changes the view immediately to the new level without animation.
animation?: boolean;
};
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Simple zoom in without animation
reearth.camera.zoomIn(2);
// Animated zoom in with custom duration and easing function
reearth.camera.zoomIn(5, {
duration: 2, // Zoom over 2 seconds
easing: t => t * (2 - t), // Ease-in-out function for smoother transition
animation: true // Enable animation
});
Description: This method enables users to zoom the camera out from the Earth’s surface. Users can control how much the camera zooms out by specifying an amount, with optional parameters to tailor the zoom behavior. It accepts two parameters: amount, which is a number, and options, which provides optional settings through the CameraOptions object.
Syntax: reearth.camera.zoomOut(amount: number, options?: CameraOptions): void
Parameters:
// Specifies how much the camera should zoom out.
amount
// Optional parameter. Includes an object that has additional settings to control the zoom action.
options?: CameraOptions = {
/** Expressed in seconds. Default is zero. */ // A longer duration results in a gradual, smoother zoom, while a duration of zero (the default) results in an immediate change.
duration?: number;
/** Easing function. */ // Defines the pace of the zoom action over time. This can be used to implement various effects, such as easing in, easing out, or more complex animation curves.
easing?: (time: number) => number;
// Specifies whether the zoom action should be animated. When set to true, the zoom will transition smoothly according to the duration and easing options. If false, the zoom changes the view immediately to the new level without animation.
animation?: boolean;
};
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Zoom out quickly without animation
reearth.camera.zoomOut(3);
// Zoom out slowly with custom animation
reearth.camera.zoomOut(10, {
duration: 3,
easing: t => t * (2 - t), // Custom easing function for a smooth start and end
animation: true
});
Description: Enables a smooth, animated transition of the camera to a specified destination. This method is particularly useful for guiding users through different geographical locations or points of interest. It accepts two parameters: FlyToDestination, and an optional parameter, CameraOptions, and they are both objects.
Syntax: reearth.camera.flyTo(destination: FlyToDestination, options?: CameraOptions): void
Parameters:
// An object specifying the target camera settings for the flight. Each property is optional.
FlyToDestination = {
/** degrees */ // The latitude to which the camera should move.
lat?: number;
/** degrees */ // The longitude to which the camera should move.
lng?: number;
/** meters */ // The altitude at which the camera should ascend or descend.
height?: number;
/** radians */ // The direction the camera should face.
heading?: number;
/** radians */ // The vertical angle of the camera's view.
pitch?: number;
/** radians */ // The lateral tilt of the camera.
roll?: number;
/** Field of view expressed in radians */ // The field of view of the camera upon arrival.
fov?: number;
};
// (Optional) - Additional settings to control the behavior of the flight:
CameraOptions = {
/** Expressed in seconds. Default is zero. */ // How long the flight should take.
duration?: number;
/** Easing function. */ // Describes the rate of change of the camera movement over time. Provides control over how the animation progresses.
easing?: (time: number) => number;
// Determines if the movement should be animated. When set to true, the flight is smooth and gradual; if false, the camera jumps directly to the destination.
animation?: boolean;
};
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Fly to a specific location with default settings
reearth.camera.flyTo({
lat: 35.681236, // Latitude in degrees
lng: 139.767125, // Longitude in degrees
height: 1000, // Height in meters
heading: 0.785398163, // Heading in radians (equivalent to 45 degrees)
pitch: -0.523598776, // Pitch in radians (equivalent to -30 degrees)
roll: 0, // Roll in radians
fov: 1.047197551 // FOV in radians (equivalent to 60 degrees)
});
// Fly to the same location with a smooth animation over 5 seconds
reearth.camera.flyTo({
lat: 35.681236,
lng: 139.767125,
height: 300
}, {
duration: 5,
easing: t => t * (2 - t), // Ease-in-out
animation: true
});
Description: This method enables the camera to adjust its position and orientation to look at a specified destination. It is useful for directing the user’s attention to specific geographical points or features by adjusting the camera's viewing angle and distance. It takes two parameters: LookAtDestination, and an optional parameter, CameraOptions, and they are both objects.
Syntax: reearth.camera.lookAt(destination: LookAtDestination, options?: CameraOptions) => void;
Parameters:
// An object that defines the target position and orientation parameters for the camera
LookAtDestination = {
/** degrees */ // The latitude coordinate of the target point.
lat?: number;
/** degrees */ // The longitude coordinate of the target point.
lng?: number;
/** meters */ // The altitude of the target point above the Earth's surface.
height?: number;
/** radians */ // The compass direction that the camera should face after adjustment.
heading?: number;
/** radians */ // The angle of the camera's tilt towards the horizon.
pitch?: number;
/** radians */ // The distance from the camera to the target point.
range?: number;
/** Field of view expressed in radians */ // The camera's field of view to be set for the camera at the new orientation.
fov?: number;
};
// (Optional) - Additional settings to customize the transition
CameraOptions = {
/** Expressed in seconds. Default is zero. */ // The duration over which the camera's adjustment should occur
duration?: number;
/** Easing function. */ // Defines the pacing of the camera's movement over time.
easing?: (time: number) => number;
// Determines if the movement should be animated. When set to true, the flight is smooth and gradual; if false, the camera jumps directly to the destination.
animation?: boolean;
};
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Look at a point without animation
reearth.camera.lookAt({
lat: 48.858844,
lng: 2.294351,
height: 100,
heading: 0.785398163,
pitch: -0.523598776,
roll: 0,
fov: 1.047197551
});
// Look at a specific point with smooth animation
reearth.camera.lookAt({
lat: 40.7128, // Set latitude of the target location in degrees
lng: -74.0060, // Set longitude of the target location in degrees
height: 200, // Set the elevation above sea level to 200 meters
heading: Math.PI / 4, // Set the camera to face northeast (π/4 radians or 45 degrees)
pitch: Math.PI / 6, // Tilt the camera downwards by π/6 radians or 30 degrees
range: 500, // Set the distance from the camera to the target point to 500 meters
fov: Math.PI / 3 // Set the camera's field of view to π/3 radians or 60 degrees
}, {
duration: 1.5, // Duration over which the movement should occur, in seconds
easing: t => t * (2 - t), // Use a quadratic ease-out function for the transition
animation: true // Enable animation for a smoother transition
});
Description: This method enables the camera to rotate to the right around its current position by a specified angle in radians. This functionality allows users to interactively explore the scene and view the environment from different angles without changing their position. It takes one parameter: radian, which is represented as a number.
Syntax: reearth.camera.rotateRight(radian: number) => void;
Parameters:
radian //The angle in radians by which the camera should rotate to the right. Positive values will rotate the camera clockwise when viewed from above.
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Rotate the camera right by π/4 radians (45 degrees)
reearth.camera.rotateRight(Math.PI / 4);
// Rotate the camera right by a quarter turn (90 degrees)
reearth.camera.rotateRight(Math.PI / 2);
// Rotate the camera right by a small increment for a subtle adjustment
reearth.camera.rotateRight(Math.PI / 18);
Description: Enables the camera to orbit around a central point or current focus by a specified angle in radians. This functionality allows users to rotate the view around the center of the earth, providing a comprehensive 360-degree perspective. It is particularly useful for exploring a specific location or object within the scene from multiple angles. It takes one parameter: radian, which is represented as a number.
Syntax: reearth.camera.orbit(radian: number) => void;
Parameters:
radian // Number. The angle in radians to orbit the camera. Positive values cause the camera to orbit in a clockwise direction when viewed from above, while negative values orbit counterclockwise.
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Orbit the camera around its current target by π/2 radians (90 degrees) clockwise
reearth.camera.orbit(Math.PI / 2);
// Orbit the camera clockwise by 45 degrees
reearth.camera.orbit(Math.PI / 4);
Description: This method is designed to enable or disable the screen space controller for the camera within reearth. This controller manages camera interactions such as panning, zooming, and rotating based directly on screen interactions such as mouse or touch inputs. It takes one parameter: enabled, which is represented as a boolean.
Syntax: reearth.camera.enableScreenSpaceController(enabled: boolean) => void;
Parameters:
enabled // boolean. Determines whether the screen space controller should be active. Setting this to true enables the controller, allowing user input to affect the camera. Setting it to false disables these controls, preventing the camera from responding to typical user inputs.
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Enable user interaction with the camera
reearth.camera.enableScreenSpaceController(true);
// Disable user interaction with the camera to lock the current view
reearth.camera.enableScreenSpaceController(false);
Description: Allows the camera to adjust its horizontal orientation by a specified amount. This method is designed to pan the camera left or right around its current position, facilitating smooth adjustments to the camera's viewing angle without altering its location. It accepts one parameter: amount, which specifies the angle in radians by which the camera should turn.
Syntax: reearth.camera.lookHorizontal(amount: number) => void;
Parameters:
amount // Number. The angle in radians by which the camera should rotate horizontally. Positive values rotate the camera to the right (clockwise), while negative values rotate it to the left (counterclockwise).
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Turn the camera right by π/6 radians (30 degrees)
reearth.camera.lookHorizontal(Math.PI / 6);
// Rotate the camera horizontally to the left by 45 degrees (counterclockwise)
reearth.camera.lookHorizontal(-Math.PI / 4);
Description: Allows the camera to adjust its vertical orientation by a specific amount. This method allows for tilting the camera's view upward or downward relative to its current orientation, enhancing the camera's ability to explore vertical aspects of the scene. This functionality is particularly useful for inspecting objects from different vertical perspectives or exploring terrain elevations directly.It accepts one parameter: amount, which specifies the angle in radians by which the camera should tilt.