TomTom Maps for JavaScript
    Preparing search index...

    Class HillshadeModule

    Map module for displaying terrain shading (hillshade).

    The HillshadeModule adds realistic terrain depth perception to the map by rendering shadow and highlight effects based on elevation data. This enhances the 3D appearance of mountainous and hilly terrain.

    Features:

    • Realistic terrain shading
    • Uses vector tile elevation data
    • Lightweight performance impact
    • Seamlessly integrates with other map layers
    • Toggle visibility on/off

    Common Use Cases:

    • Outdoor recreation maps (hiking, skiing)
    • Geographic/topographic applications
    • Environmental visualization
    • Landscape planning tools
    // Create the module with hillshade visible
    const hillshade = await HillshadeModule.getInstance(map, {
      visible: true
    });

    // Toggle visibility
    hillshade.setVisible(false);

    // Listen to events
    hillshade.events.on('click', (feature, lngLat) => {
      console.log('Clicked hillshade at:', lngLat);
    });

    Hillshade Guide

    Hierarchy (View Summary)

    Index

    Accessors

    events sourceAndLayerIDs

    Methods

    applyConfig getConfig isVisible resetConfig setVisible waitUntilModuleReady get

    Accessors

    • Gets the events interface for handling user interactions with hillshade.

      Returns EventsModule<MapGeoJSONFeature>

      An EventsModule instance for registering event handlers.

      Supported Events:

      • click: User clicks on the hillshade layer
      • contextmenu: User right-clicks
      • hover: Mouse enters hillshade area
      • long-hover: Extended hover
      hillshade.events.on('click', (feature, lngLat) => {
        console.log('Clicked terrain at:', lngLat);
      });
    • get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      Gets the source and layer identifiers for all sources managed by this module.

      This property provides access to the MapLibre source and layer IDs that were created and are managed by this module. These IDs can be used to interact directly with MapLibre's API or to identify which layers belong to this module.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its corresponding source ID and layer IDs. Each entry contains the MapLibre source identifier and an array of layer identifiers associated with that source.

      The returned IDs are useful when you need to:

      • Directly manipulate layers using MapLibre's native API
      • Identify which layers on the map belong to this module
      • Set layer ordering or positioning relative to other layers
      • Access source or layer properties through MapLibre methods
      const ids = myModule.sourceAndLayerIDs;
      console.log(ids);
      // {
      //   mySource: {
      //     sourceID: 'my-source-id',
      //     layerIDs: ['layer-1', 'layer-2']
      //   }
      // }

      // Use with MapLibre API
      const map = myModule.mapLibreMap;
      ids.mySource.layerIDs.forEach(layerId => {
        map.setLayoutProperty(layerId, 'visibility', 'visible');
      });

    Methods

    • Applies a configuration to this module.

      This method updates the module's behavior and appearance based on the provided configuration. The configuration is stored internally and will be automatically reapplied if the map style changes.

      Parameters

      • config: HillshadeModuleConfig | undefined

        The configuration object to apply to the module. Pass undefined to reset the configuration to default values.

      Returns void

      When a configuration is applied, the module updates its visual representation and behavior accordingly. The configuration persists across map style changes, ensuring consistent module behavior even when the map's base style is modified.

      // Apply a new configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Reset to default configuration
      myModule.applyConfig(undefined);
      • resetConfig for a convenience method to reset configuration
      • getConfig to retrieve the current configuration

    • Retrieves a copy of the current module configuration.

      This method returns a shallow copy of the configuration object that is currently applied to the module. If no configuration has been applied, it returns undefined.

      Returns NonNullable<HillshadeModuleConfig> | undefined

      A shallow copy of the current configuration object, or undefined if no configuration is currently applied. The returned object is a copy to prevent unintended modifications to the internal state.

      The returned configuration object is a shallow copy, which means that while the top-level properties are copied, any nested objects or arrays are still referenced from the original configuration. This is sufficient for most use cases but should be kept in mind when dealing with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, opacity: 0.8 }

      // When no config is applied
      myModule.resetConfig();
      console.log(myModule.getConfig()); // undefined

    • Checks if the hillshade layer is currently visible.

      Returns boolean

      true if visible, false if hidden.

      if (hillshade.isVisible()) {
        console.log('Terrain shading is active');
      }

    • Resets the configuration of this module to its default values.

      This is a convenience method that clears any previously applied configuration and restores the module to its initial state. This is equivalent to calling applyConfig(undefined).

      Returns void

      After calling this method, the module will behave as if no configuration was ever applied. Any custom settings, styling, or behavior modifications will be removed and replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, opacity: 0.5 });

      // Later, reset to defaults
      myModule.resetConfig();
      • applyConfig to apply a new configuration
      • getConfig to retrieve the current configuration before resetting

    • Sets the visibility of the hillshade layer.

      Parameters

      • visible: boolean

        true to show hillshade, false to hide it.

      Returns void

      Changes are applied immediately if the map is ready.

      hillshade.setVisible(true);  // Show terrain shading
      hillshade.setVisible(false); // Hide terrain shading

    • Retrieves a HillshadeModule instance for the given map.

      Parameters

      • map: TomTomMap

        The TomTomMap instance to attach this module to.

      • Optionalconfig: HillshadeModuleConfig

        Optional configuration for initialization and visibility.

      Returns Promise<HillshadeModule>

      A promise that resolves to the initialized HillshadeModule.

      Configuration:

      • visible: Initial visibility state
      • ensureAddedToStyle: Auto-add hillshade to style if missing

      Style Requirement:

      • Hillshade must be included in the map style or added via ensureAddedToStyle
      • Some styles may not support hillshade (e.g., satellite)

      Error if hillshade source is not in style and ensureAddedToStyle is false

      Default initialization:

      const hillshadeModule = await HillshadeModule.get(map);

      Auto-add to style if missing:

      const hillshadeModule = await HillshadeModule.get(map, {
        visible: true
      });

      Start hidden:

      const hillshadeModule = await HillshadeModule.get(map, {
        visible: false
      });

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods