splatone 0.0.19 → 0.0.20

package/README.md

@@ -11,15 +11,19 @@ SNSのジオタグ付きポストをキーワードに基づいて収集する
 - Bulky: クロールした全てのジオタグを小さな点で描画する
 - Marker Cluster: 密集しているジオタグをクラスタリングしてまとめて表示する
 - Majority Hex: HexGridの各セルをセル内で最頻出するカテゴリの色で彩色
+- Pie Charts: Hexセル中心にカテゴリ割合のPie Chartを描画し、カテゴリごとに半径を可変化
 - Voronoi: HexGrid単位で集約したジオタグからVoronoiセルを生成し、各Hexのポリゴンでクリップして表示
 - Heat: ヒートマップ
+- Pie Charts: 円グラフグリッド
 
 ## Change Log
 
-### v0.0.18 →　v0.0.19
+### v0.0.18 →　v0.0.19 →　v0.0.20
 
 * **[可視化モジュール]** ```--vis-voronoi```追加
   * ボロノイ図の生成
+* **[可視化モジュール]** ```--vis-pie-charts```追加
+  * Hex中心のカテゴリ割合Pie Chart描画
 
 ### v0.0.17 →　v0.0.18
 
@@ -83,6 +87,8 @@ Visualization (最低一つの指定が必須です)
       --vis-majority-hex    HexGrid内で最も出現頻度が高いカテゴリの色で彩色。Hex
                             apartiteモードで6分割パイチャート表示。透明度は全体
                             で正規化。                [真偽] [デフォルト: false]
+  --vis-pie-charts      Hex中心にカテゴリ割合Pie Chartを表示。半径はグローバル
+            出現比に応じてカテゴリ毎に可変化。 [真偽] [デフォルト: false]
       --vis-marker-cluster  マーカークラスターとして地図上に表示
                                                       [真偽] [デフォルト: false]
   --vis-voronoi         Hex GridごとにVoronoiセルを生成して表示
@@ -174,6 +180,8 @@ APIキーは以下の３種類の方法で与える事ができます
 
 ### Bulky: 全ての点を地図上にポイントする
 
+全ての点を地図上に表示する。
+
 ![](assets/screenshot_sea-mountain_bulky.png?raw=true)
 
 #### コマンド例
@@ -196,6 +204,8 @@ $ npx -y -p splatone@latest crawler -p flickr -k "sea,ocean|mountain,mount" --vi
 
 ### Marker Cluster: 高密度の地点はマーカーをまとめて表示する
 
+全マーカーを表示すると、地図上がマーカーで埋め尽くされる問題に対して、高密度地点のマーカー群を一つにまとめてマーカーとする手法。ズームレベルに応じて自動的にマーカーが集約される。
+
 ![](assets/screenshot_venice_marker-cluster.png?raw=true)
 
 #### コマンド例
@@ -211,6 +221,8 @@ $ npx -y -p splatone@latest crawler -p flickr -k "水域=canal,channel,waterway,
 
 ### Heat: ヒートマップ
 
+出現頻度に基づいて点の影響範囲をガウス分布で定め連続的に彩色するヒートマップ。
+
 ![](assets/screenshot_venice_heat.png?raw=true)
 
 #### コマンド例
@@ -235,8 +247,10 @@ $ npx -y -p splatone@latest crawler -p flickr -k "水域#0947ff=canal,river,sea,
 ![](assets/screenshot_florida_hex_majorityr.png?raw=true)
 
 #### コマンド例
+
 * クエリは水域・緑地・交通・ランドマークを色分けしたもの。上記スクリーンショットはフロリダ半島全体
