<b>GIRAM</b>

                        (Giram Is Really A Modeller)
                          -     -  -      - -

                    The Great Open Source POVray Modeller

                        http://www.giram.org/


  This is the manual as far as we've got. The first part describes how to
create a simple scene - I mean, you want to get going, not get stuck into a
big manual, right? After that we'll dive in to the toolbox, which is where we
keep all the tools for building a scene with. After that you can pick up the
more advanced techniques by experimenting.

Your First Scene
----------------

  By the time you get here, you should have managed to build or install the
Giram modeller and have it running under X-Windows (hint: type 'giram &' at an
xterm window). If you want to see the finished result you'll also need Povray
installed and running, but you can do modelling in Giram without it. For now
we'll just make a lollipop to congratulate you with. For those of you not
familiar with English confectionery, it's a sweet on a stick.

  In order to create any scene, you need to have a viewport to work in. In
Giram you make a new viewport by clicking on Giram's [File] tag, and selecting
New View.

  This presents you with a little box, offering views of the X-Y plane, X-Z
plane, Z-Y planes and something dubious labelled "New Frame". First the easy
part: If you want to edit more than one scene at a time, now is when you
should think about using the "New Frame" option. Just click on "New Frame",
and then click on "Untitled". That way all your viewports will be looking in
on the same world.

  Now to pick the direction in this world, which is what all these planes are
flying around for. It all sounds a bit complicated, but in POVray you can
basically think of X as being the left/right direction, Y being up/down and Z
as backwards/forwards. For now, just check the "View X-Y" option and click OK.
This gives us a window with rules around the edge, with up/down and left/right
behaving as you would expect them to.

  Move back to the Giram Toolbox and click on the sphere icon. If you've got a
"Dynamic Toolbox", right-click on the box icon and then select the sphere from
the pop-up toolbar (remember this trick for getting the cylinder you'll use in
a little while). Click in X-Y view somewhere around the middle of the view,
and drag the mouse until you have a circle that looks about the right size for
the head of the lollipop you deserve.

  Now for the lollipop's stalk. Select the cylinder icon from the toolbox in
the same way as you picked the sphere, return to your viewport and click in
the middle of the circle. Drag the mouse down to the bottom of the viewport,
and slightly to one side until it looks a little like the head of the lollipop
is impaled on the stick.

  You'd probably like to see your creation in 3D, so click on the X-Y view
with the right-hand mouse button to bring up a pop-up menu. Select the
"Render" option, and then "Gouraud Shading". Tada! You have won yourself a
lollipop. When you're done admiring it, close the Pov and Povfront rendering
windows.

How About Some Colour?
----------------------

  A grey lollipop isn't very apetising so we'll give it some colour - or color
for those of you in that part of the world. However you spell it, the method
is the same: From the toolbox click on the select tool - that's the single
arrow - and then click on the spherical lollipop top so that it turns red.
This indicates that it is selected and doesn't actually change the colour.

  Right-click in the view and then click on the "Operations" part of the
pop-up menu. Up comes another pop-up menu and from this you select "Change
Colour". This is where you get a colour wheel in the Change Colour popup,
and you can use it to pick the flavour (or flavor) of your lollipop. If
you want a lime lollipop, click on the green part of the wheel; if you
prefer strawberry, click on the red part; if you like having a blue tongue
like a lizard, click somewhere in the blue. You can change your mind
later.

  When you've got the right flavour, click on the big OK button at the bottom
of the Change Colour popup. You won't see anything change colour just yet,
that only happens when the scene is rendered using Povray.

Adding Lighting
---------------

  Select the little spotlight from the Toolbox, and then click somewhere in
the top right corner of the X-Y view. A New Light Source dialog will pop up,
with the default lighing set to bright white, but you can change this with the
colour wheel. Generally white is what you want, though using blue light
creates cold, harsh scenes while slightly yellow light will approximate
daylight.

  You can change the position of the lightsource in this dialog before you
