메뉴
Best practices and procedural guidelines for designing high-performance, reactive, and visually stunning map visualizations with Deck.gl and Google Maps.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/googlemaps-samples/insights-samples --skill rmi-dataviz명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SKILL.md 표시 중
| name | rmi-dataviz |
| description | Best practices and procedural guidelines for designing high-performance, reactive, and visually stunning map visualizations with Deck.gl and Google Maps. |
This skill provides expert knowledge and guidelines for developing premium, responsive, and robust geospatial visualizations using Deck.gl, Google Maps Platform, and various geospatial formats.
To deliver high-impact, premium user experiences, always avoid browser-default colors and simple styling. Use curated, high-contrast palette configurations suited for dark-mode data operations:
Obsidian / Dark Themes: Base map background should be ultra-dark (#080c14). Roads and boundaries should use neon or bright, glowing colors (emerald green, cyber cyan, amber yellow, rose red) with high opacity.
Discrete Color Schemes:
CONTROLLED_ACCESS: Purple ([168, 85, 247, 255])LIMITED_ACCESS: Orange ([249, 115, 22, 255])PRIMARY_HIGHWAY: Rose Red ([244, 63, 94, 255])SECONDARY_ROAD: Amber ([234, 179, 8, 255])MAJOR_ARTERIAL: Sky Blue ([14, 165, 233, 255])MINOR_ARTERIAL: Indigo ([99, 102, 241, 255])LOCAL: Emerald Green ([34, 197, 94, 255])TERMINAL: Slate Gray ([100, 116, 139, 255])Line Caps and Corners (Rounded Paths): To give line layers (e.g. paths, roads, track segments, and incident vectors) a premium, fluid appearance, always style them with rounded line joints and caps.
GeoJsonLayer is a composite layer containing sublayers (such as PathLayer), setting properties like capRounded: true or jointRounded: true directly on the GeoJsonLayer configuration will NOT be forwarded to the underlying line sublayer.lineJointRounded: true (for rounded corners)lineCapRounded: true (for rounded ends)Deck.gl optimizes render loops by performing shallow comparison checks on elements inside the updateTriggers object. If parent object references are mutated or shallow-copied, deep changes inside nested properties (such as checking/unchecking checkboxes in a filter sub-array) may not trigger visual attribute re-evaluations.
Always serialize complex objects inside updateTriggers using JSON.stringify(). This turns reference-based comparisons into value-based string comparisons, guaranteeing immediate and flawless rendering updates on user interaction.
return new GeoJsonLayer({
id: layer.id,
data: layer.geojson,
getLineColor: (f) => getLineColorForFeature(f, template, filters),
updateTriggers: {
// Stringify the filters object so any key/value changes trigger updates instantly
getLineColor: [opacity, template, JSON.stringify(filters || {})],
getFillColor: [opacity, template, JSON.stringify(filters || {})]
}
});
When working with local user uploads, always build light, dependency-free browser-side parsers to maintain application performance and code security.
Split the input file stream on newline boundaries, trim whitespace, and parse individual lines to construct a standard FeatureCollection:
function parseGeoJSONLToGeoJSON(textContent) {
const lines = textContent.split(/\r?\n/);
const features = [];
for (const line of lines) {
if (line.trim()) {
try {
features.push(JSON.parse(line));
} catch (e) {
console.warn("Skipping invalid JSONL line:", e);
}
}
}
return { type: "FeatureCollection", features };
}
Leverage browser-native DOMParser to parse the KML XML schema, find <Placemark> nodes, and map <Point>, <LineString>, or <Polygon> coordinates to standard GeoJSON equivalents.
Implement clean, robust regex-based matchers to transform standard coordinate lists into structured GeoJSON arrays.
When dealing with historical temporal datasets (like vehicle counts or hourly traffic disruptions), utilize the 3D extrusion capabilities of WebGL to stack features vertically:
extruded: true and translate timestamps/hours into elevation values (e.g. 10 or 20 meters per hour block).z offsets so stacked blocks align seamlessly without clipping.unpacked_segment_id) rather than the route identifier (selected_route_id / road_segment_id).
When rendering dual-direction roads, multi-lane telemetry, or overlaying direction-specific indicators, paths must be shifted laterally to represent the correct driving side of the road (Left-Hand Traffic vs. Right-Hand Traffic) and prevent overlapping overlap anomalies.
Deck.gl provides PathStyleExtension({ offset: true }) for GPU vertex shader offsets. However, in complex GIS applications with companion layers (e.g. directional arrowheads, start/end point circles, extruded 3D ribbons), PathStyleExtension creates severe visual desynchronization:
PathStyleExtension calculates offset as getOffset * getWidth. If a road line has a base width of 1 meter or 2 pixels, the shader only shifts it by a tiny fraction (e.g. $0.6\text{ m}$).ScatterplotLayer (start dots) or extruded GeoJsonLayer (3D ribbons) cannot use PathStyleExtension. If they are analytically offset in meters (e.g. $2.5\text{ m}$), arrows and markers will visibly decouple and float far off the road corridor into sidewalks or buildings.PathStyleExtension on certain composite layer setups can trigger luma.gl: Binding pathStyleUniforms not set: Not found in shader layout. warnings.For guaranteed pixel-perfect and meter-accurate alignment across all composite sublayers, perform a unified analytical coordinate offset (typically $1.5\text{ m}$ to $2.0\text{ m}$, representing half a standard lane width) at the geometry preparation layer:
/**
* Safely offsets a LineString or Feature<LineString> laterally in meters.
* Positive distance offsets to the right of travel direction, negative to the left.
*/
function offsetLine(
geomOrFeature: geojson.LineString | geojson.Feature<geojson.LineString>,
offsetDistanceMeters: number
): geojson.Feature<geojson.LineString> {
if (!geomOrFeature || offsetDistanceMeters === 0) {
return geomOrFeature.type === 'Feature' ? geomOrFeature : turf.lineString(geomOrFeature.coordinates);
}
try {
const feat = geomOrFeature.type === 'Feature' ? geomOrFeature : turf.lineString(geomOrFeature.coordinates);
const offset = turf.lineOffset(feat, offsetDistanceMeters, { units: 'meters' });
if (offset?.geometry?.coordinates?.length >= 2) {
return offset;
}
} catch (e) {
console.warn("offsetLine failed, falling back to original geometry:", e);
}
return geomOrFeature.type === 'Feature' ? geomOrFeature : turf.lineString(geomOrFeature.coordinates);
}
PathLayer): Pass offsetLine(line, isLeftHandTraffic ? -1.5 : 1.5) into getPath.PathLayer): Derive arrow vectors from the same offset line geometry via turf.along.ScatterplotLayer): Anchor marker positions directly on the same offset line.RecentTrafficLayer): Offset 2D coordinates by $\pm 1.5\text{ m}$ before mapping vertical elevation ($Z = \text{minutes} \times 1.5$).RouteDeviationLayer): Apply offsetLine before turf.buffer(), generating perfectly separated, non-colliding parallel 3D extruded volume walls.When Turf.js is unavailable, calculate lateral coordinates manually in meters and project them back into degrees.
Given a segment from p1 to p2:
When streaming vector tiles from secure cloud buckets (like Google Cloud Storage), standard client decoders must be optimized to prevent browser throttling, authentication failures, or redundant network roundtrips.
Extend standard source loaders to parse gs:// URIs, dynamically inject OAuth2 bearer tokens, and issue HTTP range headers:
async function getBytes(offset, length) {
const url = translateGcsUrl(this.gcsPath); // gs://bucket/file.pmtiles -> storage.googleapis.com
const headers = {
Range: `bytes=${offset}-${offset + length - 1}`
};
if (accessToken) {
headers["Authorization"] = `Bearer ${accessToken}`;
}
const res = await fetch(url, { headers });
return { data: await res.arrayBuffer() };
}
Deck.gl's default configurations are designed for generic tile services. For complex GIS layers (e.g., dense road network grids), enforce these performance configurations:
maxRequests: 20: Increase the concurrent request pool from the browser-default limit of 6 to 20. This allows highly parallelized tile downloading and parsing, significantly reducing initial render lag during zoom changes.maxCacheSize: 100: Raise the internal parsed-tile memory cache size to 100. This caches previously loaded tiles and ensures instant pan-back and zoom-out hits without making repetitive GCS network range requests.Temporal map visualizations (such as hourly traffic density, congestion hotspots, or incident distributions) represent localized human behaviors. Displaying them in raw UTC coordinates dilutes morning/evening rush-hour patterns. Geometries must be sliced according to their exact regional timezone.
To map UTC events back to local-time bins dynamically, query the coordinates of the tile center or active viewport against the Google Time Zone API: $$\text{localTimestamp} = \text{utcTimestamp} + \text{rawOffset} + \text{dstOffset}$$
Store the resolved tz_offset directly into feature properties at the decoder layer, letting style templates compute active hourly filters reactively:
const localDate = new Date(utcDate.getTime() + tzOffset * 1000);
feature.properties.local_hour = localDate.getUTCHours();
feature.properties.tz_offset = tzOffset;
This enables filters to slice datasets dynamically (e.g., matching features where f.properties.local_hour === selectedHour) regardless of which global region is currently being visualized.
Direct HTTP fetch calls to the Google Maps Time Zone API (timezone-backend.googleapis.com) will return a REQUEST_DENIED status if executed with an API key restricted strictly to client-side Maps SDKs (maps-backend.googleapis.com).
To prevent runtime blockages:
TIMEZONE_API_KEY or generalized API_KEY) configured with the correct API permissions for back-end or direct web timezone queries.c.start_time), using a strict exact matching window (such as Math.abs(d.getTime() - targetUTC) < 10000) is highly brittle.Asia/Kolkata at UTC+5:30, or Asia/Kabul at UTC+4:30), local hourly milestones (1:00, 2:00, etc.) map to exact :30 (or :45) minute marks in UTC. Since database hourly buckets are typically stored strictly at the top of the hour (:00 minutes in UTC), this creates a constant 30-to-45-minute offset, causing strict matchers to fail entirely and render flat baseline/fallback metrics (e.g., zero vehicle counts or dark blue overlays).let matchedCount = null;
let minDiff = 3600000; // 1 hour max search radius
counts.forEach((c) => {
const d = parseStartTime(c.start_time);
if (d) {
const diff = Math.abs(d.getTime() - targetUTC);
if (diff < minDiff) {
minDiff = diff;
matchedCount = c;
}
}
});
When blending native Google Maps UI controls (such as the Pegman or Fullscreen toggle) with bespoke custom HTML control panels, dynamic renderer race conditions and container alignment gaps can occur.
Google Maps dynamically measures and computes bounds for its native widgets as the basemap fully loads. If a custom HTML panel is pushed into the map's controls array during initial map constructor initialization, native elements and custom elements can collide. This causes native buttons to push custom containers upwards, creating unintended layout stacking and gaping.
Wait for the map's 'idle' event to trigger, and then defer the custom control registration with a small setTimeout delay (~300ms). This guarantees that Google Maps has completed its native layout passes first, allowing the custom control panel to dock cleanly at the absolute bottom of the layout stack.
map.addListener("idle", () => {
if (!loggerInjected) {
setTimeout(() => {
map.controls[google.maps.ControlPosition.INLINE_END_BLOCK_END].push(loggerElement);
loggerInjected = true;
}, 300);
}
});
Google Maps natively reserves a bottom margin (~15-20px) on control containers in bottom-right/left quadrants to clear the default Google logo, terms, and copyright lines. For a premium, full-bleed dashboard feel, custom panels can be dropped completely flush to the bottom edge.
Override Google Maps' default layout constraints by using !important to force-clear the bottom margins of your container when expanded:
.custom-bottom-panel {
margin: 0px 10px 0px 0px !important; /* Force margin-bottom to 0px */
}
Explicitly disabling unneeded basemap controls reduces interface clutter and draws immediate user focus to custom interaction controls:
const map = new google.maps.Map(element, {
// Disable defaults to maximize visualization real estate
zoomControl: false,
rotateControl: false,
tiltControl: false,
cameraControl: false
});
When presenting tooltips, event logs, or date indicators, all "local" times displayed on-screen must reflect the geographical local timezone of the geographical point currently centered in the map viewport, rather than the visitor's local browser/device timezone.
currentMapCenterTimezone) initialized with a fallback timezone.idle event, detect the center coordinates, resolve the current country or timezone offset, and update the state variable.Intl.DateTimeFormat with a neutral, globally recognized, and readable format (such as Sweden's "sv-SE" locale) to represent the local time as YYYY-MM-DD HH:mm:ss:export function formatLocalTime(date, timeZone) {
try {
return new Intl.DateTimeFormat("sv-SE", {
dateStyle: "short",
timeStyle: "medium",
timeZone: timeZone,
}).format(date);
} catch (err) {
// Fall back to standard UTC representation if timezone is invalid
return date.toUTCString();
}
}
Real-time EventSource/Server-Sent Events (SSE) data streams are subject to intermittent network drops. When an EventSource automatically reconnects, the backend database frequently re-broadcasts a full-snapshot data dump (such as a root / path payload). This dump can "resurrect" faded features on the client side, causing flickering, duplicate enter-animations, or logging noise.
rtdbFeaturesState) that persists independently of connection state.life) of incoming features. If an incoming feature is already marked as faded out or deleted, reject re-animation.function clearRealtimeLayer(layerId) {
const listener = activeRtdbListeners.get(layerId);
if (listener) {
listener.stop();
activeRtdbListeners.delete(layerId);
}
rtdbFeaturesState.clear(); // Free up memory
}
When integrating Deck.gl with the Google Maps JavaScript API (specifically using the Vector Map capability via WebGL2), always prefer interleaved rendering to achieve perfect desynchronization-free drawing during map movement.
Set interleaved: true on the GoogleMapsOverlay constructor. This integrates Deck.gl directly into the Google Maps WebGL2 vector render loop:
const overlay = new GoogleMapsOverlay({
interleaved: true,
layers: [...]
});
overlay.setMap(map);
In older deck.gl versions, interleaving could cause stencil, blend, or depth-testing state contamination (e.g. flickering, "Hung Labeler" errors, or broken label rendering). In deck.gl v9, the WebGL state save-and-restore hygiene is extremely robust, making interleaved: true safe and highly recommended for production vector overlays.
When rendering paths or features utilizing physical real-world measurements (e.g., lineWidthUnits: "meters" with a width of $1.0\text{m}$ to $2.0\text{m}$) and applying lateral lane shifts (offsets of $\pm0.6\text{m}$), paths appear extremely narrow at low-to-mid zoom levels.
For any layer or style template using real-world physical dimensions (like "Road Priority" or lanes configuration), always default to 100% (1.0) opacity. Lower opacity values cause fine lines to blend aggressively with the base map, rendering the paths faded or invisible.
Ensure that when a user switches style templates to a physical meters-scale representation, the application reactively sets or overrides the layer's opacity to 1.0. Add opacity and the selected template name to the layer's updateTriggers array to force the GPU to re-evaluate the colors instantly.
When binding database rows dynamically to client-side overlays (such as viewport-based BigQuery datasets), there is a strong architectural dependency between the SQL query structure and the map's interactive elements (e.g. hover tooltips or click callbacks).
queryTemplate or function select statement) will NOT be populated in the feature's properties map on the client.When building custom floating controls (such as file drag-and-drop targets, diagnostic log triggers, or layer presets) on top of a Google Maps Canvas, avoid absolute viewport offsets or CSS floats. These are prone to overlap during window resize events and clash with standard browser container layouts.
Leverage Google Maps' built-in control stacking layers. This registers elements directly into the native map overlay grid, handling resizing, standard margins, and Z-index layering out-of-the-box:
// Register your element as a native map control
map.controls[google.maps.ControlPosition.TOP_RIGHT].push(floatingDropZoneElement);
Using native control layouts like TOP_RIGHT or RIGHT_TOP aligns your custom tool beautifully alongside standard Maps buttons (like Fullscreen, Zoom, and Street View).
Bulkier rectangular widgets consume valuable viewport space. For drag-and-drop file import zones, prefer an ultra-sleek, circular button template with dynamic, visual-only emojis indicating load states:
40px to 50px diameter glassmorphic circle with a dashed border.transform: scale(1.15); transition: transform 0.2s ease-out;).📥 (Import)⏳ (Parsing file)✅ (Loaded successfully)❌ (Failed to parse)To enable seamless multi-environment or multi-project switching without redeploying frontend assets, support parameter injection via the URL query string.
On load, parse standard URL parameters (e.g. project_id, layer_id) to override default application variables:
const urlParams = new URLSearchParams(window.location.search);
const projectId = urlParams.get("project_id") || "default-project-id";
Always ensure crucial configuration overrides (like the active Cloud Project ID) are clearly displayed in high-visibility elements, such as the title bar of control panels, to prevent confusion when working across multiple projects:
const projectDisplay = document.getElementById("project-id-display");
if (projectDisplay) {
projectDisplay.textContent = projectId;
}
In complex map applications, the vertical stacking order of layers dictates visual legibility (e.g., placing lines on top of polygons).
0 at the top, index n at the bottom).layers array are rendered from bottom to top (first item in the array is drawn first/underneath, last item in the array is drawn last/on top of everything else).Render compact ▲ (Up) and ▼ (Down) icons on layer cards, disabling them dynamically at boundaries (index 0 cannot move up, index n-1 cannot move down):
if (idx === 0) {
upBtn.style.pointerEvents = "none";
upBtn.style.opacity = "0.15";
}
Always stop event propagation on reordering click events (e.stopPropagation()) to prevent triggering card expand/collapse accordions or detail panel toggles. After swapping indices inside the primary layer array, trigger both the sidebar UI redraw and the Deck.gl overlay redraw immediately to reflect changes.
When visualizing overlapping concentric polygons (such as drive-time isochrones of 10m, 20m, 30m, 40m, 50m, and 60m), rendering order is critical. If larger outer polygons are drawn on top of smaller inner polygons, the larger solid or semi-transparent fills will completely cover and mask the smaller ones underneath, leading to a "solid fill" visual glitch where inner colors are invisible.
GeoJsonLayer buffers) frequently iterate and draw features in reverse index order (from index length-1 down to 0).a - b) ensures that:
Standard Google Maps custom marker layers and WebGL canvas layers (such as interleaved Deck.gl layers) can fight for layout dominance on the map context, occasionally burying spatial center anchors under semi-transparent data fills.
zIndex parameter on standard google.maps.Marker or AdvancedMarkerElement configurations to elevate them above raw canvas drawing pipelines:const centerMarker = new google.maps.Marker({
map: map,
position: anchorLatLng,
zIndex: 9999, // Explicitly float atop interleaved WebGL data contexts
icon: { ... }
});
When presenting high-intensity neon geospatial overlays (like isochrones or traffic bottleneck segments), standard dark base maps are too busy and cluttered with labels, POI markers, and transit lines, which compete with the target data for visual dominance.
Always apply a custom, ultra-minimalist dark JSON stylesheet to eliminate information noise and enhance data contrast:
#12131a).#090a10).featureType: "poi", stylers: [{ visibility: "off" }]), transit lines (featureType: "transit", stylers: [{ visibility: "off" }]), and all street labels.#1c1e2b) and highways in slightly higher-contrast slate (#2d3247), omitting names. This transforms the map background into a clean, low-intensity circuit-board grid.#4f5a6b) with a dark stroke outline (#12131a).To balance instant spatial response times with zero-staleness real-time accuracy:
ST_INTERSECTS) querying across global bounding boxes with zero REST quota usage.idle event). Scope live API queries strictly to explicit user checkbox toggles (visible: true), fetching live features once for the viewport active at that exact moment to conserve network bandwidth and browser memory.When building analytical geospatial dashboards and map tools (such as route setting or corridor inspection consoles), map UI elements must provide clear visual hierarchy, quick copyability of resource identifiers, and self-documenting action triggers.
roads/ChIJ-bfSMGoZ... or routes/12345) are lengthy, hard to read, and awkward to select manually from standard text elements without accidental whitespace inclusion.text-overflow: ellipsis and set user-select: all.navigator.clipboard.writeText(resourceName).content_copy to check for 1500ms.unfold_more vs compare_arrows vs merge_type vs alt_route).md-filled-tonal-button, md-outlined-button):
TRACKING: Primary tonal button (+ Track Road) and secondary outlined button (Untrack).NETWORK STRETCH: Clearly labeled directional actions (Stretch 1-Way, Stretch 2-Way).ROUTE MANAGEMENT / ANALYTICS: Clear triggers for lifecycle mutations (Retrack, Hide Layer) and analytics workflows (Recent Traffic, History)..gm-style-iw-c), rigid padding, and unstyled multi-feature category headers.border-radius: 16px !important; and soft drop shadows box-shadow: 0 8px 28px rgba(0,0,0,0.18) !important; on .gm-style-iw-c.FeatureClass and render styled category headers (<md-icon>, category title, and pill count badge).GROUP ACTIONS blocks for bulk multi-feature operations (Track All, Track 2-Way Stretch).border-radius: 24px) with leading category icons (alt_route / route), subtle border outlines, and smooth focus-within drop shadows.#f8f9fa uppercase headers and 12px rounded container frames.interleaved: true on GoogleMapsOverlay for modern deck.gl v9 deployments.1.0 (100%) opacity as the baseline default for meters-scale styling templates.map.controls[google.maps.ControlPosition.TOP_RIGHT] or RIGHT_TOP to integrate seamlessly with native resizing and controls.📥 ➔ ⏳ ➔ ✅ / ❌) for intuitive, visual-only feedback.project_id) via URL search parameters, and display active values in high-visibility elements like the sidebar control panel title.0 and length - 1, stop event propagation, and run full UI and WebGL redraw triggers sequentially.a - b) to align with WebGL reverse draw directions and avoid masking smaller overlays.zIndex: 9999 on standard marker overlays to keep anchors floating above interleaved WebGL contexts.roads/..., routes/...) into monospace containers with 1-click clipboard copying and timeout checkmark confirmation.