-* 
+
+
 ```shell
 $ npx -y -p splatone@latest crawler -p flickr -k "水域=canal,channel,waterway,river,stream,watercourse,sea,ocean,gulf,bay,strait,lagoon,offshore|緑地=forest,woods,turf,lawn,jungle,trees,rainforest,grove,savanna,steppe|交通=bridge,overpass,flyover,aqueduct,trestle,street,road,thoroughfare,roadway,avenue,boulevard,lane,alley,roadway,carriageway,highway,motorway|ランドマーク=church,chapel,cathedral,basilica,minster,temple,shrine,neon,theater,statue,museum,sculpture,zoo,aquarium,observatory" --vis-majority-hex --v-majority-hex-Hexapartite --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 ```
@@ -253,18 +267,45 @@ $ npx -y -p splatone@latest crawler -p flickr -k "水域=canal,channel,waterway,
 
 * ```--v-majority-hex-Hexapartite```を指定すると各Hexセルを六分割の荒いPie Chartとして中のカテゴリ頻度に応じて彩色します。
 
+### Pie Charts: Hex中心にカテゴリ割合Pie Chartを描画
+
+![](assets/screenshot_pie_tokyo.png?raw=true)
+
+Hexセル中心に、カテゴリ比率を角度で、グローバル出現数を半径で示すPie Chartを描画します。カテゴリごとに円弧の半径が異なるため、同じHex内でも「世界的にどのカテゴリが多く集まったか」を直感的に比較できます。Pie Chart自体はHex境界内に収まるよう中央へ配置されます。
+
+ズームイン／アウト時にはLeafletのzoomイベントをフックしてPie Chartを再描画し、現在の縮尺でもHex境界にフィットする半径が自動再計算されます。
+
+#### コマンド例
+
+* クエリは水域・交通・宗教施設・緑地を色分け。Hexサイズに応じて自動計算される最大半径を90%まで、最小半径をその40%に設定しています。
+
+```shell
+$ npx -y -p splatone@latest crawler -p flickr -k "水域#0947ff=canal,river,sea,strait,channel,waterway,pond|交通#aaaaaa=road,street,alley,sidewalk,bridge|宗教施設#ffb724=chapel,church,cathedral,temple,shrine|緑地#00a73d=forest,woods,trees,mountain,garden,turf" --vis-pie-charts --v-pie-charts-MaxRadiusScale=0.9 --v-pie-charts-MinRadiusScale=0.4 --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+```
+
+#### コマンドライン引数
+
+| オプション                               | 説明                                                                                                          | 型   | デフォルト |
+| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :--- | :--------- |
+| `--v-pie-charts-MaxRadiusScale`          | Hex内接円半径に対する最大Pie半径の倍率(0-1.5)。1.0でHex境界いっぱい、0.9なら10%余白。                             | 数値 | 0.9        |
+| `--v-pie-charts-MinRadiusScale`          | 最大半径に対する最小Pie半径の倍率(0-1)。カテゴリが存在する場合に確保する下限割合。                                 | 数値 | 0.25       |
+| `--v-pie-charts-StrokeWidth`             | Pie Chart外周・扇形境界の線幅(px)。                                                                             | 数値 | 1          |
+| `--v-pie-charts-BackgroundOpacity`       | 最大半径ガイドリングの塗り透明度(0-1)。背景リングの見え方を調整します。                                          | 数値 | 0.2        |
+
+Pie Chartの最大・最小半径は各Hexのジオメトリから算出した内接円半径に基づき動的に決まり、カテゴリごとの扇形半径は「そのHex内カテゴリ出現数 ÷ 全カテゴリ総数」に比例して拡大します。グローバル最大カテゴリのシェアを1として正規化するため、Hex間でもカテゴリ規模を比較できます。
+
 ### Voronoi: Hex Gridをベースにしたボロノイ分割
 
 Hex Gridで集約した各セル内のジオタグを種点としてVoronoi分割を行い、生成したポリゴンをHex境界でクリップして表示します。カテゴリカラーと総数はHex集計結果に基づき、最小間隔／最大サイト数の制御で過密な地域も読みやすく整列できます。
 
-![](assets/screenshot_voronoi_kyoto.png?raw=true)
+![](assets/screenshot_voronoi_tokyo.png?raw=true)
 
 #### コマンド例
 
