3 Installation

3.1 System requirements

map3d is written in standard C/C++ and uses the OpenGL and GTK+ libraries, both choices made to ensure broad portability of the program. This first OpenGL+GTK version of map3d targets three platforms and we list the requirements and recommendations for each below. Additional platforms will follow--and follow even faster if you send us a machine to play on.

All platforms:

Requirements for all systems
OpenGL libraries (GL and GLU)	version 1.1 + 1
OpenGL/window interface library (GLX)
GTK+ libraries and dependencies	version 2.0+

SGI:

map3d runs on virtually any SGI that will support Irix version 6.5+. We have tested it on Indigo2, O2, Octane, and Origin workstations running various flavors of Irix 6.5. If you need a version for a different SGI configuration, please let us know (map3d@sci.utah.edu)

Requirements
Operating System	Irix 6.5+
Architecture	mips3 or mips4 (maybe mips2)
Applications Binary Interface	n32 or 64
Recommendations
Hardware	Texture mapping hardware
	128 MB main memory

Linux (i386):

map3d requires the OpenGL library, which is available as the mesa library at www.mesa3d.org for any Linux platform. For better performance, graphics cards from companies such as nVidia (www.nvidia.com) usually provide OpenGL libraries.

Requirements
Operating System	kernel 2.2.x
Architecture	i386 (+ maybe PPC)
Applications Binary Interface	libc2.1
Recommendations
Window system	XFree86 version 4.0 +
Hardware	3D graphics card (nVidia, 3dfx, ati)
	128 MB main memory

Windows:

Requirements
Operating System	W2K/NT4.0/9x
Architecture	i386
Applications Binary Interface	win32
Recommendations
Hardware	3D graphics card (nVidia, 3dfx, ati)
	128 MB main memory

3.2 General Installation

Unfortunately, as this is the first version of map3d with GTK+, it is not as easy as other versions where you could just download and run. We hope to be able to do that again in the future, but for now we will attempt to make it as easy as possible for you. Simplified instructions will be in a README file which comes with each package, and are also listed below:

To download the software, use this URL www.sci.utah.edu/software/map3d.html, and click on the ``Download'' button. You'll need to sign into the SCI archive. For each of the installation instructions below, you can grab those file from this page.

To test the installation, use the test files that accompany this distribution. Each has some script files included that show how to call and execute map3d.

3.3 SGI Installation Instructions

The SGI installation is relatively straightforward. You'll need to download map3d's dependencies, then download map3d itself.

3.3.1 SGI Dependencies

There are two phases to this part. First we need to get GTK+ and its dependencies. The easiest way to do this is for SGI is to run a browser with root access and go to SGI's freeware site at http://freeware.sgi.com. On that page near the bottom there should be a link to a prereq calculator. Click on that link, and in the Freeware Product box, select fw_gtk2+ (make sure you don't select fw_gtk+). Submit the query. You should see a list similar to this:

  fw_atk [relnotes] [prereqs] [install] 
  fw_expat [relnotes] [prereqs] [install] 
  fw_freetype2 [relnotes] [prereqs] [install] 
  fw_gettext [relnotes] [prereqs] [install] 
  fw_glib2 [relnotes] [prereqs] [install] 
  fw_libjpeg [relnotes] [prereqs] [install]
  fw_libpng [relnotes] [prereqs] [install]
  fw_libz [relnotes] [prereqs] [install]
  fw_pango [relnotes] [prereqs] [install]
  fw_tiff [relnotes] [prereqs] [install]

To install them, click on the install link one by one (and follow the instructions in the dialog boxes).

IMPORTANT - when you install libz - it will mention something about a security library being removed. When you install libz, allow it to do this. On the subsequent libraries, it will mention that the security package conflicts with libz, on these packages, have it continue without installing the security package.

Install them in the order:

    gettext
    expat
    freetype2
    atk
    glib2
    pango
    libjpeg
    libtiff
    libz
    libpng

