The README file for BTGA2POV - July 5 2005 ___________________________________________ ------------------------------------------- btga2pov Software to create PovRay Include files from TGA Copyright (C) 2005 Ben Teschendorff This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Contact the author: email - pov@eyedropvideo.com ******************************************************************************* 1) General Info 2) Usage 3) Compiling 4) Installing 5) Dependencies 6) ToDo 7) Change Log ************ General Info ************* btga2pov-0.2 With this command line utility you'll be able to create PovRay Include files from 8, 24 or 32 bit uncompressed Targa (TGA) files. This executable maps the value of each pixel's color from the TGA file onto PovRay primitives. These are output in a grid emulating the original image's layout and aspect ratio along the XY axis and centered at <0,0,0>. There is a choice of 6 different kinds of primitives (sphere, disc, cone, box, cylinder x-axis, cylinder y-axis) and they can be called with an optional integer argument. The default primitive is a sphere. The TGA source file doesn't have to be very large and in fact things probably will look better if it isn't. If you compiled using 'make' then you should run 'make test' to get an idea of what a 120x60 pixel source TGA looks like mapped to spheres and output by PovRay at 800x400 pixels. If you look at the file 'btga2pov_test.pov' that came with the source code you'll see what's needed for a basic scene. There's also some information on a few 'finish' variables you can declare values for. ***** Usage ***** To create the PovRay Include file just call the executable and pass along the name (and path if needed) of the TGA file like this ... btga2pov mypix.tga ... and an include file with the same name will be created (eg: mypix.inc). All you have to do after that is include this file into your PovRay scene file and adjust camera, lighting etc as needed. The default primitive shape (sphere) can be changed by using an optional integer argument as follows: 0 = sphere, 1 = disc, 2 = cone, 3 = box, 4 = cylinder x-axis, 5 = cylinder y-axis. Here's an example ... btga2pov mypix.tga 4 ... which would use the cylinder x-axis primitive. If you call btga2pov without any arguments you'll get a usage message and the executable will exit. ********* Compiling ********* I've only compiled this on Linux but I'll assume it will compile on just about anything that uses a standard C Library (see below - Other OpSys). If you use the supplied Makefile you'll need GNU Make (or compatible) plus gcc and the strip utility (these are standard Linux tools). The easiest thing to do is use the Makefile and run the command, make all This will compile and strip the binary. Then it would be a good idea to test things by running ... make test ... which will create a test include file from the supplied TGA and then call PovRay to render the image. This step isn't necessary but its a good idea to run if you've never used btga2pov before. If you have the permission run the ... make install ... command to install the binary. Or you can put it anywhere that's in your PATH. See below in the section Installing for more info. There is also a 'make uninstall' command should you wish to remove btga2pov from the default installation location. And you can use 'make clean' to remove btga2pov, plus any created test files, from the source directory. ------------------------------------------------- To compile from a command line ... gcc -Wall btga2pov.c -o btga2pov ... then strip with ... strip --strip-all btga2pov If you want to run the test then call btga2pov from the source directory using the supplied TGA as an argument. ./btga2pov testpix.tga This will create an include file called testpix.inc. To render this call povray passing along the supplied INI file as an argument. povray btga2pov_test.ini If everything is working right you'll get a 800x400 pixel image of a map of the Earth using sphere primitives. ------------------------------------------------- Other OpSys: When compiled for Linux this executable uses some date functions as defined in the Linux C Library include file. They're only used to write a creation date in the header of the PovRay Include file and aren't absolutely needed for successful operation. If they cause you grief when trying to compile then you'll have to either adjust for your C Library or take them out. I've added some comments to make things easier to find the related functions etc. ********** Installing ********** If you ran the 'make install' routine the following file(s) were installed, /usr/local/bin/btga2pov If you're doing it by hand just put the binary in ... /usr/local/bin/btga2pov ... or ... ~/bin/btga2pov ... or ... Anywhere in your PATH that you've got permission for ... and you're done! ************ Dependencies ************ C Library **** ToDo **** Create a man page. (is this really needed?) Build an X-window/GTK wrapper ********** Change Log ********** 0.2 - July 5 2005 Now can read 8, 24 or 32 bit files with row order either top or bottom. 0.1 - June 17 2005 Initial release. ******************************************************************************* email the author: pov@eyedropvideo.com