arcgis-scene-environment

ArcGIS 场景环境

使用此技能配置 SceneView 环境：光照、天气、阴影、大气、背景、地下导航和高程设置。

导入模式

ESM（npm）

import Environment from "@arcgis/core/views/3d/environment/Environment.js";
import SunLighting from "@arcgis/core/views/3d/environment/SunLighting.js";
import VirtualLighting from "@arcgis/core/views/3d/environment/VirtualLighting.js";
import SunnyWeather from "@arcgis/core/views/3d/environment/SunnyWeather.js";
import CloudyWeather from "@arcgis/core/views/3d/environment/CloudyWeather.js";
import RainyWeather from "@arcgis/core/views/3d/environment/RainyWeather.js";
import FoggyWeather from "@arcgis/core/views/3d/environment/FoggyWeather.js";
import SnowyWeather from "@arcgis/core/views/3d/environment/SnowyWeather.js";
import ShadowCastAnalysis from "@arcgis/core/analysis/ShadowCastAnalysis.js";

CDN（动态导入）

const SunLighting = await $arcgis.import(
  "@arcgis/core/views/3d/environment/SunLighting.js",
);
const RainyWeather = await $arcgis.import(
  "@arcgis/core/views/3d/environment/RainyWeather.js",
);
const ShadowCastAnalysis = await $arcgis.import(
  "@arcgis/core/analysis/ShadowCastAnalysis.js",
);

环境设置

基本环境配置

const view = new SceneView({
  container: "viewDiv",
  map: scene,
  environment: {
    lighting: {
      date: new Date("Sun Mar 15 2019 16:00:00 GMT+0100"),
    },
    atmosphereEnabled: true,
    starsEnabled: true,
  },
});

地图组件环境

<arcgis-scene item-id="YOUR_WEBSCENE_ID">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-scene>

<script type="module">
  const viewElement = document.querySelector("arcgis-scene");
  await viewElement.viewOnReady();

  viewElement.environment = {
    lighting: {
      date: new Date(),
    },
    atmosphereEnabled: true,
    starsEnabled: true,
  };
</script>

环境属性

属性	类型	说明
lighting	SunLighting | VirtualLighting	光照配置
weather	SunnyWeather | CloudyWeather | RainyWeather | FoggyWeather | SnowyWeather	天气效果
weatherAvailable	boolean (readonly)	是否支持天气效果
atmosphereEnabled	boolean	显示大气雾霭
starsEnabled	boolean	夜间显示星星
background	ColorBackground | null	场景背景颜色/透明度

光照

太阳光照

根据日期、时间和地理位置计算太阳位置，以实现逼真的光照效果。

view.environment = {
  lighting: {
    date: new Date("2024-06-21T14:00:00"),
    directShadowsEnabled: true,
  },
};

// Update sun position dynamically
view.environment.lighting.date = new Date("2024-06-21T18:00:00");

虚拟光照

提供方向一致的光照，无需计算太阳位置。

view.environment = {
  lighting: {
    type: "virtual",
  },
};

阴影

启用直接阴影

view.environment = {
  lighting: {
    directShadowsEnabled: true,
    date: new Date("Sun Mar 15 2019 16:00:00 GMT+0100"),
  },
};

切换符号阴影

const clone = layer.renderer.clone();
clone.symbol.symbolLayers.getItemAt(0).castShadows = true;
layer.renderer = clone;

阴影投射分析

const shadowAnalysis = new ShadowCastAnalysis({
  startTime: new Date("2024-03-21T09:00:00"),
  endTime: new Date("2024-03-21T17:00:00"),
});

view.analyses.add(shadowAnalysis);

天气

天气类型

// Sunny
view.environment.weather = {
  type: "sunny",
  cloudCover: 0.2,
};

// Cloudy
view.environment.weather = {
  type: "cloudy",
  cloudCover: 0.8,
};

// Rainy
view.environment.weather = {
  type: "rainy",
  cloudCover: 0.8,
  precipitation: 0.3,
};

// Foggy
view.environment.weather = {
  type: "foggy",
  visibility: 1000,
};

// Snowy
view.environment.weather = {
  type: "snowy",
  cloudCover: 0.9,
};

天气属性

天气类型	关键属性
sunny	cloudCover（0–1）、visibility（米）
cloudy	cloudCover（0–1）
rainy	cloudCover（0–1）、precipitation（0–1）
foggy	visibility（米）
snowy	cloudCover（0–1）

天气和日光组件

日光组件

<arcgis-scene item-id="YOUR_WEBSCENE_ID">
  <arcgis-daylight slot="top-right"></arcgis-daylight>
</arcgis-scene>

属性	类型	说明
date-or-season	"date" | "season"	日历或季节选择器
play-speed-multiplier	number	动画速度倍数
hide-timezone	boolean	隐藏时区显示

事件：

• arcgis-daylight-change — 日期/时间已更改
• arcgis-season-change — 季节已更改

天气组件

<arcgis-scene item-id="YOUR_WEBSCENE_ID">
  <arcgis-weather slot="top-right"></arcgis-weather>
</arcgis-scene>

阴影投射组件

