Pretty Poly Editor Documentation

I. PPE Manual - 3. Quickstart

Getting Started

   setenv PPE_ROOT  /usr/share/ppe

or

   PPE_ROOT=/usr/share/ppe
   export PPE_ROOT

   ppe

   ppe examples/data/models/dog.ac

First sight

The Toolbox Window	A Viewer Window

The blue and green grids that you see lie along the "current working plane" which defaults to the X/Y plane. The green section has a spacing of one model unit, the blue section is at a 10x10 model unit spacing. Notice that you can toggle these on and off using the check boxes in the 'Grid' section of the toolbox window. There is also a x100 grid which is drawn in magenta and disabled by default.

If you move the mouse around over the grid, you'll see a set of three white lines that intersect at the position of the "3D cursor". The cursor stays glued to the grid so if you move the mouse to point at the 'sky', the cursor will remain on the X/Y plane (probably out by the 'horizon').

The GUI controls in the 'viewer' window control only the contents of that window - the controls in the 'toolbox' window control all currently opened windows.

Key and Mouse Bindings.

Loading and Saving models.

The Viewer 'File' menu includes 'New', 'Open', 'Merge', 'Save', 'Save As' and 'Quit' options. You can load and save models in any format that PLIB supports - which includes (at last count) 18 import and 8 export formats.

Because some formats are fundamentally lacking ways to represent some of the things that PPE can do - and not all loaders and writers are 100% perfect, you should always save a copy of your model in ".ssg" format. SSG is the underlying model representation scheme used by PrettyPoly and the ".ssg" format should capture everything.

The PrettyPoly main program has really no idea of what file formats it supports - that's handled down in the PLIB level - to the exact list of what file formats PPE supports will be found on the PLIB web site.

At time of writing, you can import:

  3DS AC    ASE ATG   DXF FLT
  IV  M     MD2 MDL   OBJ OFF
  SSG Strip TRI VRML1 X

  3DS AC  ASE ATG DXF M
  OBJ OFF QHI TRI X

If you need a model to 'play' with, look in the PPE distribution under 'examples/data/models'.

Moving the Camera

The numeric keypad buttons drive the six degrees of freedom. The keys control VELOCITY. So press (say) '4' and you'll start to rotate to the left, press '4' again and you'll rotate faster. Press '6' once and you'll slow down again, press '6' again and you'll stop rotating. Use '5' or '0' to stop all rotation or stop absolutely all motion. The Fast and Slow (/ and *) keys operate to make the motion more or less sensitive.

The advantage of using the keyboard is that it works in ALL PPE modes - where the mouse will at times be needed for other operations (selecting things, building things, etc). People who use their left hands for the mouse can operate PPE ambidexterously.

Many of the PPE editing modes also allow camera motion using the mouse.

Escape from Flatland.

PPE achieves this by means of the 'Current Working Plane' ('CWP' for short).

The Current Working Plane

When you move your mouse around in the large 3D viewing area, PPE traces a ray from your eye, through your 2D mouse cursor and onto the CWP and that point is marked by the 3D cursor - which is drawn as three intersecting white lines.

That's a complicated way to say that the 3D cursor follows your mouse pointer. Being stuck on this surface is frustrating - but tap the spacebar and you'll find that you can move the mouse at right angles to the plane, hit space again and you'll be back on the plane.

You have a rich set of ways to position CWP to wherever you need it to be when creating objects. Since there is a separate CWP for each viewer window, all the controls for CWP positioning are in the viewer window in the box labelled "Current Plane".

• Use the XY, XZ and YZ radio buttons to make the current plane run parallel to those axes.
• Use the 'Offset' widget to offset the current plane away from it's current position by a known distance.
• Select three points in the model (see 'Selection' below) then click 'Thru points' to make the CWP lie in a plane that runs through those points. (If you pick more than three points then the CWP will pick the best 'least squares' fit to those points).
• Select one point and hit the 'Offset to Point' button and the CWP will move so as to be parallel to it's previous position and running through the point you selected. If you pick more than one point then CWP will run through the centroid (average) of those points.

The Current Line and Current Point

The Current Line is not rendered by default, you have to click the 'Line' checkbox in the Render section of the Toolbox window - when it'll appear as a yellow line stretching off to the "horizon". As with the current working plane, you can make it lie along one of the axes by clicking the X, Y, or Z radio buttons in the 'Current Line' area of the Viewer window. You can also select two points and click 'Thru Points' to make it run through them both. Just as with 'Thru Points' in the current plane, you can select more points and the line will do the best it can to run close to all of them. Finally, you can offset the line so it runs through another selected point but remains parallel to its former direction.

