Page still in process of being written.. still..

Installing from Binary :

At this time (Dec 2010), there isn't an up to date binary available, but as soon as there is, it will be available for download from here.

Building from Source :

Present3D is now part of the OpenSceneGraph source so a download of the code from the SVN repository will get the most up to date code, but before you do that you need to make sure you already have the following :

1)  Developer Tools :

If installed you will have a folder called Developer which has Xcode 3.x.x application, if not then you can either install from your system disk or download from the Apple site.

2) Cmake :

The OSG currently uses Cmake to generate either make  files or an Xcode project depending on your preference.

Cmake can be downloaded from here : http://www.cmake.org/cmake/resources/software.html

You want the Mac OSX Unversal .dmg

Current version is 2.8.3

Download and install as normal.

Now you are ready to download the OSG.

3) OpenSceneGraph:

To download the osg open a shell (Terminal window)  navigate to your User home directory by typing

cd ~

then return key

and then cut and paste in the following and press return:

svn checkout http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk OpenSceneGraph

Once that has finished downloading you should now have a folder in your User/your user name directory called OpenSceneGraph, which has all of the downloaded files.

Now you need to download the OSG data files into the same home directory ( not the OpenSceneGraph, but the same one where that is installed) by cutting and pasting in the following to your shell and pressing return.

svn checkout http://www.openscenegraph.org/svn/osg/OpenSceneGraph-Data/trunk OpenSceneGraph-Data

At this point, you could start the build process, but you will be missing a few extra libraries that we will want to use to enable volume rendering and vnc window support, so lets go ahead and get those, if you don't need volume rendering or VNC window support you can skip this part and go to item 7 below.

4) Insight ToolKit :

You can download ITK from here : http://www.itk.org/ITK/resources/software.html

Download the 3.14 release. There seems to be a problem with the most recent version 3.20 building and 3.14 is the last known version to work, I will try the other more recent versions and update this if more recent ones build.

Once it has downloaded you will want to move the folder to the same User home directory as for the OSG and then open the Cmake application that was installed in your applications folder at 2 above.

Now you need to set up Cmake to find the source you want it to use and where you want it to put the make files it creates. So, for both use the browse button to find and select the InsightToolkit folder you just moved or , once you have the location in the top box  you can copy and paste into the box below.

Now you are ready to let Cmake do its work, so hit the Configure button, wait till it's finished, if the main window shows red then you may need to make some configuration adjustments, but you can just hit configure again and when that is finished hit the Generate button and again wait till it's finished. You now have generated a make file that will allow you to install the Insight Toolkit.... so now you need to do that...

Go back to your shell and navigate into the InsightToollkit folder/directory by typing (changing the folder name to match yours)

cd ~/Insight_folder_name

Now we need to make and install by typing the following commands  followed by return key :

make

Once that has finished

sudo make install

you will be asked for an admin password enter that and again press return.

Once that has finished you will have installed the Insight Toolkit. If there is a build error then you may need to go back to Cmake and make a configuration change the error should give a hint to what that might be... and then go back through the process again.

5) DCMTK

Download and install : DCMTK.dmg

This has been created with  MacPorts port dmg filename command and will be placed in the usual location for all MacPorts files : /opt/local/

6) LibVNC

Don't do this unless VNC window is needed,  as edits to other files are required to avoid build problems. See Temp Fix below.

Download and install : LibVNCServer.dmg

Temp Fix :

Use BBedit (or your normal editor ) to edit the following files:

In OpenScenGraph/src/osgplugins/vnc edit the file ReaderWriterVNC.cpp on line 22 with a new path to rfb directory /opt/local/include/rfb/rfbclient.h  and then save,

then in the directory  /opt/local/include/rfb/

open rfbclient.h and edit paths to the following files :

rfbproto.h to : /opt/local/include/rfb/rfbproto.h 

keysym.h to : /opt/local/include/rfb/keysym.h 

and then save,

now open  rfbproto.h and edit the path to the following files :

rfbconfig.h to : /opt/local/include/rfb/rfbconfig.h

rfbint.h to : /opt/local/include/rfb/rfbint.h 

and then save,

This has been created with  MacPorts port dmg filename command and will be placed in the usual location for all MacPorts files : /opt/local/

7) OSG

Open the Cmake application that you installed earlier into you Applications folder.

Now you need to set up Cmake to find the source you want it to use and where you want it to put the make files it creates. So, for both use the browse button to find and select the OpenSceneGraph folder in your User home directory, or once you have the location in the top box  you can copy and paste into the box below.

Now you are ready to let Cmake do its work, so hit the Configure button, the main window will show red and there are some changes that you need to make ;

Build_OSG_Applications  :  box should be ticked

Build_PRESENT3D_WITH_SDL : box should be un-ticked

CMAKE_OSX_ARCHTIECTURES  : should say i386 only! Remove other options.

CMAKE_OSX_SYSROOT : should be : /Developer/SDKs/MacOSX10.6.sdk ( if you are building on 10.6 and 10.5.sdk if building on 10.5).

FREETYPE_INCLUDE_DIR_freetype2 : should have a path : /usr/local etc.. if not, see item 9 

FREETYPE_INCLUDE_DIR_ft2build : should have a path : /usr/local etc.. if not, see item 9 

FREETYPE_LIBRARY : should have a path : /usr/local etc.. if not, see item 9 

ITK_DIR : should be : /usr/local/lib/InsightToolkit

OSG_DEFAULT_IMAGE_PLUGIN_FOR_OSX :  must be changed to  : imageio

OSG_GL3_AVAILABLE : should be  : un-ticked

OSG_WINDOWING_SYSTEM : should be changed to : Cocoa

now hit Configure button again...

..wait till it's finished and then hit the Generate button and again wait till it's finished. You now have generated a make file that will allow you to install the OSG,  so now you need to do that...