<arcgis-scene item-id="YOUR_WEBSCENE_ID">
  <arcgis-shadow-cast slot="top-right"></arcgis-shadow-cast>
</arcgis-scene>

透明背景

配置透明背景

const view = new SceneView({
  container: "viewDiv",
  map: scene,
  alphaCompositingEnabled: true,
  environment: {
    background: {
      type: "color",
      color: [255, 252, 244, 0],
    },
    starsEnabled: false,
    atmosphereEnabled: false,
  },
});

切换背景透明度

const backgroundColor = view.environment.background.color.clone();
backgroundColor.a = 0;
view.environment.background.color = backgroundColor;

地下导航

启用地下导航（地图组件）

<arcgis-scene item-id="YOUR_WEBSCENE_ID">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-scene>

<script type="module">
  const viewElement = document.querySelector("arcgis-scene");
  await viewElement.viewOnReady();

  viewElement.map.ground.navigationConstraint = { type: "none" };
  viewElement.map.ground.opacity = 0.4;
  viewElement.map.ground.surfaceColor = "#fff";
</script>

地下导航（核心 API）

const view = new SceneView({
  container: "viewDiv",
  map: scene,
});

view.when(() => {
  view.map.ground.navigationConstraint = { type: "none" };
  view.map.ground.opacity = 0.4;
});

// Navigate underground
view.goTo({
  position: {
    x: -122.4,
    y: 37.8,
    z: -500,
    spatialReference: { wkid: 4326 },
  },
  tilt: 80,
});

地面配置

// World elevation
map.ground = "world-elevation";

// Custom elevation layer
import ElevationLayer from "@arcgis/core/layers/ElevationLayer.js";

map.ground = {
  layers: [
    new ElevationLayer({
      url: "https://elevation.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer",
    }),
  ],
};

// Underground navigation + semi-transparent ground
map.ground.navigationConstraint = { type: "none" };
map.ground.opacity = 0.5;

本地场景模式

创建本地场景

<arcgis-scene basemap="topo-vector" viewing-mode="local">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-scene>

带裁剪区域的本地场景

const viewElement = document.querySelector("arcgis-scene");
await viewElement.viewOnReady();

const clippingExtent = {
  xmax: -10834217,
  xmin: -10932882,
  ymax: 4493918,
  ymin: 4432667,
  spatialReference: { wkid: 3857 },
};

viewElement.clippingArea = clippingExtent;
viewElement.extent = clippingExtent;

viewElement.environment = {
  atmosphereEnabled: false,
  starsEnabled: false,
};

高程模式

layer.elevationInfo = {
  mode: "on-the-ground", // Draped on ground
  // mode: "relative-to-ground"  // Offset from ground
  // mode: "relative-to-scene"   // Offset from scene
  // mode: "absolute-height"     // Absolute Z values
};

// With offset
layer.elevationInfo = {
  mode: "relative-to-ground",
  offset: 100,
  unit: "meters",
};

// With Arcade expression
layer.elevationInfo = {
  mode: "relative-to-ground",
  featureExpressionInfo: {
    expression: "Geometry($feature).z * 10",
  },
  unit: "meters",
};

场景质量

view.qualityProfile = "high"; // "low", "medium", "high"

截图捕获

// Full view screenshot
const screenshot = await view.takeScreenshot({ format: "png" });

const img = document.createElement("img");
img.src = screenshot.dataUrl;
document.body.appendChild(img);

// Specific area
const screenshot = await view.takeScreenshot({
  area: { x: 100, y: 100, width: 500, height: 400 },
  format: "png",
});

// Download
function downloadImage(filename, dataUrl) {
  const element = document.createElement("a");
  element.href = dataUrl;
  element.download = filename;
  element.click();
}

downloadImage("scene-screenshot.png", screenshot.dataUrl);

视图约束

const view = new SceneView({
  container: "viewDiv",
  map: scene,
  constraints: {
    altitude: {
      min: 20000000,
      max: 25000000,
    },
  },
});

常见问题

1. Alpha 混合：必须在 SceneView 上设置 alphaCompositingEnabled: true，才能使用透明背景。

2. 局部场景：需要裁剪区域，通常还要禁用大气和星空效果。

3. 地下导航：必须设置 ground.navigationConstraint.type = "none"。

4. 阴影性能：directShadowsEnabled 可能会显著影响渲染性能。

5. 高程模式："on-the-ground" 会忽略 offset 和 featureExpressionInfo。

6. 天气效果仅适用于 SceneView：天气效果在 MapView 中不起作用。

7. 截图 CORS：外部图层可能会因 CORS 阻止截图。

参考示例

• daylight — 用于设置太阳位置的日光小组件
• weather — SceneView 中的天气效果
• scene-shadow — 3D 阴影投射
• analysis-shadow-cast — 阴影投射分析
• scene-underground — 地下导航
• scene-environment — 环境设置

相关技能

• arcgis-3d-layers — SceneLayer、PointCloudLayer、VoxelLayer
• arcgis-custom-rendering — 用于自定义 3D 效果的 RenderNode
• arcgis-core-maps — SceneView 的设置和初始化