Viewer#

Table of Contents#

• Viewer Class
  • Constructor
  • Properties
  • Methods
  • Events
• Configuration Options
  • ViewerOptions
  • Basemap Configuration BaseMapUrl
• Type Definitions

Viewer Class#

Viewer is the core class for the 3D map viewer, providing map display, camera control, layer management, scene rendering, and other capabilities.

Constructor#

constructor(containerId: string, options?: ViewerOptions)

Parameters:

• containerId (string): ID of the container DOM element
• options (ViewerOptions, optional): Initialization configuration options

Example:

const viewer = new Viewer('map-container', {
  proj4: '+proj=utm +zone=50 +datum=WGS84 +units=m +no_defs',
  sunLight: true,
  baseMapUrls: 'https://your-domain.com/tiles/{z}/{x}/{y}.png',
  terrainUrl: 'https://your-domain.com/terrain'
});

Properties#

Runtime Properties#

View Related#

Camera Properties#

Scene Rendering#

Post-processing Effects#

postProcessingManager Object:

Terrain Related#

Contour Settings#

Interaction Related#

Map Display Area#

Clouds and Sky#

Basemap and Terrain#

Others#

Methods#

Camera Control#

zoomTo(options: CameraPose): void#

Instantly jumps to specified camera position (no animation).

Parameters:

• options (CameraPose): Camera pose configuration

viewer.zoomTo({
  x: 500000,
  y: 3000000,
  z: 1000,
  heading: 0,
  pitch: -45
});

flyTo(options: CameraPose): void#

Flies to specified camera position (with animation).

Parameters:

• options (CameraPose): Camera pose configuration

flyToLookAt(options): void#

Flies to and looks at a specified position.

Parameters:

{
  x: number,
  y: number,
  z: number,
  distance?: number  // Camera distance from target point
}

Point Cloud Layers#

addPointcloudLayer(options: PointCloudLayerOptions): Promise<{id, layer}>#

Adds a point cloud layer.

Returns: Promise containing layer ID and layer object

flyToPointcloudById(id: number | string): void#

Flies to specified point cloud layer.

setPointcloudOpacityById(id: number | string, opacity: number): void#

Sets point cloud opacity.

Parameters:

• opacity: Decimal between 0-1

setPointcloudPointSizeById(id: number | string, size: number): void#

Sets point cloud point size.

setPointCloudColorScheme(id: number | string, scheme: PointCloudColorScheme): void#

Sets point cloud color scheme.

setPointCloudHeightRange(id: number | string, minHeight: number, maxHeight: number): void#

Sets point cloud height range filter.

setPointCloudIntensityRange(id: number | string, minIntensity: number, maxIntensity: number): void#

Sets point cloud intensity range filter.

3D Tiles Layers#

add3DTilesLayer(options: Tiles3DLayerOptions): Promise<{id, layer}>#

Adds a 3D Tiles layer.

Returns: Promise containing layer ID and layer object

flyTo3DTilesById(id: number | string, options?): void#

Flies to specified 3D Tiles layer.

Parameters:

options?: {
  heading?: number,
  pitch?: number
}

set3DTilesOpacityById(id: number | string, opacity: number): void#

Sets 3D Tiles opacity (0-1).

set3DTilesVisibleById(id: number | string, visible: boolean): void#

Sets 3D Tiles visibility.

set3DTilesFeatureVisibleById(layerId: number | string, features: number[]): void#

Sets visibility of specified features in 3D Tiles.

set3DTilesNoFlattening(layerIds: (number | string)[], isNoFlatten: boolean): void#

Sets whether 3D Tiles should not be flattened.

getIs3DTilesNoFlatteningById(layerId: number | string): boolean#

Gets whether a specified layer has no-flattening enabled.

getNoFlatteningList(): (number | string)[]#

Gets list of all no-flattening layer IDs.

get3DTilesFeatureTree(layerId: number | string): any#

Gets 3D Tiles feature tree structure.

setIs3DTilesRawFeatureTypesVisible(layerId, featureKeys, boolean): void#

Sets visibility of 3D Tiles raw feature types.

flyTo3DTilesBBox(layerId: number | string, bbox: any): void#

Flies to 3D Tiles bounding box.

clear3DTilesFeatureColorById(layerId: number): void#

Clears 3D Tiles feature colors.

