│
• Responsible│ forThread fetching│ nearby├─────────────────────┤ air├─────────────────────┤ traffic
│
• Uses GET /v1/uav
• Updates│ the│ map continuously

2. UAV Publishing Thread

• Responsible for publishing your UAV telemetry
• Uses POST /v1/uav │ │ Viewport queries │ │ Position updates │ │ 1Hz polling │ │ 1Hz transmission │ └─────────────────────┘ └─────────────────────┘ ↓ ↓ ┌────────────────────────────────────┐ │ Application State/Map │ └────────────────────────────────────┘

  Architectural Benefits:

  • Fault isolation: Network issues in one thread don't cascade to the other
  • RunsIndependent independentlyscaling: ofAdjust trafficpolling retrievaland publishing rates separately
  • Simplified error handling: Each thread manages its own retry logic
  • Resource optimization: Non-blocking I/O prevents thread starvation

  SeparatingImplementation theseNote: concernsIn improvessingle-threaded reliability,environments scalability,(e.g., andJavaScript), erroruse handling.separate async tasks or workers to achieve the same isolation.

  ---

  2. Retrieving Traffic forRetrieval aStrategy

  Moving Map

  Use

  Viewport-Based Queries

  For map-based applications, always preferuse viewport-basedbounding box queries insteadthat ofalign radius-basedwith searches.the visible viewport:

  GET /v1/uav?viewport=lat_min,lng_min,lat_max,lng_max
  

  Why

  Example:

  GET /v1/uav?viewport=48.8566,2.3522,48.8766,2.3922
  

  Technical Advantages:

  Aspect	Viewport Query	Radius Query
  Zoom adaptability	Natural scaling with map bounds	Fixed circular area
  Data efficiency	Fetches only visible region	Often includes off-screen data
  Rendering alignment	1:1 with visible area	Requires post-filtering
  Edge cases	Handles rectangular screens correctly	Circular overlap issues

  Performance Impact: At high zoom levels (city view), viewport queries arecan preferred

  reduce
  payload
  • Matchessize mapby rendering40-60% logic
  compared
  • Scalesto efficientlyradius-based atapproaches allthat zoomcover levels
  the
  • Avoidssame unnecessaryvisible off-screen traffic
  • Enables smooth pan & zoom interactions
  area.

  ---

  Add

  Viewport a Safety MarginPadding (Outset)

  Overscan)

  AlwaysExtend extendquery thebounds viewport slightly5-15% beyond the visible viewport to improve UX and anticipate edge transitions.

  Implementation Example:

  const OVERSCAN_FACTOR = 0.10; // 10% padding
  
  function getQueryViewport(mapBounds) {
    const latPadding = (mapBounds.north - mapBounds.south) * OVERSCAN_FACTOR;
    const lngPadding = (mapBounds.east - mapBounds.west) * OVERSCAN_FACTOR;
    
    return {
      lat_min: mapBounds.south - latPadding,
      lng_min: mapBounds.west - lngPadding,
      lat_max: mapBounds.north + latPadding,
      lng_max: mapBounds.east + lngPadding
    };
  }
  

  Benefits:

  • Eliminates visual "pop-in" during map bounds.panning
  • Pre-loads aircraft approaching screen edges
  • Smooths fast-moving traffic transitions (e.g., aircraft at 200+ knots)
  • Minimal bandwidth overhead (typically <10% additional data)

  Tuning Guidance: Use larger padding (12-15%) for high-speed traffic environments or slower network connections.

  ---

  Polling Frequency

  Recommended margin:interval: 1 second (1Hz)
  +5% to +15% on each side of the viewport

  This ensures:frequency balances real-time awareness with reasonable bandwidth consumption.

  Rationale:

  • Aircraft nearmoving screenat edges100 areknots stilltravel fetched~50 meters per second
  • No1-second visualupdates “pop-in”provide whensmooth panninginterpolation without perceptible lag
  • BetterAligns anticipationwith ofaviation-grade fast-movingsituational trafficawareness requirements
  • Acceptable load for both mobile and web clients

  FetchingNetwork slightly more traffic than visible is intentional and recommended.Optimization:

  ---

  Polling Frequency

  • RecommendedImplement GETexponential interval:backoff 1for secondfailed requests
  • ProvidesConsider smoothcompression motion(gzip/brotli) andfor near-real-time awarenessresponses
  • SuitableUse HTTP/2 or HTTP/3 where available for bothconnection UAV and crewed aircraft trafficmultiplexing

  ---

  3. Publishing UAV Telemetry

  UsePublishing the following endpoint to publish one or more UAVs:

  Endpoint

  POST /v1/uav
  Content-Type: application/json
  

  Publishing Frequency

  • Recommended POST interval:Frequency: 1 second
  (1Hz)

  ---

  Batch Publishing (Stronglyfor Recommended)

  Fleet Operations

  IfWhen managing multiple UAVsUAVs, simultaneously, always publishuse batch publishing by sending an array of telemetry objects in batch using a single POST request.

  WhyPerformance batchComparison:

  publishingmatters:

  Approach	UAVs	Requests/sec	HTTP Overhead	Network Latency
  Individual	10	10	~4KB	10× RTT
  Batch	10	1	~400B	1× RTT

  Key Benefits:

  • Reduced overhead: Single HTTP overheadhandshake vs. multiple connections
  • LowerAtomic latencytimestamps: All UAVs share consistent update time
  • ConsistentLower timestampslatency: acrossOne UAVsround-trip instead of N round-trips
  • BetterImproved scalabilityscalability: Essential for fleetsswarm andoperations swarms(20+ UAVs)

  RecommendedBest approach:Practice:

  • Aggregate all UAV telemetry updatesin peryour cycle
  application
  • Sendloop themand togetherpublish oncethe perentire second
  fleet
  • Avoidstate individual POSTs per UAV
  atomically.

  ---

  Example: Batch UAV Publish Payload

  [
    {
      "id": "UAV1",
      "latitude": 48.86584,
      "longitude": 2.63723,
      "altitude": 120,
      "course": 205,
      "ground_speed": 12,
      "status": "AIRBORNE",
      "last_update": 1733412793
    },
    {
      "id": "UAV2",
      "latitude": 48.87012,
      "longitude": 2.64188,
      "altitude": 115,
      "course": 210,
      "ground_speed": 10,
      "status": "AIRBORNE",
      "last_update": 1733412793
    }
  ]
  

  ---

  4. Pre-Flight Visibility

  (Grounded

  GROUNDED Status)

  Status

  Advertise Before Takeoff

  Broadcasting

  Before takeoff, it is considered best practice to publish thePublish UAV with:

  position

  with statusstatus: = GROUNDED
  "GROUNDED"

  When:

  • Ideally 3–3-5 minutes before takeoff.

    {
      "id": "UAV1",
      "latitude": 48.86584,
      "longitude": 2.63723,
      "altitude": 0,
      "status": "GROUNDED",
      "last_update": 1734537600
    }
    

    Operational Rationale:

    • Provides advanced notification to nearby crewed aircraft and helicopters
    • Establishes situational awareness before airspace usage
    • Aligns with aviation practice of pre-flight intent signaling
    • Particularly important near helipads, airports, or low-altitude flight zones

    Why:State Transition:

    • Makes UAV activity visible to helicopters and crewed aircraft
    • Improves shared situational awareness
    • Mirrors aviation intent signaling

    SwitchTransition to AIRBORNEstatus: "AIRBORNE" immediately afterupon takeoff.takeoff to reflect actual flight status.

    Implementation Note: For mission planning applications, this can be automated based on pre-filed flight plans or launch schedules.

    ---

    5. Smooth Aircraft Motion (Rendering

    Client-Side Extrapolation)

    Position Extrapolation

    Traffic updates arrive at discrete 1-second intervals. To avoidachieve “jumping”smooth icons:

    animation,

    Useimplement extrapolationdead reckoning between updates

    • Predict position using:
      • Last known position
      • Ground speed
      • Course
    • Linearly extrapolate until the next update arrives
    updates.

    ThisAlgorithm:

    creates:

    function extrapolatePosition(aircraft, currentTime) {
      const elapsedSeconds = (currentTime - aircraft.last_update) / 1000;
      const distanceMeters = aircraft.ground_speed * 0.514444 * elapsedSeconds; // knots to m/s
      
      const deltaLat = distanceMeters * Math.cos(aircraft.course * Math.PI / 180) / 111320;
      const deltaLng = distanceMeters * Math.sin(aircraft.course * Math.PI / 180) / 
                       (111320 * Math.cos(aircraft.latitude * Math.PI / 180));
      
      return {
        latitude: aircraft.latitude + deltaLat,
        longitude: aircraft.longitude + deltaLng
      };
    }
    

    Rendering Impact:

    • Smooth,Transforms professionaldiscrete position updates into fluid 60fps animation
    • Eliminates visual "jumping" or "teleporting" artifacts
    • Creates professional, aviation-grade map renderingpresentation
    • BetterImproves user perception of traffic flow
    • Reduced visual jitterpatterns

    Limitation: Extrapolation assumes constant velocity and heading. Maneuvering aircraft may show brief position discrepancies until the next update.

    ---

    6. Traffic Ageing,Aging Uncertainty &and Expiry

    Data Freshness Management

    Different traffic typessources have different lifetimes.validity windows based on their update characteristics.

    Advisory UAV Traffic

    • ValidValidity: upUp to 2 minutes after timestamplast expiryupdate
    • ShouldRationale: remainLower visiblespeed withand appropriatepredictable flight patterns
    • Display: Apply visual indicationindicators for aged data (reduced opacity, uncertainty ring)

    Other

    Real-Time Air Traffic (ADS-B, FLARM, ADS-L, etc.)

    L) behaviornormallywithseconds

    Time since last updateAge	RecommendedState	Visualization
    0–30 seconds0-30s	DisplayCurrent	Full opacity, normal icon
    30–45 seconds30-45s	DisplayStale	Reduced opacity + expanding uncertainty circle
    >4545s	Expired	Remove from display

    Uncertainty Visualization

    Implementation

    • ShowApproach:
      an

      function expandinggetUncertaintyRadius(lastUpdate, currentTime, groundSpeed) {
        const ageSeconds = (currentTime - lastUpdate) / 1000;
        if (ageSeconds < 30) return 0;
        
        // Assume maximum maneuvering potential
        const maxDistanceMeters = groundSpeed * 0.514444 * ageSeconds;
        return maxDistanceMeters; // Display as circle aroundradius
      last}
      known

      position

    Purpose:

    • Radius increases over time to reflect possible movement
    • Prevents false precision afterin signalposition loss
    estimates.
    Users see explicit uncertainty rather than misleading "current" positions.

    Visual Design: Use semi-transparent expanding circles that grow linearly with time since last update.

    ---

    7. Visual RepresentationDesign BestGuidelines

    Practices

    Traffic Icon States

    RecommendedImplement progressive visual cues:feedback to communicate data confidence:

    Data Freshness States:
    ┌─────────────┬──────────────┬────────────────┬──────────────┐
    │   Current   │     Aging    │  Uncertain     │   Expired    │
    │   (0-30s)   │   (30-45s)   │                │    (>45s)    │
    ├─────────────┼──────────────┼────────────────┼──────────────┤
    │ Solid icon  │ 70% opacity  │ + uncertainty  │ Remove from  │
    │ Full color  │ Subtle pulse │   circle       │   display    │
    └─────────────┴──────────────┴────────────────┴──────────────┘
    

    Traffic Categorization

    Use distinct iconography for different aircraft types:

    • SolidUAV/Drone: icon:Quadcopter freshor datafixed-wing silhouette
    • ReducedHelicopter: opacity:Rotor-based agingicon datawith rotation indicator
    • ExpandingGeneral uncertaintyAviation: circle:Small signalaircraft degradationsilhouette
    • DistinctCommercial: iconsLarger peraircraft trafficprofile
    category
    • Unknown: (UAV,Generic helicopter,aircraft GA, jet)symbol

    Accessibility Note: Ensure icons are distinguishable by shape, not just color, for colorblind users.

    ---

    8. Icon Sets

    Assets

    To simplify integration, SafeSky provides ready-to-use trafficoptimized icon sets optimised for maprapid rendering.integration.

    📦Download: Icon sets download (placeholder):
    https://docs.safesky.app/downloads/iconsets

    Includes:Package Contents:

    • Formats: SVG (vector) and PNG formats(raster)
    • MultipleSizes: sizes24×24, 32×32, 48×48, 64×64 px
    • DarkThemes: Light and dark mode variants
    • Categories: UAV, helicopter, GA, commercial, glider, balloon

    Usage Recommendations:

    • Use SVG for web applications (resolution independence, smaller payload)
    • Use PNG for native applications with fixed DPI requirements
    • Implement theme switching based on map style (dark maps = light themesicons)

    ---

    9. RecommendedConfiguration Reference

    Timing Summary

    Parameters

    ActionParameter	IntervalValue	Rationale
    GET traffic (viewport)	1 second	Optimal balance of real-time awareness and bandwidth
    POST UAV telemetry	1 second	Maintains continuity for receiving applications
    Pre-flight GROUNDED publish	3–5 minutesmin before takeoff	Provides advanced notice to nearby traffic
    StartUncertainty uncertaintyvisualization	30 seconds after update	Reflects realistic position drift
    DiscardTraffic trafficexpiry (non-UAV)	45 seconds after update	Prevents stale data display
    UAV expiry	2 minutes after update	Accommodates lower-frequency updates
    Viewport overscan	10-15%	Eliminates edge transition artifacts

    ---

    10. Reference Implementation

    AExplore livea exampleproduction implementingimplementation allof these best practices is available at:patterns:

    Live Demo: https://live.safesky.app

    The reference implementation demonstrates:

    • Dual-thread architecture with independent polling and publishing
    • Viewport-based queries with dynamic overscan
    • Client-side position extrapolation for smooth rendering
    • Progressive data aging with uncertainty visualization
    • Batch telemetry publishing for fleet operations

    Use the browser developer tools to observe network traffic patterns, polling behavior, and rendering optimizations in a production environment.

    ---

    Additional Resources

    • API Reference: Full endpoint documentation and schemas
    • Authentication Guide: HMAC signing and API key management
    • Rate Limits: Request throttling and quota information
    • Support: Technical support channels and community forums