Home

Awesome

Leaflet TimeDimension

Add time dimension capabilities on a Leaflet map.

screenshot

Examples and basic usage

Checkout the Leaflet TimeDimension Demos.

Basic usage:

<html>
    <head>
        <title>Leaflet TimeDimension Demo</title>
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.5.1/dist/leaflet.css" />
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet-timedimension@1.1.1/dist/leaflet.timedimension.control.min.css" />
    </head>
    <body>
        <div id="map" style="height: 100%; width: 100%"></div>
        <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/leaflet@1.5.1/dist/leaflet.js"></script>
        <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/iso8601-js-period@0.2.1/iso8601.min.js"></script>
        <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/leaflet-timedimension@1.1.1/dist/leaflet.timedimension.min.js"></script>
        <script type="text/javascript" src="example.js"></script>
    </body>
</html>
// example.js
var map = L.map('map', {
    zoom: 10,
    center: [38.705, 1.15],
    timeDimension: true,
    timeDimensionOptions: {
        timeInterval: "2014-09-30/2014-10-30",
        period: "PT1H"
    },
    timeDimensionControl: true,
});

var wmsUrl = "https://thredds.socib.es/thredds/wms/observational/hf_radar/hf_radar_ibiza-scb_codarssproc001_aggregation/dep0001_hf-radar-ibiza_scb-codarssproc001_L1_agg.nc"
var wmsLayer = L.tileLayer.wms(wmsUrl, {
    layers: 'sea_water_velocity',
    format: 'image/png',
    transparent: true,
    attribution: 'SOCIB HF RADAR | sea_water_velocity'
});

// Create and add a TimeDimension Layer to the map
var tdWmsLayer = L.timeDimension.layer.wms(wmsLayer);
tdWmsLayer.addTo(map);

For more control over each object creation, you can create timeDimension objects manually, see Example 9

API

L.Map

This plugin will attach to a Map a TimeDimension object and a related TimeDimension Control if timeDimension and timeDimensionControl options are included.

OptionTypeDefaultDescription
timeDimensionBooleanfalseAutomatically creates a new TimeDimension object linked to the map if set to true.
timeDimensionOptionsObject{}Options for the TimeDimension object.
timeDimensionControlBooleanfalseAutomatically adds a TimeDimension Control to the map if set to true.
timeDimensionControlOptionsObject{}Options for the TimeDimension Control object.

L.TimeDimension

TimeDimension object manages the time component of a layer. It can be shared among different layers and it can be added to a map, and become the default timedimension component for any layer added to the map.

In order to include a TimeDimension in the map, add timeDimension: true as an option when creating the map.

Usage example

L.timeDimension().addTo(map);

Creation

FactoryDescription
L.timeDimension(<Object> options?)

<a name="timeDimensionOptions"></a>Options

This options can be set up when creating the map with the option timeDimensionOptions.

OptionTypeDefaultDescription
timesNumbernullIt can be: a) An array of times (in milliseconds). b) String of dates separated by commas. c) String formed by start date/end date/period. If null, it will be constructed according to timeInterval and period
timeIntervalString"P1M/" + todayString to construct the first available time and the last available time. Format: ISO8601 Time inverval
periodString"P1D"Used to construct the array of available times starting from the first available time. Format: ISO8601 Duration
validTimeRangeStringundefinedFilter the array of available times by start hour and end hour (for any date). Format "HH:MM/HH:MM".
currentTimeNumberClosest available timeCurrent time to be loaded. Time in ms.
loadingTimeoutNumber3000Maximum time in milliseconds that the component will wait to apply a new time if synced layers are not ready
lowerLimitTimeNumberundefined
upperLimitTimeNumberundefined

Events

EventDataDescription
timeloadingtimeFired when a new time is required to load
timeloadtimeFired when a all synced layers have been loaded/prepared for a new time (or timeout)
availabletimeschangedavailableTimes, currentTimeFired when the list of available times have been updated
limitschangedlowerLimit, upperLimitFired when range limits changed. Limits are expressed in index value

Methods