set3DTilesDefaultColorById(layerId: number, color: number, alpha: number): void#

Sets 3D Tiles default color.

set3DTilesFeatureColorById(layerId: number, featureIds: number[], color: number, alpha: number): void#

Sets color for specified features in 3D Tiles.

getIs3DTilesWireframeById(layerId: number | string): boolean#

Gets whether wireframe mode is enabled.

setIs3DTilesWireframeById(layerId: number | string, isWireframe: boolean): void#

Sets 3D Tiles wireframe mode.

setIs3DTilesUseEnvMap(layerId: number | string, isUseEnvMap: boolean): void#

Sets whether 3D Tiles use environment map.

set3DTilesLoadStartEvent(layerId: number | string, callback: () => void): void#

Sets 3D Tiles load start event callback.

set3DTilesLoadEvent(layerId: number | string, callback: () => void): void#

Sets 3D Tiles load complete event callback.

set3DTilesErrorTarget(layerId: number | string, val: number): void#

Sets 3D Tiles error target value (LOD control).

Basemap Management#

addBaseMapLayer(value: BaseMapUrl, index: number): void#

Adds a basemap layer at specified index position.

removeBaseMapLayer(index: number): void#

Removes basemap layer at specified index.

moveUp(index: number): void#

Moves tile map order up.

moveDown(index: number): void#

Moves tile map order down.

getTileMap(): object | undefined#

Gets tile map object.

Returns:

{
  buffGeometryLayers: {
    highlightById: (options: { idArray: number[] }) => void
  },
  updateStyleByIndex: (index: number, baseMap: BaseMapUrl) => void
} | undefined

updateTile(id, originalGeoJSON, modifiedGeoJSON, originalProj4, currentProj4): void#

Updates tile data.

Screenshot and Recording#

getScreenCaptureRaw(): Promise<Blob>#

Gets raw screenshot data.

Returns: Promise

getScreenCapture(pictureName: string): void#

Saves screenshot to file.

startVideoRecord(): void#

Starts video recording.

stopVideoRecord(videoName: string): void#

Stops video recording and saves.

Animation#

playOrbitAnimation(config?: Partial<OrbitAnimationConfig>): void#

Plays orbit animation.

Parameters:

{
  duration?: number,           // Total duration
  lookAt?: Position3D,        // Look-at point
  isCounterClockwise?: boolean, // Whether counter-clockwise
  heading?: number,           // Heading angle
  pitch?: number,             // Pitch angle
  distance?: number,          // Distance
  circleDuration?: number     // Single circle duration
}

stopOrbitAnimation(): void#

Stops orbit animation.

Gaussian Splatting#

setSplatting(path, positionInfo, cb?): void#

Sets Gaussian splatting model.

Parameters:

path: string,
positionInfo: {
  position: Position3D,
  heading: number,
  pitch: number,
  roll: number,
  scale: number
},
cb?: () => void

flyToSplatting(): void#

Flies to Gaussian splatting model.

Weather and Scene#

setWeather(weather: Weather): void#

Sets weather effect.

Parameters:

• weather: "SUNNY" | "RAINY" | "FOGGY" | "SNOWY"

Position Information#

getScale(): number#

Gets current scale.

getPositionLocal(): {x, y, z}#

Gets current local coordinate position.

getCartographic(): [longitude, latitude]#

Gets current longitude and latitude coordinates.

Rotation Control Box#

setRotationBoxTopRight(config: {top?, right?}): void#

Sets rotation control box position.

Events#

Use the on method to listen for events:

viewer.on(eventName, callback);

Event List#

identify#

Feature identification event.

Callback Parameter: IdentifyData

viewer.on('identify', (featureInfo) => {
  console.log('Identified feature:', featureInfo);
});

bimFeatureTypeLoad#

BIM feature type load complete event.

Callback Parameters:

• json: Record<string, number[]> - Feature type mapping
• id: number - Layer ID

cameramove#

Camera move event (normal precision).

Callback Parameters:

{
  x: number,
  y: number,
  z: number,
  heading: number,
  pitch: number
}

cameramoveprecise#

Camera move event (high precision).

Callback Parameters: CameraPose

click#

Mouse click event.

Callback Parameters:

(
  position: { x: number, y: number, z: number },
  obj: any,
  event: MouseEvent
)

move#

Mouse move event.

