render3dpro Documentation
API User Guide-English
Open source repository address：render3dpro - npm
After installing via npm/yarn/pnpm, the node_modules/render3dpro directory contains an examples folder. This folder includes usage examples for render3dpro. You can view all examples through index.html (requires opening with "Open With Live Server" from the VSCode Live Server extension).
For API usage examples, refer to node_modules/render3dpro/indexCN.html or node_modules/render3dpro/indexEN.html. (Also requires opening with "Open With Live Server" from the VSCode Live Server extension.)
Introduction
render3dPro uses Cesium's Primitive rendering method, achieving efficient rendering and visualization in Cesium's 3D scenes through low-level GPU-oriented APIs.
It supports the latest open-source Cesium version, SuperMap iClient3D for Cesium version, SuperMap iClient3D for WebGL/WebGPU version, as well as other vendor versions developed based on open-source Cesium.
This visualization library has no third-party dependencies except for Cesium's Cesium and viewer objects, aiming for extreme lightweight and high performance.
The encapsulation and usage of render3dPro refer to Alibaba AntV L7's chain calls and parameter passing, and are compatible with AntV L7's key functions and syntax.
Syntax Example
const layer = new PrimitiveGeoJsonLayer(option) // option - parameter object passed to the constructor, providing initial parameters and state of the layer
.source(...) // Pass in the data required by the layer and related parsers
.filter(...) // Data filtering method
.shape(...) // Specify the specific shape and fill mode for the layer, such as: fill, circle, box, etc.
.color(...) // Specify the color configuration for the layer
.texture(...) // Specify the texture referenced by the layer (not supported yet)
.size(...) // Set the size of layer elements
.animate(...) // Set the animation mode for layer elements (not supported yet)
.active(...) // Specify whether layer elements support hover selection
.select(...) // Specify whether layer elements support click selection
.style(...) // Specify the configuration of custom styles for the layer
.render() // Execute layer rendering and add it to the map
.ready() // Asynchronous method; calling this method can determine whether data rendering is fully completed
.bottomHeight(...) // Specify the bottom height of the layer
.extrudedHeight(...) // Specify the extrusion height of the layer
.updateExtrudedHeight(...) // Dynamically update the extrusion height after layer rendering
.show(...) // Control layer visibility
.visible(...) // Control layer visibility
.popupByMouse(...) // Set the display and trigger mode of the layer's popup behavior, such as immediate display on hover, etc.
.popupByFixed(...) // Set the display and trigger mode of the layer's popup behavior, independent of mouse movement
.closePopupFixedLayers() // Close the layer's popup
.locate(...) // Set layer location
.flyTo(...) // Set layer location, equivalent to locate method
.zoomTo(...) // Set layer location, equivalent to locate method
.destroy() // Destroy and remove the layer
.remove() // Destroy and remove the layer, equivalent to destroy method
.clear() // Destroy and remove the layer, equivalent to destroy method
.close() // Destroy and remove the layer, equivalent to destroy method
Usage Example
import { PrimitiveGeoJsonLayer } from "@dist/render3dpro";
const polygonLayer = new PrimitiveGeoJsonLayer({
Cesium: Cesium, // Cesium instance
viewer: viewer, // Cesium viewer instance
clampToGround: true, // Whether to clamp to ground
})
.source( // Pass in geojson data source
{
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {
name: "黄浦区"
},
geometry: {
type: "MultiPolygon",
coordinates: [
[
[
[121.457689, 31.220196],
[121.460707, 31.213488],
[121.461555, 31.210194],
[121.462264, 31.203173],
[121.466449, 31.204395],
[121.46745, 31.203065],
[121.469605, 31.196404],
[121.470383, 31.191276],
[121.474944, 31.189886],
[121.475987, 31.187885],
[121.490752, 31.191467],
[121.494631, 31.192857],
[121.498066, 31.195601],
[121.501319, 31.199747],
[121.508368, 31.210158],
[121.509911, 31.214506],
[121.509397, 31.218459],
[121.506741, 31.223119],
[121.502014, 31.228018],
[121.495744, 31.232977],
[121.493491, 31.23615],
[121.493491, 31.240163],
[121.494826, 31.24221],
[121.487805, 31.244186],
[121.485969, 31.244091],
[121.482994, 31.241923],
[121.47892, 31.240294],
[121.474847, 31.24142],
[121.469563, 31.239216],
[121.462973, 31.241396],
[121.466129, 31.234917],
[121.467658, 31.225634],
[121.467464, 31.223862],
[121.456758, 31.223898],
[121.457689, 31.220196],
],
],
],
},
}
],
}
)
.shape("fill") // Rendering type
.color("#f00") // Custom polygon color
.style({ opacity: 0.6 }) // Custom layer style
.render() // Render to map
.locate(); // Locate
Details
source
Set layer data, only supports geojson data format.
layer.source(data);
GeoJSON Data Description
GeoJSON is a format for encoding various geographic data structures. A GeoJSON object can represent a geometry, feature, or collection of features. GeoJSON supports the following geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection. Features in GeoJSON contain a geometry object and other properties, and a feature collection represents a series of features.
source supports passing FeatureCollection or Feature.
FeatureCollection
A FeatureCollection consists of multiple features.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"name": "tom"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-2.8125, 34.59704151614417],
[65.390625, 34.59704151614417],
[65.390625, 61.10078883158897],
[-2.8125, 61.10078883158897],
[-2.8125, 34.59704151614417]
]
]
}
}
]
}
Feature
A feature has geometry (spatial information) and properties (attribute information), where geometry is required.
{
"type": "Feature",
"properties": {},
"geometry": {}
}
Geometry
Geometry types supported in a feature are as follows:
Point
{
"type": "Point",
"coordinates": [100.0, 0.0]
}
MultiPoint
{
"type": "MultiPoint",
"coordinates": [
[100.0, 0.0],
[101.0, 1.0]
]
}
LineString
{
"type": "LineString",
"coordinates": [
[100.0, 0.0],
[101.0, 1.0]
]
}
MultiLineString
{
"type": "MultiLineString",
"coordinates": [
[
[100.0, 0.0],
[101.0, 1.0]
],
[
[102.0, 2.0],
[103.0, 3.0]
]
]
}
Polygon
{
"type": "Polygon",
"coordinates": [
[
[100.0, 0.0],
[101.0, 0.0],
[101.0, 1.0],
[100.0, 1.0],
[100.0, 0.0]
]
]
}
Polygon with holes
{
"type": "Polygon",
"coordinates": [
[
[-170.0, 10.0],
[170.0, 10.0],
[170.0, -10.0],
[-170.0, -10.0],
[-170.0, 10.0]
],
[
[175.0, 5.0],
[-175.0, 5.0],
[-175.0, -5.0],
[175.0, -5.0],
[175.0, 5.0]
]
]
}
MultiPolygon
{
"type": "MultiPolygon",
"coordinates": [
[
[
[102.0, 2.0],
[103.0, 2.0],
[103.0, 3.0],
[102.0, 3.0],
[102.0, 2.0]
]
],
[
[
[100.0, 0.0],
[101.0, 0.0],
[101.0, 1.0],
[100.0, 1.0],
[100.0, 0.0]
],
[
[100.2, 0.2],
[100.8, 0.2],
[100.8, 0.8],
[100.2, 0.8],
[100.2, 0.2]
]
]
]
}
render
The execution method for data rendering, used to render data into the 3D map.
layer.render();
ready
Method to determine whether data rendering is complete. This is an asynchronous method, which uses renderReady to check if all rendering is finished.
await layer.ready();
console.log("Is all rendering complete?", layer.renderReady)
locate
When calling the locate method without parameters, it locates to the bounding box of all displayed features in the current layer.
layer.locate();
When calling the locate method with parameters, pass a callback function to determine which area(s) to locate based on the properties values of geojson.
layer.locate((properties) => {
const value = properties["name"];
if (value === "黄浦区") {
return true;
}
return false;
});
When calling the locate method with parameters, pass an attribute field and a callback function to determine which area(s) to locate based on the properties values of geojson.
layer.locate("name", (value) => {
if (value === "黄浦区" || value === "浦东新区") {
return true;
}
return false;
});
flyTo
Equivalent to the locate method.
zoomTo
Equivalent to the locate method.
filter
Data filtering method, supports callback functions, maps data to true | false; visible when result is true.
Pass a callback function to set content based on the properties values of geojson.
layer.filter((properties) => {
if (properties["weight"] >= 70) {
return true;
}
return false;
})
Pass an attribute field and a callback function to set content based on the properties values of geojson.
layer.filter("weight", (value) => {
if (value >= 70) {
return true;
}
return false;
})
shape
Generally, a layer can have multiple presentation forms. The shape method is used to specify the specific form: fill or polygon renders as polygons; fill3D or polygon3D renders as 3D polygons; line renders as lines; circle renders as circular polygons; circle3D renders as cylinders; box renders as square polygons; box3D renders as cubes. For circle3D and box3D types, it is recommended to use the size() method to specify width and extrusion height; for fill3D or polygon3D types, it is recommended to use extrudedHeight() to specify extrusion height.
Note: shape() can only be called before the render() method; the rendering form cannot be dynamically modified after rendering.
Note: When the shape is 3D type, clampToGround must be set to false.
layer.shape("circle"); // circle
layer.shape("box"); // square
const polygonLayer = new PrimitiveGeoJsonLayer({
Cesium: Cesium,
viewer: viewer,
clampToGround: false, // When shape is 3D type, clampToGround must be false
})
.source(geojsonData)
.shape("circle3D") // cylinder
.shape("box3D"); // cube
color
Method to map data values to graphic colors.
layer.color("rgba(1, 117, 152, 0.5)"); // constant color
Based on the natural breaks method, using the specified numeric field value in geojson's properties and the length of the passed color array, perform segmented color rendering on the layer.
layer.color('weight',["rgba(1, 117, 152,0.8)","rgba(28, 189, 216,0.8)","rgba(95, 249, 240,0.8)"]); // Segmented rendering based on the passed color array using natural breaks
Pass an attribute field and a callback function to set content based on the properties values of geojson.
layer.color("name", (value) => {
// 黄浦区、徐汇区、长宁区、静安区、普陀区、虹口区、杨浦区、闵行区、宝山区、嘉定区、浦东新区、
// 金山区、松江区、青浦区、奉贤区、崇明区
// rgb(1, 117, 152)
// rgb(25, 150, 174)
// rgb(28, 189, 216)
// rgb(72, 216, 218)
// rgb(95, 249, 240)
if (value === "黄浦区") {
return ["rgba(1, 117, 152,1)", "rgba(1, 117, 152,1)"];
}
if (value === "徐汇区") {
return "rgba(25, 150, 174,1)"; // Classification color // fill color, line color
}
if (value === "长宁区") {
return ["rgba(28, 189, 216,1)", "rgba(28, 189, 216,1)"]; // Classification color // fill color, line color
}
if (value === "静安区") {
return "#48d8da"; // Classification color // fill color, line color
}
if (value === "普陀区") {
return ["rgba(95, 249, 240,1)", "rgba(95, 249, 240,1)"]; // Classification color // fill color, line color
}
return ["rgba(179,185,191,1)", "rgba(179,185,191,1)"];
})
Pass a callback function to set content based on the properties values of geojson.
layer.color((properties) => {
// 黄浦区、徐汇区、长宁区、静安区、普陀区、虹口区、杨浦区、闵行区、宝山区、嘉定区、浦东新区、
// 金山区、松江区、青浦区、奉贤区、崇明区
// rgb(1, 117, 152)
// rgb(25, 150, 174)
// rgb(28, 189, 216)
// rgb(72, 216, 218)
// rgb(95, 249, 240)
const value = properties["name"];
if (value === "黄浦区") {
return ["rgba(1, 117, 152,1)", "rgba(1, 117, 152,1)"]; // fill color, line color
}
if (value === "徐汇区") {
return "rgba(25, 150, 174,1)"; // Classification color // fill color, line color
}
return ["rgba(95, 249, 240,1)", "rgba(95, 249, 240,1)"]; // fill color, line color
})
style
Set the general, overall style of the layer, such as overall line color, fill color, line width, opacity, etc.
Pass a style object to set basic styles, supporting line color, line width (line width cannot be adjusted after rendering), fill color, and opacity.
layer.style({
lineColor: "rgba(255,20,255,1)", // line color
stroke: "rgba(255,20,255,1)", // line color, equivalent to lineColor
lineWidth: 2, // line width, only effective before render
fillColor: "rgba(0,255,0,0.1)", // fill color
opacity: 0.5 // opacity
})
texture
Textures not supported yet.
size
When the rendered shape type is circle, circle3D, box, or box3D, supports setting radius size and extrusion height.
Pass an attribute field and a callback function to set content based on the properties values of geojson.
layer.size("weight", (value) => {
if (value === undefined || value === null || value <= 0) {
return [0, undefined]; // height, width in meters
}
if (value > 50) {
return [0, value * 10]; // height, width in meters
}
return [0, 200]; // height, width in meters
})
Pass a callback function to set content based on the properties values of geojson.
layer.size((properties) => {
const value = properties["weight"];
if (value === undefined || value === null || value <= 0) {
return [100, undefined]; // height, width in meters
}
if (value > 50) {
return [500, value * 20]; // height, width in meters
}
return [0, 200]; // height, width in meters
})
Pass an array of height and width values.
layer.size([0, 2000]) // height, width in meters
animate
Animations not supported yet.
active
Whether to support mouse hover events and the highlight color on hover.
layer.active(true, "rgba(255,0,0,1)") // First parameter true or false: true enables mouse hover events, false disables; second parameter is the highlight color on hover.
select
Whether to support mouse click events and highlight on click, and callback response event. The callback returns parameters: the rendered primitive's id (field: renderPrimitiveID) and its corresponding complete geojson information (field: geojson).
layer.select(true, "rgba(255,0,255,1)", (primitiveObj) => {
// First parameter indicates whether to enable click response
// Second parameter is the highlight color after click
// Third parameter is a callback function for external handling after click selection
console.log("ID:", primitiveObj.renderPrimitiveID);
console.log("GeoJSON:", primitiveObj.geojson);
setTimeout(() => {
window.alert(primitiveObj.geojson.properties.name);
});
})
bottomHeight
The layer's bottom height (elevation). Requires the layer not to be clamped to ground, i.e., clampToGround must be false when initializing the layer. Note: When rendering type is line (line layer), bottom height and extrusion height are not supported.
Pass a number to set the bottom height of the layer.
layer.bottomHeight(10000) // unit meters, note: when shape type is line, bottom height and extrusion height are not supported
Pass a callback function to set content based on the properties values of geojson.
layer.bottomHeight("weight", (value) => {
if (value === undefined || value === null || value <= 0) {
return 0; // height in meters
}
if (value > 80) {
return 40000; // height in meters
}
if (value > 50) {
return 4000; // height in meters
}
return 1000; // height in meters
}) // unit meters, note: when shape type is line, bottom height and extrusion height are not supported
Pass an attribute field and a callback function to set content based on the properties values of geojson.
layer.bottomHeight((properties) => {
const value = properties["weight"];
if (value === undefined || value === null || value <= 0) {
return 0; // height in meters
}
if (value > 80) {
return 40000; // height in meters
}
if (value > 50) {
return 4000; // height in meters
}
return 1000; // height in meters
}) // unit meters, note: when shape type is line, bottom height and extrusion height are not supported
extrudedHeight
The layer's extrusion height. Requires the layer not to be clamped to ground, i.e., clampToGround must be false when initializing; the shape type must be 3D: fill3D, polygon3D, circle3D, box3D. Note: When rendering type is line (line layer), extrusion height and bottom height are not supported.
Pass a number to set the extrusion height of the layer.
layer.extrudedHeight(10000) // unit meters, note: when shape type is line, bottom height and extrusion height are not supported
Pass a callback function to set content based on the properties values of geojson.
layer.extrudedHeight("weight", (value) => {
if (value === undefined || value === null || value <= 0) {
return 0; // height in meters
}
if (value > 80) {
return 40000; // height in meters
}
if (value > 50) {
return 4000; // height in meters
}
return 1000; // height in meters
}) // unit meters, note: when shape type is line, bottom height and extrusion height are not supported
Pass an attribute field and a callback function to set content based on the properties values of geojson.
layer.extrudedHeight((properties) => {
const value = properties["weight"];
if (value === undefined || value === null || value <= 0) {
return 0; // height in meters
}
if (value > 80) {
return 40000; // height in meters
}
if (value > 50) {
return 4000; // height in meters
}
return 1000; // height in meters
}) // unit meters, note: when shape type is line, bottom height and extrusion height are not supported
updateExtrudedHeight
Pass extrusion height, animation duration, and bottom height to perform dynamic extrusion. Requires the layer not to be clamped to ground, i.e., clampToGround must be false when initializing; the shape type must be 3D: fill3D, polygon3D, circle3D, box3D. Note: When rendering type is line (line layer), extrusion height and bottom height are not supported. Parameter 1: extrusion height in meters; Parameter 2: time in milliseconds; Parameter 3: bottom height in meters; Parameter 4: to avoid flickering, smaller values cause more flickering; larger values significantly reduce flickering, but may cause overlapping highlight issues.
layer.updateExtrudedHeight(10000, 10000, 300, 10); // Parameter 1: extrusion height in meters; Parameter 2: time in milliseconds; Parameter 3: bottom height in meters; Parameter 4: to avoid flickering, smaller values cause more flickering; larger values significantly reduce flickering, but may cause overlapping highlight issues.
popupByMouse
Popups in the map are displayed based on mouse behavior. Two mouse behaviors are supported: MouseOver (display popup on hover) and MouseClick (display popup on click). NotShow is also supported to disable popups.
Pass a callback function to set content based on the properties values of geojson.
// Passing PopupShowByEventTypes.MouseOver is equivalent to "MouseOver"
layer.popupByMouse(
PopupShowByEventTypes.MouseOver, // MouseClick: display on click, NotShow: do not show, MouseOver: display on hover
(properties) => {
const container = document.createElement("div");
container.innerText = properties["name"];
container.style.background = "#1890ff";
container.style.padding = "0.4rem";
container.style.color = "white";
container.style.marginBottom = "4rem";
return [container]; // Return a dom wrapped in an array
},
)
Pass an attribute field and a callback function to set content based on the properties values of geojson.
// Passing PopupShowByEventTypes.MouseClick is equivalent to "MouseClick"
layer.popupByMouse(
PopupShowByEventTypes.MouseClick, // MouseClick: display on click, NotShow: do not show, MouseOver: display on hover
"name",
(value) => {
const container = document.createElement("div");
container.innerText = value;
container.style.background = "#1890ff";
container.style.padding = "0.4rem";
container.style.color = "white";
container.style.marginBottom = "4rem";
return [container]; // Return a dom wrapped in an array
},
)
popupByFixed
Popups in the map are displayed based on specified behaviors. Two behaviors are supported: AfterRendered (display popup immediately after layer rendering, suitable for default popup display) and RightNow (display popup immediately when the popup method is called, suitable for dynamically modifying popups). NotShow is also supported.
Pass a callback function to set content based on the properties values of geojson.
// Passing PopupShowByEventTypes.AfterRendered is equivalent to "AfterRendered"
layer.popupByFixed(
PopupShowByEventTypes.AfterRendered, // AfterRendered: display immediately after rendering, NotShow: do not show, RightNow: display immediately when method is called
(properties) => {
const container = document.createElement("div");
container.innerText = properties["name"];
container.style.background = "#1890ff";
container.style.padding = "0.4rem";
container.style.color = "white";
container.style.marginBottom = "4rem";
return [container]; // Return a dom wrapped in an array
},
Pass an attribute field and a callback function to set content based on the properties values of geojson.
// Passing PopupShowByEventTypes.RightNow is equivalent to "RightNow"
layer.popupByFixed(
PopupShowByEventTypes.RightNow, // AfterRendered: display immediately after rendering, NotShow: do not show, RightNow: display immediately when method is called
"name",
(value) => {
const container = document.createElement("div");
container.innerText = value;
container.style.background = "#1890ff";
container.style.padding = "0.4rem";
container.style.color = "white";
container.style.marginBottom = "4rem";
return [container]; // Return a dom wrapped in an array
},
);
Use "NotShow" and "RightNow" to control popup visibility.
// Hide popup
polygonLayer.popupByFixed(PopupShowByEventTypes.NotShow);
// Show popup again
polygonLayer.popupByFixed(PopupShowByEventTypes.RightNow);
The isScaleByLevel property sets whether the popup scales with the earth's zoom level. It scales by default.
layer.popupByFixed(
PopupShowByEventTypes.AfterRendered, // AfterRendered: display immediately after rendering, NotShow: do not show, RightNow: display immediately when method is called
(properties) => {
const container = document.createElement("div");
container.innerText = properties["name"];
container.style.background = "#1890ff";
container.style.padding = "0.4rem";
container.style.color = "white";
container.style.marginBottom = "4rem";
container.isScaleByLevel = false; // Whether to scale the popup with the earth's zoom level, defaults to scaling with earth
return [container]; // Return a dom wrapped in an array
},
)
closePopupFixedLayers
Destroy popups.
layer.closePopupFixedLayers();
show
Two parameters: The first parameter controls layer visibility: true shows the layer, false hides it. The second parameter controls popup visibility: true shows popups, false hides them. By default, popup visibility follows the layer visibility parameter.
Layer show/hide control.
layer.show(false); // Hide layer and hide popups
layer.show(false,false); // Hide layer and hide popups
layer.show(false,true); // Hide layer but show popups
layer.show(true); // Show layer and show popups
layer.show(true,true); // Show layer and show popups
layer.show(true,false); // Show layer but hide popups
visible
Equivalent to the show method.
destroy
Destroy the layer, completely close and remove the layer.
layer.destroy(); // Destroy the layer, completely close and remove the layer
// Equivalent to layer.remove()
// Equivalent to layer.clear()
// Equivalent to layer.close()
remove
Equivalent to the destroy method.
clear
Equivalent to the destroy method.
close
Equivalent to the destroy method.
Top comments (0)