Skip to content
Re:Earth Visualizer Re:Earth Visualizer Developer

reearth.timeline

The reearth.timeline namespace provides a set of methods and properties to manage and interact with the timeline functionality in the reearth environment. It is designed for scenarios where time-based data or animations need to be controlled, monitored, or synchronized.

Properties

startTime

The startTime property represents the beginning of the timeline in the reearth environment. It is an optional Date object that defines when the timeline starts. This property is useful for scenarios where the plugin needs to handle time-specific data or animations.

Syntax

reearth.timeline.startTime?: Date;
Date

A JavaScript Date object representing the start time of the timeline. If the startTime is not defined, the timeline’s start time is either irrelevant or dynamically determined.

Example

// Example: Check and log the timeline's start time
if (reearth.timeline.startTime) {
  console.log("Timeline Start Time:", reearth.timeline.startTime.toISOString());
} else {
  console.log("Timeline Start Time is not set.");
}

stopTime

The stopTime property represents the end of the timeline in the reearth environment. It is an optional Date object that defines when the timeline stops. This property is useful for managing time-bound data or animations within the plugin.

Syntax

reearth.timeline.stopTime?: Date;
Date

A JavaScript Date object representing the stop time of the timeline. If the stopTime is not defined, it may indicate that the timeline does not have a fixed end or is dynamically determined.

Example

// Example: Check and log the timeline's stop time
if (reearth.timeline.stopTime) {
  console.log("Timeline Stop Time:", reearth.timeline.stopTime.toISOString());
} else {
  console.log("Timeline Stop Time is not set.");
}

currentTime

The currentTime property represents the current time on the timeline in the reearth environment. It is an optional Date object that updates as the timeline progresses. This property is useful for synchronizing plugin events or data visualization with the timeline’s current position.

Syntax

reearth.timeline.currentTime?: Date;
Date

A JavaScript Date object representing the current time on the timeline. If the currentTime is not defined, it may indicate that the timeline is not initialized or currently inactive.

Example

// Example: Check and log the current timeline time
if (reearth.timeline.currentTime) {
  console.log(
    "Current Timeline Time:",
    reearth.timeline.currentTime.toISOString()
  );
} else {
  console.log("Current Timeline Time is not set.");
}

isPlaying

This property indicates whether the timeline is currently playing. It is a boolean value that reflects the playback state of the timeline. This property is useful for controlling or monitoring timeline animations and events.

Syntax

reearth.timeline.isPlaying?: boolean;

Type boolean

  • true: The timeline is currently playing.
  • false: The timeline is paused.

If isPlaying is not defined, it may indicate that the timeline has not been initialized.

Example

// Example 1: Log whether the timeline is playing or paused
if (reearth.timeline.isPlaying === true) {
  console.log("The timeline is currently playing.");
} else if (reearth.timeline.isPlaying === false) {
  console.log("The timeline is paused.");
} else {
  console.log("The timeline state is not set or unavailable.");
}


// Example 2: Trigger an animation when the timeline is playing
if (reearth.timeline.isPlaying) {
  console.log("Playing animation linked to the timeline...");
}


// Example 3: Toggle the playback state of the timeline
if (reearth.timeline.isPlaying !== undefined) {
  reearth.timeline.isPlaying = !reearth.timeline.isPlaying; // Toggle the state
  console.log(
    `Timeline is now ${reearth.timeline.isPlaying ? "playing" : "paused"}.`
  );
} else {
  console.log("Timeline state is not set or unavailable.");
}

speed

The speed property represents the playback speed of the timeline in the reearth environment. It is a numeric value that determines how quickly the timeline progresses relative to real time. This property is useful for controlling the pace of animations or data updates tied to the timeline.

Syntax

reearth.timeline.speed?: number;

Type number

A numeric value representing the playback speed of the timeline. For example, 1.0: Real-time playback, >1.0: Faster than real-time, <1.0: Slower than real-time. If the speed is not defined, it may indicate that the timeline’s playback speed is not set or initialized.

Example