The Current Point is marked by three blue lines (like the 3D cursor only larger). It starts off at the origin and can be repositioned to any selected point (and if you have multiple points selected and you pick 'Thru Points', it'll move to the centroid (average) of those points.

The Grid

• Behind: The grid is hidden behind all 3D objects - even if that object is beneath the grid. This can be a little deceptive but it's useful when things get cluttered and you don't want to obscure your view of the action.
• Z-Buffer: (This is the default) The grid is drawn as if it were a physical object in the scene and it's occluded by objects that are in front of it and in turn the grid occludes things that are behind it.
• InFront: The grid is never hidden by 3D objects - even if they are in front of it. This can also be deceptive - but it's useful when you need to see the sizes of things that would ordinarily hide the grid.
• Ghost: The grid is drawn in as a ghostly semi-transparent manner when it's hidden by something and at normal brightness when it's visisible. This is a nice compromise between the other three modes.

The 3D Cursor

Sometimes you'll need to position the 3D cursor somewhere and then use the mouse to click on a menu item or something. Typing 'f' (freeze) will freeze the 3D cursor in place while you do that. Just type 'f' again to un-freeze it.

As you've seen, the cursor generally moves around on the current working plane (or at right angles to it if you tap the spacebar). This is generally the most useful mode - but you can also make it stick to the current working line or stay glued to the current point by clicking on Plane, Line or Point radio buttons.

The 'Screen' button allows the cursor to be moved parallel to the plane of the screen. You'll generally want to position the cursor at the desired distance, then freeze it (hit 'f' - remember?) before selecting 'Screen' and un-freezing. Notice that when you move the camera, this also moves the plane that the cursor is moving in.

You can also select 'GridSnap' in which case the cursor will snap to the nearest integer coordinate (this should be adjustable...but it isn't...yet). Notice that this may move the cursor a little way off the current plane/line/point if necessary.

The Renderer.

You can see some backfaces through the open bottom of this car model:

You can also turn off the display of the 3D cursor, the current line and the current point - this has generally little benefit - but if you are taking screenshots or something, it can be handy.

Field Of View

The Current Mouse Mode

There are keyboard shortcuts for changing modes:

• 'c' - Move Camera.
• 's' or 'v' - Select Vertices.
• 'p' - Select Primitives.
• 'o' - Select Objects.
• 't' - Move (translate).
• 'r' - Rotate.
• 'b' - Build a new...

• Scale.
• TexMove.
• TexRotate.
• TexScale.

The functions of the mouse vary somewhat from one mode to another. The collection of functions for a particular mode is called a 'binding'. Here are the current mouse bindings for various modes:

Move Camera Mode

Moving the mouse with the left button down spins the model in heading or pitch about the origin. Using the right button rolls the image. Hold down the shift key translates the image, left/right and up/down with the left button, in/out with the right. Those controls "move the model" - holding down the control key moves the camera instead.

In most other modes, you can spin the object around without changing modes using the middle button (or if you have only a two button mouse - perhaps both left and right buttons together may work - depending on your mouse, your Operating System and the settings of your Window Manager).

Select Vertex/Primitive/Object

Left-click and drag causes a magenta box to appear - when you release the mouse button, anything inside it will be selected. When you select a vertex, the primitive that contains it and the object that contains that are also selected. If you select in 'Primitive' mode then you won't select any vertices - but you can click any part of a polygon to select it. Similarly in object model, clicking on any part of an object selects all of it.

Holding down the shift key allows you to add more things to the currently selected list.

Holding down the control key subtracts the things in the magenta box from the current selection.

In this screenshots, you see a Tux with the vertices and polygons at the top of his head selected. The selected vertices are highlighted by white crosses. The selected polygons are highlighted by yellow lines around them:

Move, Rotate and Scale Modes

Rotate mode does not appear to work in PPE 0.0.1. TexMove, TexRotate and TexScale Modes will ultimately allow you to position the texture on the selected vertices - but this too is non-functional in 0.0.1.

Build Mode

Notice that if you enter (say) a triangle strip in the 'wrong' order, it'll come out back-facing - so you'll only see the back faces. The general rule is to enter points in an ANTICLOCKWISE order.

If you get it wrong, just select the primitive you created and in the Viewer window's menu, hit the 'Surface' menu and select 'Reverse'. Some primitives don't reverse very well - and the triangulation of the primitive may change. (Try this with a triangle strip with an even number of triangles in it!)

Don't forget that even during vertex entry, you can move the current plane, current point or current line - and also turn cursor gridsnap on and off or switch the cursor from current plane to line to point. You can even enter some of the points in one window and some in another!

Once you have completed your primitive, you can start another either by:

• Typing a 'b' (this changes the current mouse mode to 'Build' - which happens to be the mode we are already in - but has the side-effect of taking us out of build mode).
• Right-mouse click.

• TriStrip: The first three clicks enters a triangle, each additional click adds another triangle to to it.
• TriFan: The first three clicks enters a triangle, each additional click adds another triangle to to it.
• Triangles: Three consecutive clicks makes a triangle, you can continue to enter triangles AS A PART OF THE SAME PRIMITIVE as long as you like.
• Rectangle: (This should say "Quadrilateral"!) every four consecutive vertices makes a quadrilateral.
• Polygon: Each mouse click adds a vertex to the polygon. Right click (or hit 'r') to start a new polygon.
• QuadStrip: Similar to a TriStrip - the first four clicks enters a quadrilateral, every TWO additional clicks adds another to it.
• Quads: Every four mouse clicks adds another quad.
• LineStrip: The first two clicks create a line, every additional click adds another line to it.
• LineLoop: The first two clicks create a line, every additional click adds another line to it - but the figure you create remains joined up.
• Lines: Every two clicks adds another line.
• Points: Every click adds another point.
• Cube: The first mouse click creates a cuboid - the second mouse click sets it's size. If you click a third time, you'll reposition the cube - a fourth time and you'll resize it again. Right click (or hit 'r') to create another cube.
• Sphere: The first mouse click creates a spheroid - the second mouse click sets it's size. If you click a third time, you'll reposition the cube - a fourth time and you'll resize it again. Right click (or hit 'r') to create another sphere.
• Tux and Teapot: Don't work. :-)

Colour Selector

You can change the colours of existing vertices by selecting them, picking a new colour and then going to the 'Selection' menu in the Viewer window. That menu allows you to copy the colour from the Toolbox to the Selected vertices - or you can extract the colour of the vertices and place them back in the Toolbox 'current colour' box.

You can also change the colours of the screen background, the grids, menu's, etc. Just select Edit/Preferences/SetColourOf.../ whichever thing you want to re-colour.

Material selector

The (initially) white sphere in the Toolbox shows what the current material looks like when applied to a sphere of the current colour. Clicking on the sphere brings up the material browser. Materials can either come from the model itself (Select 'Scene' in the 'Source' box) or from a pre-built library of materials. This is useful for large scale production of models in a team where you want a consistant 'look' for a range of objects - or where you want to keep careful control of texture usage.

The browser window allows you to see what materials are present. You can 'Edit' an existing material, create a 'New' one, 'Copy' a material or 'Delete' one. Clicking on the thumbnail image (initially a sphere) with the current material applied to it also performs the 'Edit' function. When you find the material you want, click 'Apply' and it'll become the current material in the Toolbox window.

Materials are applied per-primitive rather than per vertex - but otherwise, they behave much like the current colour. Every new primitive takes the current material - and the 'Selection' menu in the viewer allows you to change the material of existing primitives or extract the material from a primitive into the 'current material' window - from which it can be edited.

When you Edit a material, you'll see a row of thumbnails that represent the last five materials you've used. Clicking on one of them makes it the one being edited. The editing controls are fairly obvious to anyone who does OpenGL modelling - so I won't go into details here.

Notice that in both the browser and the editor, you can select between displaying the material on a sphere, a cube or a cylinder and you can also select a chequerboard background so you have a better appreciation of the effect of translucent surfaces.

The Structure Viewer.

There is another way to view your model though - select the 'Open Structure Window' option in the Windows menu and you'll see a diagrammatic view of your model showing how it is structured. The heirarchy follows the PLIB/SSG library structure which is documented here

The Clipboard.

The clipboard is an absolutely standard ".ssg" file - so you can just rename it and use it like any other ".ssg" file if you like. For obvious reasons, I don't recommend that you edit the clipboard directly using PPE - people who do that are likely to vanish into a parallel universe in a puff of purple smoke.

The Edit Menu

The View Menu

You can also load and save camera positions to ".cam" files on disk.

The Windows Menu