Splatone - Multi-layer Composite Heatmap

Japanese README | Example results

Splatone is an open-source Node.js platform for collecting, normalizing, and visualizing category-aware geospatial data. It supports geotagged photographs, social media-style records, and points of interest from multiple sources, then displays their thematic spatial distributions on an interactive map.

Splatone is built around two independent plugin types:

• Providers collect data from external services and convert heterogeneous responses into a common GeoJSON-based model.
• Visualizers render the collected data as point maps, marker clusters, heatmaps, hexagonal summaries, pie charts, Voronoi diagrams, or DBSCAN-based cluster boundaries.

This architecture makes it possible to add new data sources or analytical views without modifying the core crawling and browsing pipeline.

Supported Providers

• Flickr (-p flickr): collects geotagged Flickr photographs.
• Google Places Text Search (-p gmap): collects point-of-interest records from the Google Places API.
• OpenStreetMap / Overpass API (-p overpass): collects OpenStreetMap POIs through Overpass queries.

Supported Visualizers

• Bulky (--vis-bulky): plots every collected point on the map.
• Marker Cluster (--vis-marker-cluster): groups dense points into interactive clusters.
• Heat (--vis-heat): renders a continuous heatmap from point density.
• Majority Hex (--vis-majority-hex): colors each hexagonal cell by its dominant category.
• Pie Charts (--vis-pie-charts): draws category-ratio pie charts at hex-cell centers.
• Voronoi (--vis-voronoi): creates clipped Voronoi cells from points aggregated by hex grid.
• DBSCAN (--vis-dbscan): renders category clusters as KDE contour polygons.

Requirements

Install Node.js before running Splatone. The examples below use npx, so Splatone can be installed and executed with a single command.

Quick Start

The following command collects Flickr photographs related to canals, streets, and bridges, then visualizes them with the Bulky visualizer:

npx -y -p splatone@latest crawler -p flickr -k "canal,river,sea|street,alley|bridge" --vis-bulky --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

When the browser map opens, draw a rectangle or polygon over the target area and click Start Crawling.

If the target city is already known, use --city to set the initial map position:

npx -y -p splatone@latest crawler -p flickr -k "pizza#FA0000=pizza|piazza#2B89EE=piazza" --vis-bulky --city "Napoli" --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Browse Mode

Browse mode displays previously exported Splatone result files without crawling again.

npx -y -p splatone@latest browse

You can drag and drop a result*.json file generated by crawler into the browser window. The map is redrawn immediately, and the command that generated the result is shown in the command panel.

Splatone can also load a result JSON file directly from a URL:

npx -y -p splatone@latest browse \
  --browse-load-url="https://raw.githubusercontent.com/YokoyamaLab/Splatone/refs/heads/main/examples/tower-bulky.json"

Provider Plugins

Flickr

The Flickr provider collects geotagged photographs from Flickr.

npx -y -p splatone@latest crawler -p flickr -k "sea,ocean|mountain,mount" --vis-bulky --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--p-flickr-APIKEY	Flickr API key.	string
--p-flickr-Extras	Comma-separated metadata fields to keep.	string	date_upload,date_taken,owner_name,geo,url_sq,tags
--p-flickr-DateMode	Date axis used for collection: upload date or taken date.	upload or taken	taken
--p-flickr-Haste	Enables parallelized date-range crawling.	boolean	true
--p-flickr-GimmeGimme	Directory where downloaded image files are saved. When omitted, images are not downloaded.	string
--p-flickr-DateMax	Maximum crawl date as UNIX time or YYYY-MM-DD.	string	current time
--p-flickr-DateMin	Minimum crawl date as UNIX time or YYYY-MM-DD.	string	1072882800
--p-flickr-ThrottleMaxConcurrent	Maximum number of concurrent Flickr API requests.	number	2
--p-flickr-ThrottleMinTimeMs	Minimum interval between Flickr requests in milliseconds.	number	500

With --p-flickr-GimmeGimme=PATH, Splatone downloads image files to the given directory. If image URL extras such as url_sq, url_m, url_l, or url_o are included, the highest available requested size is saved. File names include category, latitude, longitude, capture time, owner, ID, and size.

Google Places Text Search

The Google Places provider collects POIs from the Google Places Text Search API.

npx -y -p splatone@latest crawler -p gmap -k "Cafe=cafe tokyo|Landmark=landmark tokyo" --vis-bulky --city "Tokyo" --p-gmap-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--p-gmap-APIKEY	Google Places API key. If omitted, Splatone reads .API_KEY.gmap or API_KEY_gmap.	string
--p-gmap-Language	language parameter for the Places API.	string	ja
--p-gmap-MaxPages	Maximum Text Search pages, from 1 to 3.	number	3
--p-gmap-ThrottleMaxConcurrent	Maximum number of concurrent Google Places requests.	number	2
--p-gmap-ThrottleMinTimeMs	Minimum interval between Places requests in milliseconds.	number	500

