Cesium Syntax Time

CesiumJS Time and Clock

Overview

CesiumJS is time-dynamic. A Clock advances a simulation time each frame, and Property objects evaluate their value at that time. JulianDate is the time type. SampledPositionProperty interpolates a position between time-stamped samples. TimeIntervalCollection defines when an entity exists.

Core principle: ALWAYS represent simulation time as a JulianDate, NEVER a JavaScript Date or a raw number. An animation advances ONLY when viewer.clock.shouldAnimate is true.

When to Use This Skill

Use this skill when ANY of these apply:

• An entity with a time-varying position does not move
• An animation is added but stays frozen
• A clock or timeline shows the wrong time
• A SampledPositionProperty returns undefined or the wrong position
• Choosing an interpolation algorithm for a track
• Controlling when an entity is visible with availability

Do NOT use this skill for glTF model animation playback detail; that is cesium-syntax-gltf-model. Do NOT use it for the Property abstraction or CallbackProperty; that is cesium-syntax-entity. Both skills share the clock described here.

JulianDate: the time type

JulianDate stores whole days and seconds-of-day separately, internally in International Atomic Time (TimeStandard.TAI). That storage makes its arithmetic leap-second-safe. NEVER build a JulianDate from raw day numbers by hand; ALWAYS use a factory.

const fromIso = Cesium.JulianDate.fromIso8601("2026-05-20T14:30:00Z");
const fromJsDate = Cesium.JulianDate.fromDate(new Date());
const rightNow = Cesium.JulianDate.now();

ALWAYS parse ISO 8601 strings with JulianDate.fromIso8601. It accepts every ISO 8601 form and is correct where Date.parse is unreliable.

JulianDate arithmetic uses static methods that write into a result argument and return it. They do NOT change their input.

const start = Cesium.JulianDate.fromIso8601("2026-05-20T00:00:00Z");
const
  start,
  3600,
  new Cesium.JulianDate(),
);
const order = Cesium.JulianDate.compare(start, oneHourLater); // negative
const gapSeconds = Cesium.JulianDate.secondsDifference(oneHourLater, start);

NEVER add time by writing to secondsOfDay directly; that field does not roll over into dayNumber. ALWAYS use JulianDate.addSeconds, addMinutes, addHours, or addDays.

Clock: driving simulation time

A Clock advances simulation time. The Viewer owns one, reachable as viewer.clock.

const viewer = new Cesium.Viewer("cesiumContainer");
const start = Cesium.JulianDate.fromIso8601("2026-05-20T00:00:00Z");
const stop = Cesium.JulianDate.addSeconds(start, 3600, new Cesium.JulianDate());

viewer.clock.startTime = start;
viewer.clock.stopTime = stop;
viewer.clock.currentTime = Cesium.JulianDate.clone(start);
viewer.clock.clockRange = Cesium.ClockRange.LOOP_STOP;
viewer.clock.multiplier = 60; // 60 simulated seconds per real second
viewer.clock.shouldAnimate = true;
viewer.timeline.zoomTo(start, stop);

shouldAnimate is false by default. NEVER expect a track or animation to move until viewer.clock.shouldAnimate is true, or shouldAnimate: true is passed to the Viewer constructor.

ALWAYS assign currentTime a JulianDate.clone of startTime. The clock mutates its currentTime object on each tick; a shared reference would corrupt startTime.

ClockRange controls behavior when currentTime reaches stopTime:

ClockStep controls how much time each tick() adds:

ALWAYS use TICK_DEPENDENT for deterministic, frame-rate-independent playback, such as a recorded video export.

ClockViewModel

ClockViewModel is the binding layer between a Clock and the Animation and Timeline widgets. The Viewer creates one; reach it as viewer.clockViewModel. Construct a standalone one with new Cesium.ClockViewModel(clock), where the Clock argument is optional. Call synchronize() to refresh the view model after changing the underlying clock outside the tick loop.

SampledPositionProperty: time-dynamic position

A SampledPositionProperty holds time-stamped positions and interpolates between them. Assign it to entity.position and the entity moves as the clock advances.

const positionProperty = new Cesium.SampledPositionProperty();

const samples = [
  { time: "2026-05-20T00:00:00Z", lon: 4.9, lat: 52.37, height: 1000 },
  { time: "2026-05-20T00:10:00Z", lon: 4.95, lat: 52.4, height: 1500 },
  { time: "2026-05-20T00:20:00Z", lon: 5.0, lat: 52.45, height: 1200 },
];
for (const s of samples) {
  positionProperty.addSample(
    Cesium.JulianDate.fromIso8601(s.time),
    Cesium.Cartesian3.fromDegrees(s.lon, s.lat, s.height),
  );
}

