Tutorial overhaul (#201)

* explaining Action and Scaling and fixing some others * removed some "The" * emoji fixes and some other small things * Corrected grammar and some light editing * Fixed some grammar issues Co-authored-by: Jacob Zelko <[email protected]>
JuliaAnimators · Sep 25, 2020 · 2f13ce0 · 2f13ce0
1 parent 49afaf0
commit 2f13ce0
Show file tree

Hide file tree

Showing 7 changed files with 90 additions and 11 deletions.
diff --git a/docs/src/contributing.md b/docs/src/contributing.md
@@ -123,7 +123,7 @@ Finally, click "Create pull request".
 
 You may get some questions about it, and possibly suggestions of how to make it ready to go into the main project. 
 If you had test errors or problems, we are happy to help you. 
-Then, if all goes according to plan, it gets merged... **Thanks for the contribution!!** :tada: :tada: :tada:
+Then, if all goes according to plan, it gets merged... **Thanks for the contribution!!** 🎉 🎉 🎉
 
 ## Note on Adding Dependencies
 

diff --git a/docs/src/mission.md b/docs/src/mission.md
@@ -2,7 +2,7 @@
 
 ## What is Javis? 
 
-`Javis.jl` is a tool focused on providing an easy to use interface for making animations and developing visualizations quickly - while having fun! :smiley:
+`Javis.jl` is a tool focused on providing an easy to use interface for making animations and developing visualizations quickly - while having fun! 😃
 
 That being said, we decided to make this mission statement to clearly explain the scope of this project. That is, to explain what this project _is_ and what it _is not_. Here are the core tenents of `Javis` concisely explained:
 
@@ -14,7 +14,7 @@ That being said, we decided to make this mission statement to clearly explain th
 
 - **Javis is not neccesarilly geared towards data analytics.** Admittedly, there are ways to use Javis to visualize data while creating animations. However, the intent of Javis is not focused on creating functionality to analyze datasets _as of this moment_. This may change in the future.
 
-- **We love documentation and tutorials! 🤓** One of the things we prioritize in each release of Javis is to document functionalities of the tools we add. Furthermore, we like to make tutorials to also show what is possible in Javis. Do you have a cool animation or blog that you have written using Javis? Let us know by making an issue to let us know!
+- **We love documentation and tutorials! 🤓** One of the things we prioritize in each release of Javis is to document functionalities of the tools we add. Furthermore, we like to make tutorials to also show what is possible in Javis. Do you have a cool animation or blog that you have written using Javis? Let us know by opening an issue!
 
 ## Summary
 

diff --git a/docs/src/tutorials/tutorial_1.md b/docs/src/tutorials/tutorial_1.md
@@ -28,7 +28,7 @@ With all that said, let's dive into this tutorial! ✨
 `Javis.jl` is an abstraction on top of powerful graphics tools to make animations and visualizations easy to create.
 It is built on top of the fantastic Julia drawing packages, [`Luxor.jl`](https://github.com/JuliaGraphics/Luxor.jl) and [`Cairo.jl`](https://github.com/JuliaGraphics/Cairo.jl).
 `Cairo.jl` is much too complex to explain here, but `Luxor.jl` gives one the ability to define and draw on a canvas.
-`Luxor.jl` provides simple functions like `line`, `circle` and `Draw` by which one can make animations. 
+`Luxor.jl` provides simple functions like `line`, `circle` and `poly` by which one can make animations. 
 
 > **NOTE:** If you're interested in 2D graphics, you should definitely check out the awesome `Luxor.jl` package.
 > It has a [great tutorial](https://juliagraphics.github.io/Luxor.jl/stable/tutorial/) that will give you an even greater understanding of how `Javis.jl` works.

diff --git a/docs/src/tutorials/tutorial_2.md b/docs/src/tutorials/tutorial_2.md
@@ -81,6 +81,71 @@ The following invocation will create the head:
 ...
 ```
 
+`Action` objects consist of at least one part, namely calling a function which draws something on to the canvas. 
+`Action` objects are fully comprised of `frames` (which can be optional), an optional `id`, a `function` that draws something on a canvas, an optional `Animation`, an optional `Movement`, and optional `SubAction` definitions.
+
+### Frames
+
+The default of an `Action` is to use the same frames as a previous `Action`. 
+Besides that there are three other options:
+
+- Define the range explicitly i.e `1:100`.
+- Use the default or explicitly write `:same` into the unit range location which means the same frames as before
+- Use [`Rel`](@ref) to specify it relative to the previous frame
+  - `Rel(10)` which is short for `Rel(1:10)` after an `Action` which is defined for `1:100` would mean `101:110`.
+  You just want to make sure that you don't use frame numbers higher than the `BackgroundAction`.
+
+### Action ID
+
+The action id which in the above example is `:head` can be used to store a return value from the drawing function you call. 
+This can be used in later actions such that two actions can interact.
+One example was shown in the [previous tutorial](tutorial_1.md) where one object rotated around another one.
+In this tutorial it's basically used as a comment to keep track of what each `Action` is creating.
+
+### Function
+
+As mentioned the most important part of each [`Action`](@ref) is to define what should be drawn in these frames. 
+Javis calls these functions with three arguments: `video`, `action` and `framenumber`. 
+Normally this is not needed but instead one defines own arguments. 
+In this case the following syntax is used.
+
+```julia
+(args...) -> my_function(argument_1, argument_2, ..., argument_X)
+```
+
+In [Tutorial 1](tutorial_1.md), it showed that `my_function` can be a Luxor function or a function which calls some Luxor functions to draw on the canvas. 
+
+### Animation
+
+An `Action` can be used to define a simple movement of what can be drawn. 
+An example for this was shown in the [previous tutorial](tutorial_1.md) where objects rotate. 
+This movement is normally linear which is rather dull. 
+Therefore, it's possible to define the speed using so called easing functions (for more info, see [Tutorial 6](tutorial_6.md).
+
+### Movement
+
+It's possible to give an `Action`, a movement that persists over the entirety of its frames.
+This can be done using [`Translation`](@ref), [`Rotation`](@ref) and [`Scaling`](@ref). 
+However, it is suggested, and for more complex movements required, to use [`SubAction`](@ref)s to steer the animation of an `Action`. 
+
+### SubAction
+
+Actions have one more additional keyword argument called `subactions`.
+A `SubAction` is used to have fine grained control of how an objects can move  from frame to frame. 
+[Tutorial 4](tutorial_4.md) and [tutorial 6](tutorial_6.md) explain more about a `SubAction`.
+
+Now that those explanations are out of the way, back to the brain! 
+
+The code
+
+```julia
+...
+    Action(:same, :head, (args...) -> circ(O, "black", :stroke, 170)),
+...
+```
+
+creates
+
 ![](assets/head.gif)
 
 Now we are getting a - _head_! 😃
@@ -230,7 +295,7 @@ Also, we need to define the radius of our electrodes; we will set that to 15:
 
 ```julia
 ...
-        radius = 15
+    radius = 15 # needs to be defined before calling `javis`
 	Action(
             :electrodes,
             (args...) ->
@@ -354,7 +419,7 @@ Once everything is executed, we get this very nice and clean looking animation w
 
 ## Conclusion
 
-Congratulations! 🎉 🎉 🎉
+Congratulations! 🎉 🎉 🎉 
 You made a brain! 
 To recap, by working through this animation you should now:
 

diff --git a/docs/src/tutorials/tutorial_3.md b/docs/src/tutorials/tutorial_3.md
@@ -1,7 +1,6 @@
 # **Tutorial 3:** Rendering LaTeX with Javis!
 
 This is a rather brief tutorial about an exciting functionality of `Javis.jl`: the ability to render $\LaTeX$!
-By the end of this tutorial, you will be able to create 
 
 If you have never heard of `LaTeX` before, we highly recommend the following resources:
 
@@ -128,7 +127,7 @@ Let's spice it up!
 
 ## Throw it in the Blender!
 
-A fun function that `Javis` provides is the ability to blend colors together!
+A fun function that `Luxor` provides is the ability to blend colors together!
 To do so, let's modify the `draw_latex` function:
 
 ```julia
@@ -148,8 +147,8 @@ end
 ```
 
 The biggest change is that we added the `blend` and `setblend` functions.
-The `blend` function creates a linear blend between two points using two given colors - in this case, black and red.
-The `setblend` function applies the blend to the drawn object. 
+`blend` creates a linear blend between two points using two given colors - in this case, black and red.
+`setblend` applies the blend to the drawn object. 
 We also use the `translate` function this time as it makes writing the `blend` function easier.
 
 Can you guess what happens when we execute the code with this newly updated `draw_latex` function?

diff --git a/docs/src/tutorials/tutorial_5.md b/docs/src/tutorials/tutorial_5.md
@@ -170,6 +170,21 @@ From there, we need to define more `Action` objects for our `javis` function for
 
 This will grow our element from `1` to `12`, from `12` to `20`, `20` to `7`, and finally `7` to `1`.
 
+> **IMPORTANT:** `Scaling` does not really scale an object but instead the entire canvas the object is drawn on. 
+> This produces the desired effect for two reasons:
+> 1. The `Action` is inside a Luxor layer which means that scaling inside this layer does not scale elements outside the layer (e.g. the frame counter in the upper right corner).
+> 2. As it scales the canvas and not the `Action`, scaling only works nicely if the action is defined at the origin. 
+If you want to display the element somewhere else, for example, you should **not** change in the following snippet
+> ```julia
+> function element(;color = "black")
+>    sethue(color)
+>    circle(O, 4, :fill)
+> end
+> ```
+> the point where the circle appears by changing `O` to the desired `Point(x, y)`.
+> Instead use another `SubAction`, like  `SubAction(1:1, Translation(x, y))`, to move the origin of the object to the desired location.
+> Then scaling will work fine as it is defined on the first frame only. 
+
 That scaling looks like this:
 
 ![](assets/blank_atom_scaling.gif)

diff --git a/docs/src/tutorials/tutorial_6.md b/docs/src/tutorials/tutorial_6.md
@@ -186,7 +186,7 @@ Let's walk through the steps Javis takes to create the animation:
   - Remember the `O` is the same as `(0, 0)` and is at the center of the canvas at the beginning.
   - Then the circle is at position `(150, 0)`. Remember that it is still drawn at the origin so actually we shifted our whole view to the right.
 - Therefore for the next 100 frames we need to specify that we actually want to rotate around the world origin which is at `Point(-150, 0)` from our current perspective. 
-- Afterwards we are now again ath `(150, 0)` but see it as our origin and therefore need to move our circle to the left to `Point(-150, 0)` which is the world origin. 
+- Afterwards we are now again at `(150, 0)` but see it as our origin and therefore need to move our circle to the left to `Point(-150, 0)` which is the world origin. 
 
 Hope that makes sense! Let's see it in action: