Animations

ImportantExperimental Feature

Animations are an experimental feature in MolViewSpec. The API may change in future releases. Use with caution in production environments.

TipWhat are Animations?

Animations create smooth transitions between different states of your visualization, such as color changes or opacity fades over time.

MolViewSpec supports animations to create dynamic, time-based visualizations that can show molecular processes, guide viewer attention, or create cinematic presentations.

Animation Use Cases

Scientific Storytelling

  • Molecular mechanisms: Show conformational changes or binding events
  • Guided tours: Direct attention to different regions sequentially
  • Process visualization: Illustrate multi-step biochemical processes

Presentations

  • Progressive disclosure: Reveal structure elements one at a time
  • Emphasis: Fade in/out or change colors to highlight features

How Animations Work

Animations in MolViewSpec use references (ref) to target specific properties:

  1. Add ref to properties you want to animate (color, opacity, etc.)
  2. Create an animation using builder.animation()
  3. Add interpolations to animate between values over time
  4. The animation automatically runs when the scene is loaded

Basic Animation Pattern

Opacity Animation

Color Animation

Multiple Animations

Animate multiple properties simultaneously:

Sequential Animations

Use start_ms to create sequences:

Progressive Reveal Pattern

Fade in components one by one:

Animating Labels

You can also animate primitive properties like label opacity:

Animation Parameters

builder.animation()

Creates an animation controller. Optional parameters:

  • custom: Custom Molstar animations (e.g., camera rock)

    const anim = builder.animation({
  custom: {
    molstar_trackball: {
      name: 'rock',
      params: { speed: 0.05 }
    }
  }
});

interpolate()

Creates an interpolation between values:

Common Parameters: - target_ref: Reference to the property to animate - property: Property name ("color", "opacity", "label_opacity") - start_ms: When to start (milliseconds from scene start) - duration_ms: Animation duration (milliseconds)

For Color Animations (kind: "color"): - palette: Color gradient - kind: "continuous": Smooth gradient - colors: Array of color values

For Scalar Animations (kind: "scalar"): - end: Ending value (starting value comes from the ref) - easing: Optional easing function

Easing Functions

Control the acceleration of animations:

  • "linear" - Constant speed
  • "cubic-in" - Start slow, accelerate
  • "cubic-out" - Start fast, decelerate
  • "cubic-in-out" - Start and end slow, fast in middle
  • "quadratic-in", "quadratic-out", "quadratic-in-out"
  • "exponential-in", "exponential-out", "exponential-in-out"
anim.interpolate({
  kind: 'scalar',
  target_ref: 'protein_opacity',
  start_ms: 0,
  duration_ms: 2000,
  property: 'opacity',
  end: 0.3,
  easing: 'cubic-in-out'
});

Custom Camera Animations

Add camera movements to your animations:

const anim = builder.animation({
  custom: {
    molstar_trackball: {
      name: 'rock',        // Rock the camera back and forth
      params: { speed: 0.05 }
    }
  }
});

Available camera animations: - 'rock' - Rock back and forth - 'spin' - Continuous rotation

Animation in MolViewStories

NoteStory Scenes as Animation Frames

In MolViewStories, each scene can represent a “frame” in your narrative. Scene transitions provide a higher-level alternative to MolViewSpec animations.

MolViewStories provides complementary approaches: - Scene transitions: Move between different states - Scene-specific cameras: Different viewpoints per scene - Progressive scenes: Build complexity across multiple scenes - MolViewSpec animations: Smooth transitions within a single scene

Performance Tips

WarningAnimation Performance
  • Short durations: Keep animations under 3-5 seconds for best UX
  • Limit simultaneous animations: Too many at once can cause lag
  • Simple representations: Cartoon animates faster than surface
  • Test on target devices: Performance varies by hardware

Accessibility Considerations

ImportantMotion Sensitivity

Some users may be sensitive to motion. Consider: - Providing slower transitions by default - Avoiding rapid color changes or flashing - Including a note that animations are present - Testing with users who have vestibular disorders

See Also