feat: Comprehensive GPS visualisation and annotation system

[cloudmark]

GPS Visualisation Feature: Complete GPS Data Annotation System

Reason for Change

This feature directly addresses Issue #7587 - "GPS Visualizer – Interactive Time-Based GPS Signal Visualisation" opened by @cloudmark. The issue highlighted that Label Studio could not visualise GPS signals on a map, making it difficult to analyse movement, identify stationary periods, or annotate events meaningfully for geospatial data.

Problem: As described in the issue, users were limited to displaying GPS data in tables or time series charts, which "is not an intuitive or effective way to understand spatial and temporal patterns in GPS data." This made it difficult to analyse movement, identify stationary periods, or annotate events in a way that is meaningful for geospatial data.

Solution: Implemented a comprehensive GPS Visualizer component that fulfils all the requirements outlined in the issue, providing interactive, map-based visualisation of time-based GPS signals with full annotation capabilities.

Requirements Fulfilled from Issue #7587

✅ Display GPS tracks on a map, with each point linked to its timestamp

• Implemented interactive Deck.GL map visualisation with GPS path rendering
• Each GPS point is linked to its timestamp for temporal navigation
• Real-time synchronisation between map position and timeline

✅ Detect and visualise stationary clusters as circles, showing where and when stops occurred

• Advanced cluster detection algorithm identifies stationary points
• Visualised as circles on the map with configurable styling
• Shows duration and location of stops

✅ Draw arrows on the outline of each stationary cluster, pointing toward the next cluster, with a distance label in front of the arrow

• Cluster arc layers show movement direction between clusters
• Distance labels display the distance between clusters
• Arrows indicate the direction of movement

✅ Synchronise a timeline or waveform (or any syncable) with the map, allowing users to play, pause, and scrub through time

• Integrated waveform visualisation with speed and altitude metrics
• Synchronised playback controls across the map and waveform
• Real-time seeking and scrubbing functionality

✅ Support annotation of regions or events, linking them between the map and the timeline

• Region-based annotation system with sidebar integration
• Regions are linked between the map and waveform views
• Clicking regions in the sidebar seeks to corresponding time

✅ Allow toggling of clusters, arrows, and labels for a customizable view

• Comprehensive settings panel for visibility controls
• Independent toggles for clusters on map, waveform, and grid
• Customizable cluster detection parameters

Use Cases for GPS Data Annotation

As mentioned in the issue, this feature is especially useful for:

1. Sports Analysis: Track athlete movement patterns, identify training zones, analyze performance metrics
2. Delivery/Logistics Tracking: Monitor delivery routes, identify delays, optimize logistics operations
3. Wildlife Movement Studies: Track animal migration patterns, identify habitat usage, study behavior
4. Fleet Management: Monitor vehicle routes, identify stationary periods, optimize operations
5. Urban Planning: Analyse traffic patterns, identify congestion points, plan infrastructure
6. Emergency Response: Track emergency vehicle routes, coordinate response efforts

Screenshots

Video demonstration available at

The video demonstrates all the requirements from Issue #7587:

• Interactive GPS map with real-time playback controls
• Stationary cluster detection and visualisation
• Direction arrows between clusters with distance labels
• Synchronised timeline/waveform with the map
• Region-based annotation linking map and timeline
• Toggle controls for clusters, arrows, and labels

Rollout Strategy

• Feature Flags: No feature flags required - this is a new feature addition
• Environment Variables: None needed
• Deployment: Standard deployment process
• Backwards Compatibility: Fully backwards compatible - no impact on existing annotations

Testing

Comprehensive Testing Completed:

Test Data Used:

{
  "data": {
    "file": "https://storage.googleapis.com/labelstudio-uploads-public/recording_1749719922.m4a",
    "gps_data": "https://storage.googleapis.com/labelstudio-uploads-public/gps_1749719922.json",
    "gyro_data": "https://storage.googleapis.com/labelstudio-uploads-public/gyro_1749719922.json",
    "accel_data": "https://storage.googleapis.com/labelstudio-uploads-public/accel_1749719922.json",
    "magneto_data": "https://storage.googleapis.com/labelstudio-uploads-public/magneto_1749719922.json",
    "attitude_data": "https://storage.googleapis.com/labelstudio-uploads-public/attitude_1749719922.json"
  },
  "predictions": []
}

