The DKBTrace Utilities ---------------------- In many cases, creating data files for DKBTrace is difficult and tedious. To help remedy this problem, We and various other people have developed some utilities to create data files. These utilities are described below. As well, there are some utilities that perform operations on the image files created by DKBTrace. These utilities convert between various formats and allow you to modify or merge output files together. All in all there are three major types of DKB utilities, I. Data File Creation, II. Output File Manipulation, and III. Animation Utilities. We'd like to thank all the people who wrote these utilities and sent them to us. If anybody else comes up with other utilities, please let us know and we'll cheerfully include them in future distributions. Some of these utilities are written in BASIC for IBM PC systems (Arrrggh! :-P). As such,they are not easily portable from system to system. We really wanted to convert them all to C, but found that time was prohibitive. If anyone wants to try their hand at converting them to C, let us know and we'll post the C versions. They are all in Microsoft structured BASIC, which really isn't all that far away from real C, anyway. < I. > Data File Creation Utilities ------------------------------------------------------------------------------- The data creation utilities fall into two categories: Those that convert from some other format into DKB format, and those that generate DKB files using algorithmic techniques. These utilities are described below. ------------------------------------------------------------------------------- 1.) SA2DKB This program converts Sculpt-Animate 3D & 4D data files into DKB format. It currently only supports the basic triangles and textures. It doesn't support smooth triangles (it treats them like normal triangles), light sources, cameras, or floors. (This utility was formerly called "Sculpt2DKB" but the IBM systems out there kept calling it "SCULPT2D", then couldn't figure out what a 2D program had to do with raytracing or what the nonexistent Amiga program called "Sculpt-2D" was :-) 2) DXF2DKB This utility converts AutoCAD DXF (Drawing eXchange Format) files into DKBTrace format scene description files. It was written by Aaron Collins. It does not support all of the DXF primitives, but will suffice for simple objects and scenes after EXPLODE'ing and DXFOUT'ing then in AutoCAD. 3) ShellGen ShellGen is a BASIC program written by Dan Farmer. It's based on a short code fragment from Clifford Pickover's book "Computers, Pattern, Chaos, and Beauty" (St. Martin's Press). This code fragment was reprinted in Ray Tracing News Issue 3.3. As far as I know, the BASIC program only works on IBM's. It does, however, allow you to change the parameters and see a quick outline of what the result will look like. For those people without IBM's, I've changed the original code fragment to at least output a DKB-format file. No user interface has been provided, however. The file is called PICKSHELL.C and is included in this archive. The file DKBSHELL.INC is included by the program at the top of each data file it generates. If you feel the VIEW_POINT or LIGHT_SOURCE definitions need changing, go ahead. 4) Twister Twister is a C program written by Drew Wells (CIS 73767,1244). It creates data files for twisted shapes. The program uses a text interface and prompts the user with a question/answer format. 5) Chem2DKB Chem2DKB is an IBM BASIC program written by Dan Farmer. It takes models generated by the CHEM.EXE V.2.00 program written by Larry Puhl. 6) Lissajou This is an IBM BASIC program written by Dan Farmer. It creates data files for lissajous figures. The basic algorithms were from Clifford Pickover. See Scientific American Jan. '91 and Omni Feb '90 for examples. 7) 3D2-DKB This is a C program written by Steve Anger. It takes a CAD-3D (Macintosh?) .3D2 scene description data file and converts it to DKB format. There was an earlier program called 3D22DXF.BAS which performed nearly the same function, but output Auto-CAD DXF files instead of DKB data files directly. Light source locations, ambient light levels and object color information are all converted. 8) SplitDKB This is a program for IBM PC's running DOS. It works by generating a bunch of batch files meant for breaking up a long-running data file to trace in several parts for multiple machine execution. It also generates a batch file that will glue the partial output files together in the correct order when all are done. It is written in IBM BASIC by Dan Farmer, based on an idea by Randy Antler. 9) Diamond This is an IBM BASIC program written by Ken Koehler. It generates a DKB data file that describes the 3-D geometry of a faceted-cut gem stone (i.e. diamond). It will generate an entire runnable DKB data file including light sources and view points. It quickly displays an outline of the diamond shape it is about to create in graphics mode. Many parameters are user-definable, such as the height, width, number of sides, etc. 10) Gear This is an IBM BASIC program written by Ken Koehler. It generates a DKB data file that describes the 3-D geometry of a toothed gear. The gear may be solid- centered with holes drilled in it, or spoked. The teeth may be pointed or flat (the "flat" options were commented out originally, so they may not work right). It will generate a DKB data file with the gear shape DECLARE'd. It quickly displays an outline of the gear shape it is about to create in graphics mode. 11) TCE (The Color Editor) This is an IBM BASIC program written by Dan Farmer. This is an interesting color preview/mixing program. It will as for the name of a color definition file (which we all now know is called "colors.dat", right?!?!?) and allow you to browse through the file and display the colors therein, preview how they will look (approximately) when projected onto a shaded sphere, and allow you to change the R-G-B levels and create new colors for the file. Very nice bolt-down menus. 12) Font2Dat This is an IBM BASIC program written by Ken Koehler. It will take an IBM screen font file (type .FNT or .SET) and convert them to DKB 3-D data files using spheres, boxes, squares, or dots to represent each pixel in each source character. It generates either a large data file containing all the chars or individual data files, one file per char, at the user's request. The file ROMAN.FNT is an example font file you can use to try it. 13) Star This is an IBM BASIC program written by Ken Koehler. It draws an n-pointed 3-dimensional star figure, and gives a quick preview of what it looks like on the screen in graphics mode. It outputs a COMPOSITE object in a DKB data file that needs to have a view point and light sources added, and the star's color and texture need to be declared. < II. > Output File Manipulation Utilities ------------------------------------------------------------------------------- These utilities perform some useful manipulations on the dump format and Targa format output files from DKBTrace. I'd like to thank the people who wrote these utilities and provided them for general distribution. ------------------------------------------------------------------------------- 1) dump2i24 (DumpToIFF24) This program was written by Helge E. Rasmussen (her@compel.dk). It converts the dump format files produced by DKBTrace into 24-bit IFF format files. These files can then be read by a variety of programs including "The Art Department" by ASDG. 2) catdump This utility was written by Ville Saari vsaari@niksula.hut.fi (and copyright by the Ferry Island Pixelboys.) It takes two or more partially rendered files in DKBTrace's dump format and merges them into one file. This is useful for all sorts of things like rendering different parts on different computers and combining the results. NOTE: Be careful if you combine pictures produced on different systems. If the random number generator works differently between the two systems, the textures may look completely different from one another. So long as you use the same executable, you should be fine. 3) combdump (combine dump) This utility was also written by Ville Saari. It takes two images generated with DKBTrace with slightly different viewpoints, and creates one dump-format image file to be viewed with RED-BLUE or RED-GREEN 3D glasses. The program allows you to compensate for the exact filtering characteristics of your glasses to get the best possible result. 4) dump2mtv This is yet another utility written by Ville Saari. This one converts DKBTrace dump format files onto MTV format used by the MTV and RayShade raytracers. 5) dump2raw The dump2raw utility was written by Aaron Collins to convert the dump format output of DKBTrace into three separate files for red, green, and blue. On the IBM, the extensions for these files are "r8", "g8", and "b8". On the other systems, they are "red", "grn" and "blu". DKB Version 2.10 and later allows you to use the +fr option to output "raw" format files directly without the need for a conversion program like this. 6) halftga The halftga utility (written by Aaron Collins) shrinks a Targa-format file to exactly half its original size. This file can then be converted into a GIF image and used in an IMAGE_MAP statement. For systems with little memory available for imagemaps, this command can be a life-saver. 7) gluetga This utility (by Aaron Collins) is similar to catdump but works for Targa format files. It takes several partially-rendered Targa files and glues them together into one image. 8) tga2dump This utility was written by Aaron Collins. It converts Targa format 16, 24, and 32 bit images into DKB's dump format for use in importing Targa files for image-mapping textures in "true color" (24-bit). 9) ip2dkb This utility was written by Frank P. Weed II. It converts Amiga Digiview IP format output files to DKB's dump format for use in importing IP files for image-mapping. Digiview IP uses a 2-million color range, which is converted to the more common 16-million color (24-bit) range. < III. > Animation Utilities ------------------------------------------------------------------------------- One of the most frequent questions I'm asked is whether or not DKBTrace supports animation. The answer is no, not directly. However, I have made some changes to the program to provide frame-to-frame consistency so you can use it for animation if you want to. The problem, then, is creating the data files for each individual frame. That's what this section is all about. ------------------------------------------------------------------------------- 1) Anima This is an IBM BASIC program written by Dan Farmer. It will take a "skeleton" data file with syntactic variables used (like %0, %1, etc.) and use "rules" which dictate how the variables change over each frame. The program will stamp out a given number of DKB data files with the variables substituted for the actual desired values, stepped in each data file according to the "rules". The files ANIM1.DAT and ANIM2.DAT are a couple of example "skeleton" data files you can use to try it. 2) RayScene Although RayScene is not being distributed with this raytracer, we thought we'd at least mention it and tell you where you can get it. RayScene is a program that creates data files for DKBTrace based on a high-level (higher-level?) description of the motion of the camera and the objects. It was written by Jari K{hk|nen (hole@tolsun.oulu.fi) and Panu Hassi (oldfox@tolsun.oulu.fi) and is available by anonymous FTP from tolsun.oulu.fi (128.214.5.6) in the directory /pub/rayscene or from iear.arts.rpi.edu in the directory /pub/graphics/ray/rayscene. Of course, it's also on the "You Can Call Me RAY" BBS in the Chicago Area, (708) 358-5611. This explanation of RayScene was sent to me by Panu Hassi; "I've tried animation with DBW before DKBTrace2.0 was released. The procedure was this: First I wrote the first scene file, copied it for NUMBER_OF_FRAMES times and then edited some parts of those files to create movement etc. If something went wrong (I accidentally edited wrong value etc), I had to edit all those scene files again to make the changes. Not so nice if there are 100 files to edit... So a friend of mine, Jari K{hk|nen, and I decided to write RayScene to make that process even a little easier. With RayScene the process goes like this: you create a scene file and mark the places that should be changed with a variable, like: BOUNDED_BY SPHERE <0.0 0.0 0.0> #sphere_size# END_SPHERE END_BOUND Then you create another file where the values for these variables are listed. Rayscene simply creates N scene files inserting current value of each variable to proper place. That's all :D We have included couple of simple utilities that help with creating those variable values, but the original scene files are still created 'manually'. Still, the results have been really nice. There are several animations for Amiga and PC in tolsun.oulu.fi." < IV. > Concluding Remarks ------------------------------------------------------------------------------ The IBM executable versions of the utilities are compiled with 8088/no 8087 flags given to the compiler for maximum portability. If you REALLY must have them operate a LITTLE quicker, you can change the IBM*.MAK files to use a coprocessor and/or 286 opcodes, and then re-compile all of the "C" utilities. For the most part the utilities are simple and small enough that they perform adequately without really needing these optimizations. Four semi-extraneous files are included: 1) Dump2RGB.C is older version of Dump2RAW.C that uses more memory & less disk activity. 2) CHEMCONV.C is a different (C instead of BASIC) IBM P.C. Chem V.2.00 molecular modeler Data file generator (renamed from CHEM2DKB.C). 3) PICKSHEL.C is the original C program that SHELLGEN.BAS is derived from, Clifford Pickover's seashell program (renamed from SHELLGEN.C). 4) 3D22DXF.BAS is an older BASIC program that wrote DXF files. 3d2-dkb.c is by a different author, and converts 3d2 files to DKB files directly.