arcgis-feature-effects

ArcGIS フィーチャエフェクト

レイヤーに視覚効果、フィーチャフィルター、表示フィルター、フォーカス領域、ブレンドモードを適用する場合に、このスキルを使用します。

インポートパターン

ESM からの直接インポート

import FeatureEffect from "@arcgis/core/layers/support/FeatureEffect.js";
import FeatureFilter from "@arcgis/core/layers/support/FeatureFilter.js";
import FocusArea from "@arcgis/core/effects/FocusArea.js";
import FocusAreas from "@arcgis/core/effects/FocusAreas.js";
import FocusAreaOutline from "@arcgis/core/effects/FocusAreaOutline.js";

CDN の動的インポート

const [FeatureEffect, FeatureFilter, FocusArea] = await $arcgis.import([
  "@arcgis/core/layers/support/FeatureEffect.js",
  "@arcgis/core/layers/support/FeatureFilter.js",
  "@arcgis/core/effects/FocusArea.js",
]);

Note: 以下の例ではオートキャストを使用しています。CDN で使用する場合は、import X from "path" を const X = await $arcgis.import("path") に置き換えてください。

フィーチャエフェクトの基本

フィーチャエフェクトは、フィルターに基づいてフィーチャを 2 つのセット（含まれるもの／除外されるもの）に分け、それぞれに CSS のようなエフェクトを適用します。

基本的なフィーチャエフェクト

layer.featureEffect = {
  filter: {
    where: "population > 100000",
  },
  includedEffect: "bloom(1.5, 0.5px, 0.2)",
  excludedEffect: "grayscale(100%) opacity(30%)",
};

LayerView のフィーチャエフェクト

const layerView = await view.whenLayerView(layer);

layerView.featureEffect = {
  filter: {
    where: "status = 'Active'",
  },
  excludedEffect: "grayscale(100%) opacity(50%)",
};

スケール依存のエフェクト

layerView.featureEffect = {
  filter: {
    where: "party_switch = 'R' OR party_switch = 'D'",
  },
  includedEffect: [
    { scale: 36978595, value: "drop-shadow(3px, 3px, 4px)" },
    { scale: 18489297, value: "drop-shadow(2px, 2px, 3px)" },
    { scale: 4622324, value: "drop-shadow(1px, 1px, 2px)" },
  ],
};

エフェクトの種類

エフェクト	構文	説明
opacity	opacity(50%)	透明度（0～100%）
grayscale	grayscale(100%)	色を除去（0～100%）
blur	blur(5px)	ガウスぼかし
drop-shadow	drop-shadow(x, y, blur, color)	影のエフェクト
bloom	bloom(strength, radius, threshold)	発光エフェクト
brightness	brightness(150%)	明るさを調整
contrast	contrast(120%)	コントラストを調整
invert	invert(100%)	色を反転
sepia	sepia(100%)	セピア調
saturate	saturate(200%)	色の彩度
hue-rotate	hue-rotate(180deg)	色相を回転

個別のエフェクトの例

不透明度

layer.featureEffect = {
  filter: { where: "type = 'primary'" },
  excludedEffect: "opacity(25%)",
};

グレースケール

layer.featureEffect = {
  filter: { where: "category = 'important'" },
  excludedEffect: "grayscale(100%)",
};

ぼかし

layer.featureEffect = {
  filter: { where: "highlighted = 1" },
  excludedEffect: "blur(5px)",
};

ドロップシャドウ

layer.featureEffect = {
  filter: { where: "selected = 1" },
  includedEffect: "drop-shadow(3px, 3px, 4px, #000000)",
};

ブルーム（発光）

layer.featureEffect = {
  filter: { where: "active = 1" },
  includedEffect: "bloom(1.5, 0.5px, 0.2)",
};

明るさとコントラスト

layer.featureEffect = {
  filter: { where: "status = 'highlight'" },
  includedEffect: "brightness(150%) contrast(120%)",
  excludedEffect: "brightness(50%)",
};

複数のエフェクトの組み合わせ

layer.featureEffect = {
  filter: { where: "status = 'active'" },
  includedEffect: "drop-shadow(2px, 2px, 3px) brightness(120%)",
  excludedEffect: "grayscale(100%) opacity(30%) blur(2px)",
};

フィルターの種類

属性フィルター

layer.featureEffect = {
  filter: {
    where: "population > 50000 AND state = 'CA'",
  },
  excludedEffect: "grayscale(100%) opacity(30%)",
};

ジオメトリベースのフィルター

const layerView = await view.whenLayerView(layer);

layerView.featureEffect = {
  filter: {
    geometry: polygon,
    spatialRelationship: "intersects",
  },
  excludedEffect: "grayscale(100%) opacity(30%)",
};

距離ベースのフィルター

layerView.featureEffect = {
  filter: {
    geometry: point,
    spatialRelationship: "intersects",
    distance: 1000,
    units: "meters",
  },
  excludedEffect: "opacity(20%)",
};

ObjectID フィルター

