This package provides an infinite grid overlay for LuciadRIA maps.

The LuciadRIA infinite grid is a customizable grid that extends infinitely in all directions, designed as a visual orientation and measurement aid for 3D views. It’s rendered fully on the GPU and adapts automatically to camera movement. It supports both cartesian and geocentric map references.

grid geocentric
Figure 1. Infinite grid rendered on a geocentric (EPSG:4978) map, tangent to the Earth at the grid origin
grid cartesian
Figure 2. Infinite grid rendered on a cartesian (LUCIAD:XYZ) map

Overview

The central class is InfiniteGridSupport. It attaches a GPU-rendered grid to an existing RIAMap and keeps it synchronized with the map’s camera.

The infinite grid is distinct from traditional grid layers in several ways: - The infinite grid isn’t geometry-based. - No grid lines are stored as shapes or features. - All grid lines are generated in a shader, per pixel. - In terms of performance, there is one draw call per frame.

These distinctions make the grid infinite and resolution-independent.

The grid isn’t selectable. It’s also excluded from feature picking.

Key characteristics

The infinite grid supports both cartesian (LUCIAD:XYZ) and geocentric (EPSG:4978) references.

In cartesian maps, the grid lies on the XY plane (z = 0) of the map reference.

For geocentric references, the grid is rendered as a plane tangent to the surface of the earth at a chosen 3D position. Internally, a local tangent plane is constructed and used to derive a custom grid projection.

Usage

Attach the grid to an existing RIAMap: 

import { InfiniteGridSupport } from "@luciad/ria-toolbox-infinite-grid/InfiniteGridSupport.js";
const map = new RIAMap(element);
const grid = new InfiniteGridSupport(map);

The grid automatically tracks camera position and orientation and updates its projection accordingly. You don’t have to add extra layers to the map.

Configuration

You can configure the grid through setter methods on InfiniteGridSupport. Common options include:

  • gridOrigin: World-space origin of the grid plane (expressed in map reference coordinates).

  • colorGrid: Base color of the grid lines, expressed as a valid CSS color string.

  • colorAxisX: Color of the X axis line.

  • colorAxisY: Color of the Y axis line.

  • cellSize: Size of a single grid cell, expressed in meters.

  • lineThickness: Thickness of the grid lines.

  • visible: Control whether the grid is rendered.

  • forceBehind: Force the grid behind all geometry when enabled. 

// initialization
const gridSupport = new InfiniteGridSupport(map, {
  gridOrigin,
  lineThickness: 0.75,
  colorGrid: 'rgb(250,250,250)',
});
// changes at runtime
gridSupport.setGridSize(50);
gridSupport.colorGrid('rgb(10,250,10)');

Dynamic grid cell size

You can update the grid cell size dynamically at runtime, based on the camera position and its pitch angle. For this purpose, the tool provides the utility function computeGridCellSize, which estimates appropriate grid spacing by intersecting the camera frustum with the grid plane and deriving a cell size that remains visually stable on screen. 

map.on("MapChange", () => {
  const size = computeGridCellSize(map, gridSupport.getGridOrigin());
  if (size) {
    gridSupport.setCellSize(size);
  }
});