Getting Started

 

So, the first thing is to get Present3D installed on your computer.

This isn't difficult, but currently not as easy as installing a normal application, however, that will change for OSX users very shortly, as a new Present3D app will soon be available for download and soon after that, we will be adding a Windows app also.

But until then, OSX 10.8.x users can follow the instructions below, to get and build Present3D from source. For earlier versions of OSX, the instructions at the Digital Learning Foundation could be appropriate.

 

Preparation

Before you download P3D you should make sure you already have the following :

 

Xcode Developer Tools :

If you don't have Xcode it can be downloaded from the Apple Appstore.

Once Xcode is downloaded and installed as normal, open its Preferences which can be found on the Menu bar under Xcode. Then go to the Downloads tab and install the Command Line Tools.

Please note, that if you update Xcode you might need to download and install the Command Line Tools again, you can see in the Preferences/Downloads window the current state.

image of Xcode preferences download window

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 current .dmg version for your version of  Mac OSX.

Download and install as normal.

When you open Cmake for the first time it will ask what type of make files you want to use, choose the native Unix option.

If you want to clear everything and start from scratch again go to the menu bar File/Delete cache and this will clear all your previous changes and you can start again.

 

The OSX Terminal Application:

The Terminal application can be found in the Utilities folder, within the Applications folder, on your Mac.

 

A Text Editor :

I currently use both BBEdit and TextWrangler, both are by the same developer, but TextWrangler is free and does everything you will need to create and edit P3D files.

You can find TextWrangler on the Apple Appstore, or can download direct from the developer : TextWrangler Download Page

 

Optional - MacPorts :

MacPorts is only required if you are intending installing the additional Volume Rendering and VNC features, or are missing some essential libraries from your system, like FreeType.

MacPorts can be dowloaded from here : MacPorts Download Page

Follow the instructions and dowload and install as usual.

Unfortunately, I have found both of the supporting GUI apps for MacPorts, Pallet and PortAuthority, to have problems with OSX 10.8, so you might need to use the OSX Terminal app mentioned above, but you can always give them try :

Pallet is free and information can be found here : Pallet MacPorts Page 

PortAuthority is a paid app : PortAuthority Download Page

Or, you can just use the Terminal, which in some ways is easier, so we will go through that method and if one of GUI options works for you, that's great, just follow the instructions for that program.

The instructions for using MacPorts can be found here : MacPorts Guide, but I will give a quick run through of what should be required for you to install the additional libs that have MacPorts distributions.

Once MacPorts is installed open OSX Terminal and type

sudo port -d selfupdate

and press return, you will then be asked for your OSX password, enter it and press return again,

This will update MacPorts to have the latest versions of the Ports, it might take a little while. If it fails first time, try just running the same command again.

To find a port, for instance DCMTK, you would type :

port search dcmtk

 

But that's enough MacPorts for now, we will go through the install process where it is required.

 

 

 

Download Present3D 

Present3D can currently be obtained by downloading the OpenSceneGraph from the OpenSceneGraph website downloads.

To obtain the most up to date version of the code we will be using svn to download the current development snapshot, but you could choose to use one of the stable versions if you prefer, however, some newer features may not be available.

 

Download and Install : Step by Step

1: OpenSceneGraph:

To download the OSG open a shell (a Terminal window - the Terminal app can be found in the Utilities folder, in your Applications folder)  navigate to your User home directory by typing

cd ~

then return key

and then cut and paste in the following :

and press return.

image of terminal window

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.

 

2: OpenSceneGraph-Data:

Now you need to download the OSG data files into the same home directory ( User/your user name ), so do :

cd ~

then return key.

and then cut and paste the following to your shell :

and press return.

At this point, you can start the build process, but you will be missing some libraries that enable additional features like Volume Rendering and VNC window support,  so if you require these features, or just want to do a complete install, you could jump to Enable Additional Features and then come back here to complete the build.

On the other hand, building the OSG at this stage might make it easier to fault find if you do run into problems, as you will have confirmed that the base OSG is building and that the problem is likely to be one of the additional libraries. 

So, we will build the OSG now and add the additional libraries once we have that working.

 

Building OSG/Present3D

3: Build OSG

These instructions are for OSX 10.8.x, if you are building on an older system some of the paths will be different as Xcode has changed location ( add see here ).

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.

image of Cmake window

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_BUILD_TYPE : type in : Release