layerView.featureEffect = {
  filter: {
    objectIds: [1, 5, 10, 42],
  },
  includedEffect: "drop-shadow(3px, 3px, 4px)",
  excludedEffect: "grayscale(100%) opacity(40%)",
};

時間ベースのフィルター

layer.featureEffect = {
  filter: {
    timeExtent: {
      start: new Date("2020-01-01"),
      end: new Date("2020-12-31"),
    },
  },
  excludedEffect: "opacity(20%)",
};

空間関係

関係	説明
intersects	ジオメトリと交差するフィーチャ
contains	ジオメトリを含むフィーチャ
within	ジオメトリ内にあるフィーチャ
crosses	ジオメトリを横切るフィーチャ
overlaps	ジオメトリと重なり合うフィーチャ
touches	ジオメトリに接するフィーチャ
disjoint	ジオメトリと交差しないフィーチャ
envelope-intersects	エンベロープの交差（より高速）

フォーカス領域（3D SceneView）

フォーカス領域は、3D SceneView で特定のポリゴン領域を強調表示し、その外側を暗くします。3D シーンで関心のある領域に注目を集めるのに役立ちます。

フォーカス領域の作成

import FocusArea from "@arcgis/core/effects/FocusArea.js";
import Collection from "@arcgis/core/core/Collection.js";

const focusArea = new FocusArea({
  title: "Area of Interest",
  id: "focus-1",
  enabled: true,
  outline: { color: [255, 128, 128, 0.55] },
  geometries: new Collection([polygon]),
});

SceneView への追加

// Add focus area to the view
view.focusAreas.areas.add(focusArea);

// Set visual style: "bright" or "dark"
view.focusAreas.style = "bright";

フォーカス領域の切り替え

// Disable without removing
focusArea.enabled = false;

// Re-enable with different style
focusArea.enabled = true;
view.focusAreas.style = "dark";

// Remove entirely
view.focusAreas.areas.remove(focusArea);

FocusArea のプロパティ

プロパティ	型	説明
title	string	フォーカス領域のタイトル
id	string	一意の識別子（省略時は自動生成）
enabled	boolean	表示するかどうか（デフォルト：true）
geometries	Collection<Polygon>	フォーカス領域を定義するポリゴンジオメトリ
outline	FocusAreaOutline	アウトラインのスタイル：{ color }

レイヤーエフェクト（フィーチャ単位ではない）

レイヤー全体に（フィーチャごとではなく）CSS のようなエフェクトを適用します。

// Apply effect to the whole layer
layer.effect = "bloom(1.5, 0.5px, 0.2)";

// Multiple effects
layer.effect = "drop-shadow(3px, 3px, 4px) brightness(120%)";

// Remove effect
layer.effect = null;

ブレンドモード

ブレンドモードは、レイヤーとその下にあるレイヤーとのブレンド方法を制御します。

layer.blendMode = "multiply"; // Default is "normal"

ブレンドモードのカテゴリ

カテゴリ	モード
暗くする	multiply、darken、color-burn
明るくする	screen、lighten、color-dodge
コントラスト	overlay、soft-light、hard-light
コンポーネント	hue、saturation、luminosity、color
合成	destination-in、destination-out、destination-over、source-in
反転	difference、exclusion、minus
その他	normal、average、vivid-light、reflect

一般的なブレンドモードのパターン

// Darken: show dark features on light basemap
layer.blendMode = "multiply";

// Lighten: show light features on dark basemap
layer.blendMode = "screen";

// Masking: clip layers using another layer shape
maskLayer.blendMode = "destination-in";

表示フィルター

表示フィルターはフィーチャを完全に非表示にします（フィーチャを描画しないため、エフェクトよりパフォーマンスに優れています）。

シンプルな表示フィルター

layer.displayFilterInfo = {
  where: "population > 10000",
};

縮尺依存の表示フィルター

const layer = new FeatureLayer({
  url: "https://services.arcgis.com/.../FeatureServer/0",
  displayFilterInfo: {
    mode: "scale",
    filters: [
      {
        title: "Major rivers",
        minScale: 0,
        maxScale: 36_978_595,
        where: "streamOrder >= 8",
      },
      {
        title: "Large rivers",
        minScale: 36_978_595,
        maxScale: 18_489_297,
        where: "streamOrder >= 7",
      },
      {
        title: "All rivers",
        minScale: 4_622_324,
        maxScale: 0,
      },
    ],
  },
});

アクティブな表示フィルターの確認

const layerView = await view.whenLayerView(layer);
const activeFilter = layerView.effectiveDisplayFilter?.title;

表示フィルターとフィーチャエフェクトの組み合わせ

// Display filter hides deleted features entirely (performance)
layer.displayFilterInfo = {
  where: "status != 'deleted'",
};

// Feature effect styles remaining features
layer.featureEffect = {
  filter: { where: "status = 'active'" },
  excludedEffect: "opacity(50%)",
};

インタラクティブなフィーチャエフェクト

クリック時のエフェクト