MethodReturnsDescription
getAvailableTimes()Array of timesArray of all the available times of the TimeDimension
getCurrentTime()timeCurrent time of the Time Dimension
setCurrentTime(<Number> time)-Modify the current time. If the time argument is not among the available times, the previous closest time will be selected
nextTime(<Number> numSteps, <Boolean> loop)-Move the current time n steps forward in the available times array
previousTime(<Number> numSteps, <Boolean> loop)-Move the current time n steps backward in the available times array
prepareNextTimes(<Number> numSteps, <Number> howmany, <Boolean> loop)-Fire 'timeloading' for severals times (in order to pre-load layers)
registerSyncedLayer(<L.TimeDimension.Layer> layer)-TimeDimension will check if all layers are ready before firing timeload. It will listen to "timeload" event of these layers.
unregisterSyncedLayer(<L.TimeDimension.Layer> layer)-
setAvailableTimes(<Array> times, <String> mode)-Update available times of the TimeDimension with a new array of times (in ms). Mode : Update modes

L.TimeDimension.Layer

TimeDimension.Layer is an abstract Layer that can be managed/synchronized with a TimeDimension. The constructor recieves a layer (of any kind) and options.

Any children class should implement _onNewTimeLoading, isReady and _update functions to react to time changes.

<a name="timeDimensionLayerOptions"></a>Options

OptionTypeDefaultDescription
timeDimension<L.TimeDimension>nullTimeDimension object which will manage this layer. If it is not defined, the map TimeDimension will be attached when adding this layer to the map.
opacityNumber1
zIndexNumber1

Events

EventDataDescription
timeloadtimeFires when a the layer has been loaded/prepared for a new time

L.TimeDimension.Layer.WMS

Implements a TimeDimension Layer for a given WMS layer, which can be a L.TileLayer.WMS or a L.NonTiledLayer.WMS.

This component synchronizes the WMS with a TimeDimension, modifying the time parameter in the WMS requests.

Usage example

L.timeDimension.layer.wms(layer).addTo(map);

Creation

FactoryDescription
L.timeDimension.layer.wms(<L.Layer> layer, <Object> options?)

<a name="timeDimensionLayerWMSOptions"></a>Options

OptionTypeDefaultDescription
cacheNumber0
cacheBackwardNumbercache or 0Number of layers that can be kept hidden on the map for previous times
cacheForwardNumbercache or 0Number of layers that can be kept hidden on the map for future times
updateTimeDimensionBooleanfalseUpdate the list of available times of the attached TimeDimension with the available times obtained by getCapabilities
updateTimeDimensionModeString"intersect"Operation to merge the available times of the TimeDimension and the layer (intersect, union, replace or extremes). See Update modes
requestTimeFromCapabilitiesBooleanfalseGet list of available times for this layer from getCapabilities
proxyStringnullURL of the proxy used to obtain getCapabilities responses from the WMS server avoiding cross site origin problems
getCapabilitiesParamsObject{}Extra parameters needed to create getCapabilities request
getCapabilitiesUrlStringnullAlternative URL for the GetCapabilities request (useful if using a cache service like GeoWebCache)
getCapabilitiesLayerNameStringnullAlternative layer name for the GetCapabilities request (useful if using a cache service like GeoWebCache)
setDefaultTimeBooleanfalseIf true, it will change the current time to the default time of the layer (according to getCapabilities)
periodStringnullDuration between times that will be used to generate the available times of the layer from a time interval. It overwrites the value received in getCapabilities (if not null). Format: ISO8601 Duration
wmsVersionStringlayer.options.version or "1.1.1"WMS version of the layer. Used to construct the getCapabilities request

L.TimeDimension.Layer.GeoJSON

Manages a GeoJSON layer with a TimeDimension. According to GeoJSON specification, geometry coordinates can have only three dimensions: latitude, longitude and elevation. There isn't a standard way to add time dimension information. This plugin will search for some attributes inside properties:

This component will create and show new GeoJSON layers which include only those features (or part of them) that are active for the time of the TimeDimension (according to a duration option). These new layers will inherit the baseLayer options. In the case of LineStrings, if addlastPoint option is enabled, a Point feature will be added with the property last (that can be used to customize the marker of this special Point).

Usage example

L.timeDimension.layer.geoJson(layer).addTo(map);

Creation

FactoryDescription
L.timeDimension.layer.geoJson(<L.Layer> layer, <Object> options?)

<a name="timeDimensionLayerGeoJSONOptions"></a>Options