After you've done all of these, click on the alphabetical link, and click on the install buton that corresponds to libgtk2+-2.0.6.

If for some reason, the prereq calculator isn't there or isn't working, go to the alphabetical index and install the above in the order specified.

The next part is to download gtkglext, the library that supports OpenGL for GTK widgets. If your GTK version is 2.0.6 (you can find out by looking at gtkversion.h which will be where you installed gtk (normally /usr/freeware/include/gtk-2.0/gtk/gtkversion.h), and look for GTK_MAJOR_VERSION, GTK_MINOR_VERSION, and GTK_MICRO_VERSION. There will be numbers on the same lines as each of these, and if you put them together it will be something like 2.0.6). If you are using this version download gtkglext-sgi.tar.gz from the map3d download page http://www.sci.utah.edu/software/map3d.html and follow these instructions:

    cd <download directory>
    gunzip gtkglext-sgi.tar.gz
    tar xf gtkglext-sgi.tar
    cp libgtkglext-x11-1.0.so.0 /usr/local/lib
    cp libgdkglext-x11-1.0.so.0 /usr/local/lib

You can copy them to some directory other than /usr/local/lib if you wish.

If this doesn't work, you will need to download the gtkglext source and compile it yourself (don't worry--if your gtk is properly set up, this will be very easy). Download the sources from Source Forge http://sourceforge.net/projects/gtkglext and follow these instructions:

    cd <download directory>
    gunzip gtkglext-1.0.6.tar.gz
    tar xf gtkglext-1.0.6.tar
    cd gtkglext-1.0.6
    configure
    make
    make install

If you don't want these to end up in /usr/local/lib, you need to

configure --prefix=<dir>

where dir is where you want to put the libraries (The libraries will be in dir/lib).

3.3.2 SGI Executable

Download the map3d-6.0-irix.tar.gz file from the map3d download page and unzip it to a directory of your choice. We will call that RUN-DIR. This is the directory from which you will run map3d.

To run map3d, you will need to make sure that all the libraries are in your LD_LIBRARY_PATH environment variable. For this we will assume that your gtk libraries are in /usr/freeware/lib32 and your gtkglext libraries are in /usr/local/lib. Do the following:

    tcsh users:
    setenv LD_LIBRARY_PATH /usr/freeware/lib32:/usr/local/lib:$LD_LIBRARY_PATH

or bash users:

    export LD_LIBRARY_PATH=/usr/freeware/lib32:/usr/local/lib:$LD_LIBRARY_PATH

you might want to put this line in your .cshrc or .profile file to avoid having to run this multiple times.

3.4 Linux Installation Instructions

The Linux installation is relatively straightforward. You'll need to download map3d's dependencies, then download map3d itself.

3.4.1 Linux Dependencies

There are two phases to this part. First we need to get GTK+ and its dependencies. The easiest way to do this is from your distribution's installation CDs, or you can download the RPMs at www.rpmfind.net.

To get the dependencies from your distribution, run the Package Manager (Add/Remove Applications, configure-packages or something of that sort). Search for gtk, and install gtk2 (if you can't find that directly, then installing the gnome environment will take care of it).

To get the dependencies from the internet, navigate your favorite browser to www.rpmfind.net, and search for gtk-2.0. Try to find one that matches your distribution (redhat, mandrake, etc.). We directly support development for gtk2-2.2.1 and gtk2-2.0.6, so if you can find one of these that would be encouraged.

The next part is to download gtkglext, the library that supports OpenGL for GTK widgets. As of this release, this is not standard in most distributions. If your GTK version is 2.0.6 or 2.2.1 (you can find out by looking at gtkversion.h which will be where you installed gtk (normally /usr/include/gtk-2.0/gtk/gtkversion.h), and look for GTK_MAJOR_VERSION, GTK_MINOR_VERSION, and GTK_MICRO_VERSION. There will be numbers on the same lines as each of these, and if you put them together it will be something like 2.2.1). If you are using one of these versions download gtkglext-linux-2.2.1.tar.gz or gtkglext-linux-2.0.6 from the map3d download page and follow these instructions:

    cd <download directory>
    gunzip gtkglext-linux-<version>.tar.gz
    tar xf gtkglext-linux-<version>.tar
    cp libgtkglext-x11-1.0.so.0 /usr/local/lib
    cp libgdkglext-x11-1.0.so.0 /usr/local/lib

You can copy them to some directory other than /usr/local/lib if you wish.

If this doesn't work, you will need to download the gtkglext source and compile it yourself (don't worry--if your gtk is properly set up, this will be very easy). Download the sources from Source Forge http://sourceforge.net/projects/gtkglext and follow these instructions:

    cd <download directory>
    gunzip gtkglext-1.0.6.tar.gz
    tar xf gtkglext-1.0.6.tar
    cd gtkglext-1.0.6
    configure
    make
    make install

