3D Mode

The SDK supports 3D globe mode (Globe), allowing you to switch the map from flat projection to spherical projection, providing a more realistic Earth visual effect.

Enabling 3D Mode

Set Projection Type

// Enable 3D globe mode
sdk.map.setProjection({
  type: "globe",
});

// Switch back to flat mode
sdk.map.setProjection({
  type: "", // Empty string indicates default flat projection
});

Set During Initialization

const sdk = new navMap.MapSDK({
  container: "map",
  center: [116.39, 39.9],
  zoom: 10,
  // Note: Projection type needs to be set after style loading
});

sdk.on("load", () => {
  // Set 3D mode after style loading
  sdk.map.setProjection({
    type: "globe",
  });
});

3D Effect Configuration

Set Sky and Atmosphere Effects

sdk.on("load", () => {
  // Set sky color
  sdk.setSky({
    "sky-color": "#0C2E4B",        // Sky color
    "horizon-color": "#09112F",     // Horizon color
    "fog-color": "#09112F",         // Fog color
    "fog-ground-blend": 0.5,       // Ground fog blend
    "horizon-fog-blend": 0.1,       // Horizon fog blend
    "sky-horizon-blend": 1.0,       // Sky horizon blend
    "atmosphere-blend": 0.5,       // Atmosphere blend
  });
});

Set Tilt Angle

// Set map tilt angle (0-60 degrees)
sdk.setPitch(60);

// With animation
sdk.flyTo({
  pitch: 60,
  duration: 2000,
});

Set Rotation Angle

// Set map rotation angle (0-360 degrees)
sdk.setBearing(45);

// With animation
sdk.flyTo({
  bearing: 45,
  duration: 2000,
});

3D Mode Toggle

Create Toggle Button

<button id="toggle-3d">Toggle 3D Mode</button>

let is3DMode = false;

document.getElementById("toggle-3d").addEventListener("click", () => {
  is3DMode = !is3DMode;
  
  if (is3DMode) {
    // Switch to 3D mode
    sdk.map.setProjection({
      type: "globe",
    });
    
    // Set 3D effects
    sdk.setSky({
      "sky-color": "#0C2E4B",
      "horizon-color": "#09112F",
      "fog-color": "#09112F",
    });
    
    // Set tilt angle
    sdk.flyTo({
      pitch: 60,
      duration: 1000,
    });
  } else {
    // Switch back to flat mode
    sdk.map.setProjection({
      type: "",
    });
    
    // Reset tilt angle
    sdk.flyTo({
      pitch: 0,
      duration: 1000,
    });
  }
});

Interactions in 3D Mode

Rotation Control

In 3D mode, you can rotate the Earth by dragging:

// Enable rotation (enabled by default)
sdk.dragRotate.enable();

// Disable rotation
sdk.dragRotate.disable();

Tilt Control

// Right-click drag can tilt the map
// Or control with code
sdk.flyTo({
  pitch: 60,
  duration: 1000,
});

Zoom Control

// Zoom still works in 3D mode
sdk.on("zoom", () => {
  console.log("Current zoom level:", sdk.getZoom());
});

3D Mode Examples

Complete Example

let sdk;
let is3DMode = false;

async function initMap() {
  sdk = new navMap.MapSDK({
    container: "map",
    center: [116.39, 39.9],
    zoom: 3, // 3D mode recommends smaller initial zoom level
  });

  sdk.on("load", () => {
    setup3DMode();
  });
}

function setup3DMode() {
  // Enable 3D mode by default
  enable3DMode();
  
  // Set sky effects
  sdk.setSky({
    "sky-color": "#0C2E4B",
    "horizon-color": "#09112F",
    "fog-color": "#09112F",
    "fog-ground-blend": 0.5,
    "horizon-fog-blend": 0.1,
    "sky-horizon-blend": 1.0,
    "atmosphere-blend": 0.5,
  });
  
  // Set initial tilt angle
  sdk.setPitch(45);
  
  // Toggle button
  document.getElementById("toggle-3d").addEventListener("click", () => {
    if (is3DMode) {
      disable3DMode();
    } else {
      enable3DMode();
    }
  });
}

function enable3DMode() {
  is3DMode = true;
  sdk.map.setProjection({
    type: "globe",
  });
  
  sdk.flyTo({
    pitch: 60,
    bearing: 0,
    duration: 1000,
  });
}

function disable3DMode() {
  is3DMode = false;
  sdk.map.setProjection({
    type: "",
  });
  
  sdk.flyTo({
    pitch: 0,
    bearing: 0,
    duration: 1000,
  });
}

initMap();

Auto Rotate Earth

let rotationInterval;

function startAutoRotation() {
  let bearing = 0;
  
  rotationInterval = setInterval(() => {
    bearing += 0.5; // Increase by 0.5 degrees each time
    if (bearing >= 360) bearing = 0;
    
    sdk.setBearing(bearing);
  }, 50); // Update every 50ms
}

function stopAutoRotation() {
  if (rotationInterval) {
    clearInterval(rotationInterval);
    rotationInterval = null;
  }
}

// Start auto rotation
startAutoRotation();

// Stop auto rotation
stopAutoRotation();

Performance Optimization

Performance Considerations in 3D Mode

1. Zoom Level: 3D mode works best at low zoom levels (2-5)
2. Layer Simplification: In 3D mode, you can hide some detail layers to improve performance
3. Animation Optimization: Use essential: true option to skip animations on low-performance devices

sdk.on("load", () => {
  // Enable 3D mode
  sdk.map.setProjection({
    type: "globe",
  });
  
  // Adjust layers based on zoom level
  sdk.on("zoom", () => {
    const zoom = sdk.getZoom();
    
    if (zoom < 5) {
      // Low zoom level: hide detail layers
      sdk.hideLayers(["detail-layer"]);
    } else {
      // High zoom level: show detail layers
      sdk.showLayers(["detail-layer"]);
    }
  });
});

Notes

1. Projection Setting Timing: Projection type must be set after style loading (load event)
2. Browser Compatibility: 3D mode requires modern browsers with WebGL support
3. Performance Impact: 3D mode may consume more resources than flat mode
4. Zoom Level: 3D mode effects are more obvious at low zoom levels
5. Style Compatibility: Some styles may display differently in 3D mode

Common Questions

Q: How to detect if currently in 3D mode?

function is3DMode() {
  const projection = sdk.map.getProjection();
  return projection && projection.type === "globe";
}

Q: How to keep a specific area centered in 3D mode?

// Use flyTo method, SDK will automatically handle 3D projection
sdk.flyTo({
  center: [116.39, 39.9],
  zoom: 10,
  pitch: 60,
  bearing: 0,
  duration: 2000,
});

Q: How to optimize performance in 3D mode?

// 1. Reduce layer complexity
sdk.on("zoom", () => {
  if (sdk.getZoom() < 8) {
    sdk.hideLayers(["complex-layer"]);
  }
});

// 2. Use LOD (Level of Detail) configuration
sdk.layerManager.setLODEnabled(true);

// 3. Reduce animation duration
sdk.flyTo({
  pitch: 60,
  duration: 500, // Shorter animation duration
  essential: true, // Skip on low-performance devices
});