Skip to content

QuadTiles

QuadTiles is a hierarchical spatial indexing system used for geographical data organization and efficient spatial queries. In the Local Actor API v2, QuadTiles are used to define geographical coverage areas for message capabilities and to filter messages based on their geographical location.

Overview

QuadTiles divide the Earth's surface into a hierarchical grid of rectangular tiles. Each tile is identified by a string of digits, where each digit represents a quadrant subdivision:

  • 0: Northwest quadrant
  • 1: Northeast quadrant
  • 2: Southwest quadrant
  • 3: Southeast quadrant

The longer the tile identifier, the smaller and more precise the geographical area it represents.

Visual Representation

Level 0 (Root)

┌─────────────────┬─────────────────┐
│                 │                 │
│        0        │        1        │
│   (Northwest)   │   (Northeast)   │
│                 │                 │
├─────────────────┼─────────────────┤
│                 │                 │
│        2        │        3        │
│   (Southwest)   │   (Southeast)   │
│                 │                 │
└─────────────────┴─────────────────┘

Level 1 (Subdivision of quadrant "1")

┌─────────────────┬─────────────────┐
│                 │   10    │   11  │
│        0        │  (NW)   │ (NE)  │
│                 ├─────────┼───────┤
│                 │   12    │   13  │
├─────────────────│  (SW)   │ (SE)  │
│                 └─────────┴───────┘
│        2        │        3        │
│                 │                 │
└─────────────────┴─────────────────┘

Level 2 (Further subdivision of tile "10")

                  ┌─────────┬───────┐
                  │  100    │  101  │
                  │  (NW)   │ (NE)  │
                  ├─────────┼───────┤
                  │  102    │  103  │
                  │  (SW)   │ (SE)  │
                  └─────────┴───────┘

As you can see, each level of subdivision creates more precise geographical areas: - "1" - Large northeastern quadrant - "10" - Northwest sub-area within the northeastern quadrant
- "100" - Northwest sub-area within tile "10"

Usage in Local Actor API v2

Capability Coverage

Capabilities define their geographical coverage using arrays of QuadTile identifiers: 

["1001", "100221", "1003"]

Message Properties

Messages include their geographical location in the quadTree application property as a comma-separated string with leading and trailing commas:

",100132101,"

Importance of Comma Delimiters

The leading and trailing commas are crucial for accurate pattern matching in selectors. They ensure:

  • Exact boundary matching: Prevents partial matches of tile identifiers
  • Hierarchical filtering: Enables filtering by parent tiles to include all sub-tiles

Examples

Without comma boundaries (problematic): 

Message:  quadTree = "100132101"
Selector: LIKE '%0132%'
Result:   Incorrectly matches (partial substring match)

With comma boundaries (correct): 

Message:  quadTree = ",100132101,"
Selector: LIKE '%,1001%'
Result:   Correctly matches (tile "1001" and all sub-tiles)

Message:  quadTree = ",100132101,"  
Selector: LIKE '%,01321%'
Result:   Correctly does NOT match (tile "100132101" does not start with "01321")

Multiple Tiles

The format also supports multiple tiles in a single message: 

",100132101,200456789,300111222,"

Geographical Filtering

JMS selectors can filter messages by geographical area using pattern matching: 

quadTree LIKE '%,10013%'
This selector matches any message whose location falls within QuadTile area 10013 or any of its sub-areas.

Examples

  • "1" - Large quadrant covering northeastern portion of the world
  • "1001" - Smaller area within the northeastern quadrant
  • "100132101" - Very specific, precise geographical area

References