Callback Parameters:

(
  position: { x: number, y: number, z: number },
  obj: any,
  event: MouseEvent
)

Configuration Options#

ViewerOptions#

Configuration options for the Viewer constructor.

Basemap Configuration BaseMapUrl#

Basemap supports multiple service types, can be a string URL or configuration object.

1. String Template URL#

type BaseMapUrl = string;

Use tile URL template directly:

viewer.baseMapUrls = 'https://your-domain.com/tiles/{z}/{x}/{y}.png';

2. TEMPLATE Type#

Type: TEMPLATEOptions

{
  type: "TEMPLATE",
  url: "https://your-domain.com/{z}/{x}/{y}.png",
  opacity: 0.8
}

3. WMS Service#

Type: WMSOptions

WMS (Web Map Service) standard service configuration.

Example:

{
  type: "WMS",
  url: "https://your-domain.com/wms",
  version: "1.3.0",
  layers: "layer1,layer2",
  format: "image/png",
  styles: "",
  key: "your-api-key"
}

4. ArcGIS MapServer#

Type: ArcGisMapServerOptions

ArcGIS map service configuration.

Example:

{
  type: "ArcGIS_MapService",
  url: "https://services.arcgis.com/xxx/arcgis/rest/services/xxx/MapServer",
  format: "png8",
  epsg: "EPSG:4326",
  key: "your-api-key"
}

5. ArcGIS FeatureServer#

Type: ArcGisFeatureServerOptions

ArcGIS feature service configuration (supports vector rendering).

Inherits from: TileMapStyle

Example:

{
  type: "ArcGIS_FeatureService",
  url: "https://services.arcgis.com/xxx/arcgis/rest/services/xxx/FeatureServer/0",
  epsg: "EPSG:4326",
  pointColor: "#FF0000",
  pointSize: 5,
  lineColor: "#0000FF",
  lineWidth: 2,
  fillColor: "#00FF0080"
}

6. WFS Service#

Type: WFSOptions

WFS (Web Feature Service) standard service configuration.

Inherits from: TileMapStyle

Text Style:

text?: {
  color?: string,              // Text color
  fontSize?: number,           // Font size
  property?: string,           // Property field name
  scaleDenominator?: {         // Scale range
    min: number | null,
    max: number | null
  }
}

Example:

{
  type: "WFS",
  url: "https://your-domain.com/geoserver/wfs",
  version: "2.0.0",
  typeName: "workspace:layer",
  outputFormat: "application/json",
  pointColor: "#FF0000",
  lineColor: "#0000FF",
  lineWidth: 2
}

7. GeoTwin FeatureTileService (Editable Layer)#

Type: GeoTwinFeatureTileServiceOptions

GeoTwin's proprietary vector tile service supporting high-performance rendering and complex styling.

TEXTLAYER_OPTIONS:

{
  clustering: boolean  // Whether to enable text clustering
}

Highlight Configuration:

highlight?: {
  idArray: number[],
  style: {
    lineColor?: string,
    lineWidth?: number,
    fillColor?: string
  }
}

Example:

{
  type: "GeoTwin_FeatureTileService",
  url: "https://api.your-domain.com/tiles/layer1",
  token: "your-token",
  fields: ["ogc_fid", "name", "type"],
  rule: {
    type: "classification",
    property: "type",
    styles: [
      {
        value: "residential",
        fillColor: "#FFD700",
        lineColor: "#FF4500",
        lineWidth: 2
      }
    ]
  }
}

TileMapStyle (Tile Map Style)#

Basic style configuration for vector layers.

GtFeatureTileStyleRule (Style Rule)#

Advanced style rules for GeoTwin FeatureTileService.

Rule Types#

type GtFeatureTileStyleRuleType = "classification" | "range" | "gradient" | "histogram3D";

• classification: Classification rule, sets styles based on different values of a field
• range: Range rule, sets styles based on field value ranges
• gradient: Gradient rule, sets gradient colors based on field values
• histogram3D: 3D bar chart

Rule Configuration#

Style Configuration (GtFeatureTileStyleRuleStyle)#

Supports very rich style options, including:

Point Styles:

• pointColor: Point color
• pointRadius: Point radius
• text: Text style
• IconMarker: Icon marker
• TextMarker: Text marker
• GLTFModelJson: 3D model
• SectorScanJson: Sector scan effect

