gPhoton README Last updated: 28Oct00 Ok, in lieu of a manual, here's the drill: WHAT IS GPHOTON =============== gPhoton is an artistic ray-tracer for gnome. First and foremost, it is a ray-tracer which is entirely implemented in software. On the downside, ray-tracing is extremely slow compared to hardware 3d graphics. On the upside, being software, it is extremely flexible and extensible, it's more hardware independent, and can produce images of outstanding quality and absurdly high resolutions (like ANSI-E size 300 dpi images if you have that much patience). The word 'artistic' is used because this program is more for artistic curiousity (i.e., draawing pretty pictures) that for other uses. For example, if you're looking for a 3d modeller to create a space for your latest game, I wouldn't suggest gPhoton. However, if you're looking for a program that can produce high-quality ray-traced images, gPhoton might be useful. 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, and libtiff installed. * 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' * Further installation is optional. You're options are: - as root, install it (usually to /usr/local/bin) by 'make install' - don't install, just cd to the 'src' directory (.../gphoton-X.XX/gnome/src) and type 'gphoton' 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. 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: 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: The project e-mail is: