lots more writing of docs

docs/_quarto.yml

@@ -15,10 +15,9 @@ website:
       - installation.md
       - getting-started.md
       - section: Tutorials
-        contents:
-          - tutorials/interface.md
-          - tutorials/importing.md
+        contents: tutorials/*
       - examples.md
+      - molecular_nodes.qmd
       - documentation.md
       - section: Python API
         contents: reference/*

docs/molecular_nodes.qmd

@@ -0,0 +1,109 @@
+---
+title: "3. Molecular Nodes"
+number-sections: true
+number-depth: 1
+---
+
+This is a very basic introduction to Molecular Nodes. How to import a protein from the PDB & change the colour and style via editing the node graph. Molecular Nodes and Geometry Nodes in general has a lot more advanced functionality, and I encourage you to watch other YouTube tutorials and spend time playing around with it to see what is possible. Everything that I have achieved so far is through playing around to see what could be done.
+
+::: callout-ip
+## YouTube Tutorials
+
+I have also made a series of YouTube tutorials walking through some of the functionality of Molecular Nodes. Currently this tutorial series is for the older version of Molecular Nodes and not the 2.0 version. The basic functionality and idea remain the same, but I will be updating this series once I get enough time.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/CvmFaRVmZRU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
+
+</iframe>
+:::
+
+## The MolecularNodes Panel
+
+1.  Click on the `Scene Properties` panel, which will show the `MolecularNodes` panel, which has the buttons and options for downloading and importing protein structures.
+2.  Enter your PDB ID of choice and click on download. This will import the molecular data into Blender, and you will see a new object appear in the Outliner (top right) under the MolecularNodes collection.
+
+![](images/mn-panel-download-pdb.png)
+
+The structure is now imported into the scene. While initially the structure will appear as grey points, this is because Blender has a 3D view for working, then a Rendered view for actually rendering with calculated lighting.
+
+## Rendered View
+
+1.  Click the 'Render Properties' tab, which has the icon for the back of a camera.
+2.  Change the render engine from Eevee to Cycles.
+3.  Change the render device from CPU to GPU if applicable. Some computers may not have GPU compute available.
+4.  Change the view to rendered view, which will calculate the lighting for the scene and show all of the atoms.
+
+![](images/mn-render-cycles.png)
+
+## Geometry Nodes Editor
+
+This is where we edit the node graph for Molecular Nodes. The node graph is a geometry processing program you create, that is read and executed by Blender from left to right. Each node performs an action on the geometry that is passed into it, and the result of that action is passed out to the right. Think of it as creating a set of rules for the computer to follow. You define the rules, and the computer can follow those same rules, even if you start with a different data set.
+
+The data flows like a river, along the green noodles of the node graph. There must be only 1 final output. If you are using the molecular data, then there must also be a single input.
+
+![Example node tree, demonstrating the flow of information through the nodes.](images/CleanShot%202023-06-11%20at%[email protected])
+
+
+```{mermaid}
+flowchart LR
+  A{Atomic\nData} --> B[Manipulation]
+  B --> D(Style)
+  D --> G{Geometry\nOutput}
+
+```
+
+![Screenshot of the Geometry Nodes workspace.](images/mn-gn-workspace.png)
+
+The starting style `MOL_style_atoms_cycles` is only visible via inside of the Cycles render engine. You can add other styles manipulate the data through other nodes, by adding them with <kbd>Shift</kbd> + <kbd>A</kbd> and navigating to the MolecularNodes panel at the bottom. There are several categories of nodes for different animations and styles. You can add the `Ribbon Protein` node, which will create a ribbon representation based on the alpha carbons in the structure. If there is not colour in the structure, ensure that the node has a material `MOL_atomic_material` at the bottom of the node.
+
+![](images/mn-gn-style-ribbon.png)
+
+The data flows through the node graph from left to right. There should always be one input, which is the atomic data that is stored in the 3D mesh of the atoms and bonds. There should also be only one output, which is the final geometry that has been created throughout the node graph.
+
+```{mermaid}
+flowchart LR
+  A{Atomic\nData} --> B[Manipulation]
+
+  B --> D(Style 1)
+  B --> E(Style 2)
+  B --> S(Style 3)
+
+  sS[Selection] --> S
+
+  E --> F[Join\nGeometry]
+  D --> F
+  S --> F
+
+  F --> G{Geometry\nOutput}
+```
+
+As demonstrated in the diagram, the flow of the data can split across multiple different branches of the tree, with the result of each parallel computation being combined before being exported.
+
+Each of these different branches can be a different style, in this example shown two different styles are applied, and the third style has a custom selection. All of the styles are the result of the same data manipulation.
+
+The node graph in between can be as complex as you want to make it, as long as there is a continuous connection to the output of the geometry, it should produce a result.
+
+![An example of a more complex node graph, with multiple branches that diverge and come back together.](images/CleanShot%202023-06-11%20at%[email protected])
+
+Combining multiple different nodes you can create protein models and complex 3D scenes. In the example below, there is a node tree which should be present on every new structure imported via MolecularNodes. The atoms and bonds are passed in from the left, the atoms are given a colour based on their element and their `chain_id`, and then the atoms are styled as atoms, scaling the atom radii to `1.00`.
+
+The data flows through the node tree from left to right, along the bright green lines. The atomic data comes in, goes through layers of manipulation, a style is applied, and the created geometry is then outputted from the node tree.
+
+
+
+## Quick Animations
+
+There are many ways to quickly create animations inside of Blender and MolecularNodes. One such way is to use the `Wiggle` node inside of MolecularNodes. This wiggles the amino acid side chains, based on their experimentally-determined B-factor, to give life to the structure. Crystral structures are ultimately static snapshots of a dynamic system, and this is a quick way to bring some of those dynamics back to the structure.
+
+In the example below, the following steps are followed:
+
+1. Import a structure from the PDB with it's corresponding ID
+2. Add the `Wiggle` node `Molecular Nodes -> Animation -> Res Wiggle` in before the final _style_ node is applied. As you change the `Animate 0..1` value the AA side chains will animate. 
+3. Add the `Animate Value` node `Molecular Nodes -> Animation -> Animate Value` and connect the output to the `Animate 0..1` input of the `Wiggle` node.
+
+You can start and stop playback of animations in Blender with the <kbd>Space</kbd> key.
+
+The resulting node tree will wiggle the AA based on the parameters as the value goes from 0 to 1. The animation will perfectly loop from values 0 to 1. Try changing the amplitude of the wiggle, or the frame range for the animate value node to see how it changes the final animation.
+
+![Quickly adding life to a crystal structure.](images/mn-wiggle-example.gif){fig-alt="A gif showing amino acids wiggling and moving about as part of a protein cystral structure. Their movement is scaled based on their experimentally determined B-factor."}
+
+![The nodes used in the wiggle animation above.](images/mn-wiggle-nodes.png){fig-alt="A screenshot of some geometry nodes inside of Blender. The major nodes pictured are 'MOL_style_colour', 'MOL_animate_res_wiggle' and 'MOL_style_ball_and_stick' which result in an animation of amino acids wiggling about inside of a protein structure."}

docs/tutorials/00_interface.md

@@ -0,0 +1,128 @@
+---
+title: Blender's Interface
+---
+
+Blender has a _very_ overwhelming interface. There is no getting around this. Blender can do _practically anything_, and it is sometimes hard to do simple things.
+
+### A New File
+
+Starting a new file, you are greeted by the splash screen. You can click `General` to start a new session with a general-purpose setup.
+
+This 3D viewport will seem familiar if you have used other programs such as PyMol, ChimeraX & VMD. You can move the camera around just like in those other programs.
+
+In the 3D viewport, much like in real life, there are three (3) axes of possible movement and direction. Inside Blender are `X`, `Y`, and `Z`. The floor is made of  `X` and `Y`, which form the flat grid you see in the viewport coloured red and green/yellow, while `Z` is the blue vertical axis. These are labelled and highlighted on the axis widget, which is present in the top right corner of the viewport. This will rotate as you rotate the view, so it can always be used as a reference point.
+
+![The different widgets in the 3D viewport. Note the colouring of the different axes.](images/widgets.png)
+
+You can rotate the camera view either using the middle mouse button <kbd>MMB</kbd> or using your touchpad if you are on a laptop. You can also click and drag the axis widget to rotate the camera.
+
+You can pan the camera using <kbd>Shift</kbd> + <kbd>MMB</kbd>
+
+![](videos/new_file.mp4)
+
+## Transforming Objects
+
+The main difference is that you can also manipulate the 3D scene in front of you. You can select objects with a left click of the mouse <kbd>LMB</kbd>, and move them around by *Grabbing* them with the <kbd>G</kbd> key.
+
+The main actions that you use the 3D Viewport for are:\
+
+-   <kbd>G</kbd> - **Grabbing:** Moving an object around in 3D space.
+
+-   <kbd>S</kbd> - **Scaling:** Changing the relative size of an object.
+
+-   <kbd>R</kbd> - **Rotating:** Rotating the object in 3D space.
+
+![](videos/rotate_grab_scale.mp4)
+
+### Locking to an Axis
+
+When transforming by grabbing, rotating or scaling, you can lock the transformation to a particular axis. Click <kbd>X</kbd> / <kbd>Y</kbd> / <kbd>Z</kbd> after starting the transformation to lock it to those axes, or <kbd>Shift</kbd> + <kbd>X</kbd> / <kbd>Y</kbd> / <kbd>Z</kbd> to lock the transformation to be *perpendicular* to that axis.
+
+![](videos/transforms_locked.mp4)
+
+## Rendered View
+
+By default you start in `3D View`, which is characterised by everything being gray and not rendered properly.
+
+You can change to the different views via the render view buttons, or by holding <kbd>Z</kbd> and selecting one of the options.
+
+Each of the views are useful in their own way. If you have a powerful enough computer, you can spend the majority of your time in either `Rendered` or `Material Preview` view which will ensure everything is shaded and lighting is calculated. If a scene is becoming complex and your computer is slow, you can switch back to `3D View` which should improve performance.
+
+![](videos/render_views.mp4)
+
+## Rendering Engines
+
+Already there are different ways to view the scene, through the 'rendered view' and the other methods. Even with the option of rendered view, there are multiple different rendering engines. Two rendering engines come pre-installed with Blender, with the possibility to use more. The two rendering engines that come pre-installed are Eevee and Cycles. By default Eevee is enabled, but you can change to Cycles in the `Render Properties` tab.
+
+Eevee is much faster and more responsive than Cycles, but a lot of the time doesn't 'look as nice'. Eevee is a real-time rendering engine built for performance and interactivity, while Cycles is a path-traced rendering engine built for physically accurate light calculations. This is much slower to calculate but often results in 'nicer' lighting. Both rendering engines are excellent and are helpful in different scenarios depending on the desired outcomes.
+
+The default style `Atoms Cycles` inside of Molecular Nodes is only visible inside of Cycles for performance reasons. All other styles are visible inside of both rendering engines. If your atoms seem to be invisible, check the rendering engine and style that you are using.
+
+> If you have the option available, ensure to switch to `GPU Compute` instead of `CPU` when using the Cycles render engine. This will usually always be the better option, and the perforamnce will be much better.
+
+![](videos/00_interface_render_engines.mp4)
+
+## Adding Objects
+
+You can add new objects by <kbd>Shift</kbd> + <kbd>A</kbd> or by using the `Add` menu in the top left.
+
+There are a number of different object types that can be added. The most common that you will use will be `Mesh` and `Light`. Try adding some new objects, _**G**rabbing_ them to move them around, _**R**otating_ them and _**S**caling_ them to different sizes. If you have just added a new object and it isn't immediately visible, it might be inside another object, or it could be *too big* or *too small* to be immediately visible. Try moving the camera or the object around to get a better view.
+
+![The add menu. Also accesible through `Shift + A`](images/menu_add.png)
+
+![](videos/adding_objects.mp4)
+
+## Rendering an Image
+
+To render an image, you can click <kbd>F12</kbd> or use the `Render -> Render Image` menu. Blender will not render what you are immediately seeing. Instead, it will render whatever the **Camera**** is seeing. This can be frustrating at first, but it makes sense when you can have multiple cameras in a single scene.
+
+To see what the camera sees, you can click the Camera widget in the top right, or click backtick (<kbd>`</kbd>) + <kbd>1</kbd>. 
+
+> The backtick is directly under the <kdb>Esc</kbd> key on most American / Enlgish keyboards. It can vary in other language layouts.
+
+![](videos/camera_view.mp4)
+
+Once you are happy with the camera framing, click render.
+
+![The render menu.](images/menu_render.png)
+
+A window should appear, showing the rendered image. Isn't it magnificent?
+
+The rendered image is not saved. You have to manually save the image by clicking `Image` -> `Save As` and choose where to save the image.
+
+![The rendered image window.](images/render_example_1.png)
+
+## Add More Lights
+
+We can make our 3D scene more interesting by adding more lights. When the light object is selected, the green `Light Settings` tab becomes available, appearing as a small green lightbulb. Under these settings, we can change the colour of our light, along with the `Power`. Try tweaking these settings to your liking. You can duplicate an object without adding a new one by clicking <kbd>Shift</kbd> + <kbd>D</kbd>.
+
+![Adding more lights to the scene.](videos/add_mode_lights.mp4)
+
+## Materials
+
+One of the hardest things to get used to while working in 3D is the idea of materials. What if we want to make the monkey head **Red**? In 3D we can't just _make things red_. Instead we have to assign it a _material_. This material can have the property that it is primarily red, but it is also metallic, has a sheen, reflects light, can be partially transparent as well as a whole range of other properties.
+
+Complex shading is an entire career itself, so we won't get too much in to it. In this example we will just add a material to the monkey to make it red, and a different material to the cube to make it blue.
+
+> If you can't see the colors changing, ensure you are in Rendered view.
+
+In the example below, we create a _new material_ called `Material.001` for the monkey which we change to red. The cube already has a material called `Material`. We change the material being used to the monkey's material, before changing it back and editing the starting material so that it is blue.
+
+Try playing around with some of the other material settings, to see what effects you can create.
+
+![Assigning materials to objects.](videos/materials.mp4)
+
+## Edit Mode
+
+The last thing to be aware of when working inside of a 3D program like Blender, is that you can manually edit the 3D objects that are inside of the scene. In the top left hand corner of the 3D viewport. With an object selected, you can change between the different modes. You can edit the physical shape of a mesh, by moving individual or groups of vertices, by going into `Edit Mode`. You can also use the keyboard shortcut <kbd>Tab</kbd>
+
+![The different modes are available when an object is selected.](images/edit_mode_selection.png)
+
+With a mesh object selected, you can change in to edit mode. While in edit mode, different options are available to you, and you can phsyically edit the mesh. Try selecting some vertices of the mesh and moving them around individually.
+
+![Example of entering edit mode.](videos/edit_mode.mp4)
+
+You now know the _very basics_ of adding new objects, changing the materials, adding some lights and rendering an image. The same principles apply to everything that you you do in Blender, and often all of the different workspaces will contain similar keyboard shortcuts and ways of working. Try playing around some more inside of the 3D scene, rendering some different 3D images, before moving on to the section which includes actual proteins.
+
+Most things are best learnt by doing, so load some proteins in and try to follow along with the other tutorials.
+