cesiumjs-imagery

CesiumJS の画像レイヤー

CesiumJS v1.144 — 画像プロバイダーは、地球儀上にレンダリングされる、または Cesium3DTileset にドレープされるラスタタイルデータを提供します。主な抽象化は ImageryProvider（タイルを取得）、ImageryLayer（表示設定）、ImageryLayerCollection（地球儀上の順序付きスタック）の 3 つです。

ImageryProvider        (abstract -- fetches tile images)
  -> ImageryLayer      (wraps one provider; alpha, brightness, split, etc.)
    -> ImageryLayerCollection  (ordered stack; index 0 = base layer)
      -> Globe / Cesium3DTileset

レイヤーは下から上へレンダリングされます。インデックス 0 は ベースレイヤーで、矩形が世界全体を覆っていない場合でも、地球儀全体に引き伸ばされて表示されます。

クイックスタートと ImageryLayer ファクトリー

画像を扱うビューアーを作成するときは、不要なウィジェットを無効にして、画像に視覚的な焦点が当たるようにします。カメラをすぐに所定の位置へ移動する必要がある場合は、flyTo ではなく camera.setView を使用します。flyTo はアニメーションするため、コードの続行前に完了しないことがあります。

import { Viewer, ImageryLayer, OpenStreetMapImageryProvider, UrlTemplateImageryProvider, Math as CesiumMath } from "cesium";

// Clean viewer -- disable widgets that distract from imagery
const viewer = new Viewer("cesiumContainer", {
  baseLayer: new ImageryLayer(new OpenStreetMapImageryProvider({
    url: "https://tile.openstreetmap.org/",
    maximumLevel: 18,
  })),
  baseLayerPicker: false,
  animation: false,
  timeline: false,
  navigationHelpButton: false,
  navigationInstructionsInitiallyVisible: false,
});

// Position camera immediately (no animation)
viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(-73.0, 41.0, 1500000),
  orientation: {
    heading: 0.0,
    pitch: CesiumMath.toRadians(-90), // look straight down
    roll: 0.0,
  },
});

// Public URL-backed overlay
const nightLayer = new ImageryLayer(new UrlTemplateImageryProvider({
  url: "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/VIIRS_CityLights_2012/default/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpeg",
  maximumLevel: 8,
  credit: "NASA GIBS",
}));
nightLayer.alpha = 0.5;
nightLayer.brightness = 2.0;
viewer.imageryLayers.add(nightLayer);

IonImageryProvider と ImageryLayer.fromWorldImagery は、実行環境に必要な Cesium ion の利用権がある場合にのみ使用してください。公開用またはトークン不要の例では、OpenStreetMap、ArcGIS、NASA GIBS、WMS、WMTS、または URL テンプレートプロバイダーを優先してください。

画像シーンのカメラ高度の目安

次の概算高度を使用して camera.setView を設定します。

縮尺	高度（m）	例
通り／街区	500–2,000	ダウンタウンの交差点
都市	5,000–25,000	ワシントン DC、パリ
大都市圏	50,000–200,000	グレーター・ロンドン
地域／州	300,000–1,500,000	フロリダ、日本
大陸	3,000,000–8,000,000	ヨーロッパ、北アメリカ

真上から見下ろす（地図風の）ビューでは、pitch: CesiumMath.toRadians(-90) を設定します。斜めから見る 3D ビューでは、pitch: CesiumMath.toRadians(-35) から CesiumMath.toRadians(-60) を設定します。

シナリオで特定の国、都市、または地域が指定されている場合は、真上からのフレーミングをデフォルトにします。これにより、遠近法による歪みを避けながら、指定された地物を中央に表示できます。高高度から斜めに見ると、対象がビューフラスタムから外れ、隣接する陸地が表示されることがあります。

固有名詞の場所をフレーミングする目安

固有名詞の場所は、近隣の推測値ではなく、実際の経度と緯度でフレーミングします。プロンプトで斜めからのビューが明示的に求められていない限り、Cartesian3.fromDegrees(lon, lat, height) と真上からのピッチを指定して camera.setView を使用します。

