GUI & Parameter Guide

autoPACK: INTERFACE & PARAMETER Guide July 16, 2013

autoPACK made possible by Graham Johnson, Ludovic Autin, Mostafa Al-Alusi, David Goodsell, Michel Sanner & Arthur Olson

autoPACK multi-host GUIs made possible by uPy from Ludovic Autin, Graham Johnson, Johan Hake, Arthur Olson, & Michel Sanner

http://autopack.org Download free | Install | Tutorials | Gallery | Forum

http://rdb.name/Panda3D-1.9.0.dmg

Glossary

• 1. Scene– an all inclusive model that has lights, cameras, geometries, materials, effects, etc. to make up a standard 3D file

  2. Ingredient– a building-block component. Most autoPACK models will have repeated geometries. Ingredients provide the reference models that can be iterated throughout the scene to produce larger composite models. Ingredients are computational agents- they have default behaviors that affect how they will pack into their environment to provide a great deal of sophisticated control.

  3. Container– a geometric surface or volume (an actual mesh or mathematical description) that can be filled by autoPACK. Containers can be filled inside, outside, and/or on their surfaces.

  4. Recipe– a collection of parameters that add global descriptions to the ingredient's behaviors that can further affect how the ingredients pack and that can override the ingredient-level agent behaviors.

autoPACK menu

1. Help

   1. Check for latest stable updates

   2. Compares your local version of autoPACK to the latest Stable version available on the server and offers an opportunity to update.

   3. It is wise to say yes when asked if you wish to backup your current version in case you decide to revert in the future.

   4. Check for latest development updates

   5. Compares your local version of autoPACK to the latest Development version available on the server and offers an opportunity to update.

      1. This choice is not recommended for production-level users and is intended for developers or hobbyists who want to try the latest features regardless of stability.

      2. It is wise to say yes when asked if you wish to backup your current version in case you decide to revert in the future.

   6. Get latest recipes list

• • 1. Will update your GUI with the latest recipes available on the server- also occurs when restarting the host, so not necessary for most users.

1. 7. View Updates Notes

• • 1. Takes you to the text document on the server that shows the latest versions available for every host.

1. 8. Visit autoPACK website

• • 1. Goes to autoPACK.org in your systems default web browser

1. 9. Visit autoPACK API documentation

• • 1. Goes directly to the API page at autoPACK.org

1. 10. About

• • 1. Credits to the autoPACK core authors, license information and instructions for citing autoPACK.

1. 11. Close autoPACK

Viewer tab

1. Load an autoPACK/cellPACK recipe for: <RecipeName>

   1. Use this dropdown menu to select an existing recipe that you want to Construct into your scene.

   2. The options include:

      1. Default recipes from the server (like HIV, or Test_Spheres2D)

      2. Fetch a recipe from the web

      3. Load a recipe from your hard drive

2. Recipe Version

3. If loading a default recipe through the RecipeName dropdown above, use this dropdown to select the version of the autoPACK result file that you want to use.

4. Higher numbers are more recent.

5. [√] Build ingredient geometries upon loading

6. If checked, this button will add the base geometry to your scene (basic building blocks) that will later be instanced to make the full model.

7. If unchecked, you can load each base geometry "as-needed" when you turn on ingredients in the model. The ingredient-level "Build" buttons are only available in the Advanced and Debug GUI modes (see Options Tab below for mode details).

8. Unless you know that a recipe has a computationally expensive ingredient (e.g., high-poly count) that you want to avoid, there is no reason to uncheck this button.

9. [√] Show ALL ingredient instances upon loading (may slow viewport)

10. If checked, this button will attempt to display every instance of the model you choose to Construct. Large models may bring small or slow computers to their knees.

11. If unchecked, no models will be displayed upon loading- the instances are constructed, but disabled, so you can turn on ingredients one at a time or in sets and modify them as needed to manage the scene.

