add docs on pin

Author: hexaeder

docs/src/index.md

@@ -11,7 +11,6 @@ All example images on this page are created using [`Makie.jl`](https://github.co
 using CairoMakie
 CairoMakie.activate!(type="png") # hide
 set_theme!(resolution=(800, 400)) #hide
-CairoMakie.inline!(true) # hide
 using NetworkLayout
 using GraphMakie, Graphs
 nothing #hide
@@ -174,3 +173,62 @@ layout = Spectral()
 f, ax, p = graphplot(g, layout=layout, node_size=0.0, edge_width=1.0)
 f #hide
 ```
+
+## `pin` Positions in Interative Layouts
+Sometimes it is desired to fix the positions of a few nodes while arranging the rest "naturally" around them.
+The iterative layouts [`Stress`](@ref), [`Spring`](@ref) and [`SFDP`](@ref) allow to pin
+nodes to certain positions, i.e. those node will stay fixed during the iteration.
+```@example layouts
+g = SimpleGraph(vcat(hcat(zeros(4,4), ones(4,4)), hcat(ones(4,4), zeros(4,4))))
+nothing #hide
+```
+
+The keyword argument `pin` takes a Vector or a Dict of key - value pairs. The key has to be
+the index of the node. The value can take three forms:
+  - `idx => Point2(x,y) ` or `idx => (x,y)` overwrites the initial position of that vertex and pins it there,
+  - `idx => true/false` pins or unpins the vertex, position is taken from `initialpos`-keyword argument or random,
+  - `idx => (false, true)` allows for fine control over which coordinate to pin.
+
+```@example layouts
+initialpos = Dict(1=>Point2f(-1,0.5),
+                  3=>Point2f(1,0),
+                  4=>Point2f(1,0))
+pin = Dict(1=>true,
+           2=>(-1,-0.5),
+           3=>(true, false),
+           4=>(true, false))
+nothing #hide
+```
+Example animation on how those keyword arguments effect different iterative layouts:
+```@example layouts
+springl = Spring(;initialpos, pin, seed=11) #2
+sfdpl   = SFDP(;initialpos, pin, tol=0.0)
+stressl = Stress(;initialpos, pin, reltols=0.0, abstolx=0.0, iterations=100)
+
+f = Figure(resolution=(1200,500))
+ax1 = f[1,1] = Axis(f; title="Spring")
+ax2 = f[1,2] = Axis(f; title="SFDP")
+ax3 = f[1,3] = Axis(f; title="SFDP")
+
+for ax in [ax1, ax2, ax3]
+    xlims!(ax,-2,2); ylims!(ax,-1.4,1.4); vlines!(ax, 1; color=:red); hidespines!(ax); hidedecorations!(ax)
+end
+
+node_color = vcat(:green, :green, :red, :red, [:black for _ in 1:4])
+node_size = vcat([40 for _ in 1:4], [20 for _ in 1:4])
+nlabels = vcat("1", "2", "3", "4", ["" for _ in 1:4])
+nlabels_align = (:center, :center)
+nlabels_color = :white
+p1 = graphplot!(ax1, g; layout=springl, node_color, node_size, nlabels, nlabels_align, nlabels_color)
+p2 = graphplot!(ax2, g; layout=sfdpl, node_color, node_size, nlabels, nlabels_align, nlabels_color)
+p3 = graphplot!(ax3, g; layout=stressl, node_color, node_size, nlabels, nlabels_align, nlabels_color)
+
+iterators = [LayoutIterator(l, g) for l in (springl, sfdpl, stressl)]
+record(f, "pin_animation.mp4", zip(iterators...); framerate = 10) do (pos1, pos2, pos3)
+    p1[:node_pos][] = pos1
+    p2[:node_pos][] = pos2
+    p3[:node_pos][] = pos3
+end
+nothing #hide
+```
+![pin animation](pin_animation.mp4)