場所	lon, lat	推奨高度
ロンドン	-0.12, 51.50	60,000
パリ	2.35, 48.86	30,000
ニューヨーク市	-74.00, 40.71	60,000
ニューヨーク～ボストン間	-72.5, 41.5	800,000
ワシントン DC、ナショナル・モール	-77.03, 38.89	25,000
フロリダ半島	-81.5, 28.0	1,500,000
グランド・キャニオン	-112.5, 36.3	200,000
ハワイ諸島	-157.0, 20.5	1,800,000
アイスランド	-19.0, 64.9	1,200,000
イタリア半島	12.5, 42.0	2,500,000
南ヨーロッパの分割表示	13.0, 42.0	4,500,000
グリーンランド	-42.0, 72.0	5,000,000
日本、本州	138.0, 36.5	2,500,000

ImageryLayerCollection API

viewer.imageryLayers からアクセスします（viewer.scene.imageryLayers と同じです）。

const layers = viewer.imageryLayers;

layers.add(myLayer);              // add on top
layers.add(myLayer, 0);           // add at index
layers.addImageryProvider(provider); // create layer + add

layers.raise(myLayer);            // move up one
layers.lower(myLayer);            // move down one
layers.raiseToTop(myLayer);       // move to top
layers.lowerToBottom(myLayer);    // move to bottom

layers.remove(myLayer);           // remove and destroy
layers.remove(myLayer, false);    // remove without destroying
layers.removeAll();

const count = layers.length;
const base  = layers.get(0);
const idx   = layers.indexOf(myLayer);
const has   = layers.contains(myLayer);

イベント：layerAdded(layer, index)、layerRemoved(layer, index)、layerMoved(layer, newIndex, oldIndex)、layerShownOrHidden(layer, index, show)。

ImageryLayer の表示プロパティ

プロパティには数値、またはタイルごとのコールバック (frameState, layer, x, y, level) => value を指定できます。

プロパティ	デフォルト	説明
alpha	1.0	0 = 透明、1 = 不透明
brightness	1.0	< 1 は暗く、> 1 は明るくなります
contrast	1.0	< 1 は低く、> 1 は高くなります
hue	0.0	ラジアン単位の色相シフト
saturation	1.0	< 1 は彩度が低く、> 1 は彩度が過剰になります
gamma	1.0	ガンマ補正
show	true	表示／非表示の切り替え
splitDirection	SplitDirection.NONE	LEFT、RIGHT、または NONE
nightAlpha / dayAlpha	1.0	Globe.enableLighting が必要です

追加オプション：rectangle、minimumTerrainLevel / maximumTerrainLevel、cutoutRectangle、colorToAlpha / colorToAlphaThreshold、minificationFilter / magnificationFilter（デフォルトは LINEAR、または NEAREST）。

// Adjust appearance at runtime
layer.alpha = 0.7;
layer.brightness = 1.3;
layer.contrast = 1.5;
layer.saturation = 0.5;
layer.gamma = 1.2;

ベースレイヤーの差し替え

デフォルトのベースレイヤーを削除し、インデックス 0 に別のレイヤーを追加します。置き換えたレイヤーが新しいベースレイヤーとなり、地球儀全体を覆うように引き伸ばされます。

import { ImageryLayer, OpenStreetMapImageryProvider } from "cesium";

// Remove default Bing aerial
viewer.imageryLayers.remove(viewer.imageryLayers.get(0));

// Add OSM as new base layer at index 0
const osmLayer = new ImageryLayer(
  new OpenStreetMapImageryProvider({
    url: "https://tile.openstreetmap.org/",
    maximumLevel: 19,
    credit: "OpenStreetMap contributors",
  }),
);
viewer.imageryLayers.add(osmLayer, 0);

明るいライトベースマップの選択

シナリオで明るい地図や日常的なベースマップが求められている場合、夜景、ダークキャンバス、衛星夜景のタイルをベースレイヤーに使用しないでください。これらはほぼ黒いピクセルとして描画されるため、要件を満たしていないことが明らかです。信頼性の高い一般公開のライトベースマップは次のとおりです。

