blender-tutorial
NBCR Hands-on tutorial
UCSD, San Diego 8/11/2017
The requirements for the tutorial are :
- uPy Plugin Package with ePMV & autoPack
Mac OS 64bits Blender 2.7x upy-Blender-mac-64.zip
Linux 64bits Blender 2.7x (python3.4) upy-Blender-linux-64.zip
Linux 64bits Blender 2.78c (python3.5) upy-Blender-Linux-Py35.zip
Windows 64bits Blender 2.76 (python 3.4) upy-Blender-win-64.zip
Windows 64bits Blender 2.78 (python 3.5) upy-Blender2.78-win-64.zip
unzip and move the content of the extracted folder in the blender folder next to the blender executable (you should have MGLToolsPckgs and upy-addons.zip )
install add-ons upy-addons.zip using blender user preferences interface.
Restart Blender, ePMV and autoPACK should appear on the top right of the window.
Start ePMV, go to Help->Check for stable Update. Click yes. Do not restart Blender.
Start autoPACK, go to Help->Check for stable Update. Click yes.
Restart blender if you have updated.
We recommend user to check the blender reference manual and the getting started section :
https://docs.blender.org/manual/en/dev/
To test the plugin:
start Blender
start autoPACK
click on the Misc Tab
in the View panel select BloodPlasma recipe
click Construct
If you have any difficulty installing the plugins, please post on our forum: autopack google group or send me an email autin@scripps.edu.
The tutorial will cover basics usage of autoPACK :
(i) build a recipe
(i) pack a recipe
(ii) view results
(iii) advanced visualization, transition with cellVIEW for high performance visualization
See the video
Build a recipe
Building a recipe consist in describing (i) a list of ingredients (shape, concentration, etc..) and their localisation such as exterior, interior or surface of a compartment and (ii) the different packing options. In order to build a custom recipe, we are going to use our utilities that hopefully will make the process easier.
Step 1 Create the template
start Blender
Start autopack (the plugin will appear in the Misc Tab on the left)
In the Utilities Tab, enter a name for your recipe and click "Create custom Recipe". Note : this will create a new windows and prepare a template for the recipe. The template show the usual architecture of a recipe.
In the out-liner, you should see a tree similar to the one in the adjacent figure. You should see an object called myRecipe_Setup, this is where we are going to describe the recipe. The BoundingBox is the box representing the total volume to be fill. (Note: we assume 1 unit = 1 angstrom). The custom recipe we are going to build consist in 5 ingredients and 2 compartments organized as follow :
exterior
ingredient 1
compartment 1
surface
ingredient 2
interior
ingredient 3
compartment 2
surface
ingredient 4
interior
ingredient 5
Step 2 Make the compartments
Select the BoundingBox, click on "+" in the viewer to show the properties panel
In the Transform panel (top), change
in Location:, change values to
x 0
y 0
z 0
in Dimensions, change values to
x 1000 (10m = 1000cm = 1000A)
y 800 (8m = 800cm = 800A)
z 500 (5m = 500cm = 500A)
In the View panel, change the Clip End value to 100000, so that there is no camera far clipping.
Note: if you don't see the Dimension, or the Clipping value, you may be in the Edit mode of Blender, which is dedicated to mesh editing. To toggle back to the Object mode, either do it manualy with the pull down menu at the bottom of the Viewport, or type on your keyboard "Tab"
Create a second Ico Spheres
In the object attribute (right bottom), change
In the Add Ico Sphere panel (below the create panel)
Change Subidivisions to 4
Change Size to 180 (radius)
Change Location to
x 280
y 140
z 0
in the scene outliner, double click on Icospphere, and rename to compartment2.
Note: When renaming an object to be used by autoPACK, use regular character and avoid space.
Select both object in the scene outliner, drag them under the object called myRecipe_compartments_geometries.
You can now click on SetupCompartments in the plugin window. Again, this will only work if the object are triangulated meshes.
Note: For a geometry to be used as a compartments in autoPACK , it has to be a triangulated mesh. If you are working with Quad geometry, you need to triangulate them before they can be used in autoPACK. In Blender you can triangulate a polygonal object by switching to the Edit Mode. Then select the target object, and click on the menu Mesh->Faces->Triangulate faces. There is a keyboard shortcut you can use : Ctrl+T
On the left panel, click on the Create Tab
Create a Ico Spheres
In the Add Ico Sphere panel (below the create panel)
Change Subidivisions to 4
Change Size to 250 (radius)
Change Location to
x -180
y -120
z 0
in the scene outliner, double click on Icospphere, and rename to compartment1.
The SetupCompartments automatically generates the template necessary for autoPACK to recognize the compartments. Now is a good time to save your work (File->Save as->MyRecipe.blend).
We can now start to prepare the ingredients.
An ingredient is an object you want to distribute in a volume. To describe it we need a shape representation, the preferred approach is to use a sphere tree representation (coarse graining or ultra-coarse graining approach). In this simple example, we are going to prepare ingredients that represent different situation:(i) dummy sphere when no structural information is available. (ii) from the PDB (Xray or NMR) when a structure is known, (iii) electron microscopy data in case there is no Xray. While using ePMV and autoPACK it is important that you keep the cursor location to the origin.
Step 3 Build ingredients without information
The simplest ingredient you can build and use is a Sphere.
Create an Ico Spheres of size 20 and Subdivision of 2 or 4, and location at the origin (0,0,0).
We can focus the viewport on the selected object. At the bottom of the viewport click on the View menu, and click on View Selected (Notice the keyboard shortcut)
In the scene outliner change the name to ingredient1
Drag and drop the object under
myRecipe/myRecipe_Setup/myRecipe_cytoplasm_ingredient
A more complex ingredient can be made up of several spheres.
Create 1 Ico Spheres of radius 10.0
Change the name to Sphere0
Duplicate the spheres 6 times, and place the sphere so the overall shape look like in the figure (Y shape). To duplicate you can use Shift-D or Object->Duplicate.
Note: You can hide other object that are on the way.
Create an Empty object at the origin
Rename the Null empty object to ingredient2
Make all the spheres child of the ingredient2 object (drag and drop)
Drag and drop the object under
myRecipe/myRecipe_Setup/myRecipe_compartments_recipes/compartment1_recipe/compartment1_surface
Note the principal axis which is the up direction of your Y shape, which will be used for alignement to the surface. In the example I used the positive Z axis (0, 1, 0).
We can define an offset from the origin that will be applied when the object is aligned to the surface.
In order to make a mesh representation of this ingredient we can use the metaballs
Create a Metaball objects (in the viewport type Shift-A, click on Metaball->Ball), set the location to the origin
As for the sphere, duplicate the first metaball and follow the same Y shape.
Select the first created metaball, in the viewport type Alt-c, click on Mesh from Curve/Meta...(you can delete the remaining MBall objects)
This created a new object (MBall.007 in my case), rename it ingredient2_mesh
Select ingredient2_mesh, type "Tab" on the keyboard, type "a", and then "Ctrl+T". What this sequence does is to go in Edit mode, select all vertices, and triangulate the faces.
Save your work (Ctrl+S)
Step 4 Build an ingredient from a PDB file using ePMV and autoPACK utilities
We are going to build two ingredients from the PDB, one for packing inside and one for packing at the surface of compartment 1. The first ingredient is going to be the elongation factor G (PDB entry 1EFG).
Start ePMV
In ePMV enter 1efg and click fetch.
In Surface Representation, click "CoarseMolSurf"
change isovalue to 2.22
change resolution to -0.076
Select the object "CoarseMS_1efg" in the scene outliner. Below the scene outliner, in the object tab you change how the object is display in the viewport. Select Wire as the Maximum Draw Type.
In ePMV - Atom/Bond Representation tab, click on the PointsClouds. Note: this is a special representation that create a mesh with only vertices, one vertice per atom position.
Note: you may have to renceter the pointclouds to the origin.
In the autoPACK plugin utilities Tab click on "Create custom Ingredient". Note :The new window will help you generate spheres covering the protein. This approach is based on the K-means clustering algorithm.
Change the number of clusters to a value of 10
Change the scale to a value of 0.5
In the scene outliner, rename CenterSpheres to elongationFactor
In the scene outliner, rename CoarseMS_1efg to elongationFactor_mesh
Close the SphereTreeMaker windows
Drag and drop the object elongationFactor under
myRecipe/myRecipe_Setup/myRecipe_compartments_recipes/compartment1_recipe/compartment1_interior
Save your work
Step 5 Build a surface ingredient from an aligned PDB using OPM (Oriented of Protein in Membrane)
The second ingredient is a membrane protein that we want to distribute on the surface of a compartment. We are going to prepare an ingredient representing a bacterial ABC transporter (PDB entry 1L7V).
next to the fetch button, click the pull-down menu (PDB), and select OPM (Orientations of Protein in Membranes server)
enter 1l7v and click fetch
This protein consist in 6 chains, A,B,C,D,E for the protein, and an unnamed chain for the dummy atoms representing the membrane.
in the selection field enter "chain A,B,C,D,E". So we skip the dummy atoms.
In Surface Representation, click "CoarseMolSurf"
change isovalue to 4
change resolution to -0.228
In Atom/Bond Representation click on the PointsClouds (change location to origin if it isn't).
In the autoPACK plugin utilities Tab click on "Create custom Ingredient".
Change the number of clusters to a value of 10
Change the scale to a value of 0.5
Note the principal axis, and the direction of the protein toward the outside, which is along the Z axis [0, 0, 1].
Rename CenterSpheres to ABCtransporter
Rename CoarseMS_1l7v to ABCtransporter _mesh
Save your work
Close the SphereTreeMaker windows
Drag and drop the object ABCtransporter under
myRecipe/myRecipe_Setup/myRecipe_compartments_recipes/compartment2_recipe/compartment2_surface
(Optional depending on time) Step 6 Build an ingredient using electron microscopy data from EMDB
Often no precise structural information (Xray, NMR) exists for a given protein, but electron microscopy data exist and can be used to prepare an ingredient. For this tutorial we are going to use the electron microscopy data obtained for the chaperone Hsp40 in Escherichia Coli. (EMDB entry 2334).
Download the map from EMDB entry 2334 and change the extension to .mrc or download it directly at the bottom of the current page.
in ePMV, click File->Open Data. Browse to the map you just download, and load EMDB-2334.mrc
in ePMV, in the Data Player, change the step/value to the recommended isovalue 1.66
Select the object called grid_1IsoSurface
In the autoPACK plugin utilities Tab click on "Create custom Ingredient".
In the Grid Build enter 10 instead of 20
click Gridify. Note : this will generate grid point only inside the mesh. Can take up to 2 min to compute with the defaul method. This step is optional, we could use the mesh point for the clustering. Or simply place the spheres manually.
Close the SphereTreeMaker
select the object named grid_1IsoSurface_innerPts
In the autoPACK plugin utilities Tab click on "Create custom Ingredient".
Change the number of clusters to a value of 10
Change the scale to a value of 0.5
Rename CenterSpheres to chaperoneHsp40
Rename grid_1IsoSurface to chaperoneHsp40_mesh
Save your work
Close the SphereTreeMaker windows
Drag and drop the object chaperoneHsp40 under
myRecipe/myRecipe_Setup/myRecipe_compartments_recipes/compartment2_recipe/compartment2_interior
Put everything together
Make visible any object you hided (e.g. compartments or ingredients)
By now the recipe should be complete. You should have the following structure :
elongationFactor under compartment1_interior
ABCtransporter under compartment1_surface
chaperoneHsp40 under compartment2_interior
ingredient4 under myRecipe_cytoplasm_ingredient
ingredient5 under compartment2_surface
Your scene should look like the images below. Wait for instructor before going further. Save your Work.
When ready click SetupPacking, in the new window click File->Save Recipe as and save it in your recipe folder. Then follow the next step of the tutorial below.
If you have trouble you can find the corresponding blender file at the bottom (myRecipe_setup.blend).
Pack a recipe
Time for packing the recipe we just build. We are going to go through the most important options in autoPACK, and the default value that should be used most of the time. There is two levels of options. General options for the packing, and individual option per ingredients.
Select the object named myRecipe_setup, and hide it
Objects->Object Display-> Editor Off
Objects->Object Display-> Renderer Off
Packing options, leave everything as is except:
leave the packing method to jitter (e.g. grid based collision)
change the grid method to jordan3
change the smallest ingredient radius to 10. (this is the resolution of the grid used for distance and overlapping)
Recipe Options (e.g. individual Ingredients Options), leave everything as is except:
change all molarity to 0.0. Note: for an accurate recipe proper concentration or copy number is require.
for ingredient2 put 60 in the "+this many" field
for elongationFactor put 30
for ABCtransporter put 10
if present, for chaperoninHsp40 put 5
for ingredient1 put 500
click Update Total.
Ingredients Advanced Options
Edit surface Ingredient ingredient2. Click on the Edit button, this will open the detailed options for this particular ingredients. Leave everything as is except:
set the Principal Vector to 0, 0, 1. You can check the principal axis by looking at the ingredient2 geometry, and look at what
axis is perpendicular to the membrane
set the JitterMax to 1, 1, 0. Note: this control the offset from the grid point allowed. For surface ingredient, we don't want the ingredient to move freely on the principal axis.
click Apply (at the bottom of the window)
click Close
Edit surface Ingredient ABCtransporter. Click on the Edit button, this will open the detailed options for this particular ingredients. Leave everything as is except:
set the Principal Axis to 0, 0, 1. You can check the principal axis by looking at the ABC transporter geometry, and look at what axis is perpendicular to the membrane
set the JitterMax to 1, 1, 0. Note: this control the offset from the grid point allowed. For surface ingredient, we don't want the ingredient to move freely on the principal axis.
set the offset to 0.0, 0.0, 15.0.
click Apply (at the bottom of the window)
click Close
Click File->Save Recipe as "myRecipe.json"
Click PACK
#Progress BAR
After completion, save your results using File->save Result as "myRecipeResult"
You can also save your recipe to reflect the changes in the options. File->Save Recipe as
Explore the result
click Clear Pack
Change the grid resolution to 10 (slowest computation but better collision detection)
click PACK
in Packing option uncheck Rebuild the grid
click Clear Pack
change the packing method to spheresBHT (spheres collision) or RAPID (triangle collision)
Click PACK
Explore the result
click Clear Pack
change the seed, change the copy number
Click PACK
Pack existing recipes
We provided several pre-made recipe that are accessible for visualization and packing.
The Pack Tab in the plugin let you access our recipe from the repository as well as loading your custom recipe. Once loaded, the plugin will show you a dedicated windows to adjust parameters and options for building the model. See above for an example on how to use the packing interface.
Edit a recipe
Once a recipe has bee build and you want to modify it, without restarting everything from the beginning you can simply edit the recipe setup file (in json format). you can use any text editor, or special editor for json file. We would suggest to use this web server : http://www.jsoneditoronline.org/.
in a text editor open the recipe you prepare and save in the previous step (MyRecipe.json for instance)
in a browser go to http://www.jsoneditoronline.org/
copy and paste the recipe text in the left panel of the server.
click the right arrow on the server, this should fill the right panel with your recipe.
Add an existing ingredient from the repository
All recipes and ingredients currently available are on our repository. In a recipe we can include external file defining an ingredient, such as the one produce using the sphereTree plugin, or available ingredient in the repository. We are going to add the hemoglobin in the recipe.
in the json editor, find the cytoplasme compartments
insert the text below just befor ingredient4 definition
"Hemoglobin":{ "include":"Hemoglobin.json", "name":"Hemoglobin" },
save your change
restart C4D, load the modified recipe and verify the new ingredient is present.
Running/viewing recipe (View tab in the plugin)
The View Tab let you load previously build model from our repository or from your local drive. Select a Recipe in the pull down menu and click "Construct". This will gather from our repository all necessary files and display a new windows that will let you show/hide any elements in the model. You can also Load your custom recipe, and load different results you generated previously.
Advanced Visualization: cellVIEW
You should notice that as you increase the number of ingredient, and the number of copies for each of them, the frame rate of the host viewport is going to drop down, due to the amount of object and triangle to display. visualizing all ingredient at their native resolution (e.g. atomic resolution, or high number of polygons) will require high end hardware and will be not real time. For this reason we collaborate Mathieu Le Music, Peter Mindek and Ivan Viola from the Vienna University of Technology to developp a real time solution for visualing such large scene at the highest resolution possible. The result is cellVIEW, a higly performant graphics pipeline developed inside Unity capable of render up to 30 million atoms at 30fps.
cellVIEW currently supports :
any cellPACK json result file , for which a PDB entry is provided for each ingredients
cutaway object
shadow
any unity image effects
The tutorial recipe in cellVIEW. The representation will use atomistic details if available, otherwise it will use the spheres representation.