const aircraft = viewer.entities.add({
  position: positionProperty,
  point: { pixelSize: 12, color: Cesium.Color.YELLOW },
  path: { width: 2, material: Cesium.Color.CYAN },
});
viewer.trackedEntity = aircraft;

A SampledPositionProperty with one sample is constant; it can NEVER interpolate. ALWAYS add two or more samples for motion.

The constructor is new Cesium.SampledPositionProperty(referenceFrame, numberOfDerivatives). referenceFrame defaults to ReferenceFrame.FIXED. Set numberOfDerivatives to 1 ONLY when you also pass velocity vectors as the third addSample argument and intend to use Hermite interpolation.

Interpolation algorithms

By default a sampled property uses LinearApproximation at interpolationDegree 1. Change it with setInterpolationOptions.

positionProperty.setInterpolationOptions({
  interpolationAlgorithm: Cesium.LagrangePolynomialApproximation,
  interpolationDegree: 2,
});

ALWAYS keep interpolationDegree below the in-range sample count. A LagrangePolynomialApproximation at degree 5 needs at least 6 samples around the query time; with fewer, CesiumJS falls back to a lower degree and the curve is not the one configured. HermitePolynomialApproximation is correct ONLY when the property carries derivatives (numberOfDerivatives is above 0).

Extrapolation

Outside the sample range a sampled property extrapolates according to forwardExtrapolationType and backwardExtrapolationType. Both default to ExtrapolationType.NONE.

A track that vanishes before its first sample or after its last is the default NONE behavior. Set HOLD to park the entity at its endpoint.

positionProperty.forwardExtrapolationType = Cesium.ExtrapolationType.HOLD;
positionProperty.backwardExtrapolationType = Cesium.ExtrapolationType.HOLD;

TimeIntervalCollection and Entity.availability

A TimeIntervalCollection is a sorted, non-overlapping set of TimeIntervals. Assign one to entity.availability and the entity is shown ONLY while the clock is inside an interval.

const availability = new Cesium.TimeIntervalCollection([
  Cesium.TimeInterval.fromIso8601({
    iso8601: "2026-05-20T00:05:00Z/2026-05-20T00:18:00Z",
  }),
]);
aircraft.availability = availability;

Build intervals from ISO 8601 with TimeInterval.fromIso8601 for a single interval, or TimeIntervalCollection.fromIso8601 for a start, stop, or duration spec. A TimeInterval exposes isStartIncluded and isStopIncluded, both default true.

An entity whose availability excludes the current clock time is hidden even when its position is valid. When an entity will not appear during playback, ALWAYS check availability against viewer.clock.currentTime.

Decision: which time property

digraph time_property {
    rankdir=TB;
    node [shape=box, fontname="Helvetica"];
    start [label="A value that changes over time"];
    q_pos [shape=diamond, label="Is the value a position\non the globe?"];
    q_step [shape=diamond, label="Does the value jump\nbetween fixed states?"];
    use_spp [label="SampledPositionProperty\n(interpolated motion)"];
    use_sp [label="SampledProperty\n(interpolated scalar or vector)"];
    use_tivp [label="TimeIntervalCollectionProperty\n(discrete, no interpolation)"];

    start -> q_pos;
    q_pos -> use_spp [label="yes"];
    q_pos -> q_step [label="no"];
    q_step -> use_tivp [label="yes"];
    q_step -> use_sp [label="no, it interpolates"];
}

For controlling visibility windows rather than a value, use a TimeIntervalCollection on entity.availability.

Common Mistakes

Reference Files

• references/methods.md : the full JulianDate, Clock, ClockViewModel, SampledPositionProperty, SampledProperty, TimeIntervalCollection, and TimeInterval API, with enum members.
• references/examples.md : complete recipes for an animated track, a looping clock, interpolation tuning, extrapolation, and availability windows.
• references/anti-patterns.md : each time failure with symptom, root cause, and fix.

Related Skills

• cesium-syntax-entity : the Property abstraction, CallbackProperty, and path graphics that visualize a track.
• cesium-syntax-gltf-model : glTF model animations driven by this same clock.
• cesium-core-coordinates : Cartesian3 positions used as samples.
• cesium-syntax-viewer : the Animation and Timeline widgets on the Viewer.
• cesium-syntax-datasources : CZML, the time-dynamic data format.