• OpenStreetMap（https://tile.openstreetmap.org/）
• Carto Positron（https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png）
• ArcGIS World Street Map / World Topographic
• USGS Shaded Relief（WMTS）

VIIRS_CityLights_2012、BlackMarble、CANVAS_DARK は、明るいベースの上に重ねる場合、または夜景が明示的に求められているシーンでのみ使用してください。

画像プロバイダー

IonImageryProvider

Cesium ion のアセットへのアクセスが必要です。呼び出し元が ion の画像アセットを明示的に要求していない限り、一般公開またはトークンなしのサンプルでは使用しないでください。

// Always use fromAssetId (async factory); never call constructor directly
const layer = ImageryLayer.fromProviderAsync(
  IonImageryProvider.fromAssetId(3812),
);
viewer.imageryLayers.add(layer);

OpenStreetMapImageryProvider

Slippy タイルサーバー向けの UrlTemplateImageryProvider を拡張したものです。

const osm = new OpenStreetMapImageryProvider({
  url: "https://tile.openstreetmap.org/",
  maximumLevel: 19,
  credit: "OpenStreetMap contributors",
  // retinaTiles: true,  // request @2x tiles
});
viewer.imageryLayers.addImageryProvider(osm);

UrlTemplateImageryProvider

最も柔軟なプロバイダーです。プレースホルダー：{x}、{y}、{z}、{s}、 {reverseX/Y/Z}、{west/south/east/northDegrees}、 {west/south/east/northProjected}、{width}、{height}。

import { UrlTemplateImageryProvider, GeographicTilingScheme, buildModuleUrl } from "cesium";

// TMS-style with Geographic tiling
const tms = new UrlTemplateImageryProvider({
  url: buildModuleUrl("Assets/Textures/NaturalEarthII") + "/{z}/{x}/{reverseY}.jpg",
  tilingScheme: new GeographicTilingScheme(),
  maximumLevel: 5,
});
viewer.imageryLayers.addImageryProvider(tms);

// Carto Positron with subdomains
const positron = new UrlTemplateImageryProvider({
  url: "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
  subdomains: "abcd",
  credit: "Map tiles by CartoDB, under CC BY 3.0. Data by OpenStreetMap, under ODbL.",
});

// Custom tags for time-varying data
const custom = new UrlTemplateImageryProvider({
  url: "https://yourserver/{Time}/{z}/{y}/{x}.png",
  customTags: {
    Time: (imageryProvider, x, y, level) => "20240101",
  },
});

WebMapServiceImageryProvider（WMS）

import { WebMapServiceImageryProvider, ImageryLayer, Rectangle } from "cesium";

const wms = new WebMapServiceImageryProvider({
  url: "https://basemap.nationalmap.gov:443/arcgis/services/USGSHydroCached/MapServer/WMSServer",
  layers: "0",
  rectangle: Rectangle.fromDegrees(-180, -90, 180, 90),
  // parameters: { transparent: true, format: "image/png" },
  // crs: "EPSG:4326",  // WMS >= 1.3.0
  // srs: "EPSG:4326",  // WMS 1.1.x
});
viewer.imageryLayers.add(new ImageryLayer(wms));

WebMapTileServiceImageryProvider（WMTS）

必須オプション：url、layer、style、tileMatrixSetID。

import { WebMapTileServiceImageryProvider, Credit } from "cesium";

const wmts = new WebMapTileServiceImageryProvider({
  url: "https://basemap.nationalmap.gov/arcgis/rest/services/USGSShadedReliefOnly/MapServer/WMTS",
  layer: "USGSShadedReliefOnly",
  style: "default",
  format: "image/jpeg",
  tileMatrixSetID: "default028mm",
  maximumLevel: 19,
  credit: new Credit("U. S. Geological Survey"),
});
viewer.imageryLayers.addImageryProvider(wmts);

