Cavernosa

Home	Cavernosa
PyGLUT	GAME BOY ADVANCE
Nintendo DS	Java
Misc Code	Links

Cavernosa Instructions

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

To Run Cavernosa

You can use it via it's GLOW GUI; Cavernosa.exe.

To Use Cavernosa

As it is basicaly a sketching program with 2d pixels extended into 3d voxels, using Cavernosa requires you to learn to fly through the 3d grid that is it's medium.

There are also 2 key points which must be controled. The focus point is where you can add or remove material and is always dead-ahead of the viewpoint at a varying distance (the distance is what you control). The rotation point is at some offset beyond the focus point or coincident with it. It is represented on-screen by four red lines. As they radiate out and upwards, they can be used to tell which way is up if you get disoriented. You are able to circle the rotation point, simply to get around or with the focus point between you and it, to achieve the same coiling effect that is used to construct clay pots. This all entails a fairly complex control system organised around 4 pairs of keys, each of which affects the action of mouse movements.

The Key pairs are:

f & v (camera relative movement):
- f: mouse look (rotates the camera around the viewpoint).
- v: forward/back & left/right.
- f&v: up/down & twist about camera z-axis (if anti-twist is disabled).
d & c (slice-locked translation):
- d: forwards/back & left/right in the plane perpendicular to the grid axis closest to the camera up vector.
- c: up/down & left/right in the plane perpendicular to grid axis closest to camera forwards vector.
- d&c: up/down & left/right in the plane perpendicular to the grid axis closest to the camera right vector.
If you imagine the grid as a stack of 2D bitmaps, these restrict your motion to one of those bitmap slices.
s & x (circling the rotation point):
- s: up/down & left/right around the rotation point, using the grid axis closest to the camera forwards vector as the rotation axis.
- x: up/down & left/right around the rotation point, using the grid axis closest to the camera up vector as the rotation axis.
- s&x: Nothing for now.
a & z (moving the two key points):
- a: rotation point away/towards focus point & left/right translate (pointless and often slightly annoying).
- z: focus point away/towards view point & left/right translate (pointlessly).
- a&z: viewpoint and focus point together away/towards the rotation point, leaving it where it is & left/right translate (pointlessly).

The left and right mouse buttons add the current tool bit (a preview of which is drawn in green wireframe at the focus point) to the grid or subtract it respectively. Some of the smaller tools can not be used to add voxels except to fill in spaces between other voxels. They are still useful to remove voxels.

A Simple Workflow

Begin by choosing whether to create a discrete form such as a statue in a clear grid or to excavate a solid grid. Hit New O for a clear grid or New X for a solid one.

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.

Dialogues

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)

The side panel widgets are broken up into several groups:

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.

Once a mesh is exported to Blender it is a good idea to remove double verts (hit TAB to enter edit mode; press 'A' to select all verts; click on 'remove doubles' in the lower right corner of the mesh edit buttons; TAB out of edit mode). Then it can be used as an S-mesh to round out the sharp corners. This actualy works best with simple models, made up of few voxels as the the rounding out is not enough to smooth a model meant to approximate a curved surface. On the other hand, if there are enough voxels in the model, when used as an s-mesh, the resulting mesh can have a pleasing surface roughness.

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