place it. I'd suggest using something like -5 for the Z position to put the
light source behind the camera.

  If you're feeling adventurous, play with the colour balance of the light,
and maybe create multiple light sources. Do remember that every light source
added to a scene will increase the rendering time in proportion to the number
of light sources. Use two lights, and your scene takes twice as long to
render.

  Note that changing the colour of the light source will change the colour of
the Gouraud shading view. Neat, eh?

Positioning The Camera
----------------------

  First we'd rather like to have a viewport for the camera. Go to the Giram
toolbox, click on the "File" tab, and select "New View". In the resulting
dialog box, check the option next to "Camera View" and click the OK button.
There you are, but where is your lollipop?

  The camera needs to look at the scene, and at the moment it probably isn't
pointing at the lollipop. If you created the lollipop in the X-Y plane as this
tutorial suggests, you'll need to tell the camera to look along the Z-axis in
the positive direction, from somewhere back in the -Z direction.

  It's not so hard really, just right-click in the camera view and select the
"Operations" option from the popup menu. One of the items in there is "Edit
Camera", so pick that one. The resulting dialog should make sense to you if
you've used Povray before. If not, select something like <0,0,-10> for the
camera location and set the direction vector to <0,0,1> before clicking OK. If
you don't understand what you just did, I suggest it's time to read up on
cameras in the Povray documentation.

Saving & Loading POV Scenes
---------------------------

  Of course, once you've made this wonderful scene, you'll want to save it.
Just right-click on any of the viewports and the popup menu appears with
"Files" as the top entry. The side menu for that entry has "Load" and "Save"
options, so click on "Save" to bring up the standard GTK file dialog. Pick
your directory, type in a filename (preferably ending in ".pov") and click OK.

  Now you can exit Giram and your work is safe. Great. A good time to get a
beverage of your choice from the kitchen.

  To load a scene, start Giram again and click on the "File" tab at the top of
the Giram Toolbox. There is a "Load Pov" option in the drop-down menu there
which brings up the familiar file dialogue again. Just select a POV file and
click OK to load it. A configurable selection of views of the object is
displayed.

At Last, Rendering
------------------

  Having made and saved your scene, you'll probably want to render it. For
this you must have installed Povray V3.0 or better, preferably 3.1 .  You can
check for the latest version on http://www.povray.org

  You need to know the name of the command that you use to run Povray on your
system. Typically, this will be x-povray but you can change it.

  So load your scene, and right-click in one of the viewports. Near the bottom
of the popup menu it says "Render". Move to it and click on the "POVRay
Rendering" option. This gives you a whole new dialog from POVFront, which
Giram uses to launch Povray.

  Prepare POVFront by clicking on the "Options" tab and setting the name of
the renderer (probably x-povray, remember?). Apply the new command name, pick
something sensible like 320x240 graphics and use the POVFront "Options" tab to
set these as the default settings. Then just click the big "Render" button to
see your scene from before your eyes.

  The next most useful parts you can learn about are the selection tool and
the rest of the popup menu options, which we'll cover next.

The Selection Tool
------------------

  Before you can modify a scene, you have to tell Giram which objects are
going to be modified. This is what the Selection Tool is for.

  With it you can select an object, a group of objects, or change the contents
of the current selection. Once selected, objects can be a translated, rotated
or scaled.

  To select an object, just click on it.  By default, all objects under the
