| Installing Pixie

This tutorial shows what you need to do to render images with Pixie.

Pixie is a photorealistic renderer which communicates with modelers or your application through a RenderMan - like interface. Pixie is not a modeler or an animation system. So it does not have any graphical user interface.

The scenes you want to render are described in a text file in a language very similar to Pixar's RenderMan. Pixie also comes as a C/C++ library which you can link against your application. In order to find the details of this interface, you should read RenderMan Companion or RenderMan interface on http://www.pixar.com.

Pixie comes in following forms:

- Source code for Windows (Pixie-src-X.Y.Z.zip)

- Source code for Unix (Pixie-src-X.Y.Z.tgz)

- Windows Installer (Pixie-X.Y.Z-Setup.exe)
  - Follow the installation instructions. The installer will create a PIXIEHOME for you

- Windows binaries (Pixie-win-X.Y.Z.zip)
  - The zip file contains a Pixie directory which will be your PIXIEHOME

- Linux binaries (Pixie-linux-X.Y.Z.tgz)
  - The tgz file contains a Pixie directory which will be your PIXIEHOME

To compile Pixie, you will need:

- flex / bison

- libtiff (www.libtiff.org)

- fltk (http://www.fltk.org) - Optional, only needed if you want to build "show"

Below are compilation instructions for various platforms:

Compilation / Installation for WINDOWS:

You can download the Pixie source code as a zip file. To compile Pixie, you need Microsoft Visual Studio 6.0 or Microsoft Visual Studio .NET.

- Open Pixie.dsw / Pixie.sln (in Pixie/windows/vcXXX)

- Hit - Build - Batch Build

- Select the components you want to build

- Hit Build All

- Execute makeinst.bat after the compilation ends

At this point you should have a Pixie directory which contains the binary distribution.

You can also use the Windows installer which directly installs binary distribution.

Compilation / Installation for UNIX

You can download the Pixie source code as a tgz file. Do not download the zipped source code as the file permissions will be wrong.

- execute ./configure --prefix=/usr/local/Pixie --enable-selfcontained

- execute make

- execute make install

At this point you should have a /usr/local/Pixie directory which contains the binary distribution. You can substitute /usr/local/Pixie with whatever location you want Pixie in.

You can set CXXFLAGS to whatever compilation flags you want to have during the compilation.

Binary Installation for MAC OSX (by George Harker)

Currently Pixie is compiled against libtiff from fink. Under OSX 10.2 or earlier, it will also require you to use fink's dlcompat and dlcompat-shlibs libraries.

Please install fink ( http://fink.sourceforge.net ) to get a hold of the required libraries. I can recommend fink commander ( http://finkcommander.sourceforge.net ) to help ease installation of fink projects, but you'll still need to install fink. Follow the instructions over at fink for how to set it up.

Install libtiff from fink. Also, especially for 10.2 or earlier, ensure you install up to date dlcompat and dlcompat-shlib packages.

Get the binary distribution of Pixie and unpack it at `/Applications/Graphics`. There should be now a folder in `/Applications/Graphics` called `Pixie`. You may have issues unpacking with some of the gui apps. Ensure you've got the latest stuffit, or use the command line:

    (Assuming package is on your desktop)
    cd /Applications/Graphics/
    gunzip ~/Desktop/Pixie-osx-1.3.xx.tgz
    tar -xvf ~/Desktop/Pixie-osx-1.3.xx.tar

Now, for the last part, which is required for 10.2 ONLY. DO NOT PERFORM THE NEXT STEP ON PANTHER (10.3)

Pixie requires dlcompat. When installed via fink, these are in `/sw/lib/libdl.0.dylib`. Pixie binaries are compiled against Panther which had `/usr/lib/libdl.dylib`. The solution is to create a symbolic link from where the library is expected to be, to where it is. One final warning. Don't do this on Panther - you've been warned.

    sudo ln -s /sw/lib/libdl.0.dylib /usr/lib/libdl.dylib

If you don't want to do this, or can't, there's a work around, which is to set for tcsh

    setenv DYLD_INSERT_LIBARARIES /sw/lib/libdl.0.dylib

for bash

    export DYLD_INSERT_LIBARARIES=/sw/lib/libdl.0.dylib

before running pixie.

For all OSX versions:. You should be ready to roll with renders now. Remember to set up the environment variable `PIXIEHOME`:

for tcsh

    setenv PIXIEHOME /Applications/Graphics/Pixie

for bash

    export PIXIEHOME=/Applications/Graphics/Pixie

Finally, you'll probably want to put pixie binaries in your path, which you do with

for tcsh

    set path=($path /Applications/Graphics/Pixie/bin)

for bash

    export PATH=$PATH:/Applications/Graphics/Pixie/bin

That's about it. I've put these commands in my login files. There are quite a few different oppinions/preferences on how to do this. InstallingOnOSX/EnvironmentSetup shows how I do mine, for tcsh - bash will be different.

Common instructions for using Pixie

You should set PIXIEHOME environment variable to the location of your binary distribution. You can also specify search paths for various external resources that Pixie may need using:

Option "searchpath" "..." "..."

On UNIX systems, you also need to add the lib directory in your binary distribution into your LD_LIBRARY_PATH, so that the shared objects will be loaded.

Your binary distribution should have the following structure:

Pixie/
bin/ | The executables are here.
| rndr | The RIB renderer.
| sdrc | Shading language compiler
| sdrinfo | Get information about a compiled shader
| texmake | Texture preparation tool.
| show | A viewer for photon maps/irradiance caches etc..
include/ | The header files
lib/ | The library files.
tutorials/ | The Pixie tutorials/examples
doc/ | Documentation for Pixie