Source

Sources specify the geographic features to be rendered on the map. Each source must have a unique ID and a type that determines how the data is interpreted.

Sources are added to the map using map.addSource() and can be referenced by layers to define their data.

Constructor

new gtswebsdkgl.Source(id, options)
new gtswebsdkgl.Source(id: string, options: SourceOptions)

Creates a new Source with the specified ID and options. The source must be added to a map using map.addSource() before it can be used.

Parameters:

Name Type Description
id string A unique identifier for the source.
options SourceOptions Options for configuring the source's type and data.

Example:

import { Source } from 'gtswebsdkgl';

// Create a GeoJSON source
const source = new Source('my-data', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: [/* ... */]
    }
  });

// Add to map
map.addSource(source);

Source Types

The following source types are supported, each with specific properties and use cases.

Vector Source

A vector tile source. All geometric coordinates in vector tiles must be between 0 and 4096.

Example:

const vectorSource = new Source('terrain-data', {
  type: 'vector',
  url: 'https://api.example.com/tiles/{z}/{x}/{y}.pbf',
  minzoom: 0,
  maxzoom: 14,
  bounds: [-180, -85, 180, 85],
  scheme: 'xyz',
  attribution: '© OpenStreetMap contributors'
});
map.addSource(vectorSource);

All Properties:

Property Type Required Default Description
type string required - Must be "vector"
url string optional - A URL to a TileJSON resource
tiles string[] optional - Array of tile URLs. Required if no URL provided
bounds number[] optional [-180, -85, 180, 85] An array of four numbers representing bounds: [west, south, east, north]
scheme string optional "xyz" Influences the y direction of the tile coordinates. Can be "xyz" or "tms"
minzoom number optional 0 Minimum zoom level for which tiles are available
maxzoom number optional 22 Maximum zoom level for which tiles are available
attribution string optional - Contains an attribution to be displayed when the map is shown to a user

Raster Source

A raster tile source. Tiles can be in PNG, JPEG, or WebP format. Used for satellite imagery, terrain data, and other raster-based map data.

Example:

const rasterSource = new Source('satellite', {
  type: 'raster',
  tiles: [
    'https://a.tiles.example.com/{z}/{x}/{y}.png',
    'https://b.tiles.example.com/{z}/{x}/{y}.png'
  ],
  tileSize: 256,
  minzoom: 0,
  maxzoom: 19,
  bounds: [-180, -85, 180, 85],
  scheme: 'xyz'
});
map.addSource(rasterSource);

All Properties:

Property Type Required Default Description
type string required - Must be "raster"
url string optional - A URL to a TileJSON resource
tiles string[] optional - Array of tile URLs. Required if no URL provided
bounds number[] optional [-180, -85, 180, 85] An array of four numbers representing bounds: [west, south, east, north]
minzoom number optional 0 Minimum zoom level for which tiles are available
maxzoom number optional 22 Maximum zoom level for which tiles are available
tileSize number optional 512 The minimum visual size to display tiles for this layer
scheme string optional "xyz" Influences the y direction of the tile coordinates. Can be "xyz" or "tms"
attribution string optional - Contains an attribution to be displayed when the map is shown to a user

Raster DEM Source

A raster DEM (Digital Elevation Model) source for terrain and elevation data. Used to create 3D terrain effects on the map.

Example:

const demSource = new Source('terrain', {
  type: 'raster-dem',
  url: 'https://dem.example.com/{z}/{x}/{y}.png',
  encoding: 'terrarium',
  minzoom: 0,
  maxzoom: 14,
  tileSize: 512,
  attribution: 'Terrain data © NASA'
});
map.addSource(demSource);

All Properties:

Property Type Required Default Description
type string required - Must be "raster-dem"
url string optional - A URL to a TileJSON resource
tiles string[] optional - Array of tile URLs. Required if no URL provided
bounds number[] optional [-180, -85, 180, 85] An array of four numbers representing bounds: [west, south, east, north]
minzoom number optional 0 Minimum zoom level for which tiles are available
maxzoom number optional 22 Maximum zoom level for which tiles are available
tileSize number optional 512 The minimum visual size to display tiles for this layer
attribution string optional - Contains an attribution to be displayed when the map is shown to a user

