Namespace: reearth.scene
Users can modify settings related to the entire project and the Digital Earth background in the scene.
Description: Indicates whether the current scene on reearth is being viewed or interacted with in the editor mode. This property is useful for triggering certain behaviors or displays in reearth when a user is editing the scene.
Syntax: reearth.scene.inEditor: boolean
Property Type: boolean
true // indicates that the scene is currently being accessed within the editor environment.
false // means that the scene is being viewed outside the editor, possibly by end users in a published state.
Example Usage:
if (reearth.scene.inEditor) {
// Logic to execute or elements to display only in the editor
console.log("Currently in the Reearth editor environment.");
} else {
// Logic or elements intended for the published or runtime scene
console.log("Viewing the published or runtime version of the scene.");
}
Description: Indicates whether the current scene has been fully loaded. This property is important for users to understand when the scene is ready for interaction and further manipulation. A scene being "built" means that all initial assets, layers, and configurations have been processed and rendered, making the scene ready for user interaction or for additional modifications.
Syntax: reearth.scene.built: boolean
Property Type: boolean
true // implies that the scene has completed its inital loading process and is ready for interactions that modify the scene
false // implies that the scene is still loading and may not fully support all interactions or modifications
Example Usage:
if (reearth.scene.built) {
// Execute operations that require the scene to be fully loaded
console.log("The Reearth scene is fully built and ready for interaction.");
} else {
// Handle the scenario where the scene is not yet ready
console.log("The Reearth scene is still loading. Please wait.");
}
Description: This is used to define the data or configurations that users wish to attach to the reearth scene, and it is an optional method, hence the question mark(?). Its usage is dependent on how the scene is configured and what data it needs to carry.
Syntax: reearth.scene.property?: any
Property Type: any. It can hold any data type associated with the current scene, including numbers, strings, objects, arrays, etc.
Example Usage:
// Setting a simple value
reearth.scene.property = "This is a custom message.";
// Setting an object
reearth.scene.property = {
terrain: {
terrain: true,
terrainType: "cesium"
}
};
Description: This method allows users to override or set new properties for the current reearth scene. It accepts one parameter: property, which can be of any data type.
Syntax: reearth.scene.overrideProperty: (property: any) => void
Parameters:
// represents the custom property/properties to be applied to the scene.
(property: any)
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Override the set property above
reearth.scene.overrideProperty({
terrain: {
terrain: false,
terrainType: "arcgis"
}
});
// Toggle the terrain feature in the Reearth scene on and off based on the message received
reearth.on("message", (msg) => { // Listen for messages sent to reearth
if (msg.type == "terrain") { // Check if the message is related to terrain
// if terrain is not enabled, enable it
if (
!reearth.scene.property.terrain ||
reearth.scene.property.terrain.terrain == false
) {
reearth.scene.overrideProperty({ terrain: { terrain: true } });
// if terrain is enabled, disable it.
} else {
reearth.scene.overrideProperty({ terrain: { terrain: false } });
}
}
});
Description: This method enables the capturing of the current view of the reearth scene as an image. This functionality is particularly useful for creating screenshots of the scene, which can be used for reporting, documentation, or sharing purposes. It accepts two parameters: type, which is a string, and encoderOptions which is a number. The parameters are optional hence the question mark(?), and they specify the image format and options for image quality adjustment.
Syntax: reearth.scene.captureScreen: (type?, encoderOptions?) => string | undefined
Parameters:
// An optional parameter, a string that specifies the desired image format of the screenshot for e.g image/png(default), image/jpeg.
type?: string
// An optional parameter, a number that specifies the quality of the image if the type is 'image/jpeg'. This value can range from 0 to 1, where 0 indicates the lowest quality and 1 indicates the highest quality. This parameter is ignored if the image type is not 'image/jpeg'.
encoderOptions?: number
Return Value: string | undefined
<aside>
💡 This method returns a base64 encoded string representing the screenshot of the scene. If the screenshot cannot be captured, or if the feature is unsupported in the current context, the method returns undefined.
</aside>
Example Usage:
// Capture the current scene as a PNG image
const pngScreenshot = reearth.scene.captureScreen();
console.log(pngScreenshot); // Logs the Base64-encoded image data
// Capture the current scene as a JPEG image with high quality
const jpegScreenshot = reearth.scene.captureScreen("image/jpeg", 0.9);
console.log(jpegScreenshot); // Logs the Base64-encoded image data
Description: This method translates screen coordinates into geographical coordinates(latitude, longitude, and height) within the reeearth scene. This functionality is especially useful for identifying the geographical location corresponding to a specific point on the screen, such as where a user clicks or hovers. It accepts 3 parameters: x, which is a number, y, also a number, and withTerrain, which is a boolean and also an optional parameter.
Syntax: reearth.scene.getLocationFromScreen: (x, y, withTerrain?) => LatLngHeight | undefined;
Parameters:
// Number. The x-coordinate on the screen, typically representing the horizontal position from the left edge of the canvas or viewport where the scene is rendered.
x
// Number. The y-coordinate on the screen, typically representing the vertical position from the top edge of the canvas or viewport.
y
// Bolean. Optional. Indicates whether the calculation should consider the terrain's elevation at the given screen coordinates.
// If true, the method accounts for the terrain height at the calculated location. Defaults to false if not specified.
withTerrain
Return Value: LatLngHeight | undefined
<aside>
💡 The method returns an object of type LatLngHeight, containing lat (latitude), lng (longitude), and height properties, which together represent a point on or above the Earth's surface as viewed in the reeearth scene. If the screen coordinates do not correspond to a valid geographical location (e.g., clicking on the sky), the method may return undefined.
</aside>
The LatLngHeight object has the following options:
LatLngHeight = {
// The latitude of the location
lat: number;
// The longitude of the location
lng: number;
// The height above the Earth's surface at the location, which can represent elevation or altitude depending on whether withTerrain is true.
height: number;
};
// If the screen coordinates do not correspond to a valid geographical location (e.g., clicking on the sky), the method may return undefined.
undefined
Example Usage:
// Get the geographical location from screen coordinates without considering terrain elevation
const location = reearth.scene.getLocationFromScreen(100, 200);
console.log(location); // Outputs: { lat: ..., lng: ..., height: ... }
// Get the geographical location from screen coordinates considering terrain elevation
const locationWithTerrain = reearth.scene.getLocationFromScreen(100, 200, true);
console.log(locationWithTerrain); // Outputs: { lat: ..., lng: ..., height: ... }
Notes: - Not yet found use cases for some of the methods