{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8d19c6fc-e236-45bd-8d1f-473ce19c606a",
   "metadata": {},
   "source": [
    "© Copyright, 2025 G. Schaer.\n",
    "\n",
    "SPDX-License-Identifier: GPL-3.0-only"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf7d1faf-8364-4671-abf3-744c936b7fd5",
   "metadata": {},
   "source": [
    "# Animator Example Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "143af5f9-9d77-4029-809e-fa124d0a27c1",
   "metadata": {},
   "source": [
    "This module provides an example usage case for the animator. Here we create\n",
    "a figure with 2 plots, 1 line plot and 1 bar chart. On the line plot, we plot\n",
    "2 lines. On the bar chart, we show 4 bars."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "582caf6f-a776-47d4-99a0-3728f2baa27e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Required imports\n",
    "import time\n",
    "from condynsate import Animator\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5cb5af19-8037-4583-8184-5fd99fa0db1c",
   "metadata": {},
   "source": [
    "First we create the animator. In this case, we set the frame rate to 20 fps, and tell it not to record"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "0202d27d-4d45-4efe-8fd4-acaeeacecd70",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the animator with a frame rate of 20 fps\n",
    "animator = Animator(frame_rate=20.0, record=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50c5bdce-94d1-4ddb-b51b-2e2baf815f23",
   "metadata": {},
   "source": [
    "Next, we add the plots that we want to the animator. In this case, we want one line plot with two lines and one bar chart with 4 bars."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b1625a38-a762-419d-90d6-8732800966e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the line plot. add_lineplot will return a list of length\n",
    "# n_lines. In the case n_lines==1, then it will return a single value.\n",
    "# These values are used to index each line on the line plot.\n",
    "lines = animator.add_lineplot(\n",
    "    n_lines=2, #add 2 lines to the plot\n",
    "    color=['k','g'], #color then black and green\n",
    "    tail=[33, -1], #give one a tail and the other infinite length\n",
    "    line_style=['-','--'], #set the line styles to solid and dashed\n",
    "    label=['Line 1','Line 2'], #name one Line 1 and the other Line 2\n",
    "    y_lim=[0,1], #set the y limits of the plot to 0 to 1\n",
    "    x_label='Index', #set the x axis label of the plot\n",
    "    y_label='Value', #set the y axis label of the plot\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "ac187127-718a-443f-9aac-24c6d525a6a6",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the bar chart. Similarly, add_barchart returns either a list of\n",
    "# length n_bars or a single value.\n",
    "bars = animator.add_barchart(\n",
    "    n_bars=4, #add 4 bars to the chart\n",
    "    color=['k', 'r', 'g', 'b'], #color each bar a unique color\n",
    "    label=['Bar 1','Bar 2','Bar 3','Bar 4'], #name each bar\n",
    "    x_lim=[-1.1, 1.1], #set the x limits of the plot to -1.1 to 1.1\n",
    "    x_label='Number', #set the x axis label of the plot\n",
    "    v_zero_line=True #add a thin vertical line at x=0\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64c7266d-3d3a-4ca4-8ffb-ca388025af58",
   "metadata": {},
   "source": [
    "Note that the animator GUI is not open even though we have initialized an instance of the `Animator` class and added plots to it. This is because the main GUI loop does not start until the `start` function is called. Once this function is called, it is up to the user to keep the GUI responsive. This is done by either calling the `refresh` function regularly, or call any of the functions that also refresh the animator. The functions that refresh the animator automatically are \n",
    "1. `barchart_set_value`\n",
    "2. `lineplot_append_point`\n",
    "3. `lineplot_set_data`\n",
    "4. `reset`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "be7e04d9-fca7-4ac6-949d-942ff9a6e769",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Start the animator. This will open the GUI and start the rendering thread\n",
    "animator.start() # returns 0 on success"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "74841ab5-80a9-459f-b45e-89b87fbb171b",
   "metadata": {},
   "source": [
    "Now we can start the animation loop. To update the line plot, we call the `lineplot_append_point` or `lineplot_set_data` functions. To denote which line on the plot we are updating the data of, we can use the return value of `add_lineplot`. A similary process is used for updating the bar chart with the `barchart_set_value` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "19f19f4d-a4ea-499d-85ba-fc95367f4b70",
   "metadata": {},
   "outputs": [],
   "source": [
    "N = 200\n",
    "for i in range(N):\n",
    "    percent_done = i/(N-1)\n",
    "    \n",
    "    # Add a point at the current step index to both lines in the line plot\n",
    "    animator.lineplot_append_point(lines[0], i, np.random.rand())\n",
    "    animator.lineplot_append_point(lines[1], i, percent_done**2)\n",
    "\n",
    "    # Set the values of each bar in the bar chart to something\n",
    "    if i % 4 == 0: #Every fourth step update the bars\n",
    "        animator.barchart_set_value(bars[0], percent_done**2)\n",
    "        animator.barchart_set_value(bars[1], -percent_done**3)\n",
    "        animator.barchart_set_value(bars[2], np.sin(np.pi*percent_done))\n",
    "        animator.barchart_set_value(bars[3], np.random.rand()*2-1)\n",
    "    time.sleep(0.05)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d766bf9d-ff30-4726-8ab4-5306c228399c",
   "metadata": {},
   "source": [
    "When done, terminate the animator to gracefully exit all children threads and close the GUI"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "4ccc2e65-5565-4bad-9f39-f9a03562b6af",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "animator.terminate() # returns 0 on success"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.14.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}