blender-tuto-light

• NBCR Hands-on tutorial

UCSD, San Diego 8/11/2017

The requirements for the tutorial are :

- Blender 2.78c

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 except 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.

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 autin@scripps.edu.

Build a simple recipe

Building a recipe consists of describing (i) a list of ingredients (shape, concentration, etc..) and their localization, 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, and delete the starting cube.

• • Start autoPACK (push the button - the plugin will appear in the Misc Tab on the left. Register or cancel out of registration.)

• In the autoPACK Utilities Tab click "Create custom Recipe". This will open a new panel called "myRecipe recipe setup" below the autoPACK panel, and it will create some objects and prepare a template for the recipe in the scene outliner window (upper right). The template shows the usual architecture of a recipe. (Note: you can create your own recipe name by filling in the field to the right of the button. For the purposes of this tutorial, though, we recommend using the default.)

In the scene outliner, you should see a tree similar to the one in the figure above (which has several sections expanded), which includes 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 filled. (Note: we assume 1 unit = 1 angstrom).

Step 2 Setup the bounding box

• 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 100 (1m = 100cm = 100A)

      • y 100 (1m = 100cm = 100A)

      • z 100 (1m = 100cm = 100A)

• In the View panel, under Clip, change the 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, use the pull down menu at the bottom of the Viewport.

Step 3 Build ingredients without information

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

• On the left panel, click on Blender's Create Tab

  • Click "Ico Sphere"

• If the sphere is not at the origin, place it at the origin (using the Transform panel).

• 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 from "Icosphere" to "ingredient1" (double clicking on the name will let you edit it).

• To drag an object in the scene hierarchy, click on the object icon and drag over the desired parent. Drag and drop the object ingredient1 under myRecipe/myRecipe_Setup/myRecipe_cytoplasm_ingredient.

  • Save your work as a blender file, File->"Save As..." myRecipe_setup_simple.blend

When ready, in Misc->"myRecipe recipe setup", click SetupPacking. This will create a new panel in Misc called "myRecipe Filler v1.0". In this panel, click File->"Save Recipe as" and save it as myRecipe_simple.json in your working directory. Then follow the next step of the tutorial below.

If you have trouble you can download the corresponding blender file at the bottom of this page (myRecipe_setup_simple.blend).

Step 4 Pack

Time for packing the recipe we just built. We are going to go through the most important options in autoPACK, and the default values that should be used most of the time. There are two levels of options: general options for the packing ("PACKing Options" panel), and individual options per ingredient ("Recipe options" panel).

• • Packing options, leave everything as default.

    • Note: the Smallest ingredient field corresponds to the grid voxel size. This will affect speed and quality of the collision detection (when using the jitter packing method).

• Recipe options:

  • Change the Density of Ingredient1 to 0

  • In "+ this many ingredients", input "10"

  • Press "Update Total" button. The panel should look something like this:

• PACKING

  • to pack simply click PACK

  • to pack again with different parameters :

    • click Clear Packing Note: this seems to crash a lot on Mac OS, and may require you to restart.

    • change parameter (for instance the grid resolution or the number of ingredient 1 or the Random Seed)

    • Note: if you don't change the grid resolution (smallest ingredient in the recipe), you can uncheck Rebuild the grid, which saves time, especially on packs with multiple compartments.

    • click PACK

  • here are some examples with different parameter values:

Build a recipe with a compartment

Step 1 Create the template

• restart Blender

  • load the blender file from the simple recipe myRecipe_setup_simple.blend

• Start autoPACK (the plugin will appear in the Misc Tab on the left)

  • In the Utilities panel, enter the name of the recipe used in the previous steps (myRecipe). Click "Create custom Recipe". This will open the custom recipe panel.

Step 2 Setup the bounding Box

• • Select the BoundingBox, and click on "+" in the viewer to show the properties panel

  • In the Transform panel (top), change

    • in Location, change values (if necessary) to

      • x 0

      • y 0

      • z 0

    • in Dimensions, change values to

      • x 500 (5m = 500cm = 500A)

      • y 500 (5m = 500cm = 500A)

      • z 500 (5m = 500cm = 500A)

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 Subdivisions to 4

    • Change Size to 180 (radius)

    • Change Location (if necessary) to

    • x 0

    • y 0

    • z 0

  • in the scene outliner, double click on Icosphere, and rename to compartment1.

• Note: When renaming an object to be used by autoPACK, use regular characters and avoid spaces.

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

• You can now click on SetupCompartments in the plugin window. This will create the proper objects and hierarchy for setting up ingredients to be packed on the interior and surface of the compartment.

• Save your work as myRecipe_setup_comp.blend

Note: For a geometry to be used as a compartment in autoPACK, it has to be a triangulated mesh. If you are working with Quad geometry, you need to triangulate it before it can be used in autoPACK. In Blender you can triangulate a polygonal object by switching to the Edit Mode, selecting the target object, and clicking on the menu Mesh->Faces->Triangulate faces. There is also a keyboard shortcut you can use: Ctrl+T

We already have an ingredient for the exterior - we are now going to 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 (register or cancel out of registration)

• In ePMV fetch input field enter 1efg and click fetch.

• Verify that the 3D Cursor Location is at the origin

• In the Surface Representations panel, click "CoarseMolSurf"

• change isovalue to 2.22

• change resolution to -0.076

• Select the object "CoarseMS_1efg" in the scene outliner (it will be under "1efg"). Below the scene outliner, in the object settings (click on the box with the cube) you change how the object is displayed in the viewport. Select Wire as the Maximum Draw Type.

• • In ePMV - "Atom/Bond Representations" panel, click on PointClouds. Note: this is a special representation that creates a mesh with only vertices, one vertex per atom position.

• Select the object called 1efg_cloudds in the scene outliner (child of the object called 1efg). Note: you may have to re-center the pointcloud to the origin.

  • While 1efg_cloudds is selected, in the autoPACK plugin Utilities panel click on "Create custom Ingredient". This will open the SphereTreeMaker plugin at the bottom of the Misc tab. This new panel will help you generate spheres covering the protein. Note: This approach is based on the K-means clustering algorithm.

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

• Change the scale to a value of 0.5

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

  • In the scene outliner, under 1efg, rename CoarseMS_1efg to elongationFactor_mesh

  • Drag and drop the object elongationFactor under

  • myRecipe/myRecipe_Setup/myRecipe_compartments_recipes/compartment1_recipe/compartment1_interior

• Save your work as myRecipe_setup_comp.blend

Step 6 PACK

• Under Misc, in "myRecipe recipe setup", click SetupPacking. Seems to crash, and require restarting

  • This will create a new panel in Misc. In the new panel called myRecipe Filler v1.0 click File->Save Recipe as and save it as myRecipe_compartment.json in your recipe folder (Note: the Save button in this window actually says "choose a json file"). 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).

  • In the "Recipe options" panel, change all Density to 0.0. Note: for an accurate recipe, proper concentration or copy number is required.

• 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" dialog under Misc, allow 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 ABC transporter geometry, and seeing which axis is perpendicular to the membrane, pointing out.)

    • 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

• • Under "myRecipe Filler v1.0", click File->"Save Recipe as" and save as myRecipe_compartment2.json

• Click PACK and wait for the result

• as for the simple recipe, you can clear the result, change some parameters and Pack again

cellPAINT https://docs.google.com/document/d/1Grt_y0G8dq7lkdzIEJeg8s0HPQeriS0pJMxpPHwon90/edit?usp=sharing