{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "ff09d926",
   "metadata": {},
   "source": [
    "# Quick-start guide\n",
    "\n",
    "This page will guide you through the syntax and feature of Diplotocus.\n",
    "\n",
    "First, here are a few terms we will be using:\n",
    "- a `Timeline` is the main object of a project. It holds the figure, axes, and is responsible for running animations and rendering the video (See [Timeline](timeline) for more information).\n",
    "- a `plot object` is any matplotlib plotting function you are familiar with: `plot()`, `scatter()`, `hist()`, `text()`... (See [Plot objects](plot_objects) for more information).\n",
    "- an `animation` is what is applied to `plot objects` to animate it: `translate()`,`rotate()`,`tween`... (See [Animations](animations) for more information).\n",
    "- an `easing` is a mapping between frame number and time, that might not be linear ({doc}`See Easings <easings>` for more information).\n",
    "\n",
    "The basic steps involved in creating animations are the following:\n",
    "1. Create a `Timeline` object. Optionally, you can give it an existing figure, or define its initial properties.\n",
    "2. Create `plot objects`, like a scatter, plot, hist...\n",
    "3. Define `animations` for these `plot objects`, like a `translation`, a `rotation`, a `tween`...\n",
    "4. Render the animations to images using `Timeline.animate(plot_objects)`, where `plot_objects` is a list of the `plot objects` you created at step 2.\n",
    "5. Render the animation to a video file using `Timeline.save_video()`.\n",
    "\n",
    "<br/><br/>\n",
    "\n",
    "Let's go through the example on the main page step by step:\n",
    "\n",
    "First, we import our modules. By convention, we import diplotocus as dpl, *à la* import matplotlib.pyplot as plt."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4aba00f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import diplotocus as dpl\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "467509e5",
   "metadata": {},
   "source": [
    "Next, we create our Timeline object. Here, we don't pass an existing figure, so it will create one for us. We can give the initial X and Y limits of its axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "119f1382",
   "metadata": {},
   "outputs": [],
   "source": [
    "tl = dpl.Timeline(xlim=(0,6*np.pi),ylim=(-1,1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34790d30",
   "metadata": {},
   "source": [
    "We create our datapoints, and create our `plot` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f6cab3f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.linspace(0,6*np.pi,200)\n",
    "y = np.cos(x)\n",
    "\n",
    "p = dpl.plot(x=x,y=y)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37030a84",
   "metadata": {},
   "source": [
    "Next, we want our plot to appear gradually, each point being added frame after frame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1968968f",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.draw(duration=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "177c5401",
   "metadata": {},
   "source": [
    "Now we can render our animation to images. We call `Timeline.animate()` and we pass our `plot objects`. Here we only have one, so we can just pass it directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0b99d02",
   "metadata": {},
   "outputs": [],
   "source": [
    "tl.animate(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb7bc1fa",
   "metadata": {},
   "source": [
    "After the plot has fully been animated, we want to wait a few frames before animating our axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6dc5fb79",
   "metadata": {},
   "outputs": [],
   "source": [
    "tl.wait(duration=25)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92f889da",
   "metadata": {},
   "source": [
    "We want to animate our axis, by zooming out and moving its center to (0,0), simultaneously. We define our two animations, `axis_zoom` and `axis_move`, and we animate them through our `Timeline`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2e628fe5",
   "metadata": {},
   "outputs": [],
   "source": [
    "az = dpl.axis_zoom(zoom=0.5,duration=50)\n",
    "am = dpl.axis_move(end_pos=(0,0),duration=50)\n",
    "tl.animate((az,am))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c4680ff",
   "metadata": {},
   "source": [
    "For the final part of our animation, we want to fade out our plot. For that, we call `plot.hide()`, and we render it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "246ea578",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.hide(duration=100)\n",
    "tl.animate(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b4f6102",
   "metadata": {},
   "source": [
    "That's it! The only thing left to do is render our sequence of images to a video file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a9eceb6d",
   "metadata": {},
   "outputs": [],
   "source": [
    "tl.save_video(path='../_static/demo.mp4')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db90d731",
   "metadata": {},
   "source": [
    "<center>\n",
    "   <video width=\"640\" height=\"360\" autoplay loop muted playsinline>\n",
    "       <source src=\"../_static/demo.mp4\" type=\"video/mp4\">\n",
    "   </video>\n",
    "</center>\n",
    "\n",
    "Et voilà! This is a very simple example, but **Diplotocus** is capable of much more. You might want to add {doc}`easing functions <easings>` to your animation to make them feel more natural and smooth. You can also render your animations without axes, with a transparent background, with white axes for a dark presentation...\n",
    "\n",
    "If your animation gets complex, you might want to try the {doc}`GUI <GUI>` version of **Diplotocus**, which lets you build a timeline in your browser with simple controls."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}