-* クエリは水域・交通・宗教施設・緑地を色分けしたもの。Hex単位で50m以上離れたサイトだけをVoronoiセルとして採用します。
+* クエリは水域・交通・宗教施設・緑地を色分けしたもの。Hex単位で50m以上離れたサイトだけをVoronoiセルとして採用します。上記の例は東京を範囲としたもの。皇居の緑地や墨田川の水域がよく現れている。
 
 ```shell
-$ npx -y -p splatone@latest crawler -p flickr -k "水域#0947ff=canal,river,sea,strait,channel,waterway,pond|交通#aaaaaa=road,street,alley,sidewalk,bridge|宗教施設#ffb724=chapel,church,cathedral,temple,shrine|緑地#00a73d=forest,woods,trees,mountain,garden,turf" --vis-voronoi --v-voronoi-MinSiteSpacingMeters=50 --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+$ npx -y -p splatone@latest crawler -p flickr -k "水域#0947ff=canal,river,sea,strait,channel,waterway,pond|交通#aaaaaa=road,street,alley,sidewalk,bridge|宗教施設#ffb724=chapel,church,cathedral,temple,shrine|緑地#00a73d=forest,woods,trees,mountain,garden,turf" --vis-voronoi --v-voronoi-MinSiteSpacingMeters=50　--p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 ```
 
 #### コマンドライン引数
@@ -272,9 +313,9 @@ $ npx -y -p splatone@latest crawler -p flickr -k "水域#0947ff=canal,river,sea,
 | オプション                                | 説明                                                                                      | 型   | デフォルト |
 | :---------------------------------------- | :---------------------------------------------------------------------------------------- | :--- | :--------- |
 | `--v-voronoi-MaxSitesPerHex`              | 1 HexあたりにPoissonサンプリングで残す最大サイト数。0のときは制限なし。                     | 数値 | 0          |
-| `--v-voronoi-MinSiteSpacingMeters`        | Hex内の採用サイト間で確保する最小距離 (メートル)。ジオタグが密集していても空間的に均等化。 | 数値 | 50         |
+| `--v-voronoi-MinSiteSpacingMeters`        | Hex内の採用サイト間で確保する最小距離 (メートル)。ジオタグが密集していても空間的に均等化しつつ、MinSiteSpacingMeters範囲内で出現数の多いカテゴリを優先して残す。 | 数値 | 50         |
 