Line Styles:

• lineColor: Line color
• lineWidth: Line width
• lineJoin: Join style ("round" | "bevel" | "miter")
• lineCap: Cap style ("round" | "butt" | "square")
• dashArray: Dash array
• GlowLineJson: Glow line
• TraceLineJson: Trace line
• HorizontalDynamicFenceJson: Horizontal dynamic fence

Polygon Styles:

• fillColor: Fill color
• graphicFill: Graphic fill (supports line fill, etc.)
• GenericDrawPolygon: Generic polygon drawing

Example: Classification Style

{
  type: "classification",
  property: "building_type",
  styles: [
    {
      value: "residential",
      fillColor: "#FFD700",
      lineColor: "#FF4500",
      lineWidth: 2,
      text: {
        color: "#000000",
        fontSize: 14,
        property: "name"
      }
    },
    {
      value: "commercial",
      fillColor: "#87CEEB",
      lineColor: "#4169E1",
      lineWidth: 2
    }
  ]
}

Example: Gradient Style

{
  type: "gradient",
  property: "population",
  style: {
    from: 0,
    to: 100000,
    styles: [
      { value: 0, fillColor: "#FFFFE0" },
      { value: 50000, fillColor: "#FFA500" },
      { value: 100000, fillColor: "#FF0000" }
    ]
  }
}

Example: 3D Bar Chart

{
  type: "histogram3D",
  property: "value",
  baseHeight: 0,
  topHeight: "value", // Use field value as height
  material: "basic",
  styles: [
    {
      fillColor: "#4169E1",
      lineColor: "#000000",
      lineWidth: 1
    }
  ]
}

Example: Icon Marker

{
  IconMarker: {
    icon: "/assets/marker.png",
    offset: 0,
    size: { x: 32, y: 32 },
    center: { x: 0.5, y: 1 }
  }
}

Example: 3D Model Marker

{
  GLTFModelJson: {
    path: "/models/tree.glb",
    coordinateSystem: "EPSG:4326",
    pitch: 0,
    heading: 0,
    roll: 0,
    scaleX: 1,
    scaleY: 1,
    scaleZ: 1
  }
}

Example: Glow Line

{
  GlowLineJson: {
    color: "#00FFFF",
    lineWidth: 3,
    glowWidth: 10,
    brightness: 2,
    renderOnTop: true
  }
}

Type Definitions#

CameraPose#

interface CameraPose extends Position3D, Rotation {
  epsg?: string;
  roll?: number;
}

Contains:

• x, y, z: Position coordinates
• heading: Heading angle (degrees)
• pitch: Pitch angle (degrees)
• roll: Roll angle (degrees, optional)
• epsg: Coordinate system (optional)

Position3D / Position2D#

interface Position3D {
  x: number;
  y: number;
  z: number;
}

interface Position2D {
  x: number;
  y: number;
}

Rotation#

interface Rotation {
  heading: number;  // Heading angle (degrees)
  pitch: number;    // Pitch angle (degrees)
}

Weather#

type Weather = "SUNNY" | "RAINY" | "FOGGY" | "SNOWY";

CloudBoxSetting#

interface CloudBoxSetting {
  visible: boolean;      // Whether visible
  coverage: number;      // Coverage
  shadow: number;        // Shadow
  thickness: number;     // Thickness
  steps: number;         // Steps
  noise: number;         // Noise
  windSpeed: number;     // Wind speed
}

SceneCloudSetting#

interface SceneCloudSetting {
  visible: boolean;      // Whether visible
  topLevel: number;      // Top level height
  baseLevel: number;     // Base level height
  range: number;         // Range
  flowSpeed: number;     // Flow speed
  steps: number;         // Steps
  coverage: number;      // Coverage
  cloudType: number;     // Cloud type
}

VolumetricLightingSetting#

interface VolumetricLightingSetting {
  filterLen: number;     // Filter length
  intensity: number;     // Intensity
}

IdentifyData#

Data types returned by identification events, can be one of the following:

IdentifyBimData#

interface IdentifyBimData {
  layerId: number | string;
  featureId: number | undefined;
  attributes: AnyOptions | undefined;
  position: { x: number; y: number; z: number };
}

IdentifyPointCloudData#