GetFeatureInfo（1.140+、#13196）： WebMapTileServiceImageryProvider が、KVP と RESTful WMTS サービスの両方で pickFeatures をサポートするようになりました。新しいコンストラクターオプション enablePickFeatures、getFeatureInfoFormats、getFeatureInfoUrl、getFeatureInfoParameters で有効にし、provider.pickFeatures(x, y, level, longitude, latitude)（WMS と同じシグネチャ）を呼び出すと、指定した位置の属性を取得できます。

ArcGisMapServerImageryProvider

import { ArcGisMapServerImageryProvider, ArcGisMapService, ArcGisBaseMapType, ImageryLayer } from "cesium";

ArcGisMapService.defaultAccessToken = "<YOUR_ARCGIS_TOKEN>";

// From basemap type enum: SATELLITE, OCEANS, HILLSHADE
const arcgis = ImageryLayer.fromProviderAsync(
  ArcGisMapServerImageryProvider.fromBasemapType(ArcGisBaseMapType.SATELLITE),
);
viewer.imageryLayers.add(arcgis);

// From a specific MapServer URL
const streets = ImageryLayer.fromProviderAsync(
  ArcGisMapServerImageryProvider.fromUrl(
    "https://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer",
  ),
);

BingMapsImageryProvider

import { BingMapsImageryProvider, BingMapsStyle, ImageryLayer } from "cesium";

const bing = ImageryLayer.fromProviderAsync(
  BingMapsImageryProvider.fromUrl("https://dev.virtualearth.net", {
    key: "<YOUR_BING_KEY>",
    mapStyle: BingMapsStyle.AERIAL_WITH_LABELS_ON_DEMAND,
  }),
);
viewer.imageryLayers.add(bing);

スタイル：AERIAL、AERIAL_WITH_LABELS_ON_DEMAND、ROAD_ON_DEMAND、 CANVAS_DARK、CANVAS_LIGHT、CANVAS_GRAY。

MapboxStyleImageryProvider

import { MapboxStyleImageryProvider, ImageryLayer } from "cesium";

const mapbox = new MapboxStyleImageryProvider({
  styleId: "streets-v11",
  accessToken: "<YOUR_MAPBOX_TOKEN>",
  // tilesize: 512, scaleFactor: true  // retina
});
viewer.imageryLayers.add(new ImageryLayer(mapbox));

SingleTileImageryProvider

import { SingleTileImageryProvider, ImageryLayer, Rectangle } from "cesium";

const logo = ImageryLayer.fromProviderAsync(
  SingleTileImageryProvider.fromUrl("/images/overlay.png", {
    rectangle: Rectangle.fromDegrees(-75.0, 28.0, -67.0, 29.75),
  }),
);
viewer.imageryLayers.add(logo);

1.140+（#13297）： OffscreenCanvas が ImageryTypes の値として使用できるようになりました。これにより、画像ソースが求められる場所であれば、ワーカーでレンダリングした OffscreenCanvas や動的に描画した OffscreenCanvas を渡せます。データ URL を介した往復変換が不要なため、プロシージャルに生成するオーバーレイやライブ更新されるオーバーレイに便利です。

分割画面での比較

import { ImageryLayer, SplitDirection, UrlTemplateImageryProvider } from "cesium";

// Add an overlay that only appears on the left side of the split
const nightLayer = new ImageryLayer(new UrlTemplateImageryProvider({
  url: "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/VIIRS_CityLights_2012/default/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpeg",
  maximumLevel: 8,
}));
nightLayer.splitDirection = SplitDirection.LEFT;
viewer.imageryLayers.add(nightLayer);

viewer.scene.splitPosition = 0.5; // 0-1 fraction of viewport width

SplitDirection：LEFT（-1）、NONE（0）、RIGHT（1）。

2 つのベースマップを分割表示する際、プロンプトで国や地域が指定されている場合は、分割を設定する前にカメラをその地域の中心に合わせてください。オーバーレイがどちら側を覆うかにかかわらず、隣接する別の陸地が表示される分割画面は、意図された構図を満たしません。

矩形の切り抜き

import { Rectangle } from "cesium";

