reearth.viewer
Last updated
The reearth.viewer namespace provides a set of functions to interact with the viewer.
Properties
Section titled “Properties”property
Section titled “property”property provides a set of properties about the viewer, including globe, terrain, scene, tiles, sky, and more.
Syntax
Section titled “Syntax”reearth.viewer.property: ViewerProperty;Return Value
Section titled “Return Value”Type ViewerProperty
Currently, property returns only the properties that have been explicitly set; default values are not included.
viewport
Section titled “viewport”The viewport is designed to provide properties related to the map area and includes the URL query parameters for the current viewport (page).
Syntax
Section titled “Syntax”reearth.viewer.viewport: Viewport;Return Value
Section titled “Return Value”Type
type Viewport = { width: number; height: number; isMobile: boolean; query: Record<string, string>;};- width: The width of the viewport.
- height: The height of the viewport.
- isMobile: A boolean value that indicates whether the viewport is a mobile device based on bowser user-agent detection.
- query: The URL query parameters for the current page.
env provides the env info of current running Re:Earth Visualizer.
Syntax
Section titled “Syntax”reearth.viewer.env: Env;Return Value
Section titled “Return Value”Type
type Env = { inEditor: boolean; isBuilt: boolean;};inEditor and isBuilt has different values when running in different page or tab, plugin could provide different behavior based on these values.
| Property | Editor - Map/Story/Widgets Tab | Editor - Publish Tab | Published Page |
|---|---|---|---|
| inEditor | true | false | false |
| isBuilt | false | false | true |
interactionMode
Section titled “interactionMode”interactionMode provides a set of properties and methods to manage the interaction mode of the viewer in Re:Earth Visualizer.
interactionMode.mode
Section titled “interactionMode.mode”Current interaction mode of the viewer.
Syntax
Section titled “Syntax”reearth.viewer.interactionMode.mode: InteractionModeTypeReturn Value
Section titled “Return Value”Type InteractionModeType = "default" | "move" | "selection" | "sketch" | "spatialId"
default: Default interaction mode.move: Move interaction mode. Selection is disabled in this mode.selection: Selection interaction mode. Move is disabled in this mode.sketch: Sketch interaction mode. Sketch could be enabled in this mode only.spatialId: Spatial ID interaction mode. Use this mode when working with Spatial ID picking.
interactionMode.override
Section titled “interactionMode.override”Overrides the interaction mode of the viewer.
Syntax
Section titled “Syntax”reearth.viewer.interactionMode.override: ( mode: InteractionModeType) => void;Parameters
Section titled “Parameters”Type: InteractionModeType
The interaction mode to be set.
Return Value
Section titled “Return Value”None (void). The method performs its operation without returning a value.
Methods
Section titled “Methods”overrideProperty
Section titled “overrideProperty”overrideProperty is used to override the viewer property.
Syntax
Section titled “Syntax”reearth.viewer.overrideProperty: (property: ViewerProperty) => void;Parameters
Section titled “Parameters”property
Section titled “property”Type ViewerProperty
Return Value
Section titled “Return Value”Type void
This Method has no return value.
Example
Section titled “Example”// Enable Terrainreearth.viewer.overrideProperty({ terrain: { enabled: true, },});capture
Section titled “capture”capture function could generate an image for current viewer.
Syntax
Section titled “Syntax”reearth.viewer.capture: ( type?: string, encoderOptions?: number) => string | undefined;Parameters
Section titled “Parameters”Type string (optional)
A string indicating the image format. The default type is image/png; this image format will be also used if the specified type is not supported.
encoderOptions
Section titled “encoderOptions”Type number (optional)
A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
Return Value
Section titled “Return Value”Type string | undefined
A string containing the requested data URL.
Example
Section titled “Example”// Get the capture of current map,// You can post the returned image string to your widget UI and trigger download.console.log(reearth.viewer.capture("image/png"));open method is used to open a URL in a new tab.
Syntax
Section titled “Syntax”reearth.viewer.open: (url: string) => void;Parameters
Section titled “Parameters”Type string
The URL to be opened in a new tab.
Return Value
Section titled “Return Value”Type void
reload
Section titled “reload”reload method is used to reload the current Visualizer page.
Syntax
Section titled “Syntax”reearth.viewer.reload: () => void;Return Value
Section titled “Return Value”Type void
The tools module provides a collection of helper functions for performing various calculations around globe and scene.
> getLocationFromScreenCoordinate
Section titled “> getLocationFromScreenCoordinate”Return the location on the earth from the screen coordinate.
Syntax
Section titled “Syntax”reearth.viewer.tools.getLocationFromScreenCoordinate: ( x: number, y: number, withTerrain?: boolean) => { lat: number; lng: number; height: number } | undefined;Parameters
Section titled “Parameters”Type number
The x pixel coordinate on the viewer.
Type number
The y pixel coordinate on the viewer.
withTerrain
Section titled “withTerrain”Type boolean (optional)
A boolean value that indicates whether the terrain height should be considered. The default value is false.
Return Value
Section titled “Return Value”Type { lat: number; lng: number; height: number } | undefined
The location on the earth.
> getScreenCoordinateFromPosition
Section titled “> getScreenCoordinateFromPosition”Return the screen coordinate from the position on the earth.
Syntax
Section titled “Syntax”reearth.viewer.tools.getScreenCoordinateFromPosition: ( position: [x: number, y: number, z: number]) => [x: number, y: number] | undefined;Parameters
Section titled “Parameters”position
Section titled “position”Type [x: number, y: number, z: number]
The position on the earth, in Cartesian.
Return Value
Section titled “Return Value”Type [x: number, y: number] | undefined
The pixel coordinate on viewer.
> getTerrainHeightAsync
Section titled “> getTerrainHeightAsync”Return the terrain height at the given location. This is an asynchronous function.
Syntax
Section titled “Syntax”reearth.viewer.tools.getTerrainHeightAsync: ( lng: number, lat: number) => Promise<number | undefined>;Parameters
Section titled “Parameters”Type number
The longitude of the location.
Type number
The latitude of the location.
Return Value
Section titled “Return Value”Type Promise<number | undefined>
The height of the terrain at the given location.
> getGlobeHeight
Section titled “> getGlobeHeight”Return the height of the surface at the given location.
Syntax
Section titled “Syntax”reearth.viewer.tools.getGlobeHeight: ( lng: number, lat: number) => number | undefined;Parameters
Section titled “Parameters”Type number
The longitude of the location.
Type number
The latitude of the location.
Return Value
Section titled “Return Value”Type number | undefined
The height of the surface at the given location.
> getCurrentLocationAsync
Section titled “> getCurrentLocationAsync”Return the current location of the user. This is an asynchronous function that uses the browser’s Geolocation API.
Syntax
Section titled “Syntax”reearth.viewer.tools.getCurrentLocationAsync: ( options?: Options) => Promise<Location | undefined>;Parameters
Section titled “Parameters”options
Section titled “options”Type Options (optional)
An optional object including the following parameters:
- maximumAge: Maximum age in milliseconds of a cached position. Default value is
0. - timeout: Maximum time in milliseconds to wait for a position. Default value is
10,000ms. - enableHighAccuracy: Request high accuracy positioning. Default value is
false.
Return Value
Section titled “Return Value”Type Promise<Location | undefined>
type Location = { lat: number; lng: number; height: number;};The current location of the user.
> cartographicToCartesian
Section titled “> cartographicToCartesian”Converts a cartographic position to a Cartesian position.
Syntax
Section titled “Syntax”reearth.viewer.tools.cartographicToCartesian: ( lng: number, lat: number, height: number, options?: { useGlobeEllipsoid?: boolean }) => [x: number, y: number, z: number] | undefined;Parameters
Section titled “Parameters”Type number
The longitude of the location.
Type number
The latitude of the location.
height
Section titled “height”Type number
The height of the location.
options
Section titled “options”Type { useGlobeEllipsoid?: boolean } (optional)
- useGlobeEllipsoid: A boolean value that indicates whether the globe ellipsoid should be used. The default value is
false.
Return Value
Section titled “Return Value”Type [x: number, y: number, z: number] | undefined
The Cartesian position.
> cartesianToCartographic
Section titled “> cartesianToCartographic”Converts a Cartesian position to a cartographic position.
Syntax
Section titled “Syntax”reearth.viewer.tools.cartesianToCartographic: ( x: number, y: number, z: number, options?: { useGlobeEllipsoid?: boolean }) => [lng: number, lat: number, height: number] | undefined;Parameters
Section titled “Parameters”Type number
The x coordinate of the location.
Type number
The y coordinate of the location.
Type number
The z coordinate of the location.
options
Section titled “options”Type { useGlobeEllipsoid?: boolean } (optional)
- useGlobeEllipsoid: A boolean value that indicates whether the globe ellipsoid should be used. The default value is
false.
Return Value
Section titled “Return Value”Type [lng: number, lat: number, height: number] | undefined
The cartographic position.
> transformByOffsetOnScreen
Section titled “> transformByOffsetOnScreen”Transforms the position by the offset on the screen.
Syntax
Section titled “Syntax”reearth.viewer.tools.transformByOffsetOnScreen: ( rawPosition: [x: number, y: number, z: number], screenOffset: [x: number, y: number]) => [x: number, y: number, z: number] | undefined;Parameters
Section titled “Parameters”rawPosition
Section titled “rawPosition”Type [x: number, y: number, z: number]
The raw position on the earth.
screenOffset
Section titled “screenOffset”Type [x: number, y: number]
The offset on the screen.
Return Value
Section titled “Return Value”Type [x: number, y: number, z: number] | undefined
The transformed position.
> isPositionVisibleOnGlobe
Section titled “> isPositionVisibleOnGlobe”Check if the position is visible on the globe.
Syntax
Section titled “Syntax”reearth.viewer.tools.isPositionVisibleOnGlobe: ( position: [x: number, y: number, z: number]) => boolean;Parameters
Section titled “Parameters”position
Section titled “position”Type [x: number, y: number, z: number]
The position on the earth.
Return Value
Section titled “Return Value”Type boolean
A boolean value that indicates whether the position is visible on the globe.
Events
Section titled “Events”resize
Section titled “resize”resize event will be triggered when the viewer is resized.
Syntax
Section titled “Syntax”reearth.viewer.on("resize", ({width: number, height: number, isMobile:boolean}) => void);Parameters
Section titled “Parameters”- width: The width of the viewport.
- height: The height of the viewport.
- isMobile: A boolean value that indicates whether the viewport is a mobile device based on bowser user-agent detection.
Example
Section titled “Example”reearth.viewer.on("resize", ({ width, height, isMobile }) => { console.log(`width: ${width}, height: ${height}, isMobile: ${isMobile}`);});mouse events
Section titled “mouse events”Viewer has a set of mouse events that can be listened to. They have the same parameters.
Supported events are:
- click
- doubleClick
- mouseDown
- mouseUp
- rightClick
- rightDown
- rightUp
- middleClick
- middleDown
- middleUp
- mouseMove
- mouseEnter
- mouseLeave
- wheel
Syntax
Section titled “Syntax”reearth.viewer.on("click", (event: MouseEvent)=> void);Parameters
Section titled “Parameters”event: MouseEvent
type MouseEvent = { x?: number; y?: number; lat?: number; lng?: number; height?: number; layerId?: string; delta?: number;};- x: the x corrdinate of cursor relative to the viewer.
- y: the y corrdinate of cursor relative to the viewer.
- lat: the latitude of cursor on earth.
- lng: the longitude of cursor on earth.
- height: the height of cursor on earth.
- layerId: the layerId of the object that cursor is on.
- delta: the delta value of wheel event.
Example
Section titled “Example”reearth.viewer.on("mouseMove", ({ lat, lng, height }) => { console.log(`lat: ${lat}, lng: ${lng}, height: ${height}`);});