-Hex内にサイトが存在しない・ダウンサンプリングで0件になった場合は、コンソールにWarnを出しつつ他のHexの描画を継続します。
+MinSiteSpacingMetersによる間引きは、各サイト周辺 (MinSiteSpacingMeters以内) の同カテゴリ出現数を優先度として利用するため、同距離内で競合した場合も局所的に密度の高いカテゴリのサイトが採用されやすくなります。一方で密度は低いが他の場所に比べて顕著に出現するカテゴリを見逃す可能性があります。なお、Voronoi図の作成は消費メモリが大きい為、デフォルトでは50m間隔に間引きます。厳密解が必要な場合は```--v-voronoi-MinSiteSpacingMeters=0```を指定してください。ただし、その場合はヒープを使い果たしてクラッシュする可能性があります。マシンパワーに余裕がある場合は```npx --node-options='--max-old-space-size=10240'```のようにヒープサイズを拡大して実行する事も可能です。もう一つのオプション```--v-voronoi-MaxSitesPerHex```はHex内の最大アイテム数を制限するものです。ポワソンサンプリングに基づいてアイテムを間引きます。MinSiteSpacingMetersと共に、適切な結果が得られるよう調整してください。
 
 ## キーワード指定方法
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splatone",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Multi-layer Composite Heatmap",
   "homepage": "https://github.com/YokoyamaLab/Splatone#readme",
   "bugs": {

package/visualizer/pie-charts/node.js

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { featureCollection, centroid as turfCentroid } from '@turf/turf';
+import { VisualizerBase } from '../../lib/VisualizerBase.js';
+
+function buildHexIndex(target = {}) {
+	const features = target?.hex?.features;
+	const index = new Map();
+	if (!Array.isArray(features)) return index;
+	for (const feature of features) {
+		const hexId = feature?.properties?.hexId;
+		if (hexId == null) continue;
+		index.set(String(hexId), feature);
+	}
+	return index;
+}
+
+function computeHexCentroid(hexFeature) {
+	if (!hexFeature) return null;
+	try {
+		const center = turfCentroid(hexFeature);
+		const coords = center?.geometry?.coordinates;
+		if (Array.isArray(coords) && coords.length >= 2) {
+			return coords;
+		}
+	} catch (err) {
+		console.warn('[PieChartsVisualizer] Failed to compute centroid', err?.message);
+	}
+	return null;
+}
+
+function extractPrimaryRing(feature) {
+	const geometry = feature?.geometry;
+	if (!geometry) return null;
+	if (geometry.type === 'Polygon') {
+		const ring = geometry?.coordinates?.[0];
+		if (!Array.isArray(ring) || ring.length < 3) return null;
+		return ring.map(coords => Array.isArray(coords) ? [coords[0], coords[1]] : null).filter(Boolean);
+	}
+	if (geometry.type === 'MultiPolygon') {
+		const firstPoly = geometry?.coordinates?.[0]?.[0];
+		if (!Array.isArray(firstPoly) || firstPoly.length < 3) return null;
+		return firstPoly.map(coords => Array.isArray(coords) ? [coords[0], coords[1]] : null).filter(Boolean);
+	}
+	return null;
+}
+
+function aggregatePieChartFeatures(result = {}, target = {}) {
+	const hexIndex = buildHexIndex(target);
+	const features = [];
+	let globalMaxCategoryCount = 0;
+	let globalTotalCount = 0;
+
+	for (const [hexId, categories] of Object.entries(result ?? {})) {
+		if (!categories) continue;
+		const breakdown = [];
+		let totalCount = 0;
+
+		for (const [categoryName, payload] of Object.entries(categories)) {
+			const count = payload?.items?.features?.length ?? 0;
+			if (count <= 0) continue;
+			breakdown.push({ name: categoryName, count });
+			totalCount += count;
+			globalTotalCount += count;
+			if (count > globalMaxCategoryCount) {
+				globalMaxCategoryCount = count;
+			}
+		}
+
+		if (totalCount === 0) continue;
+
+		const hexFeature = hexIndex.get(String(hexId));
+		if (!hexFeature) {
+			console.warn(`[PieChartsVisualizer] Missing hex polygon for ${hexId}`);
+			continue;
+		}
+
+		const centroidCoords = computeHexCentroid(hexFeature);
+		if (!centroidCoords) {
+			console.warn(`[PieChartsVisualizer] Unable to place pie chart for hex ${hexId}`);
+			continue;
+		}
+
+		const ring = extractPrimaryRing(hexFeature);
+		if (!ring || ring.length < 3) {
+			console.warn(`[PieChartsVisualizer] Missing polygon ring for hex ${hexId}`);
+			continue;
+		}
+
+		breakdown.sort((a, b) => b.count - a.count);
+
+		features.push({
+			type: 'Feature',
+			geometry: {
+				type: 'Point',
+				coordinates: centroidCoords
+			},
+			properties: {
+				hexId,
+				totalCount,
+				categories: breakdown,
+				hexCoordinates: ring
+			}
+		});
+	}
+
+	return {
+		features,
+		globalMaxCategoryCount,
+		globalTotalCount
+	};
+}
+
+export default class PieChartsVisualizer extends VisualizerBase {
+	static name = 'Pie Charts Visualizer';
+	static version = '0.0.1';
+	static description = 'Hex中心にカテゴリ割合のPie Chartを描画するビジュアライザ';
+
+	constructor() {
+		super();
+		this.id = path.basename(path.dirname(fileURLToPath(import.meta.url)));
+	}
+
+	async yargv(yargv) {
+		return yargv
+			.option(this.argKey('MaxRadiusScale'), {
+				group: 'For ' + this.id + ' Visualizer',
+				type: 'number',
+				description: 'Hex内接円半径に対する最大半径スケール (0-1.5)',
+				default: 0.9
+			})
+			.option(this.argKey('MinRadiusScale'), {
+				group: 'For ' + this.id + ' Visualizer',
+				type: 'number',
+				description: '最大半径に対する最小半径スケール (0-1)',
+				default: 0.25
+			})
+			.option(this.argKey('StrokeWidth'), {
+				group: 'For ' + this.id + ' Visualizer',
+				type: 'number',
+				description: 'Pie Chart輪郭線の太さ(px)',
+				default: 1
+			})
+			.option(this.argKey('BackgroundOpacity'), {
+				group: 'For ' + this.id + ' Visualizer',
+				type: 'number',
+				description: '最大半径ガイドリングの透明度 (0-1)',
+				default: 0.2
+			});
+	}
+
+	getFutureCollection(result, target, visOptions) { // visOptions reserved for future use
+		const { features, globalMaxCategoryCount, globalTotalCount } = aggregatePieChartFeatures(result, target);
+		const collection = featureCollection(features);
+		collection.properties = {
+			globalMaxCategoryCount,
+			globalTotalCount
+		};
+		return collection;
+	}
+}
+

package/visualizer/pie-charts/web.js

@@ -0,0 +1,271 @@
+let layerGroup = null;
+let styleInjected = false;
+let zoomHandler = null;
+let activeMap = null;
+let cachedContext = null;
+
+function reset(map) {
+	if (layerGroup && map) {
+		map.removeLayer(layerGroup);
+	}
+	if (map && zoomHandler) {
+		map.off('zoomend', zoomHandler);
+	}
+	layerGroup = null;
+	zoomHandler = null;
+	activeMap = null;
+	cachedContext = null;
+}
+
+function ensureStyles() {
+	if (styleInjected) return;
+	const style = document.createElement('style');
+	style.textContent = `
+	.pie-chart-marker {
+		background: transparent !important;
+		border: none !important;
+	}
+	.pie-chart-marker svg {
+		pointer-events: none;
+		display: block;
+	}
+	`;
+	document.head.appendChild(style);
+	styleInjected = true;
+}
+
+function normalizeFeatureCollection(payload) {
+	if (!payload) return null;
+	if (payload.type === 'FeatureCollection') return payload;
+	if (payload?.pieCharts?.type === 'FeatureCollection') {
+		return payload.pieCharts;
+	}
+	return null;
+}
+
+const DEFAULTS = {
+	MaxRadiusScale: 0.9,
+	MinRadiusScale: 0.25,
+	StrokeWidth: 1,
+	BackgroundOpacity: 0.2
+};
+
+function polarToCartesian(cx, cy, radius, angle) {
+	return {
+		x: cx + radius * Math.cos(angle),
+		y: cy + radius * Math.sin(angle)
+	};
+}
+
+function buildSlicePath(cx, cy, radius, startAngle, endAngle) {
+	if (radius <= 0 || endAngle <= startAngle) return '';
+	const start = polarToCartesian(cx, cy, radius, startAngle);
+	const end = polarToCartesian(cx, cy, radius, endAngle);
+	const largeArcFlag = (endAngle - startAngle) > Math.PI ? 1 : 0;
+	return `M ${cx} ${cy} L ${start.x} ${start.y} A ${radius} ${radius} 0 ${largeArcFlag} 1 ${end.x} ${end.y} Z`;
+}
+
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+
+function computeHexRadiusPx(map, centroidLatLng, ring = []) {
+	if (!map || !centroidLatLng || !Array.isArray(ring) || ring.length === 0) {
+		return 32;
+	}
+	const centerPoint = map.latLngToLayerPoint(centroidLatLng);
+	let minDistance = Infinity;
+	for (const coord of ring) {
+		if (!Array.isArray(coord) || coord.length < 2) continue;
+		const latLng = L.latLng(coord[1], coord[0]);
+		const point = map.latLngToLayerPoint(latLng);
+		const dist = centerPoint.distanceTo(point);
+		if (Number.isFinite(dist) && dist > 0) {
+			minDistance = Math.min(minDistance, dist);
+		}
+	}
+	if (!Number.isFinite(minDistance) || minDistance === Infinity) {
+		return 32;
+	}
+	return Math.max(4, minDistance - 2);
+}
+
+function deriveRadiusRange(map, feature, visOptions) {
+	const coords = feature?.geometry?.coordinates;
+	const centroidLatLng = Array.isArray(coords) && coords.length >= 2 ? L.latLng(coords[1], coords[0]) : null;
+	const ring = feature?.properties?.hexCoordinates ?? [];
+	const baseRadius = computeHexRadiusPx(map, centroidLatLng, ring);
+	const maxScale = clamp(Number(visOptions.MaxRadiusScale ?? DEFAULTS.MaxRadiusScale), 0.1, 1.5);
+	const minScale = clamp(Number(visOptions.MinRadiusScale ?? DEFAULTS.MinRadiusScale), 0, 1);
+	const maxRadius = Math.max(4, baseRadius * maxScale);
+	const minRadius = clamp(baseRadius * minScale, 0, maxRadius * 0.95);
+	return { maxRadius, minRadius };
+}
+
+function computeRadiusPixels(count, stats, radiusRange) {
+	if (!Number.isFinite(count) || count <= 0) return 0;
+	const { maxRadius, minRadius } = radiusRange;
+	const globalTotal = Math.max(1, Number(stats.globalTotalCount) || 1);
+	const globalMaxCount = Math.max(1, Number(stats.globalMaxCategoryCount) || 1);
+	const maxShare = globalMaxCount / globalTotal;
+	const share = count / globalTotal;
+	const normalized = maxShare > 0 ? clamp(share / maxShare, 0, 1) : 0;
+	if (normalized <= 0) return minRadius;
+	return minRadius + (maxRadius - minRadius) * normalized;
+}
+
+function renderPieSvg(feature, palette, visOptions, stats, radiusRange) {
+	const categories = feature?.properties?.categories;
+	const totalCount = feature?.properties?.totalCount ?? 0;
+	if (!Array.isArray(categories) || categories.length === 0 || totalCount === 0) {
+		return null;
+	}
+
+	const maxRadius = radiusRange.maxRadius;
+	const strokeWidth = Math.max(0, Number(visOptions.StrokeWidth ?? DEFAULTS.StrokeWidth));
+	const backgroundOpacity = Math.min(1, Math.max(0, Number(visOptions.BackgroundOpacity ?? DEFAULTS.BackgroundOpacity)));
+	const size = (maxRadius + strokeWidth) * 2;
+	const cx = size / 2;
+	const cy = size / 2;
+
+	const validCategories = categories.filter(cat => (cat?.count ?? 0) > 0);
+	if (!validCategories.length) return null;
+
+	const total = validCategories.reduce((sum, cat) => sum + cat.count, 0);
+	if (total === 0) return null;
+
+	let currentAngle = -Math.PI / 2;
+	const slices = [];
+	for (const cat of validCategories) {
+		const ratio = cat.count / total;
+		const angleSpan = ratio * Math.PI * 2;
+		if (angleSpan <= 0) continue;
+		const startAngle = currentAngle;
+		const endAngle = currentAngle + angleSpan;
+		currentAngle = endAngle;
+	const radius = computeRadiusPixels(cat.count, stats, radiusRange);
+		if (radius <= 0) continue;
+		slices.push({
+			path: buildSlicePath(cx, cy, radius, startAngle, endAngle),
+			color: palette[cat.name]?.color || '#888888',
+			stroke: palette[cat.name]?.darken || 'rgba(0,0,0,0.4)',
+			count: cat.count,
+			name: cat.name
+		});
+	}
+
+	if (!slices.length) return null;
+
+	const outlineColor = 'rgba(0,0,0,0.35)';
+	const svgParts = [`<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" aria-label="hex pie chart">`];
+	svgParts.push(`<circle cx="${cx}" cy="${cy}" r="${maxRadius}" fill="rgba(255,255,255,${backgroundOpacity})" stroke="${outlineColor}" stroke-width="${strokeWidth}" />`);
+
+	for (const slice of slices) {
+		if (!slice.path) continue;
+		svgParts.push(`<path d="${slice.path}" fill="${slice.color}" stroke="${slice.stroke}" stroke-width="${Math.max(0.5, strokeWidth * 0.6)}" />`);
+	}
+
+	svgParts.push('</svg>');
+	return { svg: svgParts.join(''), size };
+}
+
+function createMarker(map, feature, palette, visOptions, stats) {
+	const coords = feature?.geometry?.coordinates;
+	if (!Array.isArray(coords) || coords.length < 2) return null;
+	const radiusRange = deriveRadiusRange(map, feature, visOptions);
+	const rendered = renderPieSvg(feature, palette, visOptions, stats, radiusRange);
+	if (!rendered) return null;
+
+	const icon = L.divIcon({
+		className: 'pie-chart-marker',
+		html: rendered.svg,
+		iconSize: [rendered.size, rendered.size],
+		iconAnchor: [rendered.size / 2, rendered.size / 2]
+	});
+
+	const marker = L.marker([coords[1], coords[0]], { icon });
+	const total = feature?.properties?.totalCount ?? 0;
+	const breakdown = feature?.properties?.categories ?? [];
+	const htmlLines = [`<strong>Hex ${feature?.properties?.hexId ?? ''}</strong>`, `Total: ${total}`];
+	for (const cat of breakdown) {
+		const color = palette[cat.name]?.color || '#888888';
+		const pct = total > 0 ? ((cat.count / total) * 100).toFixed(1) : '0.0';
+		htmlLines.push(`<span style="display:inline-flex;align-items:center;gap:4px;">
+			<span style="width:10px;height:10px;background:${color};display:inline-block;border-radius:50%;"></span>
+			${cat.name}: ${cat.count} (${pct}%)
+		</span>`);
+	}
+	marker.bindTooltip(htmlLines.join('<br/>'), { direction: 'top', opacity: 0.9 });
+	return marker;
+}
+
+function renderPieLayer({ fitBounds } = {}) {
+	if (!activeMap || !cachedContext) return false;
+
+	if (layerGroup) {
+		activeMap.removeLayer(layerGroup);
+		layerGroup = null;
+	}
+
+	const markers = [];
+	const { featureCollection, palette, visOptions, stats } = cachedContext;
+	for (const feature of featureCollection.features) {
+		const marker = createMarker(activeMap, feature, palette, visOptions, stats);
+		if (marker) markers.push(marker);
+	}
+
+	if (!markers.length) {
+		console.warn('[PieChartsVisualizer] All pie charts skipped due to insufficient data.');
+		return false;
+	}
+
+	layerGroup = L.layerGroup(markers).addTo(activeMap);
+
+	if (fitBounds) {
+		const bounds = L.latLngBounds(markers.map(m => m.getLatLng()));
+		if (bounds.isValid()) {
+			activeMap.fitBounds(bounds, { padding: [16, 16] });
+		}
+	}
+
+	return true;
+}
+
+function attachZoomHandler(map) {
+	if (!map || !cachedContext) return;
+	zoomHandler = () => {
+		renderPieLayer({ fitBounds: false });
+	};
+	map.on('zoomend', zoomHandler);
+}
+
+export default async function main(map, geojson, options = {}) {
+	reset(map);
+	ensureStyles();
+
+	const featureCollection = normalizeFeatureCollection(geojson);
+	if (!featureCollection || !Array.isArray(featureCollection.features) || featureCollection.features.length === 0) {
+		console.warn('[PieChartsVisualizer] No data to render.');
+		return {};
+	}
+
+	const palette = options.palette || {};
+	const visOptions = options.visOptions || {};
+	const stats = {
+		globalMaxCategoryCount: featureCollection.properties?.globalMaxCategoryCount ?? 0,
+		globalTotalCount: featureCollection.properties?.globalTotalCount ?? 0
+	};
+
+	activeMap = map;
+	cachedContext = { featureCollection, palette, visOptions, stats };
+
+	const rendered = renderPieLayer({ fitBounds: true });
+	if (!rendered) {
+		return {};
+	}
+
+	attachZoomHandler(map);
+
+	return { pieCharts: layerGroup };
+}
+

package/visualizer/voronoi/node.js

@@ -226,13 +226,69 @@ function warnHexNotRendered(hexId, reason, extra = {}) {
     console.warn(`[VoronoiVisualizer] Skipped hex ${hexId}: ${reason}${details}`);
 }
 
+function computeLocalCategoryDensityScores(features = [], minMeters = 0) {
+    const scores = new Map();
+    if (!Number.isFinite(minMeters) || minMeters <= 0) {
+        for (const feature of features) {
+            scores.set(feature, 0);
+        }
+        return scores;
+    }
+
+    const points = features.map(feature => {
+        const coords = feature?.geometry?.coordinates;
+        return Array.isArray(coords) ? turfPoint(coords) : null;
+    });
+
+    for (let i = 0; i < features.length; i++) {
+        const feature = features[i];
+        const category = feature?.properties?.category;
+        const point = points[i];
+        if (!category || !point) {
+            scores.set(feature, 0);
+            continue;
+        }
+
+        let density = 0;
+        for (let j = 0; j < features.length; j++) {
+            if (i === j) continue;
+            const other = features[j];
+            if (other?.properties?.category !== category) continue;
+            const otherPoint = points[j];
+            if (!otherPoint) continue;
+            const dist = turfDistance(point, otherPoint, { units: 'meters' });
+            if (!Number.isFinite(dist)) continue;
+            if (dist <= minMeters) {
+                density++;
+            }
+        }
+
+        scores.set(feature, density);
+    }
+
+    return scores;
+}
+
 function enforceMinSpacing(features = [], minMeters = 0) {
     if (!Number.isFinite(minMeters) || minMeters <= 0) {
         return features;
     }
 
+    const localDensityScores = computeLocalCategoryDensityScores(features, minMeters);
+
+    const prioritized = [...features].sort((a, b) => {
+        const scoreA = localDensityScores.get(a) ?? 0;
+        const scoreB = localDensityScores.get(b) ?? 0;
+        if (scoreA !== scoreB) {
+            return scoreB - scoreA;
+        }
+        const orderA = a?.properties?.__voronoiOrder ?? 0;
+        const orderB = b?.properties?.__voronoiOrder ?? 0;
+        return orderA - orderB;
+    });
+
     const accepted = [];
-    for (const feature of features) {
+    for (const feature of prioritized) {
         const coords = feature?.geometry?.coordinates;
         if (!Array.isArray(coords)) continue;
         const candidatePoint = turfPoint(coords);
@@ -263,15 +319,12 @@ function aggregateGeotagsByHex(result = {}, maxSitesPerHex = 0, minSpacingMeters
         if (!categories) continue;
 
         const aggregatedFeatures = [];
-        const categoryBreakdown = {};
         let featureOrder = 0;
 
         for (const [categoryName, payload] of Object.entries(categories)) {
             const features = payload?.items?.features ?? [];
             if (!features.length) continue;
 
-            categoryBreakdown[categoryName] = (categoryBreakdown[categoryName] ?? 0) + features.length;
-
             for (const feature of features) {
                 const cloned = cloneFeature(feature);
                 const coords = Array.isArray(cloned?.geometry?.coordinates) ? cloned.geometry.coordinates : [];