view.on("click", async (event) => {
  const response = await view.hitTest(event);
  const graphic = response.results[0]?.graphic;

  if (graphic) {
    const oid = graphic.attributes.OBJECTID;
    layerView.featureEffect = {
      filter: {
        objectIds: [oid],
      },
      includedEffect: "drop-shadow(3px, 3px, 4px)",
      excludedEffect: "grayscale(100%) opacity(40%)",
    };
  }
});

スライダーを使ったエフェクト

slider.on("thumb-drag", (event) => {
  const value = event.value;
  layer.featureEffect = {
    filter: { where: `value > ${value}` },
    excludedEffect: `opacity(${100 - value}%)`,
  };
});

フィーチャエフェクトのクリア

layer.featureEffect = null;
// or
layerView.featureEffect = null;

ヒストグラムを使ったエフェクト

import histogram from "@arcgis/core/smartMapping/statistics/histogram.js";

const histogramResult = await histogram({
  layer: layer,
  field: "population",
  numBins: 30,
});

const slider = new HistogramRangeSlider({
  bins: histogramResult.bins,
  min: histogramResult.minValue,
  max: histogramResult.maxValue,
  values: [histogramResult.minValue, histogramResult.maxValue],
});

slider.on("thumb-drag", () => {
  const [min, max] = slider.values;
  layerView.featureEffect = {
    filter: {
      where: `population >= ${min} AND population <= ${max}`,
    },
    excludedEffect: "grayscale(100%) opacity(30%)",
  };
});

参考サンプル

• featureeffect-geometry - 空間的な関係に基づくジオメトリベースのフィーチャエフェクト
• featureeffect-drop-shadow - 縮尺依存のドロップシャドウエフェクト
• featureeffect-layers-histogram - ヒストグラムウィジェットを使ったフィーチャエフェクト
• featureeffect-multiple-effects - 複数の視覚エフェクトの組み合わせ
• effect-blur-shadow - レイヤーのぼかしとシャドウのエフェクト
• intro-effect-layer - レイヤーエフェクトの概要
• display-filter - 縮尺依存の表示フィルタリング
• focus-area - 3D SceneView のフォーカス領域
• highlight-features-by-geometry - ジオメトリを使ったフィーチャのハイライト
• blendmode-darkening - 暗くするブレンドモードのエフェクト
• blendmode-grouplayer - グループレイヤーのブレンドモード
• blendmode-multiple-layers - 複数レイヤーにわたるブレンドモード

よくある落とし穴

1. Layer と LayerView の違い：layer のフィーチャエフェクトはすべてのビューに影響しますが、layerView の場合はそのビューのみに影響します。

   // Affects all views
   layer.featureEffect = { ... };
   
   // Affects only this view
   const layerView = await view.whenLayerView(layer);
   layerView.featureEffect = { ... };
   

2. パフォーマンス：多数のフィーチャに複雑なエフェクト（ぼかし、ブルーム）を適用すると、描画パフォーマンスに影響します。まず表示フィルターを使ってフィーチャ数を減らしてください。

3. エフェクトの順序：複数のエフェクトを組み合わせる場合、文字列に記載された順序で適用されます。

4. 表示フィルターとフィーチャエフェクト：フィーチャを完全に非表示にするには、displayFilterInfo を使用します（パフォーマンスに優れています）。対象と対象外のセットを異なるスタイルにするには、featureEffect を使用します。

5. 時間範囲フィルター：時間ベースのフィルターを使用するには、レイヤーに時間情報が設定されている必要があります。設定されていない場合、フィルターは通知なく無視されます。

6. LayerView のみで使える空間フィルター：ジオメトリベースのフィルター（geometry、distance）は、layer.featureEffect ではなく layerView.featureEffect でのみ機能します。

7. ブルームのパラメーター：bloom(strength, radius, threshold) - threshold（0～1）は、どの明るさから光り始めるかを制御します。値が高いほど、光る範囲は小さくなります。

8. エフェクト文字列の構文：エフェクトはカンマではなく、スペースで区切ります。構文が正しくない場合、通知なく失敗します。

   // Anti-pattern: comma-separated effects
   excludedEffect: "grayscale(100%), opacity(30%)";
   
   // Correct: space-separated effects
   excludedEffect: "grayscale(100%) opacity(30%)";
   

9. フォーカス領域には Polygon ジオメトリが必要：FocusArea.geometries でサポートされるのは Polygon ジオメトリのみです。ポイントとポリラインはサポートされていません。

10. 縮尺依存のエフェクト：縮尺依存のエフェクトに配列形式を使う場合、縮尺間を滑らかに補間するには、少なくとも2つの停止点を指定してください。

関連スキル

• arcgis-visualization - レンダラーとシンボル
• arcgis-smart-mapping - ヒストグラムを使った自動生成レンダラー
• arcgis-interaction - ユーザー操作とヒットテスト
• arcgis-layers - レイヤーの種類と設定
• arcgis-core-maps - マップとビューの設定