12. For most default models on computers after 2010 with 8+GB of RAM, this button should be left checked by default.

13. [√] (Re)Build the grid upon loading (may slow the loading)

14. If checked, and Constructing the scene in Debug mode, the grid used by the recipe to build the result file will be reconstructed into the scene using the parameters of the default recipe to enable analysis of the grid.

15. This option is currently for advanced users, but will be refined for use by intermediate autoPACK users in autumn of 2013.

16. [√] Force downloading the ingredient geometries

17. If checked, autoPACK will compare the versions of the ingredients in the cache on your local harddrive to those on the server. If different, the local versions will be replaced.

18. Checking this option will slow the load time, but we recommend doing this periodically to make sure you have the most up to date and robust models.

19. WARNING: IF you are an advanced user and are generating your own custom ingredient mesh files and placing them in the cache_ingredients folder, checking this box could cause your file to be overwritten by the Server version, so be sure to use a different name for your local result file version, e.g., HIV_1_3_dev.apr

20. [√] Force downloading the latest result

21. If checked, autoPACK will compare the versions of the result file in the cache on your local harddrive to the version on the server. If different, the local versions will be replaced.

22. We recommend checking this option periodically to make sure you have the most up to date and robust result files. Result files that have major overt errors or that cause instability are replaced, but in most cases, the project does not replace old result files and encourages the release of a new version of a recipe model, even if there are only minor changes.

23. WARNING: IF you are an advanced user and are generating your own result files from a default recipe using the Filler, checking this box could cause your file to be overwritten by the Server version, so be sure to use a different name for your local result file version, e.g., HIV_1_3_dev.apr

24. [Construct] selected recipe scene into the current document

• 1. When clicked, this button will setup the current scene of your 3D software with an autoPACK model using the selected recipe and version.

  2. In short, the [Construct] button will:

     1. download any needed geometries (or use ones you already downloaded that it finds in your cache) for every unique ingredient shape in your scene

     2. build materials for each of the meshes if the recipe calls for materials

     3. add hidden versions of these geometries to your scene to use as "reference geometries"

     4. use an instancing technology of your hosting 3D software to generate "copies" of the geometries in the locations assigned by the autoPACK Result File you've pointed to

     5. add a RecipeName Viewer (popup GUI window) to the scene that allows you to turn objects and object groups on and off or to edit and customize ingredients (Advanced and Debug modes only)

     6. update the hierarchy/node managers and viewport with the model according the the settings in the recipe file and selections in this GUI

RecipeName Viewer v1.0 dialog box

1. [Clear Ingredient]

   1. Use this button to remove all of the instances of all of the ingredients from your scene while retaining the base geometries.

   2. As of autoPACK v0.5.622, this button has no effect. It will return soon, so update often.

2. [Clear Recipe]

• 1. Use this button to remove everything that autoPACK added to your scene.

  2. As of autoPACK v0.5.622, this button has no effect. It will return soon, so update often.

3. [reConstruct Recipe]

