Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / dos / grafik / sega / pvquant / quant.doc < prev next >

Wrap

Text File | 1991-11-28 | 22.7 KB | 555 lines

QUANT Version 1.30 A Colour Quantiser for the Persistence of Vision Raytracer Written and Distributed by: Frank van der Hulst, 101 Epuni St, Lower Hutt, New Zealand Electronic mail to: UseNet: frankv@cit.ac.nz, frank@cavebbs.gen.nz FidoNet: frank vanderhulst at GenBoard (Node 3:771/160) 19 November 1991 ─────────────────────────────────────────────────────────────────────────── This program is freely distributable. The author retain the copyright to the program but authorizes free distribution by BBS'es, networks, magnetic media, etc. The distributor may charge no more than five dollars ($5) U.S. for this software. The images and data files generated by the quantiser are the property of the user of the software and may be used for any purpose without restriction. The author makes no guarantees or warranties with this program and claims no responsibility for any damage or loss of time caused by this program. Bug reports may be sent to the author but the author is under no obligation to provide bug fixes, features, or any support for this software. The following conditions are placed on the use of this program: 1) That it should not be used as part of any commercial package without the explicit written consent of the author. 2) If you make any changes to the source code, please let me know. That's the way this program was built! 3) This text file must accompany the program. This manual is divided into the following sections: 1) Program Description 2) Background 3) Getting Started 4) Command Line Parameters 5) Output File Format 6) Source Code Information 7) Displaying the Images 8) Animation 9) Compiling the Code 10) Porting to Different Platforms 1) Program Description ~~~~~~~~~~~~~~~~~~~~~~ QUANT is a program to convert image files produced by DKB-Trace or Persistence of Vision raytracer into a format suitable for display on a VGA screen. To do this, it must select 256 colours from a palette of 256K colours to best represent the colours in the image file which are selected from a palette of 16 million. In other words, it must "quantise" the colours in the image file (which are selected from a palette of 16 million) into a set of 256 colours selected from a palette of 256K colours. QUANT is a colour quantisation program which post-processes raw image files produced by the Persistence of Vision Ray Tracer (PoV Ray). Two versions can be compiled: one uses Heckbert's median-splitting algorithm, whereas the other uses Octree quantisation. The Heckbert version takes much longer to run, especially on a 286. On the other hand, it produces much better results. The Octree version is faster, but not as good. As an additional feature, the program allows the user to generate a single palette from several image files, thus making it possible to produce a stereoscopic 3D image from two views of a scene, or animation. 2) Background ~~~~~~~~~~~~~ I have a 286 PC clone with a VGA screen, and am interested in virtual reality. I realise that a 286 doesn't have the horsepower to be good for that, but that's all I got. Attached to this I have a pair of Sega 3D glasses, which allows me to view see a 3D image by displaying stereoscopic pairs of images on the screen. I started off drawing images with Turbo C, but that was time-consuming and not very effective. I then got a copy of DBW_RENDER and used it (over many nights over many weeks) to produce images. In the meantime, Craig Kolb had sent me a copy of his COLORQUANT code, which I ported to Turbo C. I also found code to display images in 320x400 mode on my VGA. Finally I could display some good images. I modified the quantiser to read two input files to produce one palette, so that I could display a 3D image. The primitives available in DBW_RENDER were very limited, so I switched to DKB-TRACE v2.12. And ran my machine day and night for months. Then I got access to a 486 running SCO Unix. Great! My 286 took a rest at nights, because I could generate the most complex scenes in only a few hours. Unfortunately, I couldn't display the images, or even move them easily from the 486 (the only direct interchange medium is 360K floppies, and the QRT-format files are too big). Also working with the QRT-format was clumsy, so I converted the quantiser to read raw format files (each of which is only 128K long, thus easily transported). Then I saw a copy of the Octree quantisation code on UseNet, so I tried that. It was much faster (a real advantage on the PC) but produced inferior results. Next step was to move the quantiser to Unix, and suddenly the Heckbert technique was best. The extra speed of the Unix box opened up some new possibilities -- I started to look at animation. I could generate about seven images per hour, then use a display program to flip them up one by one. That works fine (although it needs a lot of memory on the PC). Then I received an assembler source file by K. Heidenstrom which did page flipping in 320*200*256 mode. This makes animation easier, since each image requires less memory. It also makes 3D animation possible. Next is Floyd-Steinberg dithering, to remove unwanted "banding" of coloured regions (called false contours). Or perhaps converting the GIF files to a standard animation format such as .FLI or GRASP. Or perhaps 3d animation.... 3) Getting Started ~~~~~~~~~~~~~~~~~~ Before quantising an image, you must create one! Use either DKB-TRACE or PoVRAY to produce output in the "raw" format. I use the following command line: PVRAY -ipacman -opacman -w320 -h400 -v +fr +p +x -a See the raytracer documentation on what all the above mean. Most important is the "+fr" option which tells the raytracer to produce "raw" files. These are simply three files with no header information and no line number information - just the raw data. If you ran PVRAY on a PC, you'll probably need to rename the files produced. By default it gives extensions of .R8, .G8, and .B8, whereas QUANT needs extensions of .RED, .GRN, and .BLU. Now try running the OCTREE quantiser program: OCTREE pacman 4) Command Line Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~ Command line format: HECKBERT [/C=colours][/W=width][/H=height][/D=display][/T=type] [/O=outputbits][/S=speed] file_1 [file_n]* or OCTREE [/C=colours][/W=width][/H=height][/D=display][/T=type] [/O=outputbits] file_1 [file_n]* Default value outputbits = bits per colour being output [6] type = 0, 1 or 2 to select output format [1] 0 selects 4-planar output for 320x400 or 320x200 images 1 selects linear output 2 selects GIF output. Only one image at a time can be converted to GIF format. display = 1 to display while outputting [1] Only available on the PC. colours = number of separate colours to produce [256] width = number of pixels wide the image is [320] height = number of pixels high the image is [200] speed = 1 or 0 for fast or slow quantisation [1] Heckbert speed switch. If zero, the program does another pass through the data, to find the optimal palette selection. This pass is much slower than the earlier passes, and produces slightly better results. file_1, file_n... are the names (without extensions) of files to be displayed -- the extensions .RED, .GRN, and .BLU are added automatically. If only one file is given to QUANT, it calculates a palette for that file and writes it to disk with a .2D extension. If two files are given to QUANT, it calculates one combined palette from both images, then writes this palette, as well as the data from both files to an output file with a .3D extension. If more than two files are given, QUANT assumes this is an animation sequence, and generates one palette for all the files, then writes the output in the form of several 2D-format files (one for each input file), all with the same palette. The files are named FILE_1.0, FILE_1.1, FILE_1.2, ... For example, C:\>OCTREE GLASS /c=16 will open the files GLASS.RED, GLASS.GRN, and GLASS.BLU, use Octree quantisation to find the 16 best colours, then write the output to to the file GLASS.2D. As it creates the file, it will display the image on the screen. C:\>HECKBERT PACMAN PACMAN_R /c=64 /d=0 will open the files PACMAN.RED, PACMAN.GRN, and PACMAN.BLU, then the files PACMAN_R.RED, PACMAN_R.GRN, and PACMAN_R.BLU, then create the file PACMAN.3D. This will be done using Heckbert's median-splitting algorithm. C:\>HECKBERT TEST_0 TEST_1 TEST_2 TEST_3 will read the files TEST_0.RED/GRN/BLU, TEST_1.RED/GRN/BLU, etc., then create the files TEST_0.0, TEST_0.1, TEST_0.2, and TEST_0.3. This will be done using Heckbert's median-splitting algorithm. Note that both versions of QUANT require large amounts of memory. 5) Output File Format ~~~~~~~~~~~~~~~~~~~~~ QUANT produces output in one of four possible output formats: GIF 2D -- a single image 3D -- two stereoscopic images of the same scene nn -- animation The GIF output file can be displayed using a GIF display program such as CSHOW or Image Alchemy. The 2D and 3D format files can be displayed using the provided DISPLAY program. The animation output is in the form of several 2D-format files (one for each input file), all with the same palette. The files are named FILE_1.1, FILE_1.2, FILE_1.3, ... The 2D and 3D files have the following format: 7-byte header 256*3-byte palette one or two screen images (one byte per pixel). The header consists of: <signature> - 2 bytes long, value '2D' or '3D', depending on the image type. <num columns> - 2 bytes long (LS byte first) <num rows> - 2 bytes long (LS byte first) <num colours> - 1 byte The palette consists of a series of 3-byte fields, each corresponding to the combination of blue, green, and red signals for the corresponding colour. A zero value in the <num colours> field represents 256 colours. A screen image can be in one of two formats: 4-planar or linear (corresponding to setting the type command line parameter to 0 or 1). The 4-planar format was designed to make it fast and easy to display an image in either 320x400x256 or 320x200x256 mode. To facilitate this, the format of screen image(s) is similar to the memory organisation of the VGA card in that mode. For any other image size, the program automatically outputs images in the linear format. Each byte is used by the VGA card as an index into the palette, which is then used to display the correct colour on the screen. For the 4-planar format of a 320x400 image, each screen image is made up of 128,000 bytes, one per pixel. Because of the memory organisation of the VGA card, each image is made up of 4 banks of 32,000 bytes. A VGA register is set, then a bank is loaded into VGA memory. Each bank consists of 80 bytes per scan line by 400 scan lines. The bytes from the four banks illuminate adjacent pixels. For a 4-planar 320x200 image, the total image size is 64,000 bytes, made up of 4 banks of 16,000. In the linear format, each byte in turn is stored. 6) Source Code Information ~~~~~~~~~~~~~~~~~~~~~~~~~~ This program is the amalgamation of several pieces of work by different authors: The colour quantisation algorithms used in QUANT.EXE come from two sources: 1. The files OCTREE.C and OCTREE.H are based on code written by Wolfgang Stuerzlinger who placed it in the public domain. The code implements the algorithm described in: Graphic Gems, edited by Andrew Glassner Article: A Simple Method for Color Quantisation: Octree Quantisation, pg. 287 ff by: Michael Gervautz, Werner Purgathofer Technical University Vienna, Austria 2. The files HECKBERT.C and HECKBERT.H are based on COLORQUANT.C written by Craig E Kolb who placed it in the public domain. The GIF output code is based on code in version 1.1 (Sep. 1990) of Gif-Lib, a package written by Gershon Elber. The VGA 320*400 output is based on a program published by Michael Abrash in Programmer's Journal. The VGA 320*200 output is based on a program (FLIPDEMO.ASM) sent to me by K. Heidenstrom. All of the above programs are in the public domain. I took all these bits and chopped them round a bit to make them work the way I like, and added my own code to do things like outputting to my 2D/3D file, virtual memory management, handle command line parameters, etc. 7) Displaying the Images ~~~~~~~~~~~~~~~~~~~~~~~~ The DISPLAY program provided will display either 320x400 or 320x200 images, either 2D, or stereo 3D. According to Abrash's article, this should work on any VGA or SVGA card. (On one machine which has a VGA card, this didn't work). It has the following command line options: Command line format: display FILE1 [FILE2]... [/W] [/C] [/R] [/H] where FILE1, FILE2... are the names (with extensions) of files to be displayed. /W => wait after each following image has been displayed /C => clear screen after each image /R => reverse eye-image sync for following 3D images /H => toggle screen height between 400 and 200 line modes Each of these switches acts as a toggle. The program has the following defaults: wait after each image for a keypress before displaying the next clear the screen after each image first image of a 3D-pair is for left eye, second is for right eye 400 line mode 8) Animation ~~~~~~~~~~~~ Three programs are provided to support animation: 1) MAKEANIM generates .DAT files for PoVRay 2) ANIMGIF converts multiple 2D files produced by QUANT into a single multi-image GIF file 3) ANIM displays the resulting animation. MAKEANIM: This program reads an animation source file (*.ANM), and uses it to generate data files for the PoV ray tracer. An initial data file must also be given. Command format: MAKEANIM data animation The animation file is a text file with the following format: Line 1: time, sound, name1 [,name2]... Line 2: t1, s1, value1 [,value2]... name1, name2, etc. are the names of items #declared in the initial data file, separated by commas. The names must be in the same order as they are #defined in the data file. t1 is the time in milliseconds, expressed as an integer, that this image is to be displayed for. s1 is the frequency of sound, expressed as an integer, to be produced while this image is displayed. A frequency of 0 represents no sound. The t1 and s1 values are ignored by MAKEANIM -- they are used by ANIM (see below). value1, value2, etc. are the values to be assigned to those #defined items, separated by commas. Each line represents one screen. This program reads the initial data file, searching for the lines where the items named in the animation file are defined. Data files are then generated, replacing the lines containing the #defines identified with new values. For example, assuming the following is contained in a file called PACMAN.ANM. time, sound, lip_upper_angle, lip_lower_angle 10, 0, -35, +10 20, 0, -28, +8 10, 500, -20, +6 10, 800, -12, +4 Executing MAKEANIM PAC_BASE PACMAN would make 4 copies of PAC_BASE.DAT, generate 4 data files, named PACMAN_1.DAT, PACMAN_2.DAT, PACMAN_3.DAT, and PACMAN_4.DAT, with the given values being inserted into the lines which define lip_upper_angle and lip_lower_angle. These 4 files are then given to PoVRay to generate 4 scenes. ANIMGIF: This program produces a .GIF file containing a series of images to be displayed. The images to be read in must be generated by QUANT (either version) with the output format set to "type 0" (4-planar). Images are stored in the GIF file in a 4-planar format. For example, a 320x200 image appears to a conventional GIF display program as if it is 80x800. The first image in the file is complete, but the others only contain part of the image. The program calculates the location of the first and last lines which are different between two graphic images. The segment between these two lines is stored in GIF format. This file can then be read by ANIM to produce animation. The differences stored in the GIF file are designed to use two frame buffers, so they correspond to the following: GIF Image 1 contains the entire first frame (320x200) 2 contains the difference between image 1 & frame 2 3 1 3 4 2 4 5 3 5 6 4 6 etc. Command line format: ANIMGIF INPUT_FILE OUTPUT_FILE where INPUT_FILE is the name (without any extension) of the sequence of input files to be loaded into the GIF OUTPUT_FILE is the name (without extension) of the GIF file to be created. ANIM: This program produces animation on a 320*200 screen using page flipping. The command line parameter is the name (without extension) of the GIF file (produced by ANIMGIF above) containing the sequence of images. Command line format: ANIM INPUT_FILE [-B[D/G/N] [-T[1/0]] Note that ANIM *must* be run on a PC with a VGA card. It expands the GIF contents to memory, using all available memory (conventional memory first, then XMS, then EMS). Note that to use XMS a suitable driver such as HIMEM.SYS must be loaded first. Similarly, to use EMS a driver must first be loaded. INPUT_FILE specifies the name of the file to be displayed without any extension. ANIM opens the corresponding .GIF file to extract the images, and also reads the corresponding .ANM file to find the time and sound information. The -B(uffer) parameter controls what the program will do if it runs out of memory. -BD instructs it to continue to expand the GIF images to a file called ANIM.TMP. The resulting animation will be very slow, though, unless you have a very fast hard disk with a large cache. -BG instructs it to expand the remaining images "on-the-fly" from the original GIF file. This is even slower than using -BD, and only useful on a very fast machine. -BN instructs the program to stop expanding images. The -T(ext) parameter controls whether the program displays the images as it decompresses them. -T0 (the default) instructs it to display images. -T1 instructs it to display text information, such as the destination of each image, on the screen while decompressing images. While images are being decompressed, pressing the ESC key aborts the decompression phase and moves immediately to the display phase. When all the images have been read (or if you decide not to use a disk buffer, or press ESC), it will display the animation on the screen. Pressing any key will stop the program and return to DOS. 9) Compiling the Code ~~~~~~~~~~~~~~~~~~~~~ 1) Create a subdirectory for each ZIP file contained in this archive (QUANT, ANIM, VGA, GIFLIB), and unZIP each of the ZIP files to its directory. UnZIP the INCLUDE.ZIP to your include directory. 2) Move to the VGA directory, and edit MAKEFILE to use your compiler and library manager. Then use your make utility to create VGA.LIB in your LIB directory. 3) Move to the GIFLIB directory, and edit MAKEFILE to use your compiler and library manager. Then use your make utility to create GIFLIB.LIB in your LIB directory. 4) Move to the QUANT directory, and edit the makefiles OCTREE.MAK, HECKBERT.MAK, and DISPLAY.MAK as above, and again make the various programs. Alternatively, in Turbo C use the IDE with the appropriate project files. To compile the Heckbert version using Turbo C's IDE, you need to define the symbol HECKBERT in the Compiler/Defines menu. Note that OCTREE and HECKBERT have some filenames in common which are not compatible from one version to another. After successfully compiling and linking one version, you should delete all the object files produced by that before compiling and linking the other version. 5) Move to the ANIM directory, and edit the makefiles MAKEANIM.MAK, ANIMGIF.MAK, and ANIM.MAK as above, and again make the various programs. Alternatively, in Turbo C use the IDE with the appropriate project files. ANIM also requires the XMSLIB.H and EMSLIB.H files, as well as XMSLIBC.OBJ and EMSLIBC.OBJ. These all relate to the XMSLIB and EMSLIB packages written by James W Birdsall. I used XMSLIB v1.21 and EMSLIB v2.15. The licence conditions for these does not allow them to be distributed. They are available from various sources, including the SIMTEL archive. 10) Porting to Different Platforms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I've tried to make QUANT portable. So far, it's working out fairly well. All the programs (except ANIM -- it is specific to MS-DOS) compile cleanly and run properly (no warnings, no errors) using either Turbo-C v2.01 or SCO Unix. If you want to port QUANT to another system, please try to modify the core as little as possible. Similarly, if you implement a different quantisation algorithm, try to keep it as a separate module.