Cavernosa Instructions

Contents

• To Run Cavernosa
• To Use Cavernosa
• Side Panel
• Dialogues
  • Display Options !!! Empty for now !!!
  • Physics Dialogue
  • Control Dialogue !!! Empty for now !!!

Now do a little sculpting, adding and removing material with the mouse buttons untill the desired result is achieved.

The final stage is to save the sculpture and get it exported in a standard polgon format that can be read by other programs. Exporting is begun by checking the Capture box. While the Capture box remains checked editing of the grid will be disabled. At this point the captured polgon mesh can be manipulated by means of the controls in the Physics Dialogue. For Example, changing the Physics Type to Multi and enabling edge springs, the grid force, and viscous damping only, allows, through varying the strengths of the forces, a mesh to be generated that ranges in appearance from sharply faceted (with the grid force dominant) to stretched rubber (with edge resting lengths less than one and edge spring forces dominant). If the captured mesh is taking a while to settle, hitting the Fire button will run the physics on it repeatedly. This can be repeated untill it does settle. The last step is to hit the Export button and type in a filename to save the mesh as.

In Summary: 1) New Grid 2) Sculpt 3) Save 4) Capture 5) Fire 6) Export

The Side Panel:

File Group
	Load: Load a previously saved voxel file. Save: Save the voxel grid in native format. Choose the filename for this carefully as it will be unconditionally overwritten. New X: Replaces the current voxel grid with a new one which is completely solid. A solid grid is the starting point for the excavation of a cave system. New O: Replaces the current voxel grid with a new one which is empty. An empty grid is the starting point for sculptures of figures and of other discrete forms. Capture: When checked, a single mesh is generated over the whole grid or that part which lies within the display box (see Display Options) and a mode is entered in which editing the grid is disallowed. In this mode, the physical simulation which smoothes or deforms the mesh can be manipulated and the mesh can be exported. Fire: Runs the mesh deformation/smoothing until it settles down or a max number of iterations is reached. The simulation runs during the display loop but this button executes a number of iterations without the overhead of display. Note the "Static TPF" figure in the window title bar will match the "Total TPF" figure when the mesh has finished settling. Export: Opens a file selector in which can be entered a filename to save the captured mesh to in VRML 1.0 format. Take care with the filename chosen as it will be overwritten without prompting for confirmation. Note that Captured mode must be in effect for export to take place.
Display Group
	DB Fixed: Locks the Display Box at it's present position. The Display Box is the volume drawn every frame and it is adjustable via the Display Options Dialogue. Fixing it is useful when working on a large volume as one of the present inefficiencies of Cavernosa is the Display Box update. Limit MCA: Enables the drawing of a smooth mesh extracted from the voxels. Squares: Enables the drawing of squares that separate solid and clear voxels. This is the most direct display of the voxel grid. Verts: Enables the drawing of the vertexes of the tessellation and their interconnections. Wireframe: Enables the drawing of all polygons in outline mode. Lighting: Enables an ambient light and a right-pointing directional light (right-pointing so surfaces always have highlights on one side and shadows on the other from the viewpoint). Texturing: Enables the drawing of each mesh in multiple passes with the results of three texture map projections blended together. This is currently done in pure OpenGL 1.1 and so is unbearably slow except on a fast implementation such as that of the NVIDIA Geforce family. RGB Tex: As above but with R, G, and B passes replacing the textures. Quite pretty for a diagnostic. Fogging: Enables fog. Extractions: Enables the drawing of boxes around groups of vertexes whose colour indicates whether the corresponding meshes are being generated (red), having their geometry updated(yellow), or are static(green). Options: Brings up the Display Options Dialogue.
Physics Group
	Snap: Move all verts to the location of their corresponding voxels and zero their velocities. ZV: Zero Vertex Velocities. F: Force Physics on. Options: Brings up the Physics Dialogue.