Splatone sends each category query for each hexagonal cell. The query radius is derived from the UI cell size, capped at 50 km, and each request is constrained by the target cell bounding box.

OpenStreetMap / Overpass

The Overpass provider collects OpenStreetMap nodes, ways, and relations that match tag conditions.

npx -y -p splatone@latest crawler -p overpass -k "Cafe#ff5f5f=amenity=cafe,amenity=coffee_shop|Culture#3366ff=tourism=museum,tourism=gallery" --vis-bulky --city "Kyoto"

Option	Description	Type	Default
--p-overpass-Endpoint	Overpass API interpreter endpoint.	string	https://overpass-api.de/api/interpreter
--p-overpass-TimeoutSeconds	Timeout per Overpass request in seconds.	number	25
--p-overpass-MaxRetries	Maximum retry count for HTTP or network errors.	number	3
--p-overpass-UserAgent	User-Agent sent to Overpass. A contact URL or email is recommended.	string	Splatone-Overpass (+https://github.com/YokoyamaLab/Splatone)
--p-overpass-ThrottleMaxConcurrent	Maximum concurrent Overpass requests.	number	1
--p-overpass-ThrottleMinTimeMs	Minimum interval between Overpass requests in milliseconds.	number	1500

Tag conditions usually use key=value, such as amenity=restaurant. Multiple conditions can be separated with , for OR searches. Prefixes such as node:amenity=cafe, way:building=yes, or relation:tourism=museum restrict the geometry type.

Visualizer Plugins

Bulky

Bulky displays every collected point as a marker. For Flickr data, clicking a marker opens the corresponding Flickr photo page.

npx -y -p splatone@latest crawler -p flickr -k "sea,ocean|mountain,mount" --vis-bulky --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-bulky-Radius	Point marker radius.	number	5
--v-bulky-Stroke	Enables marker stroke.	boolean	true
--v-bulky-Weight	Marker stroke width.	number	1
--v-bulky-Opacity	Marker stroke opacity.	number	1
--v-bulky-Filling	Enables marker fill.	boolean	true
--v-bulky-FillOpacity	Marker fill opacity.	number	0.5

Marker Cluster

Marker Cluster groups dense point sets into cluster markers. Clusters expand automatically as the user zooms in.

npx -y -p splatone@latest crawler -p flickr -k "water=canal,river,sea|bridge=bridge|street=street,road,alley" --vis-marker-cluster --vis-bulky --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-marker-cluster-MaxClusterRadius	Radius used to form marker clusters.	number	80

Heat

Heat renders a continuous heatmap based on point density.

npx -y -p splatone@latest crawler -p flickr -k "Water#0947ff=canal,river,sea|Transport#00a73d=road,street,bridge|Religion#ffb724=chapel,church,temple,shrine" --vis-heat --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-heat-Radius	Heatmap blur radius in the selected distance unit.	number	50
--v-heat-Units	Distance unit for the radius.	string	meters
--v-heat-MinOpacity	Minimum heatmap opacity.	number	0
--v-heat-MaxOpacity	Maximum heatmap opacity.	number	1
--v-heat-MaxValue	Maximum heatmap intensity. If omitted, Splatone estimates it from the data.	number
--v-heat-WeightThreshold	Points with fewer neighboring points than this threshold are not drawn.	number	1

Majority Hex

Majority Hex aggregates points into a hexagonal grid and colors each cell by the most frequent category inside it.

npx -y -p splatone@latest crawler -p flickr -k "Water=canal,river,sea|Green=forest,woods,trees|Transport=bridge,street,road|Landmark=church,temple,museum" --vis-majority-hex --v-majority-hex-Hexapartite --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-majority-hex-Hexapartite	Splits each hex cell into six colored parts according to category frequency.	boolean	false
--v-majority-hex-HexOpacity	Hex border opacity.	number	1
--v-majority-hex-HexWeight	Hex border width.	number	1
--v-majority-hex-MaxOpacity	Maximum normalized fill opacity.	number	0.9
--v-majority-hex-MinOpacity	Minimum normalized fill opacity.	number	0.5

Pie Charts

Pie Charts draws category-ratio pie charts at hex-cell centers. Slice angle represents the category ratio in each cell, and slice radius reflects the global occurrence scale of each category.

npx -y -p splatone@latest crawler -p flickr -k "Water#0947ff=canal,river,sea|Transport#aaaaaa=road,street,bridge|Religion#ffb724=chapel,church,temple,shrine|Green#00a73d=forest,woods,trees,garden" --vis-pie-charts --v-pie-charts-MaxRadiusScale=0.9 --v-pie-charts-MinRadiusScale=0.4 --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-pie-charts-MaxRadiusScale	Maximum pie radius as a ratio of the hex incircle radius.	number	0.9
--v-pie-charts-MinRadiusScale	Minimum radius ratio relative to the maximum radius.	number	0.25
--v-pie-charts-StrokeWidth	Pie outline and slice border width in pixels.	number	1
--v-pie-charts-BackgroundOpacity	Opacity of the maximum-radius guide ring.	number	0.2

Voronoi

Voronoi creates Voronoi cells from geotagged points aggregated by hex grid, then clips the cells by the corresponding hex polygons. This keeps dense areas readable while preserving local category structure.

npx -y -p splatone@latest crawler -p flickr -k "Water#0947ff=canal,river,sea|Transport#aaaaaa=road,street,bridge|Religion#ffb724=chapel,church,temple,shrine|Green#00a73d=forest,woods,trees,garden" --vis-voronoi --v-voronoi-MinSiteSpacingMeters=50 --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-voronoi-MaxSitesPerHex	Maximum number of sites kept per hex cell. 0 disables the limit.	number	0
--v-voronoi-MinSiteSpacingMeters	Minimum distance between retained sites in meters.	number	50

MinSiteSpacingMeters reduces overplotting by keeping spatially separated sites. Setting it to 0 uses the full point set, but large datasets may require a larger Node.js heap.

DBSCAN

DBSCAN clusters hex-aggregated points by category, estimates a kernel density surface inside each cluster, and extracts contour polygons. Use it together with Bulky when both cluster boundaries and original points should be visible.

npx -y -p splatone@latest crawler -p flickr -k "Water#0947ff=canal,river,sea|Transport#aaaaaa=road,street,bridge|Religion#ffb724=chapel,church,temple,shrine|Green#00a73d=forest,woods,trees,garden" --vis-dbscan --v-dbscan-Eps=0.25 --v-dbscan-MinPts=4 --v-dbscan-KernelScale=0.4 --v-dbscan-GridSize=30 --v-dbscan-ContourPercent=0.05 --vis-bulky --p-flickr-APIKEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Option	Description	Type	Default
--v-dbscan-Eps	DBSCAN epsilon radius using the selected distance unit.	number	0.6
--v-dbscan-MinPts	Minimum number of points required to form a cluster.	number	6
--v-dbscan-Units	Distance unit for epsilon.	string	kilometers
--v-dbscan-StrokeWidth	Cluster polygon outline width.	number	2
--v-dbscan-StrokeOpacity	Cluster polygon outline opacity.	number	0.9
--v-dbscan-FillOpacity	Cluster polygon fill opacity.	number	0.35
--v-dbscan-DashArray	Leaflet dash pattern. Empty string means solid line.	string
--v-dbscan-KernelScale	KDE kernel radius as a multiplier of epsilon.	number	1
--v-dbscan-GridSize	Number of cells on the longer side of the KDE grid.	number	80
--v-dbscan-ContourPercent	Contour threshold as a ratio of the maximum density.	number	0.4

Keywords, Categories, and Colors

Keywords are passed with -k or --keywords.

Use | to compare multiple categories:

-k "sea|mountain"

Use , to group synonymous terms within one category:

-k "sea,ocean|mountain,mount"

Use category=keywords to assign category names:

-k "Water=sea,ocean|Mountain=mountain,mount"

Use category#RRGGBB=keywords to assign colors:

-k "Water#037dfc=sea,ocean|Mountain#7fc266=mountain,mount"

Color Palette Utility

Splatone includes a small palette utility:

npx -y -p splatone@latest color <count> <sets>

For example, generate three sets of six colors:

npx -y -p splatone@latest color 6 3

The browser preview lets you inspect and adjust colors. Click a color code to copy it.

Use --no-ansi to print a plain comma-separated HEX list:

npx -y -p splatone@latest color --no-ansi 6 3

API Keys

Provider API keys can be supplied in three ways:

• Pass the key as a command-line option, such as --p-flickr-APIKEY="...".
• Store the key in an environment variable named API_KEY_<provider>, such as API_KEY_flickr.
• Store the key in a local file named .API_KEY.<provider> in the project root, such as .API_KEY.flickr.

Do not share commands that contain raw API keys.

Exporting Results

Use the image-download icon in the lower-right corner of the browser UI to export the current map as a PNG image. The exported image does not include the legend.

Use the export button below the legend to download visualization data. Each selected visualizer is exported as a GeoJSON FeatureCollection. If the raw crawled points are needed, include a simple point visualizer such as Bulky.

Change Log

Recent updates include:

• Google Places Text Search provider (-p gmap).
• OpenStreetMap / Overpass provider (-p overpass).
• Browse mode for loading result files from local files or URLs.
• DBSCAN visualizer for cluster-boundary visualization.
• Browser-based color palette preview and adjustment.

See CHANGELOG.md for older changes.