cursor are selected. As scenes can get quite complicated when displayed in 2D,
and shapes are displayed stacked up on top of one another, this may not be
what you want. So with Giram you can modify the way objects are selected with
the [Shift], the [Ctrl] and [Alt] 'Modifier keys.

  * No Modifier:    All the objects under the cursor are selected. Previous
                    selections are forgotten.

  * [Shift]:        All the objects under the cursor are added to the
                    selection.

  * [Ctrl]:         All the objects under the cursor are removed from the
                    selection.

  * [Ctrl]+[Shift]: Select only the objects that are under the cursor AND were
                    in the previous selection.

  * [Alt]:          The selection is made by the 'first' object under the
                    cursor - the 'first' object being the one that is higher
                    up in the CSG heiracy (basically the one that was created
                    first).  Following clicks in the same spot, with the [Alt]
                    modifier, will select the next object under the cursor and
                    so on...

  * [Alt]+[Shift]:  The 'first' object under the cursor is added to the
        current selection.  Following clicks in the same spot,
        with the [Alt]+[Shift] modifier, will add the next object
        under the cursor to what were the selection before the
        first click, and so on...

  * Alt+Ctrl:       The 'first' object under the cursor is removed from the
        current selection.  Following clicks in the same spot,
        with the [Alt]+[Ctrl] modifier, will removed the next
        object under the cursor from the selection as it was
        before the first click, and so on...

  * Alt+Ctrl+Shift: The 'first' object under the cursor will become the new
        selection, but only if it was already in the previous
        selection, otherwise nothing is selected.  Following
        clicks in the same spot, with the [Alt]+[Ctrl]+[Shift]
        modifer, will do the same thing but with the 'next'
        object.

Viewing The Selection
---------------------

  Giram has a trick or two to help you navigate quickly around your scene as
you build it. For instance, to save fiddling around with zoom to get the whole
scene in one window, just right-click in any viewport except the camera, move
down the popup menu to "View" and select the "Fit to Scene" option. The view
automatically zooms to include all visible objects except light sources (which
aren't technically visible anyway).

  For working on a section of the model, there is a "Fit to Selection", which
rather predictably makes the currently selected objects fill the viewport.

The Different Toolboxes
-----------------------

  People expect different things from their programs, and so we have two
different layouts for the toolbox. It's a little bit confusing, but you do get
a choice:

  The "Static Toolbox" shows all the icons in one great, big block. If you've
ever used "The Gimp", it will look familiar. You want it, it's in there
somewhere. The problem is that there are quite a few tools to pick from, and
the toolbox can take up quite a bit of screen real estate. On the plus side,
it is quicker to get into.

  The "Dynamic Toolbox" tries to use as little screen space as possible. It
puts the tools into categories. The ones used most frequently like move,
rotate and scale are left there much as the Static Toolbox. But the shapes are
collected into categories like 3D shapes, 2D shapes, lathes, lights and
patches - don't worry, you don't have to understand all the shapes yet.

  If you want to pick a shape from the Dynamic Toolbox and you can't see it,
you right-click on an icon that is in the same kind of class. You'll know which
ones are dynamic because they have a little black triangle in the top-right
corner.

  So, if you can't see a sphere, but you can see a box (which is a 3D shape),
right-click on the box's icon. Up pops a long, thin toolbar of all 3D shapes
and there's your sphere to click on. The sphere icon then stays in the toolbox
until you replace it with another 3D shape in the same way. More complicated,
but the toolbox takes up a lot less space.

  Currently you have to manually edit the giramrc file to switch between
static and dynamic toolboxes (see "Preferences" section below). When the
User Preferences are saved, we'll fix that.

Using The Tools
--------------- 

  When the Rotate Tool or Scale Tool is active, a green cross will appear
near the currently selected object. This indicates the whereabouts of the
'pivot point' or 'scale centre point' of an object or group of objects.

  If you click on the "Dialogs" option on the Toolbox, you will see an
entry called "Tool Options". Clicking on this brings up a little window
that shows what can be changed about the currently selected too. Cones,
for example, can be pointy (like a funnel) or be a cylinder with tapered
sides. If you're feeling awkward, you can even make the cone's sides cross
over at a point. It might even render.

  Those of you familar with user interface for The Gimp may prefer to do
the same thing by double-clicking the tool in the Toolbox.
        
The Move Tool
-------------

  To move the current selection, just Drag 'n' Drop it whereever you want.

The Rotate Tool
---------------

  To rotate the current selection around the green cross, Drag'n Drop and
the selection will rotate around the pivot point in the plane of the
active view.  You can place the green pivot point whereever you want, by
pressing the Ctrl and clicking in the right place when the Rotate Tool is
active.

The Scale tool
--------------

  The Scale Tool uses the scale centre point as a kind of focus for
scaling objects. Just click and drag on the shape, and the selection will
grow or shrink with the cursor.  You can place the pivot point whereever
you want, by pressing [Ctrl] and clicking in the right place. You can
choose to scale evenly or unevenly with the 'Tool Options Box'.

The 'Box' Tool
--------------

  To create a new box, click to place the first corner, then drag the
mouse pointer to the place you want the second corner to be. The box is
created when you release the button.

The 'Cylinder' Tool
-------------------

  To create a new cylinder, click to place the center of the cylinder's
base. Then drag the mouse pointer vertically to set the length, and
horizontally to set the radius. The cylinder is created when you release
the button.

The 'Plane' Tool
----------------

  To create a new infinite plane, click in the View window which resembles
the plane required. For example, a click in the X-Y view will create an
infinite (X-Y) plane (i.e. with a normal toward the Z vector).

The 'Sphere' Tool
-----------------

  To create a new sphere, click to place the center of the Sphere, then
drag the mouse pointer to choose the radius of the sphere and release the
button.

The 'SuperEllipsoid' Tool
-------------------------

  When the SuperEllipsoid Tool is active, a click in a XYZ view will bring
up a dialog box. There, you can choose to two exponents of the
superellipsoid. Exponents near 0 lead to sharp edge, and exponents higher
than two lead to pinchy objects. Experiment with this and have fun; a
surprising variety of effects can be produced. The forms you'll obtain
will vary from spheres, rounded boxes, rounded cylinders, pillows, and so
forth.

CSG Tree
--------

  Before you go much further you need to know about the CSG Tree, which is
usually invoked from the popup menu's "Dialogs" option on the Giram
viewport. The CSG Tree is a window gives you an insight as to how the
objects are connected and related. Currently its only other use is to
allow you to make specific objects invisible by clicking on the eye at the
left of each object's row in the "Visible" column. The objects dimensions
are in the far right column marked "Info", and the centre "Tree" shows the
graphic artist's version of a directory tree, and you will find that it
works a lot like a File Manager utility. Logical branches of a complex
object can be individually opened and closed much as directories are on a
hard disk.

  The CSG Tree can also be invoked from the "Dialogs" menu on the Giram
Toolbox, but this will load the tree from the last scene loaded, which may
not always be what you would expect.

  If this sounds complex, do not be alarmed. You don't need to use it yet
and it's a piece of cake anyway.

Main Popup Menu
---------------

  The popup menu is where we've stuffed all the parts of Giram that you
use to manipulate your vision; you get it by right-clicking in a Giram
viewport. You've already met the "Files" section and Render" in the
'lollipop' tutorial, but there are many more useful options that are close
to your pointer. The menu options are arranged like this:

Files
  Load Pov
  Load Autocad DXF
  Save Pov
  Save Autocad DXF
  Quit
Edit
  Cut
  Copy
  Paste
  Snap
View
  Zoom In
  Zoom Out
  Fit to Selection
  Fit to Scene
Selection
  Select All
  Select None
  Invert Selection
  Export to DXF
  Import DXF Objects
Operations
  Translate
  Rotate
  Scale
  Change Colour
  Edit Camera
Render
  Wire Frame
  Hidden Faces
  Gouraud
  OpenGL Wireframe
  POVray Rendering
Dialogs
  CSG Tree
  Tool Options
Plugins
  Your choice here.

  If you have a different range of options, maybe you've got the wrong
documentation. It is even possible you need the version after the one
that's just been written...

Files
-----

  "Load Pov" and "Save Pov" load and save Povray scripts pretty much as
you'd expect them to. Povray scripts can be hugely complicated, and there
are many ways of achieving the same effects so don't expect to get out
exactly what went in. If you fancy programming, additions and corrections
are more than welcome.

  "Load Autocad DXF" and the corresponnding "Save" option will load and
save ASCII Autocad DXF files. Yes, you can use Giram as a file converter.
We hope to add binary DXF capability soon.

  Also on this menu is the "Quit" option, which is used to terminate Giram
prior to re-entering the "real world".

Edit
----

  "Copy", "Cut" and "Paste" should be pretty obvious to most people by now.
But just in case you've been living in the Amazonian rainforest since editors
were invented, they allow you to copy your currently selected items to an
invisible clipboard, cut the selection out of the existing scene and into the
clipboard, or to bring what's already in the clipboard out into the current
scene.

  The "Snap" option needs a little more explaination. It's basically like
opting to draw your design on graph paper, except that every line you draw
goes from one intersection on the graph paper's grid to another. You get to
say how fine the graph paper is. Because we tend to design things in whole
multiples of units given the chance, your shapes will naturally fall into
place. All the corners will line up, all the edges will be square. Cool, eh?

  When you click on "Snap" the "Snap" dialogue pops up. In there you can
change the scale of the grid independently for each axis, depending on the
demands of your model. You can turn the snap action on and off, and you can
hide or show the grid. Give ti a go and generate a few shapes - note how they
always line up when you make them or when you move them around.

View
----

  The options "Zoom In" and "Zoom Out" are fairly obvious: The current
viewport appears to get closer to or further away, keeping the centre of
the view in the middle.

  The "Fit to Selection" option is very useful when you start creating
more complex models. It allows you to select one or more objects, and then
zoom in or out automatically to the point where all of the objects
selected are just in view.

  "Fit to Scene" does much the same thing but zooms in or out to encompass
all the objects - except the lights - in the current viewport. Both of the
exotic zooms leave your selection untouched.

Selection
---------

  "Select All" is fairly obvious. Sometimes it is easier to select all the
objects in the secne and then deselect the ones you didn't want. Even
objects which are not currently visible (either by virtue of being off the
current view, or made invisible through the CSG Tree dialog) will be
selected.

  "Select None" is also a no-brainer. It deselects everything.

  "Invert selection" is again useful when you want everything but a few
bits of the scene. Just select them, and then invert the selection.

  "Export to DXF" allows you to take the currently selected objects and
write them out as an Autocad DXF file, which you can specify using the
usual file dialog that will be presented to you. Saving DXFs is subject to
the usual limitations associated with exporting files in differing
formats.

  The "Import DXF Objects" option does the reverse. You are presented with
a file dialog with which you can select an existing DXF file. This file is
then merged with the current frame.

Operations
----------

TBA

  "Change Colour" does just that. The colour of the current selection is
set to a colour which you get to choose from a colour wheel. Click or drag
the mouse anywhere in the colour wheel to pick the basic hue of the colour
you want, and then use the vertical bar in the middle to adjust the
shading from your pure colour to pitch black.

TBA

Render
------

  There are a variety of different ways of rendering your masterpiece on
the screen. Ideally we'd like to see a high resolution image with
textures, shadowing, glints and all but unfortunately the processing power
required to do this is beyond the reach of most people - and indeed many
small countries.

  The easiest way of doing things is to construct a "Wireframe" view that
is traditionally associated with 3D computer graphics. It's easy for the
programmer anyway, and the user gets to see what is inside objects.

  A slightly more realistic view is "Hidden Faces", in which lines that
would not be seen because the front of the object is in the way are
identified and not drawn. Depending on what you are designing, this may or
may not be preferable to a wireframe view.

  "Gouraud Shading" is about as good as it gets without doing a proper
rendering. The faces of the objects are rendered, and the angle of the
face is used to create a shading effect.

  The OpenGL Wireframe option uses a 3-D graphics library developed by
Silicon Graphics. It will also run with packages that are compatible with
the OpenGL API such as Mesa (http://www.ssec.wisc.edu/~brianp/Mesa.html)
and take advantage of any hardware-specific acceleration that may be
supported on your machine. Presently this is minimal in Linux, but things
are changing fast.

  But to see your masterpiece in its true, virtual light you must use a
package that does a lot more work, and so takes much longer. Povray
(available from http://www.povray.org) is such a program - some would say
the best - and it is supported in Giram via the "Povfront" front-end. The
front-end saves you having to remember many obscure command line options
and saves them for next time, so leaving your brain free to work on your
artistic creations.

Dialogs
-------

  In here you'll find options to toggle the Tool Options and CSG Tree
boxes on and off. This is included for people who like the Gimp way of
doing things from a popup menu. They can also be reached from the
"Dialogs" menu on the Giram Toolbox.

Plugins
-------

  Here you'll find additional modules which can written by keen
programmers and added to Giram without modifying the Giram source code.
The practical upshot is that users will not need to recomplie the Giram
code to use a plugin.

  People can add plugins for creating multiple objects, possibly even ones
that vary slightly according to how the plugins are written. The plugins
can even have their own Tool Options menus. "Spheres" is a sample plugin
that comes with Giram. Try it out.

  A complete description of the programming interface for plugins is not
yet available, but if anyone should feel like writing a plugin, please
contact Giram's original creator, David@dindinx.org

Shortcut Keys
-------------

  To make Giram more convenient for your own pattern of use, you can
assign your own shortcut keys to menu items. Let's say you want to use
[Ctrl]L to load a new Pov file. Move the pointer to the [File][Load]
option but don't click on it yet. Press [Ctrl]L and note that the menu
gets automagically changed to include your keystrokes as a shortcut.

  From this point on, you can use [Ctrl]L to bring up the File menu. You
don't have to use the [Ctrl] key. [Alt], [Shift], combinations or just a
plain alphanumeric keypress will do fine. Use the backspace key to delete
a shortcut.


Preferences
-----------

  There is currently no GUI preferences option: You have to edit it the
old-fashioned way in the top-level Giram directory's giramrc file. Options
are in a standard ASCII file separated by newlines. Amongst the options
available are:


      (toolbox static)

      All tools are displayed simultaneously in the toolbox.


      (toolbox dynamic)

      Only classes of tools are displayed in the toolbox.


      (dynamic-toolbox-shape vertical)
      (dynamic-toolbox-shape horizontal)
      (dynamic-toolbox-shape square)

      These describe the orientation of tools in the toolbox.


      (library_path "[path1][[:path2]...]")

      Tells Giram where to look for include files that are mentioned in
      Povray scripts. Multiple paths may be defined, each separated by a
      colon.


The CSG Tree
------------

  Eventually this will be a powerful tool showing the structure of your model and
allowing you to assign portions of models to specific groups and boolean
operations.

  For the moment, it shows you the logical structure of your model and provides
a way of selecting objects which we've not yet written the selection code for.
To select an object, just click on its CSG tree entry and watch the entry turn
blue. At the same time, the object's representation in the views will turn red.

  The open eye at the left of some objects indicates that they are visible if
they are within the view window or camera's field of view. Clicking on the eye
will cause it to close, and the shape will no longer be visible. Click the
closed eye, and it opens revealing the shape in the view window once more.

  Note that it is possible to have an object invisible but selected. If you
modify the selected shapes at this point, the invisible ones will be affected
too.


To Do
-----

  Add numerous descriptions for Toolbox icons, popup menus and Toolbox
feature boxes.

  Section on making a sor shape.
 
  Many new items in preferences section.

Small Print
-----------

  All trademarks mentioned in this document are properties of their
respective owners.

*END*