// Cover the full named region. Florida peninsula needs roughly -87..-80 lon,
// 24..31 lat; a narrow strip or off-center box will miss the visual target.
const cutout = Rectangle.fromDegrees(-87.6, 24.5, -80.0, 31.0);

// Cut a hole in the base layer to reveal imagery beneath
const base = viewer.imageryLayers.get(0);
base.cutoutRectangle = cutout;

切り抜きのサイズは、表示する地物の全範囲に合わせてください。半島、州、島の場合は、経度と緯度の両方で指定した地物全体を覆う矩形を使用し、同じ地域がカメラの中心になるようにしてください。そうすることで、切り抜き部分がフレームの中央に配置されます。

色をアルファに変換

colorToAlpha は対象色に一致するピクセルを削除し、colorToAlphaThreshold は類似色をどの程度積極的に削除するかを制御します。デフォルトのしきい値は、タイルごとに「黒」の背景色が異なる夜景オーバーレイには厳しすぎます。明るいベースが実際に見えるように、しきい値をかなり高く設定してください。

import { Color } from "cesium";

// On a VIIRS-style night-lights overlay added above an OSM base
const overlay = viewer.imageryLayers.get(1);
overlay.colorToAlpha = new Color(0.0, 0.016, 0.059); // dark ocean blue
overlay.colorToAlphaThreshold = 0.2;                  // generous tolerance

それでも全体的に暗く見える場合は、しきい値をさらに上げる（およそ 0.3～0.5）か、オーバーレイのアルファ値を下げてください。半透明または明るくしたオーバーレイにするには、layer.alpha < 1.0 と layer.brightness > 1.0 の両方を明示的に設定してください。

3D Tiles への画像のドレープ表示

import { Cesium3DTileset, ImageryLayer, IonImageryProvider } from "cesium";

const tileset = await Cesium3DTileset.fromUrl("/path/to/tileset.json");
viewer.scene.primitives.add(tileset);

const labelLayer = ImageryLayer.fromProviderAsync(
  IonImageryProvider.fromAssetId(2411391),
);
tileset.imageryLayers.add(labelLayer); // drape on tileset, not globe
labelLayer.show = false; // toggle off

公開サンプルのタイルセットに画像をドレープ表示するデモでは、タイルセット全体が収まるまでズームアウトしてください。モデル表面全体に画像が表示されるようにし、近接した一部分だけが表示される状態は避けてください。

1.144 以降では、タイルセットにドレープ表示されたレイヤーでもフィーチャー情報のピッキングが機能します。地球儀でのピックで何も見つからない場合、Viewer の InfoBox と ImageryLayerCollection.pickImageryLayerFeatures は tileset.imageryLayers にフォールバックします。そのため、enablePickFeatures が設定された WMS／WMTS レイヤーは、3D Tiles のサーフェス上でもメタデータを返します（Imagery Providers の WMTS GetFeatureInfo オプションを参照してください）。

プロバイダーのデバッグ

import { TileCoordinatesImageryProvider, GridImageryProvider, ImageryLayer, Color } from "cesium";

// Show x/y/level labels on every tile
viewer.imageryLayers.add(new ImageryLayer(
  new TileCoordinatesImageryProvider({ color: Color.YELLOW }),
));
// Wireframe grid overlay
viewer.imageryLayers.add(new ImageryLayer(new GridImageryProvider()));

タイル破棄ポリシー

ポリシー	動作
DiscardEmptyTileImagePolicy	0 バイトの画像を破棄します（Bing Maps のデフォルト）
DiscardMissingTileImagePolicy	ピクセルを既知の「欠落」タイルと比較します
NeverTileDiscardPolicy	破棄しません（サーバーが常に有効なタイルを返す場合に使用します）

import { NeverTileDiscardPolicy, UrlTemplateImageryProvider } from "cesium";

const provider = new UrlTemplateImageryProvider({
  url: "https://my-server/{z}/{x}/{y}.png",
  tileDiscardPolicy: new NeverTileDiscardPolicy(),
});

エラー処理