• 1. Use this button to remove and rebuild the recipe- to get it back to the defaults you saw when you first constructed in case anything has moved or changed.

  2. As of autoPACK v0.5.622, this button has no effect. It will return soon, so update often.

  3. Compartment #1: CompartmentName

  4. [√] Display CompartmentName surface representations

     1. If an object has a geometric representation that was filled by autoPACK, it can be shown with this button.

     2. For example, if you packed model of a wooden barrel (set in the recipe to = Compartment #1) with a recipe of monkey mesh geometries, you can check this button to display the wooden barrel.

  5. [√] Display CompartmentName packing surface

• • 1. This option is only available in the Advanced and Debug GUI modes.

    2. If checked, this option will display the mesh of the geometry that was used to define the boundaries of Compartment #1 for packing.

    3. This option is generally only useful in the Viewer for analysis- to ensure that the packing is behaving as expected, not for final renders.

• 6. Show Name

• • 1. Column labels for the Simple mode of the RecipeName Viewer window to describe buttons beneath

• 7. Show Advanced Name

• • 1. Column labels for the Intermediate mode of the RecipeName Viewer window to describe buttons beneath

• 8. Show Build Advanced Name

• • 1. Column labels for the Advanced mode of the RecipeName Viewer window to describe buttons beneath

• 9. Show Build Primitives Advanced Name

• • 1. Column labels for the Debug mode of the RecipeName Viewer window to describe buttons beneath

• 10. Show

• • 1. [√] When checked, all instances of the ingredient will be visible in the scene (unless hidden manually by the user)

    2. Build (Advanced and Debug modes only)

    3. [√] When checked, the base reference geometry will be added to the scene

    4. If unchecked, the base reference geometry will be deleted from the scene (if you are certain you never want to use an ingredient, unchecking build will reduce the size of your 3D file when saving.

    5. This option is not yet fully functional for all hosts

• 11. Primitives (Debug mode only)

• • 1. [√] When checked, the primitives used for jitter-based collision detection and for packable space availability during packing are displayed (usually a collection of spheres and/or cylinders that roughly describe the shape of the object.

    2. This option is used primarily to study the interaction of ingredients with one another and with the packing grid for analysis of the packing method and results, e.g., with the jitter packing method, minor overlaps are allowed between objects and turning on the primitives will show the limits of these allowable overlaps to the knowledgeable user.

• 12. Advanced

• • 1. [Edit] Clicking this edit button will open a new IngredientName Display Options window to allow the user to modify the display properties of that ingredient (will apply to all instances of that ingredient) See details below.

    2. IngredientName Display Options window:

    3. Object (leave empty to use current selection) { uniqueOrFirstSceneObjectName }

    4. Type the name of the object in your scene that you want to be instances as the geometry to represent the ingredient

    5. In the HIV model for example, make a cube with your host, name it "CubeA" and set it to a sensible size (similar to the iSUTM proteins) and translate its center to (0,0,0)

    6. Type "CubeA in this Object box and click Apply and watch as all the Spike proteins (iSUTMs) become copies of CubeA

    7. Resolution: <Medium>

    8. Many ingredients have multiple representations available, ranging from simple shapes (Low) to highly detailed molecular surfaces (High)

    9. Because an ingredient may be duplicated/instanced/copied 10s or even millions of times throughout a scene by an autoPACK result file,

    10. a user must be careful not to load a representation that thier computer cannot handle.

    11. [Reset] Clicking this button writes the original name back into the Object box.

    12. [Apply] Applies any changes to the Object box or Resolution

    13. [Apply and Close] Applies any changes to the Object box or Resolution while closing the IngredientName Display Options window.

• 13. Name

• • 1. IngredientName This shows the name of the ingredient that is provided in the autoPACK result file and the recipe_setup file.

    2. The name in the recipe_setup file must match the name in the autoPACK ingredient file.

Filler tab

1. Build an autoPACK: <RecipeName>

   1. Use this dropdown menu to select an existing recipe that you want to Construct into your scene.

   2. The options include:

      1. Default recipes from the server (like HIV, or Test_Spheres2D)

      2. Fetch a recipe from the web

      3. Load a recipe from your hard drive

2. Recipe Version

3. If loading a default recipe through the RecipeName dropdown above, use this dropdown to select the version of the autoPACK result file that you want to use.

4. Higher numbers are more recent.

PACKing Options tab

1. [ ] Display packing in realtime (slow)

2. If checked, the viewport will update every time an object is placed or moves to jitter.

3. Because viewport updates take a relatively long time compared to raw calculations occurring behind the scene, checking this button can cause a fill to take many 100s of times longer than if left unchecked.

4. [ ] Overwrite per-ingredient packing method with Overriding Packing Method:

5. If checked, every ingredient will use the Overriding Packing Method listed in the dropdown menu below as opposed to any packing methods specified as attributes of each ingredient.

6. Overriding Packing Method = < jitter >

   1. jitter– this default packing method quickly places objects while minimizing collision overlaps based on a fast grid-masking and grid-testing algorithm. The method allows objects to overlap up to 1/2 of a grid space which is generally small enough for the host physics engine to relax the entire packing as a post-processing step if absolute collision avoidance is required.

   2. spring– when an object attempts to place itself, it collects the nearby neighbors and generates a harmonic spring from the center of any overlapping neighbor to the center of the placing object. The algorithm then runs several relaxation frames to avoid collision while still keeping the object in the closest possible proximity. The algorithm can extend to allow a probability for springs to be generated to distant objects in a binding-partner list to enable a potential for association according to some distance probability relationships.

   3. rigid-body– when an object attempts to place itself, it collects the nearby neighbors and declares them to be "collider objects" and the placing object to be a "rigid body" in the host physics engine. The algorithm then runs several frames to relax any overlapping objects apart. It then performs a final collision test to ensure that the packing achieved zero overlap- if not it eliminates the objects, reduces the "distance value" at that point by one unit and continues with the packing loop to select a new object to pack.

   4. pandaBullet– when an object attempts to place itself, it collects the nearby neighbors and declares them to be "collider objects" and the placing object to be a "rigid body" in the Bullet physics engine wrapped by the Panda 3D software. The algorithm then runs the jitter loop, but instead of testing the masked grid for overlaps with masked points, the algorithm's collision detection loop uses the Bullet collision detection function to test for absolute collisions. If an object is overlapping any other object while trying to pack itself, that position will be rejected and the algorithm will move on to "jitter" up to a threshold number of attempts- if still colliding, that packing point will be rejected, the "distance value" at that point will be reduced by one unit and the algorithm will move back out to the main packing loop to select a new object to pack.

   5. pandaBulletRelax– when an object attempts to place itself, it collects the nearby neighbors and declares them to be "collider objects" and the placing object to be a "rigid body" in the Bullet physics engine wrapped by the Panda 3D software. The algorithm then runs several frames to relax any overlapping objects apart. It then performs a final collision test to ensure that the packing achieved zero overlap- if not it eliminates the objects, reduces the "distance value" at that point by one unit and continues with the packing loop to select a new object to pack.

   6. pandaDev– Used to test new algorithms under development.

7. [ 0.15 ] Mask grid while packing (0=always | 1=never)

8. Upon depositing a new ingredient, the grid-based packing method records distances-to-closest objects for every nearby point up to a relevant threshold distance in order to mask off points that would be impossible for objects over a certain packingRadius (size) to pack into. This greatly speeds up the packing if a volume is densely packed, but can be an unnecessary and expensive calculation to do in a sparsely packed volume where there is a very low probability of picking an "impossible" point. This value sets a threshold to start updating points after the provided percentage of the volume is already packed.

9. We recommend leaving this value at default or systematically testing it to hone in on the most efficient value.

Builder tab

1. Details coming soon

Options tab

1. GUI mode < Options Simple–Advanced >

   1. Use this dropdown menu to select a level of GUI

   2. We recommend that beginners start with the default of Simple and then move up through Intermediate to Advanced.

   3. The Debug option is for experienced users to analyze or perform more complex filling operations.

2. [√] Check for latest recipes at startup (takes effect after host restart)

• 1. Access any new recipes added to the server when you restart your 3D software package (host)

  2. Most users should keep this on

3. [√] Force downloading of the newest recipes

• 1. Overwrite any outdated recipes with upgraded or corrected versions

  2. Most users should keep this on, but WARNING: IF you are an advanced user and are generating your own recipe files from a default recipe using the Filler, checking this box could cause your file to be overwritten by the Server version, so be sure to use a different name for your local result file version, e.g., HIV_1_3_dev.py

Last update January 7, 2013

GJ