// Example 1: Log the current playback speed of the timeline
if (reearth.timeline.speed !== undefined) {
  console.log("Timeline Playback Speed:", reearth.timeline.speed);
} else {
  console.log("Timeline speed is not set.");
}


// Example 2: Increase the timeline playback speed to double-time (2x)
reearth.timeline.speed = 2.0;
console.log("Playback speed set to:", reearth.timeline.speed);

stepType

This property defines the type of stepping used by the timeline to progress through time. This determines whether the timeline advances at a variable rate (proportional to time) or at fixed intervals. It is useful for controlling how data or animations tied to the timeline are updated.

Syntax

reearth.timeline.stepType?: "rate" | "fixed";

Type rate

The timeline progresses at a variable rate. This means the timeline advances continuously, and the progression speed is determined by the speed property.

Type fixed

The timeline progresses at fixed time intervals (e.g., every second, minute, or hour). This type is ideal for timelines with discrete steps or evenly spaced updates.

If stepType is not defined, the default stepping type may depend on the plugin’s configuration or the Reearth environment.

Example

// Example 1: Log the step type of the timeline
if (reearth.timeline.stepType) {
  console.log("Timeline Step Type:", reearth.timeline.stepType);
} else {
  console.log("Timeline step type is not set.");
}


// Example 2: Set the step type to 'rate' for continuous progression
reearth.timeline.stepType = "rate";
console.log("Timeline step type set to 'rate'.");


// Example 3: Set the step type to 'fixed' for discrete steps
reearth.timeline.stepType = "fixed";
console.log("Timeline step type set to 'fixed'.");

rangeType

The rangeType property defines how the timeline handles its range of time progression. It determines whether the timeline can extend beyond its defined startTime and stopTime or if it is constrained within specific bounds. This property is crucial for controlling the behavior of animations and events tied to the timeline.

Syntax

reearth.timeline.rangeType?: "unbounded" | "clamped" | "bounced";

Type unbounded

The timeline can extend beyond its defined startTime and stopTime. This allows the timeline to progress indefinitely, even past its boundaries. This type is useful for continuous animations or data updates.

Type clamped

The timeline is restricted to the range between startTime and stopTime. It cannot progress before the start or beyond the stop time. This type is useful for time-bound animations or events.

Type bounced

The timeline “bounces” back and forth between the startTime and stopTime, creating a loop-like effect. When the timeline reaches the end, it reverses direction and moves back to the start. This type is useful for creating continuous animations or cycles.

If rangeType is not defined, the behavior may default to the timeline’s configuration or remain unrestricted.

Example

// Example 1: Log the range type of the timeline
if (reearth.timeline.rangeType) {
  console.log("Timeline Range Type:", reearth.timeline.rangeType);
} else {
  console.log("Timeline range type is not set.");
}


// Example 2: Allow the timeline to progress indefinitely
reearth.timeline.rangeType = "unbounded";
console.log("Timeline range type set to 'unbounded'.");


// Example 3: Restrict the timeline to its start and stop times
reearth.timeline.rangeType = "clamped";
console.log("Timeline range type set to 'clamped'.");


// Example 4: Enable bouncing behavior for the timeline
reearth.timeline.rangeType = "bounced";
console.log("Timeline range type set to 'bounced'.");

Methods

tick

The tick method retrieves the current timeline tick value as a Date object. This method is useful for synchronizing animations or plugin-specific events with the timeline’s progression.

Syntax

reearth.timeline.tick?: () => Date | undefined;

Return Value:

Type Date | undefined

  • "Date": Represents the current tick value on the timeline as a Date object.
  • "undefined": If the timeline is uninitialized or inactive, the method returns undefined.

Example

// Example: Retrieve and log the current tick value
const tickValue = reearth.timeline.tick?.();
if (tickValue) {
  console.log("Current Tick Value:", tickValue.toISOString());
} else {
  console.log("Timeline tick is not set or the timeline is inactive.");
}

play

The play method starts the timeline’s playback. It is used to trigger the timeline to begin progressing through its range, resuming from its current state. This method is useful for scenarios involving animations, time-based data visualizations, or user-triggered timeline actions.

Syntax