interface IdentifyPointCloudData {
  layerId: number | string;
  featureId: null;
  pointAttributes: {
    position: { x: number; y: number; z: number };
    color: [r: number, g: number, b: number, a: number];
    intensity: number;
    classification: number;
  };
}

IdentifyMapData#

type IdentifyMapData = IdentifyMapSuccessData | IdentifyMapFailureData;

interface IdentifyMapSuccessData {
  layerId: string;
  position: Position2D;
  type: "GeoTwin_FeatureTileService" | "WFS";
  attributes: Record<string, string | number | boolean | null>;
  geometry?: Geometry;  // GeoJSON Geometry
}

interface IdentifyMapFailureData {
  error: string;
  layerId: undefined;
  position: Position2D;
  type: string;
}

Usage Examples#

Basic Initialization#

import { Viewer } from './Viewer3D';

const viewer = new Viewer('map-container', {
  proj4: '+proj=utm +zone=50 +datum=WGS84 +units=m +no_defs',
  sunLight: true,
  baseMapUrls: [
    'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}',
    {
      type: "GeoTwin_FeatureTileService",
      url: "https://api.your-domain.com/tiles/roads",
      token: "your-token",
      fields: ["ogc_fid", "name", "road_type"],
      rule: {
        type: "classification",
        property: "road_type",
        styles: [
          {
            value: "highway",
            lineColor: "#FF0000",
            lineWidth: 4
          },
          {
            value: "local",
            lineColor: "#FFFFFF",
            lineWidth: 2
          }
        ]
      }
    }
  ],
  terrainUrl: 'https://your-domain.com/terrain'
});

Event Listening#

// Camera move event
viewer.on('cameramove', (pos) => {
  console.log('Camera position:', pos);
});

// Feature identification event
viewer.on('identify', (data) => {
  if ('layerId' in data && 'attributes' in data) {
    console.log('Identified feature:', data.attributes);
  }
});

// Click event
viewer.on('click', (position, obj, event) => {
  console.log('Click position:', position);
});

Camera Control#

// Fly to specified position
viewer.flyTo({
  x: 500000,
  y: 3000000,
  z: 1000,
  heading: 0,
  pitch: -45
});

// Orbit animation
viewer.playOrbitAnimation({
  lookAt: { x: 500000, y: 3000000, z: 0 },
  distance: 2000,
  circleDuration: 30000,
  pitch: -30
});

Adding Layers#

// Add 3D Tiles
const { id, layer } = await viewer.add3DTilesLayer({
  url: 'https://your-domain.com/tileset.json',
  name: 'Building Model'
});

// Add point cloud
await viewer.addPointcloudLayer({
  url: 'https://your-domain.com/pointcloud/metadata.json',
  name: 'Point Cloud Data'
});

Post-processing Effects#

// Enable bloom effect
viewer.postProcessingManager.blooming = true;
viewer.postProcessingManager.bloomingStrength = 1.5;
viewer.postProcessingManager.bloomingThreshold = 0.8;

// Color adjustment
viewer.postProcessingManager.brightness = 0.1;
viewer.postProcessingManager.contrast = 1.2;
viewer.postProcessingManager.saturation = 1.1;

// Load LUT
viewer.postProcessingManager.lut = '/assets/luts/cinematic.cube';
viewer.postProcessingManager.lutIntensity = 0.8;

Weather Effects#

// Set weather
viewer.setWeather('RAINY');

// Cloud box configuration
viewer.cloudBox = {
  visible: true,
  coverage: 0.6,
  shadow: 0.5,
  thickness: 50,
  steps: 100,
  noise: 0.3,
  windSpeed: 10
};

Notes#

1. Basemap Order: In the baseMapUrls array, basemaps earlier in the array are at lower levels (underneath)
2. LUT Deprecated: Using viewer.lut directly is deprecated, please use viewer.postProcessingManager.lut
3. Coordinate System: Ensure all layers and camera positions use a consistent coordinate system (configured via proj4)
4. Performance Optimization: Use basemapScreenSpaceError and set3DTilesErrorTarget to control LOD, balancing performance and quality
5. GeoTwin FeatureTileService:
   • Recommend using binary format (format: true) for best performance
   • Explicitly specify fields list to avoid missing or loading unnecessary data
   • Style rules rule will gradually migrate to SLD object
6. Event Listening: When using TypeScript, event callbacks will automatically infer correct types