GeoJSON Source

A data source containing GeoJSON. This source can be used with the Converter class to convert between different formats. Supports both inline GeoJSON and URLs to GeoJSON files.

Example:

const geojsonSource = new Source('earthquakes', {
  type: 'geojson',
  data: {
    type: 'FeatureCollection',
    features: [
      {
        type: 'Feature',
        geometry: {
          type: 'Point',
          coordinates: [-122.4194, 37.7749]
        },
        properties: {
          title: 'San Francisco'
        }
      }
    ]
  },
  maxzoom: 14,
  buffer: 128,
  tolerance: 0.375,
  cluster: true,
  clusterRadius: 50,
  clusterMaxZoom: 14,
  clusterMinPoints: 2
});
map.addSource(geojsonSource);

All Properties:

Property Type Required Default Description
type string required - Must be "geojson"
data object | string required - A GeoJSON data object or URL to one
maxzoom number optional 18 Maximum zoom level at which to create vector tiles
attribution string optional - Contains an attribution to be displayed when the map is shown to a user
buffer number optional 128 Size of the tile buffer on each side
tolerance number optional 0.375 Douglas-Peucker simplification tolerance
lineMetrics boolean optional false Whether to calculate line distance metrics
generateId boolean optional false Whether to generate ids for the geojson features
cluster boolean optional false If the data is a collection of point features, setting this to true clusters the points
clusterRadius number optional 50 Radius of each cluster when clustering points
clusterMaxZoom number optional 14 Max zoom to cluster points on
clusterMinPoints number optional 2 Minimum points to form a cluster
clusterProperties object optional - Custom properties on clusters using aggregation expressions

Image Source

An image source. Displays a single image stretched to the bounds specified. Useful for adding overlays, historical maps, or custom imagery.

Example:

const imageSource = new Source('radar-overlay', {
  type: 'image',
  url: 'https://example.com/radar.png',
  coordinates: [
    [-80.425, 46.437], // top-left
    [-71.516, 46.437], // top-right
    [-71.516, 37.936], // bottom-right
    [-80.425, 37.936] // bottom-left
  ]
});
map.addSource(imageSource);

All Properties:

Property Type Required Default Description
type string required - Must be "image"
url string required - URL that points to an image
coordinates number[][] required - The four geographical coordinates denoting where to place the image on the map

Video Source

A video source. Displays a video stretched to the bounds specified. Useful for adding video overlays, security camera feeds, or animated content.

Example:

const videoSource = new Source('security-cam', {
  type: 'video',
  urls: [
    'https://example.com/camera.mp4',
    'https://example.com/camera.webm'
  ],
  coordinates: [
    [-122.51596391201019, 37.56238816766053], // top-left
    [-122.51467645168304, 37.56238816766053], // top-right
    [-122.51467645168304, 37.56110286312794], // bottom-right
    [-122.51596391201019, 37.56110286312794] // bottom-left
  ]
});
map.addSource(videoSource);

All Properties:

Property Type Required Default Description
type string required - Must be "video"
urls string[] required - An array of one or more video source URLs
coordinates number[][] required - The four geographical coordinates denoting where to place the video on the map

Methods

setData()
setData(data: object | string): this

Updates the data of a GeoJSON source. For vector or raster sources, the source must be recreated with new data.

Parameters:

Parameter Description
data The new data for the source. Can be a GeoJSON object or a URL to a GeoJSON file.
Returns: this (The Source instance)
getId()
getId(): string

Gets the source's unique identifier.

Returns: string (The source ID)
getType()
getType(): string

Gets the source's type.

Returns: string (The source type)
getData()
getData(): object | string

Gets the source's data.

Returns: object | string (The source data)
on()
on(type: string, listener: Function): this

Adds an event listener for the specified event type.

Parameters:

Parameter Description
type The event type to listen for.
listener The callback function to execute when the event is fired.
Returns: this (The Source instance)
off()
off(type: string, listener: Function): this

Removes an event listener for the specified event type.

Parameters:

Parameter Description
type The event type to remove the listener from.
listener The callback function to remove.
Returns: this (The Source instance)
load()
load(): Promise<void>

Loads the source data asynchronously. Returns a promise that resolves when the data is loaded.

Returns: Promise<void>