Test Configuration:

<View>
  <Labels name="label" toName="gps_display" zoom="true" hotkey="ctrl+enter" showInline="true" choice="single">
    <Label value="category_a" background="#ff0d00" hotkey="1"/>
    <Label value="category_b" background="#00ff1e" hotkey="2"/>
  </Labels>
  
  <Audio name="audio_sample" value="$file" hotkey="space" sync="group_a" spectrogram="true" height="300"/>
  
  <TimeSeries name="gyro_timeseries" value="$gyro_data" valueType="url" timeColumn="relative_timestamp" sync="group_a" fixedScale="false" overviewWidth="10%">
    <MultiChannel>
      <Channel column="gyro_x" strokecolor="#0047AB" legend="Gyro X" height="100"/>
      <Channel column="gyro_y" strokecolor="#FFBF00" legend="Gyro Y" height="100"/>
      <Channel column="gyro_z" strokecolor="#DC143C" legend="Gyro Z" height="100"/>
      <Channel column="gyro_magnitude" strokecolor="#00FF7F" legend="Gyro Magnitude"/>
    </MultiChannel>
  </TimeSeries>
  
  <TimeSeries name="accel_timeseries" value="$accel_data" valueType="url" timeColumn="relative_timestamp" sync="group_a" fixedScale="false" overviewWidth="10%">
    <MultiChannel>
      <Channel column="accel_x" strokecolor="#0047AB" legend="Accel X" height="100"/>
      <Channel column="accel_y" strokecolor="#FFBF00" legend="Accel Y" height="100"/>
      <Channel column="accel_z" strokecolor="#DC143C" legend="Accel Z" height="100"/>
      <Channel column="accel_magnitude" strokecolor="#00FF7F" legend="Accel Magnitude"/>
    </MultiChannel>
  </TimeSeries>
  
  <GPSMap name="gps_display" value="$gps_data" timeline="gps_timeline" sync="group_a"/>
</View>

Manual Testing Completed:

• ✅ All Issue GPS Visualizer – Interactive Time-Based GPS Signal Visualization #7587 Requirements: Every requirement from the original issue has been implemented and tested
• ✅ Multi-modal Synchronisation: GPS, audio, and time series data perfectly synchronized
• ✅ GPS Data Loading: Real GPS data from JSON URL loads correctly
• ✅ Interactive Map Visualization: Deck.GL map with real GPS coordinates
• ✅ Stationary Cluster Detection: Advanced algorithm identifies stops with configurable parameters
• ✅ Cluster Visualisation: Circles on the map showing where and when stops occurred
• ✅ Direction Arrows: Arrows between clusters with distance labels
• ✅ Temporal Waveform Display: Speed and altitude metrics from actual GPS data
• ✅ Region Creation and Editing: Annotations work with real GPS data
• ✅ Region Selection and Seeking: Clicking regions in sidebar seeks to correct time
• ✅ Playback Controls: Play, pause, seek synchronised across all components
• ✅ Toggle Controls: Independent visibility controls for clusters, arrows, and labels
• ✅ Settings Panel: All customisation options work with real GPS data
• ✅ Cross-browser Compatibility: Chrome, Firefox, Safari with real data
• ✅ Performance: Handles real GPS datasets efficiently
• ✅ Integration: Seamless integration with existing Label Studio workflows

Risks

Low Risk:

• Performance: Optimised with GPU-accelerated rendering and efficient data structures
• Security: No security implications - purely client-side visualisation
• Data Integrity: Maintains existing Label Studio data formats
• Compatibility: Fully compatible with existing annotations

Mitigation:

• Implemented efficient data processing with pre-allocated arrays
• Used WebGL rendering for optimal performance
• Added comprehensive error handling for data validation
• Maintained existing Label Studio patterns and conventions
• Real-world testing with actual GPS and sensor data

Reviewer Notes

Key Components Added:

1. Core Visualization Components:

   • GPSVisualization.tsx - Main map visualisation with Deck.GL
   • GPSVisualizationWithWaveform.tsx - Combined map + waveform view
   • GPSMetricsWaveform.ts - Temporal waveform with metrics display

