Add animation documentation

README.adoc

@@ -1,4 +1,6 @@
 = ReCo.jl
+:source-highlighter: highlight.js
+:highlightjs-languages: bash, julia
 
 image:https://img.shields.io/badge/code%20style-blue-4495d1.svg[Code Style: Blue, link=https://github.com/invenia/BlueStyle]
 
@@ -20,7 +22,7 @@ julia --threads auto
 
 `auto` automatically sets the number of threads to use. If you want to use a specific number `N` of threads, replace `auto` with `N`.
 
-=== Acitivating environment
+=== Activating environment
 
 After launching Julia, the package environment has to be activated by running the follwing in the REPL:
 
@@ -32,7 +34,7 @@ Pkg.activate(".")
 
 === Install dependencies
 
-After activating the package environment, run the follwing to install the package dependencies:
+After activating the package environment, run the following to install the package dependencies:
 
 [source,julia]
 ----
@@ -48,7 +50,11 @@ You can import the package by running:
 using ReCo
 ----
 
-This will export the package methods that are intended to be used by the end user.
+This will export the package's methods that are intended to be used by the end user.
+
+== Help mode
+
+To access the documentation of the presented package methods further in this README, run `using ReCo` first. Then, enter the help mode by pressing `?` in the REPL. Now, enter the method's name followed by enter to see its documentation.
 
 == Run simulation
 
@@ -66,13 +72,20 @@ Run the simulation:
 run_sim(sim_dir, duration=20.0)
 ----
 
-The values for the number of particles, self-propulsion velocity and simulation duration are used here as an example. For more information about possible values and other optional arguments, press `?` in the REPL after running `using ReCo`. Then type `init_sim` or `run_sim` followed by pressing enter. This will show the method's documention.
+The values for the number of particles, self-propulsion velocity and simulation duration are used here as an example. For more information about possible values and other optional arguments, see the documentation of `init_sim` or `run_sim`.
 
 == Simulation visualization
 
 === Animation
 
-//TODO
+To generate an animation of a simulation, run the following:
+
+[source,julia]
+----
+animate(sim_dir)
+----
+
+The method's documentation includes all possible optional arguments.
 
 === Snapshot plot
 
@@ -86,10 +99,12 @@ Run a reinforcement learning process and return the environment helper and the t
 env_helper, rl_dir = run_rl(ENVTYPE)
 ----
 
-ENVTYPE has to be replaced by one of the environments named after the file names in the directory `ReCo.jl/RL/Envs`, for example: `LocalCOMEnv`. A description of an environment is included at the beginning of the corresponding file.
+`ENVTYPE` has to be replaced by one of the environments named after the file names in the directory `ReCo.jl/RL/Envs`, for example: `LocalCOMEnv`. A description of an environment is included at the beginning of the corresponding file.
 //TODO: Descriptions of envs
 
-For more information about all possible optional arguments, press `?` in the REPL after running `using ReCo`. Then type `run_rl` followed by pressing enter.
+The documentation of `run_rl` includes all possible optional arguments.
+
+=== Q-matrix
 
 `env_helper` has the abstract type `EnvHelper`. To access the Q-matrix, enter the following:
 
@@ -106,7 +121,9 @@ include("src/RL/latex_table.jl")
 latex_rl_table(env_helper, FILENAME)
 ----
 
-FILENAME has to be replaced by the wanted file name of the `.tex` file. This file can then be found under `ReCo.jl/exports/FILENAME`.
+`FILENAME` has to be replaced by the wanted file name without extension of the `.tex` file. This file can then be found under `ReCo.jl/exports/FILENAME.tex`.
+
+=== Rewards
 
 To access the rewards, run the following:
 
@@ -122,6 +139,8 @@ To plot the rewards, run the following:
 plot_rewards(rl_dir)
 ----
 
+=== Mean kappa
+
 To plot the mean of kappa as the ratio of the eigenvalues of the gyration tensor, run the following:
 
 [source,julia]