Go back to your shell and navigate into the OSG  folder/directory by typing (changing the folder name to match yours)

cd ~/OpenSceneGraph

and then type 

make

and press return.... and then wait...

...and once that is finished, assuming you had no errors, you have finished building the OSG and Present3D. 

Handy Hint :  You can speed up the make process by giving permission to use more than one core by adding -j x where x is the number of cores. So in my case, with 8 cores, that would be : make -j8

Another Handy Hint : Should you get an error and it is obvious that it is from a non essential library, then you can continue the build by adding  -i which will ignore the error, so that would now make the command :

: make -j8 -i

But beware, as this will not only ignore the first error that stopped the build, but also any subsequent errors, should there be any.... however, at least you will know the full extent of your problem.

Before you can jump in and start using Present3D, you will need to set up your shell environment and we cover that in the next section...

8) .tcshrc file

By default Terminal opens a Bash shell, but out of long use and sheer habit I use Tcsh, so this section is going to assume that you are happy to make the change to the tcsh shell and that if you are a seasoned bash user, that you will know how to adapt what follows to suit the bash environment.

So, if not already open, open the Terminal application, now open it's preferences (Terminal/Preferences) and in the Startup section, where is says : Shells open with: select the second option : command (complete path): and edit the box below so that it says :

/bin/tcsh

and that's it, open a new shell and it should now say tcsh on the window header... you can close the preferences. 

Now, there are various paths and environmental variables that we want to have set automatically when we open the shell, and for this we create a .tcshrc file. The dot in front of the name means that this is a hidden file and once saved you will only be able to see it with an editor that will allow you to see such files... you could use Dashcode that comes with the Xcode tools, but my preference is BBedit from Bare Bones Software and a free 30 day trial can be downloaded from here : http://www.barebones.com/products/bbedit/  but TextWrangler, also from Bare Bones is cheaper I believe and so may be worth considering.

Now we need to create or add to your .tcshrc file. 

9) MacPorts

When you look through the OSG Cmake window you will see references to a number of other libs that may or may not be useful. Ones to avoid at this time are FFmpeg and Xine as these tend to cause build problems and aren't required if the CoreVideo  plugin is installed, which it is by default.

One that you should already have is  Freetype2 but if the lines :

FREETYPE_INCLUDE_DIR_freetype2

FREETYPE_INCLUDE_DIR_ft2build

FREETYPE_LIBRARY

have -NOTFOUND against them, then you could use MacPorts to download and install this lib. (or download the ,dmg file from here : FreeType2 )

MacPorts can be downloaded from here : http://www.macports.org/install.php

Once installed you can use the command line in terminal to do the download and install process, however, I find it handy to have a GUI for this, and so I use the free Porticus application that can be downloaded from here : http://porticus.alittledrop.com/download.html

Once downloaded and installed you should open the Porticus app and do a SelfUpdate which is found on the main menu under Ports. You will probably be asked for you password during this process. 

You should now be able see that the All Ports folder in the sidebar of the Porticus window is listing over 7,400 ports available. Select that folder and then in the search bar enter the name or part of the name of the library that you want to install, in this case you should type freetype and then select the freetype 2.4.3 or later option that is listed, then hit the install button on the window menu bar... you will then be given some options, tick the universal box and then install.

If you do add libraries you will then need to go back to the Cmake and configure once again, make sure that the library that you have added now has a path against it along the lines of /opt/local/xxxx instead of the -NOTFOUND that was there previously. If it hasn't updated you can tell Cmake to start from scratch again by throwing away its cache (Menu bar /File/Delete Cache) but you will then need to make all the changes that we did in section 7 once again. 

10) Colour Lookup Tables (CLUT)

Without a colour lookup table CT and MRI data will be displayed in greyscale. At this point, CLUT are little more than a text file that you can edit by hand to control colour and alpha values for particular densities of the original data. However, with the next round of funding it is intended to create an interactive GUI driven application that will allow you to visually define the colour, contrast, exposure and crop the data before saving for use in Present3D.

A folder with some sample CLUT can be downloaded here and a copy saved either in the same location as your .xml "show" file or in a single standard location like the osgconfigs folder, remember to include the full path to the CLUT file in the xml file.

Download : Sample CLUT File

11) Sample Shows (shows still to be added/uploaded)

For information on how to run Present3D shows and what keys can be used go : here.

Download : Sample_Show  folder : This  includes two shows: setup.xml includes some grids for projector alignment with passive stereo systems, polariser adjustment screen and a skull dataset that should help confirm that the "eyes" are the correct way round. The second show, sample.xml includes some pointcloud datasets captured by a laser scanner, some stereo movies and an example of a movie applied to a sphere. Once the folder has been downloaded and unziped, open a terminal window and "cd" into the folder, then type :

present3D setup.xml

or

present3D sample.xml

You can move through the show by using either the "n" key or left and right arrow keys. You can rotate, pan and zoom,  either by using a 3 button mouse or by holding down the mouse button, or mouse button plus "alt" or mouse button plus "ctrl" keys.

Download : Sample Volume Show : This show includes a CT scan which is being rendered using the different methods possible, this can be changed interactively by pressing the "v" key. Transparency can be controlled by holding down the "t" key and moving the cursor up and down the screen. Data can be removed by density by holding down the "a" key and moving the cursor up and down the screen.

Once the folder has been downloaded, open a terminal window and "cd" into the folder, then type :

present3D volume.xml

You can use this same command to open any Present3D show just replacing volume.xml with the actual name of the .xml file that you want to open.

A good source for test volume datasets can be found here : CTDATA

at this point only use those that have the Modality listed as CT. We are working on solving the problem with the other modalities and will update this when it is fixed.

For information on how to build a Present3D show go : here