CMAKE_OSX_ARCHTIECTURES  : should say x86_64. 

CMAKE_OSX_SYSROOT : should be : /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk

 

The majority of the others should just be the defaults, but check these :

FREETYPE_INCLUDE_DIR_freetype2 : should have a path : /usr/local etc.. if not,  use MacPorts to add the Freetype port.

FREETYPE_INCLUDE_DIR_ft2build : should have a path : /usr/local etc.. if not,  as above.

FREETYPE_LIBRARY : should have a path : /usr/local etc.. if not, as above.

OSG_DEFAULT_IMAGE_PLUGIN_FOR_OSX :  should be  : imageio

OSG_GL3_AVAILABLE : should be  : un-ticked

OSG_WINDOWING_SYSTEM : should be : 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 build 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 return key, 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. 

 

Possible Errors since Nov 2013

There have been changes to the OSG to support Xcode 5.x and this means you might get errors when building that will require you to make a change to your CMake settings and configure and generate and then build again.

To make the change, open CMake and click on the Advanced tick box so that it shows a tick, as per the image below.

cmake window showing selections to make

This will reveal the advanced settings, being careful not accidentally change any settings, scroll down till you see :

OSG_CXX_LANGUAGE_STANDARD    

there are two possible options : C++98  or C++11.

So if the build failed with one option, change to the other and Configure and Generate in Cmake again, then in terminal do : make  : all as before.

 

Handy Hint #1 :  

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

 

Handy Hint #2 : 

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, using -i should only be used as a last resort, 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 Setting Up Present3D section.

Handy Hint #3 :

If you are going to be using the Terminal app for MacPorts installs, open another shell and do those in that and keep your OSG shell open and ready just to do make when you are ready. You can actually callup previous commands in an active shell just by using the up and down arrows on your keyboard, you can also use the tab key to auto-complete long names.

 

 

Enable Additional Features :

There are a number of additional features that can be added to the basic build of OSG/Present3D and these all require some additional libraries to be installed and the OSG/Present3D built to include them.

Currently these features are Volume Rendering, VNC Window and Udp/Http Remote Control.

 

Volume Rendering

To enable volume rendering there two additional libraries that need to be installed the Insight Toolkit and DCMTK, so again, step by step:

4:1 Insight ToolKit :

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

Download the current release. At the time of writing this was version 4.4.2. There is also a .pdf that gives installation instructions.

Once it has downloaded you will want to move the compressed InsightToolkit folder to the same User home directory as the OSG and uncompress.

Now at the same location, create a new folder (directory) and call it insight_binary.

Now open Cmake

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 source use the Browse Source button to find and select the InsightToolkit folder you just uncompressed and for binaries use the Browse Build button and find and select the insight_binary folder you created.

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 insight_binary folder by typing (changing the folder name to match yours)

cd ~/insight_binary

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.

Once this is completed, you will need to retarget Cmake to the OpenSceneGraph source and binary locations as above, and then go through the build process at 3.0 again.

In the Cmake window you should check :

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

 

4.2 : DCMTK

We will use the MacPorts distribution of DCMTK. So if you haven't already done so, you should download and install MacPorts as mentioned above at Optional : MacPorts

Now open the OSX Terminal app and type

port search dcmtk

and press return, MacPorts should respond with 

Terminal window showing dcmtk versions available

the actual version of DCMTK might have changed, but as long as you get something like this, you can then just type

sudo port install dcmtk

You might notice that MacPorts seems to be installing other stuff, it is, it is installing other libs that DCMTK requires to work. After a little while you should get a success message.

If you want to see what the dependencies are before you install you can type

port deps dcmtk

and MacPorts will respond with the various libs. This can be handy if the Port you are trying to install fails, you can then find what its dependencies are and then check if they are installed, or if there is a problem with one of them, but for help with this please refer to the MacPorts Guide. The MacPorts Lists are also really helpful, but do search before posting as there is a good chance that your problem has been answered before.

Once installed you will need to open Cmake again, checking it is still pointing to OpenSceneGraph for both source and binary. To enable Volume Rendering you will also need to include the BUILD_OSG_EXAMPLES option by clicking on its tick box. 

 

Once this is done click on Configure, you should then check that the DCMTK_ sections have the correct paths :

cmake window showing dcmtk paths

and if it looks like above, then click on Generate and once it has completed, go back to your OSG shell window and do "make" as before.

 

 

