GeoLocatorExplorer

A playful, data-rich explorer for bird migration. Spin the globe, dive into projects, and track individual tags with a cinematic 3D bird view.

This visualization tool shows all Geolocator studies submitted to the Geolocator DP Zenodo community and following the standardized format GeoLocator Data Package (GeoLocator DP).

Raw data source

The raw_data/ folder is the source used to build the frontend data assets.
It consists of a snapshot from Zenodo record 10.5281/zenodo.18187093 (not yet published).

Core input files are:

• datapackage.json (resource schema/column definitions)
• datapackages.csv (project-level metadata)
• tags.csv
• observations.csv
• paths.csv
• staps.csv
• edges.csv
• pressurepaths.csv
• twilights.csv
• species.csv

How raw_data is processed

Processing is done by scripts/process_data.py:

1. Load project metadata from raw_data/datapackages.csv.
2. Load and enrich species metadata from raw_data/species.csv:
   • canonical scientific name
   • common name
   • Cornell species code
   • in_ebirdst
3. Parse tags, observations, movement paths, stopovers, edges, and pressure paths.
4. Keep only the first 10 simulations where j <= 10 for raw paths/pressurepaths embedded in tag assets.
5. Filter to tags with valid staps + paths data.
6. Write optimized frontend assets into public/data/:
   • projects.json
   • tags.json
   • globe.json
   • projects/<project_id>.json
   • tags/<tag_id>/meta.json
   • tags/<tag_id>/paths.json
   • tags/<tag_id>/staps.json
   • tags/<tag_id>/observations.json
   • tags/<tag_id>/pressurepath.json

The processor writes files only when their serialized content changes and removes stale generated project/tag assets after each run. Tag metadata is separated from large path arrays so metadata updates do not rewrite every large tag file.

How to run

# 1) install JS dependencies
npm install

# 2) install Python dependencies for scripts/process_data.py
# Install uv first if needed: https://docs.astral.sh/uv/getting-started/installation/
uv sync

# 3) set env vars
cp .env.example .env
# then set at least: VITE_MAPBOX_TOKEN

# 4) build processed data assets from raw_data/
uv run python scripts/process_data.py

# optional: skip pressurepaths processing for faster builds
uv run python scripts/process_data.py --skip-pressurepaths

# 5) start local dev server
npm run dev

Production build:

npm run build
npm run preview

If build fails with stream did not contain valid UTF-8 from threebox-plugin, run:

npm run fix:threebox-encoding
npm run build

Tests and error checks

Use Node.js 24 LTS for the development tools and CI.

npm test            # Run unit and component tests once
npm run test:watch  # Rerun tests while editing
npm run lint        # Check JavaScript and Vue for errors
npm run check       # Lint, test, then build
npm audit           # Review dependency advisories

Tests cover Zenodo authorization and token handling, conditional inputs, modal selection/dismissal, private/public project identities, import/removal selection, CSV resource paths, and missing coordinates/pressure values. Storage tests use fake-indexeddb to exercise writes, replacement, deletion, commit timing, and aborts. Tests use synthetic fixtures and mocked network and Mapbox rendering; they require no private credentials and do not verify the live Zenodo service, browser storage quotas, or WebGL rendering.

Vitest runs the tests, with Vue Test Utils and jsdom for components. ESLint uses its recommended JavaScript checks and eslint-plugin-vue’s essential rules to catch errors without imposing a formatting style. Checks run on pull requests and before deployment.

What this app does

Global view

Globe view — big-picture look at all projects and tags.

Project view

Project view — metadata, species context, and map exploration.

Tag view

Tag view — timelines, pressure paths, and a 3D bird model that follows the track.

Try BirdView mode in full screen.

Private datapackages

In the Project view, open the private Zenodo dialog and paste the full share link from Zenodo’s Share → Links dialog, then select Load Record. The link must grant access to the record and its files. No personal access token is needed for a share link. Record URLs, DOIs and record ids are also accepted, with an optional personal access token for restricted files.

Processed data is cached in this browser and appears in the project and tag views. The share token and personal access token are not stored in the cache. Use Remove in the dialog to delete a cached datapackage.

Tech stack

Vue UI framework	Vite Build & dev tooling	Tailwind CSS Utility-first styling	Mapbox GL JS Interactive maps & globe	Threebox 3D bird model on map	Plotly Charts & timelines