Control Group
	Load: Load a grid to be used as a brush by a special grid tool tip. Grids to be used as brushes should only have a few set voxels. That is, they should be very small discrete forms. TT may need to be hit a few times to cycle to the grid tool tip if it is not current. Save: Save the current grid as a brush. The save dialogue popped up defaults to the brushes folder but the grid saved is identical to any other. Spray Mode: When checked, the current tool tip is projected forwards from the viewpoint untill it hits a set voxel of the grid. TT: Cycle through tool tips. Prop/Drct: Proportional/Direct control mode toggle. Affects the way the mouse's position and motion within the viewport is converted to motion of the camera, focus point, and rotation point. Direct mode was broken somewhere along the way. AT: Camera anti-twist. Disabling allows freer camera motion. Options: Brings up the Control Dialogue.
Bit 'N Bobs Group
	! Ignore ! ! These buttons and dialogues thrown up by them are pressed at the user's own risk ! Any or none of this stuff could be here and may or may not be connected up to functional code in released versions.

• Display Options !!! Under Construction !!!
• Physics Dialogue
• Control Dialogue !!! Under Construction !!!

Special Keys Used When Running From The Python Interpreter

• p: Saves the current grid to Test.vox
• o: Loads the current grid from Test.vox
• u: New solid grid.
• i: New clear grid.
• q: Toggles movement mode.
• e: Changes tool bit.
• 3-7: Set new grid level.
• Check Cavernosa.py for any others.

The Blender GUI:
(for the first release of Cavernosa only)

• Resize This:
  • PH: Slider that controls the width of the side panel.
  • BH: Slider that controls the height of the side panel buttons.
• Display:
  • F: Fog On/Off toggle.
  • W: Wireframe/Solid grid toggle.
  • DB: Display Box stick/follow-focus toggle. (The display box is the volume of the grid which is actualy rendered or output on export. It has two modes: a) follow the focus; b) stay where it is. The second mode is useful if you want to be sure how large the sculpture you are making is or if you want to take a look at a part of it from a distance.)
  • T: Twist Compensation On/Off toggle. (Helps to draw straight lines with the plane locked translators and avoid disorientation among other uses.)
  • A: Author credit On/Off toggle.
  • R: Rendering toggle. Disables the display loop and allows you to read the tool tip messages for the widgets. Once released, this button is reluctant to be pressed again. Clicking around on other buttons or restarting the script is nescessary to make it depress.
  • Count Faces: Print the number of grid faces in the display box to std::cout. As blender has a 64k vertex limit at the moment and I don't remove duplicate verts yet, the limit for exporting is about 16k faces.
• Display Box:
  • x: X dimension of grid display box. Click on it and drag left or right to change the value.
  • y: Y dimension of grid display box. Click on it and drag left or right to change the value.
  • z: Z dimension of grid display box. Click on it and drag left or right to change the value.
• Control:
  • Sensitivity: Mouse motion is scaled by this value. Useful to set low when doing detailed work in direct control movement mode (see below).
  • Proportional/Direct: Movement mode. In proportional mode the offset of the mouse cursor from the center of the the viewport is proportional to the magnitude of the resulting motion. In direct mode the motion of the mouse is tranlated directly into movement.
  • Change Affector: Rotates through the available affectors or 'tool bits'. The current tool tip can be seen in the 3d view as a green wireframe.
• Export:
  • Dimension: Largest dimension of the the bounding box of the resulting Blender mesh. The display box contents will be scaled to fit. Click and drag left or right to change.
  • Mesh: An input edit box to set the name that will be given to the mesh in Blender.
  • To Mesh: Export the current display box contents to the named Blender mesh.
• Save/Load:
  • File: Input edit box used to set the filename used for saving and loading.
  • Save: Save the voxel grid to the file named above.
  • Load: Attempt to load the voxel grid from the file named above.
  • New Grid: Replace the current grid with a new, empty one.
  • New Grid Levels: Set the number of levels the new grid will have.
    3 levels equates to a grid of 512 x 512 x 512 voxels.
    4 levels equates to a grid of 4096 x 4096 x 4096 voxels.
    5 levels equates to a grid of 32768 x 32768 x 32768 voxels.
    6 levels equates to a grid of 262'144 x 262'144 x 262'144 voxels.
    7 levels equates to a grid of 2'097'152 x 2'097'152 x 2'097'152 voxels.
    8 levels equates to a grid of 16'777'216 x 16'777'216 x 16'777'216 voxels.
    
  • Quit: Close down the GUI.

If you find this explanation confusing you are welcome to email me with your queries.