Blender-tutorial-20180110

HIVE Training Retreat - January 10, 2018

This tutorial requires Blender 2.78c. It may not work with other versions. Download Blender 2.78c for your OS at: http://download.blender.org/release/Blender2.78/

Note for Mac user:

install in your user folder

if you have trouble getting the plugin to run, try running blender from the executable directly. Open the blender.app Package Content with Finder, browse to Content/MacOS/ and then run blender)

the current version of the plugin seems unstable and tend to crash. We highlight in red in the tutorial when you should expect a crash :(

Note for Windows User:

if the plugin doesnt start, try to install the visual C++ redistributable for vs2015 https://www.microsoft.com/en-us/download/details.aspx?id=48145

- uPy Plugin Package with ePMV & autoPack

1. Download plugins, depending on which system you're using:

   • 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

• 1. Unzip and move the contents of the extracted folder (MGLToolsPckgs and upy-addons.zip) into the Blender folder (where the executable is)

  2. Install add-ons upy-addons.zip using blender user preferences interface.

     1. In Blender, go to File>User Preferences

     2. Click on the Add-ons tab

     3. Click the "Install from File..." button at the bottom

     4. Navigate to upy-addons.zip and install it (double-click or push the "Install from File..." button)

     5. On the Add-ons tab, check the boxes for "System: autoPack", "System: ePMV", and "System: ePMV synchro" (easiest to find if you first click on the "System" Category on the left)

2. Restart Blender, ePMV and autoPACK should appear on the top right of the window.

3. Start ePMV (push the button, ePMV will appear in the Misc Tab on the left), at the top of the ePMV window, click Help->"Check for stable updates". Click yes. Do not restart Blender.

4. Start autoPACK, go to Help->Check for stable Update. Click yes.

5. 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:

If you have any difficulty installing the plugins, please post on our forum: autopack google group or send me an email at autin@scripps.edu.

FAST PACK

Step 1 Set Up

• • Start Blender. Click once to remove the splash screen. You should see a workspace laid out as in the figure below, with Tabs on the left edge, Viewport in the middle, and Outliner in the upper right. Resize the various windows as needed so you can see clearly. Also, for now, be careful not to do anything else or it might mess things up.

• • Disable the 3D Cursor, if you have not already done so. Click File>User Preferences>Input>3D View>3D View(Global)>Set 3D Cursor(clear the check box). Click the "Save User Settings" button on the bottom of the window so you don't have to do this every time you launch. Close the Preferences window.

In the Viewport you will see a cube and some other stuff. In the Outliner you will see a "Cube" object and some other stuff corresponding to the things in the Viewport. The "other stuff" is not important for this tutorial - just ignore it.

• • Delete the Cube by right-clicking on it in the Outliner, then clicking on "Delete".

  • Start autoPACK (push the button). A new tab named "Misc" containing the plugin interface will appear on the far left, and an (empty) object called "Welcome to autoPack" will appear in the Outliner.

  • Click on the Misc tab. To make space, close the "Register AP" panel by clicking the "Cancel" button at the bottom of the panel.

Step 2 Create a template

• • In the "autoPACK" panel, open the "Utilities" section.

  • In the Utilities section, click "Create custom Recipe". This will open a new panel called "myRecipe recipe setup" below the autoPACK panel, and it will create an object called "myRecipe" in the Outliner. In the Viewport, it will now look like you are inside a large box. This is the "BoundingBox", and describes the total volume to be filled.

  • Expand myRecipe by clicking the "+" to the left of the text. You will see several "children" of the myRecipe "parent" object. One of these children will be "BoundingBox" described above. The other important one right now is "myRecipe_Setup".

  • Expand myRecipe_Setup. You will see three children. The first is "myRecipe_compartments_geometries" - this is where we put our compartments. The third is "myRecipe_cytoplasm_ingredient" - this is where we put our ingredients. Expand both of these. Your workspace should look like the image below.

Step 2 Create an Ingredient

The simplest ingredient you can build and use is a Sphere.

• Click on the "Create" tab on the left. This will open the "Add Primitive" panel.

  • Click "Ico Sphere". This will create an icosahedral sphere object. This is important - "UV Sphere" creates a sphere using a quadrangular mesh; in general, one should only use triangular meshes in autoPACK.

  • Rename "Icosphere" to "Ingredient1" by double-clicking on the object in the Outliner. Your workspace should look something like the figure below. If not, something is messed up and you should restart.

Step 3 Insert Ingredient into Template

To drag an object in the scene hierarchy, click on the object icon to the left of the text.

• • Drag and drop Ingredient1 under myRecipe/myRecipe_Setup/myRecipe_cytoplasm_ingredient.

Step 4 Set Up Packing

• • Open the Misc tab.

  • In the "myRecipe recipe setup" panel, click SetupPacking. This will replace the "myRecipe recipe setup" panel with a new panel called "myRecipe Filler v1.0". It will also create some new objects in the Outliner and Viewport, including a new yellow spherical mesh for Ingredient1.

  • Save this configuration as "myRecipe_fast.blend" using Blender's "File->Save as..." drop-down menu on the top left.

Step 4 PACK

• • click PACK (at the bottom of the myRecipe Filler v1.0 panel)

That's it! You've completed your first PACK!

To get a better look at it, zoom out. NOTE: some spheres are outside of the box, which might seem strange, but don't worry about it.

You can now navigate around to look at the model from different perspectives.

Adjusting parameters:

Take a look at the myRecipe Filler v1.0 panel. It has several parameters that you can change to suit your needs. The most important for now are the "Recipe options" of "Density" and "+ this many". "Density" for soluble ingredients is in terms of Molarity. For surface ingredients, it is molecules per square nanometer. You will see that we packed Ingredient1 at "1.0 Molar, +0". If you want to pack 10 Ingredients, you can set it to "0.0 Molar +10". If you want to pack at 200 nanomolar, but want to make sure there is at least one Ingredient packed, you can set it to ".0002 Molar, +1". In the "Total to attempt" column, you will also see that we tried to pack 60 of Ingredient1, but could only fit 39. This tells us that for objects of this size or greater (which includes most proteins), there is not enough room to pack at a 1.0 Molar concentration. This is, in fact, physiologically true. So we have already learned something by making this simple model.

RECIPE WITH A COMPARTMENT

Step 1 Create the template

• Restart Blender.

• Load the blender file "myRecipe_fast.blend" from above.

• Start autoPACK.

  • In the Utilities panel, click "Create custom Recipe".

Step 2 Setup the bounding Box

• • Select BoundingBox in the Outliner.

  • In the window below the Outliner is a row of icons - select the icon that looks like a box.

  • In the Transform panel, under Scale, set X, Y, and Z to 25. This will enlarge the BoundingBox to a 500 Angstrom cube.

  • Scroll to the bottom of the window and find the "Display" panel. Set "Maximum Draw Type:" to Wire. This can be used to display objects as a wireframe so you can see the contents. It is good for the BoundingBox and for the compartments.

  • Zoom out so you can see the whole BoundingBox.

Step 3 Create the compartment

• On the left panel, click on the Create Tab

  • Click "Ico Sphere"

• In the "Add Ico Sphere" panel (below the create panel)

  • • Change Size to 180 (radius)

  • Change Subdivisions to 4 (to make it rounder)

  • Set "Maximum Draw Type:" to Wire.

  • In the scene outliner, double click on Icosphere, and rename to compartment1. Note: When renaming an object to be used by autoPACK, always use regular characters and avoid spaces.

• Select the compartment1 object in the scene outliner, and drag it under the object called myRecipe_compartments_geometries.

• Click the Misc tab.

• Click on SetupCompartments in the "myRecipe recipe setup" panel. This will put your Compartment into the correct structure for adding Ingredients.

• Save your work as "myRecipe_comp1.blend".

Ingredient1 is already in place in the cytoplasm. Now we will create ingredients to populate the compartment.

Step 4 Build the ingredient for the compartment interior

We are going to build two ingredients from the PDB - one for packing inside compartment1, and one for packing on the surface. The first ingredient is going to be elongation factor G (PDB entry 1EFG).

• • Start ePMV (cancel out of registration)

• In ePMV's "Get a Molecule" section, in the "pdbId:" field, enter 1efg and click Fetch.

• In the Surface Representations section, click "CoarseMolSurf".

  • Zoom in so you can see it better. You will see that the Coarse Molecular Surface does not look too good. 90% of the time, ePMV's preset values will display the molecules in an acceptable default form. Some PDB files, however, are only a backbone or carbon trace - these need to have the isovalue and/or resolution adjusted so that they look reasonable.

• change isovalue to 2.22

• change resolution to -0.076

• Select the object "CoarseMS_1efg" in the scene outliner (it will be under "1efg").

  • Rename CoarseMS_1efg to elongationFactor_mesh (Note: all of these names must be entered precisely, because these are the handles autoPACK uses to identify them)

  • Set "Maximum Draw Type:" to Wire.

  • In ePMV - "Atom/Bond Representations" section, click on PointClouds. This will create an object called 1efg_cloudds in the scene outliner (child of the object called 1efg) with a vertex for every atom.

• Select 1efg_cloudds.

  • In the autoPACK Utilities section, click on "Create custom Ingredient". This will create an object called "Cluster" in the Outliner with a child called "CenterSpheres", and open the SphereTreeMaker panel at the bottom of the Misc tab. This new panel will help you generate spheres covering the protein.

• In SphereTreeMaker, in the "SphereTree Build" section, change the "Number of clusters" to a value of 10.

  • In the scene outliner, under Cluster, rename CenterSpheres to elongationFactor

  • Drag and drop the object elongationFactor under

  • myRecipe/myRecipe_Setup/myRecipe_compartments_recipes/compartment1_recipe/compartment1_interior

• Save your work as "myRecipe_comp1_efg.blend".

Step 6 PACK

• • In "myRecipe recipe setup" (Misc tab), click SetupPacking. This will create a new "myRecipe Filler v1.0" panel. Note: If you're having trouble, you can download the corresponding blender file provided at the bottom of this page (myRecipe_setup_comp.blend).

  • In the "PACKing Options" panel, leave the placeMethod as jitter (e.g. grid based collision), and the innerGridMethod as jordan3, but change the "Smallest ingredient packing radius override" to 20.0 (this is the resolution of the grid used for distance and overlapping - a larger value will speed up the packing, but make it less accurate).

  • In the "Recipe options" panel, change all Density to 0.0, and in the "+ this many ingredients" column:

    • for ABCtransporter put 10

    • for elongationFactor put 30

    • for ingredient1 put 100

  • click "Update Totals", this will gave you an estimation of the final number of proteins in total.

  • In the "Advanced Options" column, click Edit for the ABCtransporter. This will open the "ext__ABCtransporter options" panel under Misc, allowing you to edit the detailed options for this particular ingredient. Leave everything as is except:

    • • set the principalVector to x0, y0, z1. Note: In general, you can determine the principal axis by looking at the Ingredient's geometry, and seeing which axis is perpendicular to the membrane, pointing out. The principal vector for this ingredient, is along the Z axis [0, 0, 1].

    • set the jitterMax to x1, y1, z0. (Note: this controls the distance from the grid point allowed. For surface ingredients, we want the ingredient to be able to move horizontally in the membrane, but not along the principal axis.)

    • set the offset to 0.0, 0.0, -15.0. (Note: this information can be found on OPM)

    • click Apply (at the bottom of the window)

    • click Close

• • Save your recipe - under "myRecipe Filler v1.0", click File->"Save Recipe as" and save as myRecipe.json (Note: the Save button in this window actually says "choose a json file")

• Click PACK and wait for the result

Now, elongationFactor and ABCtransporter are both the default red color, so it's difficult to distinguish them. To fix this:

• Select ABCtransporter_mesh.

• In the Display panel, below the Outliner, four icons to the right of the little box, select the icon that looks like a circle divided into four sections.

• In the "Diffuse" panel, click on the colored rectangle. A color palette will pop up.

• Select your desired color by clicking on the palette - green would be good for contrast. You can also hold the button down and slide it around to test other colors.

• Save your work as "myRecipe_final.blend".

Congratulations! You have completed the Tutorial!

myRecipe_final is a completed model, which you can export in your desired format. You can try deleting unnecessary objects to clean it up.

You are now ready to start making your own models. You can use any PDB or OPM file to generate your Ingredients, and you can use any triangulated mesh to identify your compartments. Any number of compartments and ingredients can be entered using the methods outlined in this Tutorial. You can also adjust the concentrations of the Ingredients as you wish.

There is a lot more about cellPACK to learn, but this will get you started. Feel free to contact us when you have questions.

Brett Barbaro - bbarbaro@scripps.edu

Ludovic Autin - autin@scripps.edu

Happy PACKing! :)

NOTE: downloadable files below are not perfect, and should be replaced with better versions. Also, myRecipe_comp1_efg_ABC.blend was too large to upload. (Same with final files) There is apparently no space left for new uploads. Old stuff should probably be deleted to make space.