❮ The Elastic Graph
Distances & Heights ❯

Map Nodes

In the Spatial Experience SDK, a Map is a continuous two-dimensional matrix of floating-point values representing spatial density, height, or clearance weight across your active generation bounds.

Unlike discrete object vectors, Maps act as continuous fields. Each pixel of a Map can contain any floating-point value representing a real-world measurement (such as a physical height of 35.5 meters or a road clearance distance of 150.0 meters), rather than being restricted to a normalized 0.0 to 1.0 range.

When visualized in the graph editor's preview windows, the rendering shader dynamically scales the gray gradients relatively based on the active buffer's bounds (following the standard heightmap convention where lighter is higher and darker is lower):

  • Solid White: The highest relative value currently present in the active map buffer (whether that value is 1.0, 150.0, or 500.0).
  • Solid Black: The lowest relative value currently present in the active map buffer.
  • Shades of Blue: Ranges below zero shift the grayscale into a blue color palette (water metaphor) to identify negative offsets or depressions at a glance.

A classic example of a Map Source is the Road Network Mask node. This node retrieves real-world geographic road paths from our Map Server and rasterizes them into a binary float mask: 1.0 where a road lane physically exists, and 0.0 everywhere else.

Sources & Modifiers

The data pipeline of the Elastic Graph separates Map operations into two distinct, high-performance node categories:

---
config:
  flowchart:
    subGraphTitleMargin:
      bottom: 30
---
flowchart LR
    subgraph Sources ["1. Map Sources (Generators)"]
        OSM["Road Mask Node <br> (Ingests real GIS roads)"]
        Noise["Perlin Noise Node <br> (Generates continuous noise)"]
    end

    subgraph Modifiers ["2. Map Modifiers (Processors)"]
        Dist["Distance Transform <br> (Calculates euclidean distance)"]
        Mult["Multiply Modifier <br> (Blends maps pixel-by-pixel)"]
    end

    subgraph Scene_Deformation ["3. ESG Output"]
        Heightmap([Final Terrain Heightmap])
    end

    OSM -->|Binary Road Mask| Dist
    Dist -->|Continuous Distance Map| Mult
    Noise -->|Raw Noise Grid| Mult
    Mult -->|Sloped Hills + Flat Roads| Heightmap

    %% Styling (Vibrant, borderless theme)
    style Sources fill:#e0f2fe,stroke-width:0px
    style OSM fill:#0284c7,stroke-width:0px,color:#fff
    style Noise fill:#0ea5e9,stroke-width:0px,color:#fff
    
    style Modifiers fill:#f3e8ff,stroke-width:0px
    style Dist fill:#7c3aed,stroke-width:0px,color:#fff
    style Mult fill:#9c27b0,stroke-width:0px,color:#fff
    
    style Scene_Deformation fill:#dcfce7,stroke-width:0px
    style Heightmap fill:#16a34a,stroke-width:0px,color:#fff
  • Map Sources: Nodes that generate or retrieve initial data matrices (such as Perlin Noise, satellite-derived Terrain Elevations, or GIS-mapped OpenStreetMap geometries).
  • Map Modifiers: Nodes that accept one or more Maps as inputs, execute pixel-by-pixel mathematical transformations (such as addition, multiplication, convolution filters, blurring, or distance transformations), and compile a new output Map.

Combining Modifiers (A Practical Example)

To sculpt a terrain where hills rise in the distance but flatten perfectly to 0.0 at the road's coordinate borders to prevent blocking the vehicle, you combine Map Modifiers:

  1. Calculate Distance: Connect the binary Road Network Mask source into a Distance Transform modifier to calculate the continuous euclidean distance (in meters) away from the nearest road.
  2. Inject Organic Detail: Connect the resulting distance map and a Perlin Noise source into a Multiply modifier.
  3. The Mathematical Result: Multiplying the distance map by the noise grid forces the height values to scale down smoothly toward 0.0 as they approach the road center, ensuring a perfectly cleared driving corridor while retaining organic rolling hill profiles further out.

Performance & Map Resolution

Because Maps are stored as two-dimensional floating-point arrays, their size directly dictates the CPU computation cost and RAM allocation during origin shifts:

  • The ESG Setting: The density of the Map matrix is determined by the Map Resolution parameter on your scene's ElasticSceneGenerator component.
  • The Performance Principle: Increasing the Map Resolution creates finer, more detailed terrain meshes, but exponentially increases background thread evaluation latency.
  • Mobile Devices Recommendation: For experiences targeting mobile devices, it is highly recommended to keep the Map Resolution at its default value (128 or 256). This ensures real-time world generation can easily keep pace with physical vehicle speeds of 100+ km/h without stuttering.
Note

Advanced Optimization Reference:
For a detailed deep-dive into profiling update latencies, object pooling transitions, and dynamic framerate scaling across the pipeline, refer to our comprehensive Quality and Performance guide.

❮ The Elastic Graph
Distances & Heights ❯