OptionTypeDefaultDescription
durationStringnullPeriod of time which the features will be shown on the map after their time has passed. If null, all previous times will be shown. Format: ISO8601 Duration
addlastPointBooleanfalseAdd a Point at the last valid coordinate of a LineString.
waitForReadyBooleanfalseIf true, it will wait until the baseLayer is loaded to mark itself as ready. You can use it with layers created using leaflet-omnivore.
updateTimeDimensionBooleanfalseUpdate the list of available times of the attached TimeDimension with the available times of this GeoJSON
updateTimeDimensionModeString"extremes"Operation to merge the available times of the TimeDimension and the layer (intersect, union, replace or extremes)
updateCurrentTimeBooleanupdateTimeDimensionAutomatically change the current time of map to the first available time of the GeoJSON layer.

L.Control.TimeDimension

Leaflet control to manage a timeDimension. With play|pause, next, back, current time, time slider and speed slider controls.

Usage example

L.control.timeDimension().addTo(map);

Creation

FactoryDescription
L.control.timeDimension(<Object> options?)

<a name="timeDimensionControlOptions"></a>Options

OptionTypeDefaultDescription
timeDimension<L.TimeDimension>null
styleNSString"leaflet-control-timecontrol"
positionString"bottomleft"
titleString"Time Control"
backwardButtonBooleantrueShow backward button
forwardButtonBooleantrueShow forward button
playButtonBooleantrueShow play/pause button
playReverseButtonBooleanfalse
loopButtonBooleanfalseShow loop button to enable/disable loop animation
displayDateBooleantrueShow display date control
timeSliderBooleantrueShow time slider control
timeSliderDragUpdateBooleanfalseUpdate the map when dragging
limitSlidersBooleanfalseShow limit knobs on the time slider to restrict animation range
limitMinimumRangeNumber5The minimum number of steps allowed in animation range
speedSliderBooleantrueShow speed slider control
minSpeedNumber0.1Minimum selectable value for speed slider in fps (1000/transitionTime)
maxSpeedNumber10Maximum selectable value for speed slider in fps
speedStepNumber0.1Speed slider step size
timeStepsNumber1Number of time steps applied to the TimeDimension (forwards or backwards) in a time change
autoPlayBooleanfalseAnimate the map automatically
player<L.TimeDimension.Player>undefinedAttach an existing player to that control
playerOptionsObject{transitionTime: 1000}Options for the TimeDimension Player object attached.(Cannot be used with player option)
timeZonesArray of strings["UTC", "Local"]Clicking on the date cycles between these

L.TimeDimension.Player

Component to animate a map with a TimeDimension, changing the time periodically.

Usage example

var player = new L.TimeDimension.Player({}, timeDimension).addTo(map);

Creation

FactoryDescription
L.TimeDimension.Player(<Object> options?, <L.TimeDimension> timeDimension)

<a name="timeDimensionPlayerOptions"></a>Options

OptionTypeDefaultDescription
transitionTimeNumber1000Milliseconds that the player will wait to check and launch the next time in the TimeDimension
bufferNumber5(Number or Function) Number of times forward that will be requested in each iteration. Function callback will be called with 3 parameters (transitionTime, minBufferReady, loop)
minBufferReadyNumber1If this option is greater than 0, the player will full the buffer every time the number of next ready times (next layers ready) is below this number.
loopBooleanfalseLoop the animation when it reaches the last available time
startOverBooleanfalseWhen the player is at the last position, it start over to the beginning when the user press play

<a name="timeDimensionPlayerEvents"></a>Events

List of events triggered by the player. Register with .on()

EventDataDescription
play-When the animation is started/unpaused
running-When the animation is resuming after a waiting state
stop-When the animation is stopped/paused
waitingbuffer, availableWhen the animation is waiting for some layers to be loaded
animationfinished-When the animation has reached the end of the timeline (loop is disabled)
loopchangeloopWhen the loop setting is changed
speedchangetransitionTime, bufferWhen the transitionTime setting is changed

<a name="timeDimensionPlayerMethod"></a>Methods

MethodReturnsDescription
start(<Number> numSteps)-Start animation
stop()-Stop active animation
pause()-Pause active animation
release()-Resume animation paused
getTransitionTime()<Number>Return the time interval between two animation steps (in milliseconds)
setTransitionTime(<Number> transitionTime)-Change the time interval between two animation steps
isLooped()<Boolean>Return the loop state
setLooped(<Boolean> looped)-Activate/Desactivate the loop state

TimeDimension update modes

Update mode can be one of these values: intersect, union, replace, extremes.

Requisites

Talks

Bugs, issues and contributions

Contributions and criticisms are welcome.

If you have any doubt or problem, please fill an issue!

If you fix something or want to add some contribution, many thanks in advance!