=== Tcl-SIPP 3.0c === Tcl-SIPP provides a 3D image specification and rendering toolkit for use with Tcl and Tk. It is based on SIPP, the SImple Polygon Processor, a library for creating 3-dimensional scenes and rendering them using a scan-line z-buffer algorithm. Tcl is an easy to use, powerful, interpretive programming language, that is designed to be imbeddable in applications. Tk is a X11 toolkit programmed in Tcl. Tcl-SIPP is a set of Tcl commands used to programmed SIPP without having to write and compile C code. Commands are used to specify surfaces, objects, scenes and rendering options. Scenes may be rendered to files in the PPM format or in Utah Raster Toolkit RLE format. Tk interactive applications may also be developed that do rendering to the Tk photo widget. This interface greatly speeds the development of scenes because no compile and link phase is required. Data is represented in a simple ASCII form. This is particularly useful when for producing 3D scenes from ASCII data generated by other programs. Since most of the work in creating a scene is still done in libsipp, the is only a small performance penalty in programming in Tcl. NEW FEATURES ============ The following new features have been added in this release. o Ported to Tcl7.3, TclX7.3a and Tk3.6. o Incorporated version 2.3 of the Tk photo widget. REQUIREMENTS ============ The following software packages are required to build and use Tcl-SIPP: o Tcl 7.3 - The Tcl command language fpt.cs.berkeley.edu:/pub/tcl/tcl7.3.tar.Z or ftp.neosoft.com:/pub/tcl/tcl7.3.tar.gz or ftp.uu.net:/languages/tcl/tcl7.3.tar.Z o TclX7.3 - Extended Tcl, an add on package for Tcl. (beta version) ftp.neosoft.com:/pub/tcl/beta/tclX7.3a-B5.tar.Z or harbor.ecn.purdue.edu:/pub/tcl/extensions/tclX7.3a-B5.tar.Z (final version, when released) ftp.neosoft.com:/pub/tcl/distrib/tclX7.3a.tar.Z or harbor.ecn.purdue.edu:/pub/tcl/extensions/tclX7.3a.tar.Z o Utah Raster Toolkit (optional) - This tool kit is great, check it out. cs.utah.edu:/pub/urt/urt-3.0.tar.Z cs.utah.edu:/pub/urt/urt-3.0.patch1 cs.utah.edu:/pub/urt/urt-3.0.patch2.Z or wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.tar.Z wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.patch1 wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.patch2.Z o Tk 3.0 (optional) - A Tcl-based X11 toolkit. sprite.berkeley.edu:/pub/tcl/tk3.6.tar.Z or ftp.uu.net:/languages/tcl/tk3.6.tar.Z The SIPP 3.0 sources required to build Tcl-SIPP are included in this distribution and compiled automatically. If you wish to get the entire SIPP distribution, it is available from: wuarchive.wustl.edu:/graphics/graphics/packages/sipp/sipp-3.0.tar.Z or isy.liu.se:/pub/sipp/sipp-3.0.tar.Z (note: this site is in Sweden) The Tk photo widget version 2,3 is included in this release. The full photo widget distribution is available from: harbor.ecn.purdue.edu:/pub/tcl/extensions/photo2.3.tar.Z The latest version of Tcl-SIPP should be available from: ftp.neosoft.com:/pub/tcl/distrib/tsipp*.tar.Z or harbor.ecn.purdue.edu:/pub/tcl/extensions/tsipp*.tar.Z VERSION NUMBERING ================= The Tcl-SIPP version number is a concatenation of the SIPP library version number that it works with and a single letter indicating the Tcl interface version. The version may also include a patch level if Tcl-SIPP has been patched. This is Tcl-SIPP 3.0c. DIRECTORY STRUCTURE =================== The following is the directory structure of the Tcl-SIPP code: tsipp3.0c src libsipp photo tclsrc man tests demos help master o src - The source directory containing the Tcl interface to SIPP. o libsipp - The complete SIPP 3.0 libsipp sources. A few modifications were made in libsipp for Tcl-SIPP. The entire libsipp sources are included for convenience. See libsipp/README for a description of the changes made for Tcl-SIPP support. o photo - Contains the amazing Tk photo widget by Paul Mackerras (paulus@cs.anu.edu.au). o tclsrc - Contains Tcl source that is built into an demand loadable .tlib. o man - Contains the Tcl-SIPP and photo widget manual pages. o tests - Contains basic tests that validate the individual commands. o demos - A port of the demo programs from SIPP. These also server to test Tcl-SIPP functionality not checked by the basic tests. o help - This directory contains help files that can read via the Extended Tcl help system. It is shipped pre-built, but maybe rebuilt from the manual pages. o master - This dirsctory is not in the distribution, it is constructed during the build process. All Tcl-SIPP runtime files are placed in this directory. o colorfocus.patch - Paul Mackerras' patch to add a command for managing colormaps to Tk. BUILDING ======== Tcl-SIPP is built on several pieces of software, so its somewhat tedious to build, however the configuration is straight forward with very few system dependencies. Follow these instructions carefully and all should go well. o Configure and build Tcl 7.3 according to the instructions. o If you are going to be using Tk to build interactive graphical applications: o Extract the Tk distribution, cd to the Tk directory and apply the colorfocus patch: cd tk3.6 patch <../tsipp3.0c/colorfocus.patch o Configure and build Tk 3.6 according to the instructions. o Configure and build the Extended Tcl (TclX) 7.3a distribution. If you already have a built TclX, you must recompile the tksrc directory to pick up changes introduced by the colorfocus patch. If your not using Tk, this is not necessary. Extended Tcl must be installed to run tsipp, or the TCL_LIBRARY and TK_LIBRARY environment variables must be set to point to the tclX7.3a/tclmaster and tclX7.3a/tkmaster directories. o Compile and build the Utah Raster Toolkit, it you wish to use RLE files and its not already built. o cd to the tsipp3.1c directory. o Edit "Config.mk" to set the compilation options and to point to the other packages required by Tcl-SIPP. Follow the instructions in Config.mk carefully. o Enter the command "make" to compile and link Tcl-SIPP. This should result in an interactive Tcl interpreter being created in top-level directory called "tsipp". This program is the Extended Tcl shell with the Tcl-SIPP commands built-in. A very minimal test is to run tsipp to see if you get an interactive prompt (tsipp>). Use the exit command or enter an EOF to exit tsipp. If specified in the Config.mk file, a Tk shell based on extended wish will be build called "tksipp". TESTING ======= A basic set of tests to validate Tcl-SIPP is run with the command: make test This will do some basic validation of the commands. If the RLE libraries are linked into Tcl-SIPP, then the URT program `rlehdr' should be in a directory in the PATH, or some tests will fail. DEMOS ===== The demonstration pictures are built by entering the command: make demo If you built Tcl-SIPP with the RLE library, the RLE format files will be built by default. IF RLE is not available, PPM format files will be build. The can be overridden in the Config.mk file. Other options controlling the creation of the demo images may be set in Config.mk. The programs to create these images are ports of the C programs provided with SIPP. They are good example on how to use Tcl-SIPP. If your generate RLE images, use the Utah Raster Toolkit program getx11 (or what ever get command is appropriate for your environment). to display them. If you have a 256 color display instead of full color, try the following: cat demos/*.rle | rlequant | getx11 A RLE comment is added to the image to specify a correct image gamma for these images. See Utah Raster Toolkit Documentation for more details. If you create PPM images, use your favorite view capable of handling them, or use the PBMPlus toolkit to convert them to a format that you can view. A simple tksipp demo application is included. Enter make tkdemo to run it. The demos are installed and may be run out of the installed master directory. The user must have write access to the directory they are run in. TSIPP HELP FILES ================ Extended Tcl help files for tsipp are included in the distribution. They were built from the manual pages. If you need to rebuild them for any reason, enter the command "make buildhelp". Note that this requires nroff to be installed on your system. INSTALLING ========== Tcl-SIPP uses a "master" directory installation model similar to the option available to TclX. See the TclX INSTALL document for more detailed information. The installed directories look like this: o ${prefix}/tsipp/3.0c - Runtime files. o ${prefix}/tsipp/3.0c/man - Manual pages. o ${prefix}/tsipp/3.0c/bin - Executable programs. o ${prefix}/tsipp/3.0c/lib - tsipp library. o ${prefix}/tsipp/3.0c/help - Help pages. o ${prefix}/tsipp/3.0c/demos - Demonstration programs. If you specify the architecture variable, the executables and library will be installed in: ${prefix}/tsipp/3.0c/bin${ARCH} ${prefix}/tsipp/3.0c/lib{ARCH} Symbolic links are built from the standard directories to the files in the master directory. ${prefix}/bin/tsipp -> ${prefix}/tsipp/3.0c/bin${ARCH}/tsipp ${prefix}/bin/tksipp -> ${prefix}/tsipp/3.0c/bin${ARCH}/tksipp Type "make install" to install tsipp. THE FUTURE ========== Potential future work on Tcl-SIPP may include the following. Any input on these or other changes is very welcome: o Switching to Tk style objects-as-commands. Objects, surfaces, shaders, handles would all become commands. Operations on them would then be dome by calling the command with an action. o Support for reading and writing TIFF files. The TIFF spec is rather huge, so any suggestions about the best approach would be helpful. Tcl-SIPP AUTHOR =============== Mark Diekhans - markd@grizzly.com Please send all bugs, questions or comments to this address. AUTHORS OF OTHER SOFTWARE IN THIS DISTRIBUTION ============================================== The SIPP 3D rendering package was developed by: Jonas Yngvesson - jonas-y@isy.liu.se Inge Wallin - ingwa@isy.liu.se of Linkoping Institute of Technology, Sweden The photo widget was developed by: Paul Mackerras (paulus@cs.anu.edu.au) of The Australian National University. Thanks for the great software!!!