Update tutorials to new API

Author: AleMorales

docs/make.jl

@@ -43,7 +43,8 @@ makedocs(;
         ],
         "How-to guides" => [
             "Setting up a grid cloner" => "howto/GridCloner.md",
-            "Messages in scenes" => "howto/Message.md"
+            "Messages in scenes" => "howto/Message.md",
+            "Multiple materials/colors" => "howto/Materials.md"
         ],
         "API" => [
             "Graphs" => "api/graphs.md",

docs/src/howto/Materials.md

@@ -1,23 +1,21 @@
-# Forest
 
-Alejandro Morales and Ana Ernst
 
-Centre for Crop Systems Analysis - Wageningen University
+````@example Forest
+#= Forest
+
+Alejandro Morales
 
-> ## TL;DR
-> Similar in functionality to [Tree](https://virtualplantlab.com/dev/tutorials/from_tree_forest/tree/) tutorial with separate graphs for each tree
-> - Modify tree parameters for each tree
-> - Multithreaded simulation (grow trees in parallel)
-> - Scene customization (e.g., add soil)
-> - Export Scenes
+Centre for Crop Systems Analysis - Wageningen University
 
 In this example we extend the tree example into a forest, where
 each tree is described by a separate graph object and parameters driving the
 growth of these trees vary across individuals following a predefined distribution.
+This tutorial requires using the Distributions.jl package:
+
 The data types, rendering methods and growth rules are the same as in the binary
 tree example:
 
-````julia
+=#
 using VirtualPlantLab
 using Distributions, Plots, ColorTypes
 import GLMakie
@@ -28,8 +26,8 @@ module TreeTypes
     struct Meristem <: VirtualPlantLab.Node end
     # Bud
     struct Bud <: VirtualPlantLab.Node end
-    # TreeNode
-    struct TreeNode <: VirtualPlantLab.Node end
+    # Node
+    struct Node <: VirtualPlantLab.Node end
     # BudNode
     struct BudNode <: VirtualPlantLab.Node end
     # Internode (needs to be mutable to allow for changes over time)
@@ -46,29 +44,23 @@ module TreeTypes
         growth::Float64 = 0.1
         budbreak::Float64 = 0.25
         phyllotaxis::Float64 = 140.0
-        leaf_angle::Float64 = 45.0
-        branch_angle::Float64 = 30.0
+        leaf_angle::Float64 = 30.0
+        branch_angle::Float64 = 45.0
     end
 end
 
 import .TreeTypes
-````
 
-Create geometry and color for the *internodes*:
-
-````julia
+# Create geometry + color for the internodes
 function VirtualPlantLab.feed!(turtle::Turtle, i::TreeTypes.Internode, data)
     # Rotate turtle around the head to implement elliptical phyllotaxis
     rh!(turtle, data.phyllotaxis)
     HollowCylinder!(turtle, length = i.length, height = i.length/15, width = i.length/15,
                 move = true, colors = RGB(0.5,0.4,0.0))
     return nothing
 end
-````
-
-Create geometry and color for the *leaves*:
 
-````julia
+# Create geometry + color for the leaves
 function VirtualPlantLab.feed!(turtle::Turtle, l::TreeTypes.Leaf, data)
     # Rotate turtle around the arm for insertion angle
     ra!(turtle, -data.leaf_angle)
@@ -79,21 +71,16 @@ function VirtualPlantLab.feed!(turtle::Turtle, l::TreeTypes.Leaf, data)
     ra!(turtle, data.leaf_angle)
     return nothing
 end
-````
-
-Insertion angle for the bud nodes:
 
-````julia
+# Insertion angle for the bud nodes
 function VirtualPlantLab.feed!(turtle::Turtle, b::TreeTypes.BudNode, data)
     # Rotate turtle around the arm for insertion angle
     ra!(turtle, -data.branch_angle)
 end
-````
 
-Rules for meristem and branches:
 
-````julia
-meristem_rule = Rule(TreeTypes.Meristem, rhs = mer -> TreeTypes.TreeNode() +
+# Rules
+meristem_rule = Rule(TreeTypes.Meristem, rhs = mer -> TreeTypes.Node() +
                                               (TreeTypes.Bud(), TreeTypes.Leaf()) +
                                          TreeTypes.Internode() + TreeTypes.Meristem())
 
@@ -129,7 +116,7 @@ of each tree and rotates it.
 (ii) Wrap the axiom, rules and the creation of the graph into a function that
 takes the required parameters as inputs.
 
-````julia
+````@example Forest
 function create_tree(origin, growth, budbreak, orientation)
     axiom = T(origin) + RH(orientation) + TreeTypes.Internode() + TreeTypes.Meristem()
     tree =  Graph(axiom = axiom, rules = (meristem_rule, branch_rule),
@@ -141,7 +128,7 @@ end
 The code for elongating the internodes to simulate growth remains the same as for
 the binary tree example
 
-````julia
+````@example Forest
 getInternode = Query(TreeTypes.Internode)
 
 function elongate!(tree, query)
@@ -169,43 +156,50 @@ of 2 meters. First we generate the original positions of the trees. For the
 position we just need to pass a `Vec` object with the x, y, and z coordinates of
 the location of each TreeTypes. The code below will generate a matrix with the coordinates:
 
-````julia
+````@example Forest
 origins = [Vec(i,j,0) for i = 1:2.0:20.0, j = 1:2.0:20.0]
 ````
 
 We may assume that the initial orientation is uniformly distributed between 0 and 360 degrees:
 
-````julia
+````@example Forest
 orientations = [rand()*360.0 for i = 1:2.0:20.0, j = 1:2.0:20.0]
 ````
 
-For the `growth` and `budbreak` parameters we will be assumed to follow a
+For the `growth` and `budbreak` parameters we will assumed that they follow a
 LogNormal and Beta distribution, respectively. We can generate random
 values from these distributions using the `Distributions` package. For the
 relative growth rate:
 
-````julia
-growths = rand(LogNormal(-2, 0.2), 10, 10)
+````@example Forest
+growths = rand(LogNormal(-2, 0.3), 10, 10)
 histogram(vec(growths))
+savefig("growths.png") ## hide
 ````
 
+![](growths.png)
+
 And for the budbreak parameter:
 
-````julia
+````@example Forest
 budbreaks = rand(Beta(2.0, 10), 10, 10)
 histogram(vec(budbreaks))
+savefig("budbreaks.png") ## hide
 ````
 
+![](budbreaks.png)
+
 Now we can create our forest by calling the `create_tree` function we defined earlier
 with the correct inputs per tree:
 
-````julia
-forest = vec(create_tree.(origins, growths, budbreaks, orientations))
+````@example Forest
+forest = vec(create_tree.(origins, growths, budbreaks, orientations));
+nothing #hide
 ````
 
 By vectorizing `create_tree()` over the different arrays, we end up with an array
 of trees. Each tree is a different Graph, with its own nodes, rewriting rules
-and variables. This avoids having to create large graphs to include all the
+and variables. This avoids having to create a large graphs to include all the
 plants in a simulation. Below we will run a simulation, first using a sequential
 approach (i.e. using one core) and then using multiple cores in our computers (please check
 https://docs.julialang.org/en/v1/manual/multi-threading/ if the different cores are not being used
@@ -216,108 +210,126 @@ as you may need to change some settings in your computer).
 We can simulate the growth of each tree by applying the method `simulate` to each
 tree, creating a new version of the forest (the code below is an array comprehension)
 
-````julia
-newforest = [simulate(tree, getInternode, 2) for tree in forest]
+````@example Forest
+newforest = [simulate(tree, getInternode, 2) for tree in forest];
+nothing #hide
 ````
 
 And we can render the forest with the function `render` as in the binary tree
 example but passing the whole forest at once
 
-````julia
-render(Scene(newforest))
+````@example Forest
+pl = render(Scene(newforest))
+GLMakie.save("newforest1.png", pl) ## hide
 ````
 
+![](newforest1.png)
+
 If we iterate 4 more iterations we will start seeing the different individuals
 diverging in size due to the differences in growth rates
 
-````julia
+````@example Forest
 newforest = [simulate(tree, getInternode, 15) for tree in newforest];
-render(Scene(newforest))
+pl = render(Scene(newforest))
+GLMakie.save("newforest2.png", pl) ## hide
 ````
 
+![](newforest2.png)
+
 ## Multithreaded simulation
 
 In the previous section, the simulation of growth was done sequentially, one tree
 after another (since the growth of a tree only depends on its own parameters). However,
 this can also be executed in multiple threads. In this case we use an explicit loop
 and execute the iterations of the loop in multiple threads using the macro `@threads`.
-Note that the rendering function can also be run in parallel (i.e. the geometry will be
+Note that the rendering function can also be ran in parallel (i.e. the geometry will be
 generated separately for each plant and the merge together):
 
-````julia
+````@example Forest
 using Base.Threads
 newforest = deepcopy(forest)
-@threads for i in eachindex(forest)
+@threads for i in 1:length(forest)
     newforest[i] = simulate(forest[i], getInternode, 6)
 end
-render(Scene(newforest), parallel = true)
+pl = render(Scene(newforest, parallel = true))
+GLMakie.save("newforest3.png", pl) ## hide
 ````
 
+![](newforest3.png)
+
 An alternative way to perform the simulation is to have an outer loop for each timestep and an internal loop over the different trees. Although this approach is not required for this simple model, most FSP models will probably need such a scheme as growth of each individual plant will depend on competition for resources with neighbouring plants. In this case, this approach would look as follows:
 
-````julia
+````@example Forest
 newforest = deepcopy(forest)
 for step in 1:15
-    @threads for i in eachindex(newforest)
+    @threads for i in 1:length(newforest)
         newforest[i] = simulate(newforest[i], getInternode, 1)
     end
 end
-render(Scene(newforest), parallel = true)
+pl = render(Scene(newforest, parallel = true))
+GLMakie.save("newforest4.png", pl) ## hide
 ````
 
+![](newforest4.png)
+
 # Customizing the scene
 
-Here we are going to customize the scene of our simulation by adding a horizontal tile representing soil and
+Here we are going to customize the scene of our simulation by adding a horizontal tile represting soil and
 tweaking the 3D representation. When we want to combine plants generated from graphs with any other
 geometric element it is best to combine all these geometries in a `GLScene` object. We can start the scene
 with the `newforest` generated in the above:
 
-````julia
-scene = Scene(newforest)
+````@example Forest
+scene = Scene(newforest);
+nothing #hide
 ````
 
 We can create the soil tile directly, without having to create a graph. The simplest approach is two use
 a special constructor `Rectangle` where one species a corner of the rectangle and two vectors defining the
 two sides of the vectors. Both the sides and the corner need to be specified with `Vec` just like in the
 above when we determined the origin of each plant. VPL offers some shortcuts: `O()` returns the origin
-(`Vec(0.0, 0.0, 0.0)`), whereas `X`, `Y` and `Z` returns the corresponding axes, and you can scale them by
+(`Vec(0.0, 0.0, 0.0)`), whereas `X`, `Y` and `Z` returns the corresponding axes and you can scale them by
 passing the desired length as input. Below, a rectangle is created on the XY plane with the origin as a
 corner and each side being 11 units long:
 
-````julia
+````@example Forest
 soil = Rectangle(length = 21.0, width = 21.0)
 rotatey!(soil, pi/2)
 VirtualPlantLab.translate!(soil, Vec(0.0, 10.5, 0.0))
 ````
 
 We can now add the `soil` to the `scene` object with the `add!` function.
 
-````julia
+````@example Forest
 VirtualPlantLab.add!(scene, mesh = soil, colors = RGB(1,1,0))
 ````
 
 We can now render the scene that combines the random forest of binary trees and a yellow soil. Notice that
 in all previous figures, a coordinate system with grids was being depicted. This is helpful for debugging
-your code but also to help set up the scene (e.g. if you are not sure how big the soil tile should be).
-However, it may be distracting for the visualization. It turns out that we can turn that off with
-`show_axes = false`:
+your code but also to help setup the scene (e.g. if you are not sure how big the soil tile should be).
+Howver, it may be distracting for the visualization. It turns out that we can turn that off with
+`axes = false`:
 
-````julia
-render(scene, axes = false)
+````@example Forest
+pl = render(scene, axes = false)
+GLMakie.save("newforest5.png", pl) ## hide
 ````
 
+![](newforest5.png)
+
 We may also want to save a screenshot of the scene. For this, we need to store the output of the `render` function.
 We can then resize the window rendering the scene, move around, zoom, etc. When we have a perspective that we like,
 we can run the `save_scene` function on the object returned from `render`. The argument `resolution` can be adjusted in both
 `render` to increase the number of pixels in the final image. A helper function `calculate_resolution` is provided to
 compute the resolution from a physical width and height in cm and a dpi (e.g., useful for publications and posters):
 
-````julia
+````@example Forest
 res = calculate_resolution(width = 16.0, height = 16.0, dpi = 1_000)
-output = render(scene, axes = false, resolution = res)
+output = render(scene, axes = false, size = res)
 export_scene(scene = output, filename = "nice_trees.png")
 ````
 
 ---
 
 *This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+