ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / GRAPHICS / MISC / PVQUAN15.ZIP / PVQUAN.DOC < prev next >

Wrap

Text File | 1992-04-06 | 29.1 KB | 696 lines

PVQUANT Version 1.50 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: frank@cit.ac.nz, frank@whare.cavebbs.gen.nz FidoNet: frank vanderhulst at GenBoard (Node 3:771/160) 03 April 1992 ─────────────────────────────────────────────────────────────────────────── These programs are freely distributable. The authors 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 these programs are the property of the user of the software and may be used for any purpose without restriction. The authors make no guarantees or warranties with these programs and claim no responsibility for any damage or loss of time caused by this program. Bug reports may be sent to the authors but the authors are 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) Archive 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) Archive Description ~~~~~~~~~~~~~~~~~~~~~~ This archive contains C source code for a set of programs to convert image files produced by DKB-Trace or Persistence of Vision raytracer into a format suitable for display on a VGA screen, or to GIF format. It includes programs to generate a single stereoscopic 3D image from two views of a scene, as well as programs to produce animation from multiple ray-traced images. The programs (or large parts of them) were written by several different people. All of the programs are in the public domain to some extent, with some restrictions put on them by their respective authors. I have collected these from various places, ported them to Turbo-C and GNU C if necessary, and formatted them in a way that I like. The copyright for each program still belongs to its author -- my copyright claim extends only to the collection of programs (like the editor of a journal, for example). QUANT (HECKBERT & OCTREE): 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. DISPLAY: Displays either 320x400 or 320x200 images, either 2D, or stereo 3D. 3D images require Sega 3D-glasses to be connected to the serial port for viewing. MAKEANIM: Reads an animation source file (*.ANM), and uses it to generate data files for the PoV ray tracer. ANIMGIF: Produces a .GIF file containing a series of images to be displayed by ANIM. ANIMFLI: Produces a .FLI file containing a series of images to be displayed by a .FLI player (e.g. Autodesk's AAPLAY). ANIM: Produces animation on a 320*200 screen using page flipping, including sound. Files contained in this archive: ------------------------------- QUANT.ZIP Quantiser source code PAC_BASE.DAT Sample PoVRay data file for generating animation SHAPES.DAT Required to produce sample animation image MAZE.IFF Required to produce sample animation image INCLUDE.ZIP To be unzipped to C include directory VGA.ZIP VGA 320x200x256x4 & 320x400x256x2 driver source code GIFLIB.ZIP GIF encoding/decoding ANIM.SH Unix shell script for generating animation TRACE.SH Unix shell script to run ANIM.SH as background task PACMAN.ANM Sample animation script ANIM.ZIP Animation source code QUANT.DOC Documentation README This file FLILIB.ZIP FLI creation routines 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. Now I have easier access to a Sun IPC workstation than the the '486 -- so I've ported the raytracer and other files to compile using the GNU C compiler gcc. The GIF display program needs lots of memory, and the files (even after GIF compression) are huge... the GIF standard isn't well suited to animation. So I took the FLILIB source from Simtel... that was designed to be compiled on the PC using TurboC (included was 8086 assembler source code to open and close files, amongst other things). I ported that to gcc, converting things back to C and fixing some annoying pointer addressing problems. Next is Floyd-Steinberg dithering, to remove unwanted "banding" of coloured regions (called false contours). Or maybe adding sound to a FLI player. 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 "Targa" format. I use the following command line: PVRAY -ipacman.dat -opacman.tga -w320 -h400 -v +ft +p +x -a See the raytracer documentation on what all the above mean. Most important is the "+ft" option which tells the raytracer to produce "Targa" files. The quantiser can also read "raw" format files (use the "+fr" switch). If you use this (there's no real reason why you should) and run 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. Command line format: HECKBERT [-C=colours][-W=width][-H=height][-D=display][-T=type] [-O=outputbits][-S=speed][-N=numfiles] file_name or OCTREE [-C=colours][-W=width][-H=height][-D=display][-T=type] [-O=outputbits][-N=numfiles] file_name If no parameters are given, a usage message is shown. Default value outputbits = bits per colour being output [6] intype = 0 or 1 to select input format [0] 0 selects raw files (.RED, .GRN, .BLU) 1 selects Targa (.TGA) 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 [0] 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. numfiles = number of files to convert [1] If numfiles = 1, QUANT calculates a palette for that file and writes it to disk with a .2D extension. If numfiles = 2, QUANT 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 numfiles > 2, 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_0.0, FILE_0.1, FILE_0.2, ... file_name the base part of the filename(s) of files to be converted -- a numeric part and an extension are added automatically. The numeric part consists of an underscore followed by a number, and the extension will depend on the input file type. (e.g. if the file_name is PAC and the input type is Targa, the first file read will be PAC_0.TGA. When the final result is to be a .FLI file, it may be better to generate the palette for each image separately, since .FLI players can use different palettes for each frame. 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 -n=2 -c=64 -d=0 will open the files PACMAN_0.RED, PACMAN_0.GRN, and PACMAN_0.BLU, then the files PACMAN_1.RED, PACMAN_1.GRN, and PACMAN_1.BLU, then create the file PACMAN.3D. This will be done using Heckbert's median-splitting algorithm. C:\>HECKBERT PACMAN -i=1 -t=1 will open the file PACMAN.TGA, and create the file PACMAN.2D. This will be done using Heckbert's median-splitting algorithm. C:\>HECKBERT TEST -n=4 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 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 FLI creation code comes from FLI.LIB (Dec 1989) by Jim Kent of Dancing Flame, San Francisco. Following is an excerpt from his README file: Fli.lib and the associated source and documentation files are Copyright 1990 Dancing Flame, San Francisco. Permission is granted to distribute fli.lib and to use fli.lib in any non-commercial program. If you would like to use fli.lib in a commercial program please contact Dancing Flame. The normal licensing fee is the retail price of 5 copies of the program you are selling. Dancing Flame 3312 16th St. San Francisco, CA 94114. (415) 861-6119 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 ~~~~~~~~~~~~ Four 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. 4) ANIMFLI converts multiple 2D files into a FLI file 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]] [/S[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 (the default) instructs the program to stop expanding images. The -T(ext) parameter controls whether the program displays the images as it decompresses them. -T0 instructs it to display images. -T1 (the default) instructs it to display text information, such as the destination of each image, on the screen while decompressing images. The -S(ound) parameter controls whether the program makes sounds as indicated in the .ANM file. -S0 instructs it to not make any sounds. -S1 (the default) instructs it to make sounds. 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 at the end of the sequence and return to DOS. ANIMFLI: This program produces a .FLI 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 1" (single plane) Image size must be 320x200. This file can then be read by any standard FLI player to produce animation. Note that this will not use some of the information in the file read by MAKEANIM -- all images are displayed for the same length of time, and no sound is produced. Command line format: ANIMFLI INPUT_FILE OUTPUT_FILE where INPUT_FILE is the name (without any extension) of the sequence of input files to be loaded into the FLI OUTPUT_FILE is the name (without extension) of the FLI file to be created. 9) Compiling the Code ~~~~~~~~~~~~~~~~~~~~~ 1) Create a subdirectory for each ZIP file contained in this archive (QUANT, ANIM, VGA, GIFLIB, FLILIB), 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 FLILIB directory, and edit MAKEFILE to use your compiler and library manager. Then use your make utility to create FLILIB.LIB in your LIB directory. 5) 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. 6) 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 and DISPLAY -- they are specific to MS-DOS) compile cleanly and run properly (no warnings, no errors) using either Turbo-C v2.01, GNU C, 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.