reearth.timeline.play?: () => void;

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example: Play the timeline
if (reearth.timeline.play) {
  reearth.timeline.play();
  console.log("Timeline playback started.");
} else {
  console.log("The play method is not available.");
}

pause

The pause method halts the timeline’s playback without resetting its current position. This method is useful for temporarily stopping animations or time-based processes tied to the timeline, allowing playback to resume later from the same position.

Syntax

reearth.timeline.pause?: () => void;

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example: Pause the timeline
if (reearth.timeline.pause) {
  reearth.timeline.pause();
  console.log("Timeline playback paused.");
} else {
  console.log("The pause method is not available.");
}

setTime

This method allows users to set the start, stop, and current times of the timeline. This method is useful for dynamically controlling the timeline’s range and position, such as syncing animations or adjusting time-based data visualizations.

Syntax

reearth.timeline.setTime?: (time: Options) => void;

Parameters

time

The time object in the setTime method allows users to define three key points in the timeline.

Type:

type Options = {
  start: Date | string;
  stop: Date | string;
  current: Date | string;
};
  • start: Date | string;: Defines the starting point of the timeline.
  • stop: Date | string;: Defines the ending point of the timeline.
  • current: Date | string;: Defines the current point of time on the timeline.

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example: Set custom timeline times
if (reearth.timeline.setTime) {
  reearth.timeline.setTime({
    start: new Date("2023-01-01T00:00:00Z"),
    stop: new Date("2023-12-31T23:59:59Z"),
    current: new Date("2023-06-01T12:00:00Z"),
  });
  console.log("Timeline times set successfully.");
} else {
  console.log("The setTime method is not available.");
}

setSpeed

This method allows users to dynamically adjust the playback speed of the timeline. This method is useful for controlling how quickly the timeline progresses through its range, providing flexibility for animations or time-based data visualizations.

Syntax

reearth.timeline.setSpeed?: (speed: number) => void;

Parameters

speed

Type: number

A numeric value representing the playback speed of the timeline. 1.0: Real-time playback, >1.0: Faster than real-time (e.g., 2.0 doubles the speed), <1.0: Slower than real-time (e.g., 0.5 halves the speed).

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example 1: Set playback speed to real-time (1.0)
if (reearth.timeline.setSpeed) {
  reearth.timeline.setSpeed(1.0);
  console.log("Timeline speed set to real-time (1.0).");
} else {
  console.log("The setSpeed method is not available.");
}


// Example 2: Adjust timeline speed dynamically from user input
const userSelectedSpeed = 3.0; // Example user input


if (reearth.timeline.setSpeed) {
  reearth.timeline.setSpeed(userSelectedSpeed);
  console.log(`Timeline speed dynamically set to ${userSelectedSpeed}.`);
} else {
  console.log("The setSpeed method is unavailable.");
}

setStepType

The setStepType method allows users to dynamically adjust the stepping behavior of the timeline. This controls whether the timeline progresses at a variable rate (rate) or in fixed intervals (fixed). It is useful for customizing how the timeline handles time progression, such as for animations or data updates.

Syntax

reearth.timeline.setStepType?: (stepType: "rate" | "fixed") => void;

Parameters

stepType

Specifies the stepping behavior.

Type: "rate" | "fixed"

  • rate: The timeline progresses at a variable rate proportional to time, typically influenced by the playback speed (speed property).
  • fixed: The timeline progresses in fixed time intervals (e.g., every second, minute, or hour).

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example 1: Set timeline stepping to 'rate'
if (reearth.timeline.setStepType) {
  reearth.timeline.setStepType("rate");
  console.log("Timeline step type set to 'rate'.");
} else {
  console.log("The setStepType method is not available.");
}


// Example 2: Set timeline stepping to 'fixed'
reearth.timeline.setStepType?.("fixed");
console.log("Timeline step type set to 'fixed'.");


// Example 3: Set timeline step type dynamically based on data requirements
const requiresContinuousUpdates = true;


if (reearth.timeline.setStepType) {
  if (requiresContinuousUpdates) {
    reearth.timeline.setStepType("rate");
    console.log("Timeline step type dynamically set to 'rate'.");
  } else {
    reearth.timeline.setStepType("fixed");
    console.log("Timeline step type dynamically set to 'fixed'.");
  }
}

setRangeType

The setRangeType method allows users to dynamically define how the timeline handles its range of time progression. This method determines whether the timeline can extend beyond its defined startTime and stopTime, is restricted within those bounds, or “bounces” between the start and stop times in a looping effect.

Syntax

reearth.timeline.setRangeType?: (
  rangeType: "unbounded" | "clamped" | "bounced"
) => void;

Parameters

rangeType

Specifies the range behavior.

Type: "unbounded" | "clamped" | "bounced"

  • unbounded: The timeline can extend indefinitely beyond startTime and stopTime.
  • clamped: The timeline is restricted to the defined startTime and stopTime range.
  • bounced: The timeline “bounces” back and forth between startTime and stopTime, creating a loop-like effect.

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example 1: Allow the timeline to progress indefinitely
if (reearth.timeline.setRangeType) {
  reearth.timeline.setRangeType("unbounded");
  console.log("Timeline range type set to 'unbounded'.");
} else {
  console.log("The setRangeType method is not available.");
}


// Example 2: Restrict the timeline within the defined range
reearth.timeline.setRangeType?.("clamped");
console.log("Timeline range type set to 'clamped'.");


// Example 3: Enable bouncing behavior for the timeline
if (reearth.timeline.setRangeType) {
  reearth.timeline.setRangeType("bounced");
  console.log("Timeline range type set to 'bounced'.");
}


// Example 4: Dynamically set range type based on application needs
const useInfiniteTimeline = true;


if (reearth.timeline.setRangeType) {
  if (useInfiniteTimeline) {
    reearth.timeline.setRangeType("unbounded");
    console.log("Timeline range type dynamically set to 'unbounded'.");
  } else {
    reearth.timeline.setRangeType("clamped");
    console.log("Timeline range type dynamically set to 'clamped'.");
  }
}

Events

tick

The tick event fires every time the timeline’s current time updates. This is typically triggered as the timeline progresses or is manually adjusted.

Syntax

reearth.timeline.on("tick", (event: Date) => void): void;

Parameters

event: Date

A JavaScript Date object representing the timeline’s current time during the tick event.

Example

// Log each tick of the timeline's current time
reearth.timeline.on("tick", (e) => {
  console.log("Timeline tick at:", e.toISOString());
});


// Perform actions based on specific tick values
reearth.timeline.on("tick", (e) => {
  const targetTime = new Date("2023-12-25T00:00:00Z");
  if (e.getTime() === targetTime.getTime()) {
    console.log("Merry Christmas! Timeline reached the target time.");
  }
});

commit

The commit event fires whenever the timeline is modified due to an action, such as updates from widgets, plugins, or other timeline blocks.

Syntax

reearth.timeline.on("commit", (event: TimelineCommitter) => void): void;

Parameters

event: TimelineCommitter

An object describing the source of the timeline modification and additional metadata.

type TimelineCommitter = {
  source:
    | "widgetContext" // Timeline modifications from widget interactions
    | "pluginAPI" // Changes made through the plugin API
    | "featureResource" // Updates from feature-specific resources
    | "storyTimelineBlock" // Modifications from timeline blocks in stories
    | "storyPage" // Changes triggered by story page navigation
    | "initialize"; // Initial timeline setup
  id?: string;
};
  • source: string: Specifies the origin of the commit action.
  • id?: string: An optional identifier for the source of the commit.

Example

// Log commit source and ID when the timeline is modified
reearth.timeline.on("commit", (e) => {
  console.log(`Timeline commit from source: ${e.source}`);
  if (e.id) {
    console.log(`Commit ID: ${e.id}`);
  }
});


// Perform specific actions based on the commit source
reearth.timeline.on("commit", (e) => {
  if (e.source === "pluginAPI") {
    console.log("Timeline updated via Plugin API.");
  } else if (e.source === "storyPage") {
    console.log("Timeline updated by a story page.");
  }
});