notebooks/animation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# MeshCat Animations\n",
    "\n",
    "MeshCat.jl also provides an animation interface, built on top of the [three.js animation system](https://threejs.org/docs/#manual/introduction/Animation-system). While it is possible to construct animation clips and tracks manually, just as you would in Three.js, it's generally easier to use the MeshCat `Animation` type.\n",
    "\n",
    "Let's show off building a simple animation. We first have to create our scene: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Optional: \n",
    "# These commands tell the Julia package manager to use the exact\n",
    "# set of dependencies specified in the Project.toml file in this folder. \n",
    "# That should give you a nice, reproducible environment for testing. \n",
    "\n",
    "using Pkg\n",
    "Pkg.activate(@__DIR__)\n",
    "Pkg.develop(Pkg.PackageSpec(path=dirname(@__DIR__)))\n",
    "Pkg.instantiate()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "using MeshCat, GeometryBasics, CoordinateTransformations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "vis = Visualizer()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a few different ways of opening the visualizer:\n",
    "- In a new browser tab with `open(vis)`.\n",
    "- Inside this jupyter notebook with `render(vis)`.\n",
    "- In a standalone window with\n",
    "    ```julia\n",
    "    import Electron\n",
    "    open(vis, Electron.Application())\n",
    "    ```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "render(vis)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "setobject!(vis[:box1], Rect(Vec(0, 0, 0), Vec(0.1, 0.2, 0.3)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Building an Animation\n",
    "\n",
    "We construct an animation by first creating a blank `Animation()` object. We can then use the `atframe` function to set properties or transforms of the animation at specific frames of the animation. Three.js will automatically interpolate between whatever values we provide. \n",
    "\n",
    "For example, let's animate moving the box from [0, 0, 0] to [0, 1, 0]: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "anim = Animation(vis)\n",
    "\n",
    "atframe(anim, 0) do\n",
    "    # within the context of atframe, calls to \n",
    "    # `settransform!` and `setprop!` are intercepted\n",
    "    # and recorded in `anim` instead of having any\n",
    "    # effect on `vis`.\n",
    "    settransform!(vis[:box1], Translation(0, 0, 0))\n",
    "end\n",
    "\n",
    "atframe(anim, 30) do\n",
    "    settransform!(vis[:box1], Translation(0, 1, 0))\n",
    "end\n",
    "\n",
    "# `setanimation!()` actually sends the animation to the\n",
    "# viewer. By default, the viewer will play the animation\n",
    "# right away. To avoid that, you can also pass `play=false`. \n",
    "setanimation!(vis, anim)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should see the box slide 1 meter to the right in the viewer. If you missed the animation, you can run it again from the viewer. Click \"Open Controls\", find the \"Animations\" section, and click \"play\". "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Animating the Camera\n",
    "\n",
    "The camera is just another object in the MeshCat scene. To set its transform, we just need to index into the visualizer with the right path (note the leading `/`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "settransform!(vis[\"/Cameras/default\"], Translation(0, 0, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To animate the camera, we just have to do that same kind of `settransform!` to individual frames in an animation: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "anim = Animation(vis)\n",
    "\n",
    "atframe(anim, 0) do\n",
    "    settransform!(vis[\"/Cameras/default\"], Translation(0, 0, 0))\n",
    "end\n",
    "\n",
    "atframe(anim, 30) do\n",
    "    settransform!(vis[\"/Cameras/default\"], Translation(0, 0, 1))\n",
    "end\n",
    "\n",
    "setanimation!(vis, anim)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also animate object properties. For example, let's animate the camera's `zoom` property to smoothly zoom out and then back in. Note that to do this, we have to access a deeper path in the visualizer to get to the actual camera object. For more information, see: https://github.com/meshcat-dev/meshcat#camera-control"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "anim = Animation(vis)\n",
    "\n",
    "atframe(anim, 0) do\n",
    "    setprop!(vis[\"/Cameras/default/rotated/<object>\"], \"zoom\", 1.0)\n",
    "end\n",
    "\n",
    "atframe(anim, 30) do\n",
    "    setprop!(vis[\"/Cameras/default/rotated/<object>\"], \"zoom\", 0.5)\n",
    "end\n",
    "\n",
    "atframe(anim, 60) do\n",
    "    setprop!(vis[\"/Cameras/default/rotated/<object>\"], \"zoom\", 1.0)\n",
    "end\n",
    "\n",
    "setanimation!(vis, anim)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Making Objects Appear and Disappear\n",
    "\n",
    "MeshCat does not support adding or deleting objects in frames of an animation. Instead, you will need to call `setobject!` ahead of time to add all the objects in the scene, then call `setvisible!` on individual frames to toggle the visibility of objects on and off. \n",
    "\n",
    "Let's demonstrate this by animating a moving box and a sphere which appears halfway through the animation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "setobject!(vis[:box1], Rect(Vec(0.0, 0, 0), Vec(0.1, 0.2, 0.3)))\n",
    "setobject!(vis[:sphere], HyperSphere(Point(0.0, 0, 0), 0.25))\n",
    "\n",
    "# Start with the sphere hidden\n",
    "setvisible!(vis[:sphere], false)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "anim = Animation(vis)\n",
    "atframe(anim, 0) do\n",
    "    setvisible!(vis[:sphere], false)\n",
    "    settransform!(vis[:box1], Translation(0.0, 0, 0))\n",
    "end\n",
    "\n",
    "atframe(anim, 15) do\n",
    "    setvisible!(vis[:sphere], true)\n",
    "end\n",
    "\n",
    "atframe(anim, 30) do\n",
    "    settransform!(vis[:box1], Translation(0.0, 1, 0))\n",
    "end\n",
    "\n",
    "setanimation!(vis, anim)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Recording an Animation\n",
    "\n",
    "To record an animation at a smooth, fixed frame rate, click on \"Open Controls\" in the viewer, and then go to \"Animations\" -> \"default\" -> \"Recording\" -> \"record\". This will play the entire animation, recording every frame and then let you download the resulting frames to your computer. \n",
    "\n",
    "To record activity in the MeshCat window that isn't a MeshCat animation, we suggest using a screen-capture tool like Quicktime for macOS or RecordMyDesktop for Linux. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Converting the Animation into a Video\n",
    "\n",
    "Currently, meshcat can only save an animation as a `.tar` file consisting of a  list of `.png` images, one for each frame. To convert that into a video, you can run: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MeshCat.convert_frames_to_video(expanduser(\"~/Downloads/meshcat_1528401494656.tar\"))"
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Julia 1.11.1",
   "language": "julia",
   "name": "julia-1.11"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.11.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}