2. Map Layers (Addressing Issue GPS Visualizer – Interactive Time-Based GPS Signal Visualization #7587 Requirements):

   • StaticPathLayer.tsx - GPS path visualisation with timestamp linking
   • CurrentPointLayer.tsx - Current position indicator
   • BearingLayer.tsx - Direction indicators
   • ClusterLayer.tsx - Stationary cluster visualisation as circles
   • ClusterArcLayers.tsx - Direction arrows between clusters with distance labels
   • AnimatedTrailLayer.tsx - Animated playback trail

3. Waveform Components:

   • MetricWaveform.ts - Speed and altitude waveform rendering
   • ClusterMarkers.ts - Cluster visualisation on waveform
   • Regions.ts - Region creation and management
   • PlayHead.ts - Playback position indicator

4. GPS Region Model:

   • GPSRegionModel.js - Region data model with seeking functionality
   • GPSRegionProperties.tsx - Region properties panel

5. Supporting Infrastructure:

   • types.ts - Comprehensive TypeScript interfaces
   • Utils.ts - GPS calculation utilities
   • clusters.ts - Cluster detection algorithms
   • mapProviders.js - Map tile provider configurations

Code Quality:

• Follows React best practices with functional components and hooks
• Comprehensive TypeScript typing throughout
• Modular architecture with clear separation of concerns
• GPU-optimised rendering for performance
• Consistent with existing Label Studio patterns
• Real-world tested with actual GPS and sensor data

Testing Focus Areas:

• ✅ Issue GPS Visualizer – Interactive Time-Based GPS Signal Visualization #7587 Requirements: All original requirements implemented and tested
• ✅ Multi-modal Synchronisation: Verified perfect sync between GPS, audio, and time series
• ✅ Real GPS Data: Tested with actual GPS coordinates and sensor data
• ✅ Performance: Validated with real-world datasets
• ✅ Region Annotation: Confirmed workflows with real GPS tracks
• ✅ Cluster Detection: Verified accuracy with real movement patterns
• ✅ Cross-browser Compatibility: Tested across major browsers
• ✅ Integration: Confirmed seamless integration with existing features

General Notes

This feature directly addresses the community feature request in Issue #7587 and provides a comprehensive solution for GPS data visualisation and annotation. The implementation fulfils all the requirements outlined in the original issue while extending the functionality with additional features for a complete GPS annotation experience.

Technical Implementation Highlights:

• GPU-Accelerated Rendering: Uses Deck.GL for high-performance map visualisation
• Efficient Data Processing: Optimized algorithms for large GPS datasets
• Modular Architecture: Clean separation between map, waveform, and region components
• Real-time Synchronisation: Seamless coordination between map and waveform views
• Advanced Cluster Detection: Sophisticated algorithms for identifying stationary points and patterns
• Interactive Annotation: Full region creation and editing capabilities
• Multi-modal Sync: Perfect synchronisation with audio and time series data

Performance Optimizations:

• Pre-allocated arrays for data processing
• Efficient colour scheme calculations
• Optimised rendering with layer culling
• Memory management for large datasets
• Smooth playback with requestAnimationFrame

Real-world Validation:

• Tested with actual GPS data from real-world scenarios
• Multi-modal synchronisation verified with audio and sensor data
• Performance validated with real GPS datasets
• User workflows tested with actual annotation scenarios
• All Issue GPS Visualizer – Interactive Time-Based GPS Signal Visualization #7587 requirements implemented and validated

Future Considerations:

• Potential for additional GPS-specific annotation tools
• Integration with external mapping services
• Advanced clustering algorithms
• Real-time GPS data streaming
• Export capabilities for GPS-specific formats

The video demonstration and real-world testing clearly show that this implementation fully addresses the requirements outlined in Issue #7587, providing the community with the GPS visualisation capabilities they requested while extending the functionality for comprehensive multi-modal AI training data annotation.

[netlify]

👷 Deploy request for heartex-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	93cf0cc

[netlify]

👷 Deploy request for label-studio-docs-new-theme pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	93cf0cc

[netlify]

✅ Deploy Preview for label-studio-playground ready!

Name	Link
🔨 Latest commit	93cf0cc
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-playground/deploys/6863fbde2ed3990008a7d891
😎 Deploy Preview	https://deploy-preview-7880--label-studio-playground.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for label-studio-storybook ready!

Name	Link
🔨 Latest commit	93cf0cc
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-storybook/deploys/6863fbdec769470008f15451
😎 Deploy Preview	https://deploy-preview-7880--label-studio-storybook.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.