If you don't want these to end up in /usr/local/lib, you need to

    configure --prefix=<dir>

where dir is where to put the libraries.

3.4.2 Linux Executable

Download the map3d-6.0-linux.tar.gz file from the map3d() download page and unzip it to a directory of your choice. We will call that RUN-DIR. This is the directory from which you will run map3d.

To run map3d, you will need to make sure that all the libraries are in your LD_LIBRARY_PATH environment variable. For this we will assume that your gtk libraries are in /usr/lib and your gtkglext libraries are in /usr/local/lib. Do the following: tcsh users:

   setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH

or
bash users:

 
    export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

you might want to put this line in your .cshrc or .profile file to avoid having to run this multiple times.

3.5 Windows Installation Instructions

The Windows installation is relatively straightforward. You'll need to download map3d's dependencies, then download map3d itself.

3.5.1 Windows Dependencies

Download the map3d-win-environment.zip file from the map3d download page and unzip it into a location of your choice - we will call that INSTALL-DIR. It will create a directory called INSTALL-DIR\map3d.

Add INSTALL-DIR\map3d\lib to your path. To do this, open the Control Panel, select System, and click on the `Advanced' tab on the top of the screen. Click on the Environment Variables button. You should see a variable called Path or PATH in the System Variables section. Click on it, and select Edit. Go to the end of the line, add a semi-colon (;) and type INSTALL-DIR\map3d\lib.

3.5.2 Windows Executable

There is an executable of map3d in the environment directory. We have also placed an executable here to facilitate future downloads, so you only have to download the environment once. If you wish, download the map3d-6.0-windows.zip file from the map3d download page and unzip it to a directory of your choice. We will call that RUN-DIR. This is the directory from which you will run map3d.

3.6 Documentation

This document should have reached you either as a pdf file or via the map3d web site. If you would like more copies or the latest version, go to the same web site and look for the links under Documentation:

www.sci.utah.edu/software/map3d.html

3.7 Bug reporting

We want to hear your response to using map3d and especially to learn about any bugs you may find. They may be features, rather than bugs, but if so, we will be happy to hear your impressions.

To submit a bug report please send email to map3d@sci.utah.edu or point your browser at software.sci.utah.edu/bugzilla (you will need to register your e-mail address) with the following information:

1. Type and version of the operating system and hardware you are using.
2. Version of map3d.
3. Description of the bug/feature you encountered.
4. Suggestions for fixing the bug or altering the program behavior.

3.8 How to reach us

We have established an email address for map3d, map3d@sci.utah.edu, and web pages within the website www.sci.utah.edu/ncrr dedicated to map3d. There is also a majordomo mailing list for map3d users called map3d-users@sci.utah.edu. To subscribe to this list, send email to majordomo@sci.utah.edu with the following in the message body

      subscribe map3d-users

Please let us know how you use map3d and how we can make it better for your purposes. We can only develop this program with continued support and the best way to achieve this is to show that others use the program and find it helpful.