User's Guide

Installation

1. Install one of the Blender 3 releases from https://www.blender.org/download/. We recommend using Blender 3.3. Remember the folder location of Blender’s executable file.
2. Clone the Goo repository (or download and unzip).
3. In Blender, go to Edit>Preferences. Then, check Add Mesh: Extra Objects in the ‘Add-ons’ tab.

Nagivate to the preferences	Enable Add Mesh: Extra Objects add-on

1. In Edit>Preferences, go to the File Paths tab and add the /path_to_your_Goo_clone/Goo/scripts/ folder to Scripts.

Add Goo scripts to Blender’s path

1. Re-start Blender.

Your first script

Create cells

1. Open Blender and its Scripting tab.
2. Import goo and Blender's Python API, and set up Blender's scene:

from goo import goo
import bpy
goo.setup_world() 

3. Declare your first cell collection, link your first two cells to it. The first cell is displayed in purple, which is the default material and the other in red. Colors are encoded following RGB color model:

# create first collection
goo.make_collection(name = "my_cell_collection")

# create first cell
goo.make_cell(name = "my_first_cell", 
                loc = (0,0,0), 
                collection = "my_cell_collection")
# create second cell
goo.make_cell(name = "my_second_cell", 
                loc = (0,2,0), 
                material = ("red", 0.1, 0, 0), # optional, default = ("purple", 0.007, 0.021, 0.3)
                stiffness = 2, # optional, default = 1
                collection = "my_cell_collection")  

4. Create your first scene by clicking the play button in the scripting tab of Blender.
5. Yay. You have created your first cells in Blender using Goo. Next steps elaborate on how to add adhesion forces and how to animate the scene using Blender's physics engine.

Add cell adhesion

Cells do not interact yet thus declare the corresponding adhesion forces:

# create first force collection
goo.make_collection(name = "my_force_collection")           
# declare first force
goo.make_force(force_name = "my_first_force", 
                cell_name = "my_first_cell", 
                strength = -1000, 
                collection = "my_force_collection")
# declare second force
goo.make_force(force_name = "my_second_force", 
                cell_name = "my_second_cell",
                strength = -1000, 
                falloff = 1, # optional, default = 1
                collection = "my_force_collection")

Add simulation details and launch

Handlers wrap up functions from Blender and Goo to update Blender’s scene when certain critera are met e.g. triggers cell division.

# launch simulation
goo.launch_simulation(start = 1, # optional, default = 1
                      end = 250, # optional, default = 250
                      filepath = "path_to_data_file//file.json", # if data = True
                      adhesion = True; # optional, default = True
                      growth = False, # optional, default = False
                      division = False, # optional, default = False
                      motility = False, # optional, default = False
                      data = False # optional, default = False
                      )

Execute your script

1. Execute your script from Blender’s Scripting tab then run the simulation in Blender’s Layout tab (shortcut: spacebar).
2. Execute and run your Python/Goo script from a VSCode terminal with the following command:

python simulations/blender_background.py

blender_background.py specifies your Blender executable path and the path to your newly created Goo script.

subprocess.run(
["<your_blender_folder>\\blender.exe",
"--python",
"<your_path>\\my_fist_script.py"])

Biological features supported in Goo

1. Biological cells

Goo’s cells models biological cells as polygon mesh deformable upon collision with other cells. Cells’ physical behavior such as stiffness, pressure and adhesion are tunable for biologists to investigate their impact on cell and tissue shapes. Homotypic adhesion is supported in Goo.

2. Cell adhesion

Adhesion forces are mimmicked by Blender’s built-in force fields. In Goo, they emanate from the cell’s surface, are local and centered on the cell’s center of mass.

3. Cell growth

Goo cells grow at a user-specified rate so that they volume isotropically increase.

4. Cell random motility

Goo implements cell undirected motility as a uniform random walk.

5. Cell division

Goo’s model for cell division follows Hertwig’s rule, stating that cells divide along their long axis. Therefore, the division plane is described as the plane orthogonal to the long axis and that passes by the cell’s center of mass.