VNC Window 

5.1 : LibVNC Server

This is also a MacPorts distribution and so you will follow the same process as above. 

Now open the OSX Terminal app and type

port search libvnc

and press return, MacPorts should respond with

LibVNCServer @0.9.9_4  

or something similar, the actual version number might have changed. If it does you can then type

sudo port install libvncserver

and press return.. then wait for it to install.

Once installed you will need to open Cmake again, checking it is still pointing to OpenSceneGraph for both source and binary and again check that the LIBVNCSERVER_ sections are pointing at the correct paths 

cmake window showing libvnc paths

and if it looks like above, then click on generate and once it has completed, go back to your OSG shell window and do "make" as before.

 

Remote Control

To use the new remote control features, either from an other computer, or from a mobile device like an iPad, you will need the following libraries.

6.1 : Asio

We only use the headers from the Asio lib and so you just download the asio-1.5.3.zip from here : download asio and then unzip in an appropriate location, you could use the OpenSceneGraph-Data folder, or perhaps your osgconfigs folder. There are arguments for either, but we will chose the OpenSceneGraph-Data folder.

 

6.2 : Boost

For Boost we will use MacPorts, so back to OSX Terminal and type :

sudo port install boost

and press return, then enter your password and return... and wait till install is finished.

Now you need to open Cmake again and click configure, then tick the advanced checkbox.

cmake window showing asio and boost paths

ASIO_INCLUDE_DIR should be pointed to the location you chose for asio, so for OpenSceneGraph-Data the path would be :

/Users/username/OpenSceneGraph-Data/asio-1.5.3/include

As we used MacPorts to install Boost, the required files should have been found by Cmake, see the image above. If it doesn't look like this, have you ticked the advanced checkbox?

Boost_DIR : Boost_DIR-NOTFOUND

Boost_INCLUDE_DIR : /opt/local/include

Boost_LIBRARY_DIRS : /opt/local/lib

and if it looks like above, then click on Generate and once it has completed, go back to your OSG shell window and do "make" as before.

 

And that should be you finished with installing. But 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...

 

Setting up Present3D

7.1 : The .tcshrc file

This file is where you set the paths for the OSG, and the environmental variables that are the defaults for how Present3D will be setup to display on your screen/s,  whether stereo is on, or off and what stereo driver is required, you can also control which widescreen config will be used and which cursor and much more. A number of these environmental variables can be overridden by including <env> tags in the header of the Present3D xml file, but we will cover that later, for now, you need to create the default settings that will be used.

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 ash 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, so you will need to setup TextWrangler to see hidden files by opening a new browser window by going to the top menu bar File/New Browser and once the new window opens, click on the spyglass on the bottom LHS of the window and from the popup menu,  Show section, select "Everything".

TextWrangler window

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

Download this example : dot_tcshrc  file and either add the relevant bits to your existing file or save as .tcshrc  in your home folder, to create a new one.  The system will ask are you sure you want to use the prefix .  say yes! 

Now you need to find and replace all instances of username and change to the username of the home folder that you saved the OSG etc into above. You can use the search and replace feature within TextWrangler to do this.

For the above to work it is important that you name the file .tcshrc and save it in the users home folder as in the image above. 

 

 

7.2 : OsgConfig

OsgConfig  .cfg files allow control of the size and proportions of the window that will be displayed on your desktop. This is most often used when wanting to create a single graphics context that will stretch across two displays rather than each of the display being rendered individually and potentially loosing stereo sync when handling large datasets.

We will go into creating custom .cfg files in a later tutorial.

If not required you can comment out the following line in the .tcshrc file or include an <env> in the header of your xml show file. To comment out use a # in front of the line.

#setenv OSG_CONFIG_FILE /Users/username/osgconfigs/wideWindow1024.cfg 

Download example osgconfig folder, unzip and put in same user folder/directory as OSG etc above. The folder includes sample widewindow configs, a cursor and a folder of CLUT files.

Download : osgconfigs Folder

 

Setting up Volumes

8.1 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, within the current 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.

We will go into creating and editing CLUT files in a later tutorial.

A folder with some sample CLUT's 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

 

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 : 671MB

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, Present3D has great success with files that have the Modality listed as CT.

MRI and others will usually load in greyscale, but CLUT's are hit and miss, there is a workaround for this that will be covered in a later tutorial.

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

Like: