gPhoton README
Last updated: 09Feb2001

WHAT IS GPHOTON

gPhoton is a simple 3d modeller and ray-tracer for Gnome.

HOW TO INSTALL/RUN GPHOTON

HARDWARE REQUIREMENTS

There really aren't any 'requirements'. 3d graphics hardware is not required. I highly recommend that your 2d graphics hardware is being in used in at least 24 bit mode. 16 bit or less is OK, but shows a lot of contours -- not my problem. Note that when you save screenshots, it is always in done correctly in 24-bit mode, and doesn't depend on the bit-level you happen to be viewing it at.

INSTALLING GPHOTON

You need to have gtk+, lots of gnome stuff, libtiff, Mesa (or OpenGL) and gtkglarea
Expand the tar file, using 'tar xvzf gphoton-X.XX.tar.gz', where you substitue the version number for X.XX (duh). Uh, you probably already had to do that to get here.
Change to the gnome directory, probably something like 'cd gphoton-X.XX/gnome'. Uh, again, that's probably where this file is at.
Run the confiuration program, './configure'
Compile the program by running 'make'
If it doesn't compile, here are some pointers
- make sure you have the headers tiff.h, GL/gl.h, GL/glu.h and gtkgl/gtkglarea.h
  - if one of these are the problem, you'll have to install the right header or modify the program to look for the header in the right place
- make sure you have the libraries libtiff, libGL, libGLU, and libgtkgl
  - if one of these is the problem, you can point to it in src/Makefile.am
- if you can't get the gl or gtkgl stuff to work at all, you can disable all gl stuff by commenting out the "#define RT_USE_GL" in rt.h
Further installation is optional.
- as root, install it by 'make install'

RUNNING GPHOTON

If you did a 'make install' as root, you should just be able to type 'gphoton' at any command prompt. The executable should be '/usr/local/bin/gphoton'
If you didn't 'make install', cd to 'gphoton-X.XX/gnome/src' and type 'gphoton'

GREAT, NOW WHAT DO I DO WITH IT?

LOADING PRE-MADE 3D SCENES

In the directory 'gphoton-X.XX/gnome/pho_files' there are several example files you can load. Just click [File][Open] to open the file.

MOVING AROUND IN 3D

There are two main ways to move around: (1) use the 'Navigator' dialog, or (2) use the 'Set Viewer' dialog.

NAVIGATOR DIALOG
The 'Navigator' dialog is invoked by clicking [View][Navigator]. Each time you click [Navigator] in the [View] menu, the state of the dialog is toggled. This dialog is meant for precise positioning, and here's a few things you can do:
* Left-click on the 'fisheye' 180 front view to change the viewing direction. You can change up to 90 deg in any direction. * Right-click on the 'fisheye' view to change rotation. * Click on the up/down ruler on the left to rotate up or down. Each small line is 5 deg, with larger ticks at 15 deg, 45 deg, and 90 deg. * Click on the right/left ruler much like the up/down ruler. * Click on the 'R' button to reverse the view 180 degrees. * The 'Move Dist' entry box doesn't affect what I just mentioned, just the buttons below it.
* The buttons just below the 'Move Dist' entry box (Fwd, Back, Up, Down, Right, Left) are panning. They pan by the amount in the 'Move Dist' box. * The buttons below that are 'Tele' and 'Wide'. These affect the main view only, as the fisheye view is always a 180 degree view. * The undo button gives you one level of undo on any action in the Navigator.

SET VIEWER DIALOG
Set viewer is invoked by [View][Set Viewer] or by clicking the [Set Viewer] in the 'Navigator' dialog. The 'Screen Origin' is where your viewing screen origin is in 3d space. This isn't where the focal point is (i.e., not your retina, but your computer screen). The 'View Direction' is the vector direction you're looking. The 'ScreenY Direction' is the 'up' direction of your computer screen. It is essential that 'ScreenY Direction' is not a vector multiple of 'View Direction'. Also, 'View Direction' takes precedence over 'ScreenY Direction'. 'Focal Distance' is the distance from the 'Screen Origin' to the focal point for calculating perspective -- smaller is more like 'wide', larger is more like 'telephoto' -- values here of 1X to 2X of the screen width look the most realistic, as that's about how far you are from your computer screen. 'Screen Width' is how wide your screen is in the 3d space. Note that if you change 'Screen Width' and 'Focal Distance' by the same multiple, you get very similar (though not identical) results. 'Brightness' is an analog brightness tuner -- a value 256 is default, but it depends on your light sources.

CREATING/MODIFYING 3D SCENES

All creation and modification of geometry is done through the 'Browser' dialog. Each time you click [Browser] on the menu, the state of the dialog is toggled.

Note that unlike other 3d engines, light sources are not a separate type of object. They are just regular objects that have a material that has emmittance properties.

The scene database is made of 'objects' and 'materials'. All 'objects' are made of a 'material' that gives the object it's visual properties like color, shinyness, or emittance. Several 'objects' can use the same 'material'. A 'material' doesn't have to have any 'objects' associated with it.

ADDING NEW OBJECTS
Just under the 'Objects' tree, click [New]. Click on the type of object to add. Fill in the boxes and press [OK].

EDITING OBJECTS
Click on the object you want to edit in the 'Objects' tree and click [Edit]. Change and press [OK] or [Cancel]

DELETING OBJECTS
Click on the object you want to delete in the 'Objects' tree and click [Delete].

ADDING/EDITING/DELETING MATERIALS
This is very similar to adding/editing/deleting objects as outlined above.

<TODO: Add more about the properties of specific objects and especially the materials dialog here.>

LOADING/MERGING/SAVING FILES

Note that there is a big differnce in what you see on the screen and the 3d scene you are viewing. The same 3d database can be viewed from any number of viewing positions/parameters.

NEW/OPEN/MERGE

You can only load 3d data. That is, a 2d screenshot cannot be loaded -- if you saved a screenshot, you have to use another 2d graphics program (like xpaint or gimp).

[File][New] starts a new database. By default, if a file by the name of 'photon.pho' is found in the current directory, it is loaded as the starting point of a new file. Typically, you'd want this to contain material specifications.

[File][Open] clears the existing database, loads 'photon.pho' and then loads the file you specify. Duplicates are removed and the view is positioned where it was when the file you specified was saved.

[File][Merge] is like 'Open' but does not clear the existing database. The old database is preserved, the new one is loaded, and duplicates are then removed.

SAVE/SAVE SCREENSHOT

You can save the 3d data (which you can load again in gPhoton) or you can save just a 2d screenshot of the current view (which you can then load into another 2d graphics program).

[File][Save As] will save the entire 3d database including the [Set Viewer] position. You'll want to do this before exiting to save your work. The recommended extension for 3d files is *.pho.

[File][Save Screenshot As] will save the current screen as a tiff file. This file cannot be reloaded into gPhoton.

QUALITY MENU PICKS

Ray-tracing can be slow. To make this easier to deal with, all tracing of the main screen is done in the background, allowing you to continue to work. Also, you can select the speed/quality tradeoff from the [Quality] menu picks. Speed and quality are traded off by: * subsampling (super-pixeling)
* turning texturing on/off
* varying the level of reflections

Here's a table of the current quality defaults:

             Super-
Pick         Pixel      Texture       MaxReflections
-----------  -----      -------       --------------
FASTEST      27x27        No               0
FASTER        9x9         No               0
FAST          3x3         No               0
OK            1x1         No               0
GOOD          1x1        Yes               0
BETTER        1x1        Yes               1
BEST          1x1        Yes              lots

FEEDBACK

We'd like to hear from you!

If you come up with cool .pho files, please e-mail them to us. We'll probably include them with a later release.

Please submit all bugs and requests for new features at: <http://sourceforge.net/projects/gphoton> For bugs, click on [BUGS] on the toolbar at that site. For support, or new features, click on [SUPPORT] on the toolbar at that site.

Our homepage is:
<http://gphoton.sourceforge.net>

The project e-mail is:
<gphoton@excite.com>