const layer = ImageryLayer.fromProviderAsync(IonImageryProvider.fromAssetId(3812));
viewer.imageryLayers.add(layer);

// Provider creation failure
layer.errorEvent.addEventListener((error) => {
  console.error("Layer creation failed:", error);
});

// Provider resolved -- listen for per-tile errors
if (layer.readyEvent) {
  layer.readyEvent.addEventListener((provider) => {
    provider.errorEvent.addEventListener((tileError) => {
      console.warn("Tile error:", tileError.message);
    });
  });
}

明示的な準備完了／エラー処理が必要な場合にのみ、readyEvent を待機してください。通常の静的なマップシーンでは、レイヤーを追加してすぐにカメラのフレーミングを行ってください。これにより、準備完了イベントが存在しない場合や、バージョン固有のイベントがある場合でも、レンダリング処理が中断されません。

時間で変化する WMTS

時間とともに変化するレイヤーには、clock と times（TimeIntervalCollection）を渡してください。シナリオで時間によって変化するレイヤーが必要な場合は、timeline と animation のビューワーウィジェットを有効にしておきます。表示される時計コントロールは、時間間隔の設定が有効であることを示す最も明確な視覚的証拠です。

import { WebMapTileServiceImageryProvider, TimeIntervalCollection, JulianDate, Credit } from "cesium";

const times = TimeIntervalCollection.fromIso8601({
  iso8601: "2015-07-30/2017-06-16/P1D",
  dataCallback: (interval) => ({ Time: JulianDate.toIso8601(interval.start) }),
});
const weather = new WebMapTileServiceImageryProvider({
  url: "https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/AMSR2_Snow_Water_Equivalent/default/{Time}/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}.png",
  layer: "AMSR2_Snow_Water_Equivalent",  style: "default",
  tileMatrixSetID: "2km",  maximumLevel: 5,  format: "image/png",
  clock: viewer.clock,  times: times,
  credit: new Credit("NASA Global Imagery Browse Services for EOSDIS"),
});
viewer.imageryLayers.addImageryProvider(weather);

パフォーマンスのヒント

1. 同時に表示するレイヤーを制限する — 一般的には 2～3 レイヤーです。レイヤーごとにタイルリクエストと GPU テクスチャメモリが増加します。
2. 不透明なプロバイダーでは hasAlphaChannel: false を設定する — メモリ使用量とアップロード時間を削減できます。
3. minimumTerrainLevel／maximumTerrainLevel を設定する — 関係のないズームレベルでのタイル取得を省略できます。
4. 手動で await する代わりに ImageryLayer.fromProviderAsync を使用する — プロバイダーの読み込み中に地球儀が空白になるのを防げます。
5. 地域プロバイダーには範囲を絞った rectangle を設定する — 範囲外のタイルリクエストを防げます。
6. プロバイダーインスタンスを再利用する — 再作成する代わりに、destroy: false を指定して削除し、再追加します。
7. タイルが常に有効な場合は NeverTileDiscardPolicy を使用する — ピクセル比較のオーバーヘッドを避けられます。
8. 分類済みラスターデータの場合にのみ NEAREST フィルタリングを選択する — LINEAR（デフォルト）のほうが高速です。

よくあるフレーミングの問題

• 大陸が違う。 アイスランドを指定してグリーンランドを表示するのは、明らかなフレーミングの失敗です。参照座標をそのまま使用してください。
• 地域が隅にある。 切り抜き、分割表示、境界付きの矩形は、カメラの下で中央に配置し、片側に寄せないでください。
• 明るいベースマップの指定に対して、暗いベースレイヤーを使う。 ベースには OSM、ArcGIS World Street Map、Carto Positron、または USGS Shaded Relief を使用してください。
• デフォルトのズーム範囲が広すぎる。 都市が技術的には表示されていても、大陸規模の高さから見た都市シーンは、フレーミングが不適切に見えます。

関連項目

• cesiumjs-viewer-setup -- Viewer コンストラクター、Ion トークン、createWorldImageryAsync
• cesiumjs-terrain-environment -- 地球儀、地形プロバイダー、大気、ライティング