@@ -134,7 +153,7 @@ plot_mean_kappa(; rl_dir=rl_dir, n_last_episodes=N_LAST_EPISODES)
 
 == Run analysis
 
-After running the following command blocks in the REPL, the output can be found in the directory `exports/graphics`.
+After running the following command blocks in the REPL, the output can be found in the directory `ReCo.jl/exports/graphics`.
 
 === Mean squared displacement
 

src/RL/latex_table.jl

@@ -11,7 +11,7 @@ function latex_table(
     return nothing
 end
 
-function latex_rl_table(env_helper, filename::String)
+function latex_rl_table(env_helper, filename_without_extension::String)
     table = copy(env_helper.shared.agent.policy.learner.approximator.table)
 
     for col in 1:size(table)[2]
@@ -40,7 +40,7 @@ function latex_rl_table(env_helper, filename::String)
     df = DataFrames.DataFrame(table, states)
     DataFrames.insertcols!(df, 1, :Actions => actions)
 
-    latex_table(df, filename)
+    latex_table(df, "$filename_without_extension.tex")
 
     return nothing
 end

src/Visualization/Animation.jl

@@ -12,6 +12,13 @@ using ..ReCo: ReCo
 
 include("common.jl")
 
+const DEFAULT_FRAMERATE = 10
+const DEFAULT_SHOW_CENTER_OF_MASS = false
+const DEFAULT_SHOW_INTERACTION_CIRCLE = false
+const DEFAULT_SHOW_SKIN_CIRCLE = false
+const DEFAULT_SHOW_FRAME_DIFF = false
+const DEFAULT_SHOW_PROGRESS = false
+
 function animate_bundle!(args, sim_consts::ReCo.SimConsts)
     bundle_t = args.bundle.t
     bundle_c = args.bundle.c
@@ -141,14 +148,29 @@ function animate_bundle!(args, sim_consts::ReCo.SimConsts)
     return nothing
 end
 
+"""
+    animate(sim_dir::String; <keyword arguments>)
+
+Animate a simulation.
+
+The output is `sim_dir/animation.mkv`.
+
+# Arguments
+- `framerate::Int64=$DEFAULT_FRAMERATE`: Framerate
+- `show_center_of_mass::Bool=$DEFAULT_SHOW_CENTER_OF_MASS`: Show center of mass as transparent white circle.
+- `show_interaction_circle::Bool=$DEFAULT_SHOW_INTERACTION_CIRCLE`: Show the interaction radius with a circle around every particle.
+- `show_skin_circle::Bool=$DEFAULT_SHOW_SKIN_CIRCLE`: Show the skin radius with a circle around every particle.
+- `show_frame_diff::Bool=$DEFAULT_SHOW_FRAME_DIFF`: Show translation of particles between two frames as lines connecting the old and new position. This is helpful to recognize unwanted jumps.
+- `show_progress::Bool=$DEFAULT_SHOW_PROGRESS`: Show animation progress bar.
+"""
 function animate(
     sim_dir::String;
-    framerate::Int64=1,
+    framerate::Int64=DEFAULT_FRAMERATE,
-    show_center_of_mass::Bool=false,
+    show_center_of_mass::Bool=DEFAULT_SHOW_CENTER_OF_MASS,
-    show_interaction_circle::Bool=false,
+    show_interaction_circle::Bool=DEFAULT_SHOW_INTERACTION_CIRCLE,
-    show_skin_circle::Bool=false,
+    show_skin_circle::Bool=DEFAULT_SHOW_SKIN_CIRCLE,
-    show_frame_diff::Bool=false,
+    show_frame_diff::Bool=DEFAULT_SHOW_FRAME_DIFF,
-    show_progress::Bool=true,
+    show_progress::Bool=DEFAULT_SHOW_PROGRESS,
 )
     println("Initializing GLMakie...")