# Raider3D UNIX installation and usage notes

### Okyz Documentation Group

Copyright © 2002 by OKYZ

$Id: r3d-en.sgml,v 1.7 2004/03/18 08:19:16 dockes Exp $ (C) 2002 OKYZ

This document describes the installation and usage of Okyz Raider3D on Unix systems. The focus is on the full capture edition of the product, but the information about installing the software and viewing files is valid for the free viewer version.

# 1. Introduction

## 1.1. Raider3D

The Raider3D tool will capture images from 3D applications. The captured data keeps all the 3D information and can be saved in the Raider3D internal format. The resulting files can be displayed on any machine where the free Raider3D viewer is installed.

The Raider3D viewer is included in the Raider3D capture distribution, or it can be downloaded from the Okyz web site

## 1.2. How it works: a quick explanation

Raider3D intercepts the OpenGLŪ [1] instructions flow between the captured application and the system's OpenGLŪ library. The instruction flow is interpreted and translated to the Raider3D format, then saved to a file on user request..

More precisely, this is accomplished by preloading a dynamic library during the application startup. This library has a standard OpenGL interface, which overrides the system's library interface. For each OpenGL call, the data is processed, then the native call is performed to update the display.

# 2. Installation

## 2.1. License

The capture functionality in Raider3D will only work if a valid license file is found on the workstation. If no license is present, the installation can be normally done, and the viewing functions will work, but no capture will be possible. To obtain a license, please contact support@okyz.com.

You can download the free Raider3D viewer from the Okyz web site..

## 2.2. Installation

The Raider3D installation procedure will not copy or modify any file out of its own directory. You do not need to be `root` as long as you have write access rights on the directory where you extract the distribution.

Raider3D Unix distributions are stored in compressed tar files. After downloading, you can extract the file anywhere in the workstation's file system. (typically `/usr/local/`, or `/opt/okyz/`). The top directory for the extracted subtree will be named r3d-Version. You can rename it as you like.

After extracting the tar file, you should change your current directory to the newly created r3d-version directory and execute the `r3dsetup.sh` script which you will find there. `r3dsetup.sh` should be run again if you rename or move the installation directory later.

The `R3D_HOME` environment variable designates the top installation directory and must always be set when executing a Raider3D command. The top directory will be designated as `$R3D_HOME` in the following.

`r3dsetup.sh` will create `$R3D_HOME/etc/r3dcshrc` and `$R3D_HOME/etc/r3dprofile`. These two files contain directives to be included in user shell startup files. `r3dcshrc` is for `csh`-like shells (`csh, tcsh...`). `r3dprofile` is for `Bourne`-like shells (`sh, ksh, bash...)`

Example 1. Setting the environnement with csh

    source r3dcshrc

Example 2. Setting the environnement with ksh

     . r3dprofile

The environment must be set whenever you execute a Raider3D command (especially, if you use several windows, you'll have to do it in each of them). Of course, it is highly recommended to include the environment setting directives in the user shell startup file.

If you have a license file, you should at this point copy it to `$R3D_HOME/etc/` (not needed for the free viewer).

Installation procedure examples:

Example 3. With ksh and a licence file

    % cd /home/me

    % gunzip < /var/tmp/r3dcapt-1.36f-solaris8.tgz | tar xf -

    % cd r3d-1.36f

    % sh r3dsetup.sh

    % cp /var/tmp/r3d_license etc/r3d_license

    % . etc/r3dprofile

Example 4. With tcsh, and no license file

    % cd /home/me

    % gunzip < /var/tmp/r3dcapt-1.36f-solaris8.tgz | tar xf -

    % cd r3d-1.36f

    % sh r3dsetup.sh

    % source etc/cshrc

If you do not use `r3dcshrc` or `r3dprofile`, two variables (`R3D_HOME` et `PATH`) should be set in the user's environment. You can copy and paste lines from the `r3dcshrc` and `r3dprofile` files.

- `R3D_HOME` must be set to the name of the installation directory. Bourne shell example:

                R3D_HOME=/home/me/r3d-1.36f/
                export R3D_HOME

- `${R3D_HOME}/bin` should be added to the `PATH`. Bourne shell example:

                PATH=$PATH:${R3D_HOME}/bin
                export PATH

# 3. Commands

Short descriptions for the main commands in the Raider3D capture distribution:

- `r3dwrap`: a shell-script that sets an appropriate environment for executing the application to capture.

- `r3dview`: the viewing program, also used as the capture control interface.

- `r3dsnap`: a different way of executing `r3dview`, which will only create a small capture control satellite window.

- `libGL.so`: the dynamic library which is linked to the captured application. It is located in `$R3D_HOME/lib`.

The free Raider3D distribution only contains `r3dview`, without the capture functions.

Note: `r3dwrap` is a small script that sets a few environment variables (depending on system type: `LD_PRELOAD`, `_RLD_LIST`, `LD_LIBRARY_PATH` ...), before executing the captured application. You can dispense with using it by using equivalent directives in your own application startup scripts.

# 4. Configuration

## 4.1. Environment variables

- `R3D_HOME` points to the Raider3D installation directory, ie: `/usr/local/r3d-1.36f/`. This variable must be set, there is no default value.

- `R3D_RC` can be used to name an user-specific capture configuration file. See further for default values.

- `R3D_LICENSE` names the license file. See further for default values.

- `R3D_CAPTUREFILE` is the default name for the capture file (this value can be set from the capture user interface). If the variable is not set, the default value is `$HOME/Lastcapture.r3d`

- `R3D_LOGFILE` is the name of the file where the capture library will possibly write error or information messages. The default value is `$HOME/r3dcaptrace`.

- `R3D_LOGLEVEL` is the capture library verbosity level. This is an integer and the verbosity increases with the value. By default (level 2), only error messages will be printed. A value of 4 will print a detailed trace of all OpenGL calls and their parameters, as made from the captured application. Higher values of the parameters are only for debugging purposes. Values of 4 and higher will cause the printing of a high volume of messages, and can have a severe impact on application performance level.

- `R3D_SNAPNOASK` will suppress the confirmation dialog which would otherwise raise if the next capture would delete an existing file.

- `R3D_LIBGL` names the library that will be loaded to find the actual system OpenGL interface. By default, `X11LIBDIR/libGL.so` will be opened. `X11LIBDIR` is the usual X11 library directory for the specific system (ie: /usr/openwin/lib on Solaris, /usr/X11R6/lib on linux, ...).

- `R3D_BINDIR` `R3D_LIBDIR` `R3D_SHAREDIR` `R3D_CONFDIR` could be used in special cases to point to the subdirectories normally found under `R3D_HOME`. To be used only in very special cases.

- `R3D_TEXDIR` names the directory where texture image files will be created if `LOGTEXTURESTOBMP` is set in the capture configuration.

## 4.2. Configuration files

Programs in Raider3D read and write configuration data from two configuration files, one for capture parameters, the other from user-specific viewer parameters (the files are kept separate for performance reasons). The files are normally named `$HOME/.r3drc` and `$HOME/.r3drc_user`, but see further for details.

### 4.2.1. Capture parameters

This file is looked for as follows:

- If the environment variable `R3D_RC` is set, its value is the name of the file.

- Else, the program tests for `$HOME/.r3drc`.

This file will be created if it does not exist and the filesystem permissions allow it.

The configuration file contents are independant of the operating system and described in the generic documentation. Default values in the distributed file are generally appropriate.

In the common case where an Raider3D installation is shared by several users, it is very desirable that each one creates his private copy of the configuration file in the default location in his home directory (`$HOME/.r3drc`), or elsewhere by using `R3D_RC`. Some capture control settings can only be activated if the configuration file is writable.

### 4.2.2. User parameters

This file contains values such as the user's email address, or the conference connection memorized parameters.

The file is named `.r3drc_user`, and can be found in the user's home directory.

When the file is accessed for the first time (ie, the first time the viewer is used), and if it does not exist, it is copied from the file `$R3D_HOME/etc/r3drc_user`.

Using a central file for initialization allows the administrator to set common initial values for some of the variables. To create the central file, the normal and easiest way is to edit a user file normally created by using the viewer, and delete the lines not wanted for common initialization. The text file format is self-evident.

## 4.3. License file

The license file is looked for as follows:

- If the `R3D_LICENSE` environment variable is defined, its value is the name of the configuration file. If the file does not exist, the program will not function.

- Else, programs test for the existence of `$HOME/.r3d_license`.

- Else the default value for the license file name is `$R3D_HOME/etc/r3d_licence`

# 5. Using Raider3D

There are no Unix-specific issues in using the viewing tool, which will not be described here.

## 5.1. Capture

To capture an application:

1. Start the application to capture, using `r3dwrap`. Example:

       % r3dwrap myapp myappParam1 myappParam2

2. If it is not already running, start `r3dview`, and click the capture button (butterfly net icon in toolbar). You will see a small control satellite. You can alternatively directly access the control satellite by starting `r3dsnap` instead (more compact but no viewing capability).

   The top button in the satellite allows you to change the name of the capture file, the next one allows starting a capture, the next one shows status info, and allows cancelling.

3. Arrange so that your application displays the 3d object that you want to capture, then click the ``Capture'' button in the satellite. The mouse cursor will change to a small cross. Then click in the window to be captured. If this was started from `r3dview`, the captured object will be displayed

The influence of the capture environment on application performance is very dependant on the type of application and system that you are using.

In some cases, you may be able to execute your application in the capture environment at all times, allways being ready for a capture. In other cases, it will be better to use the standard environment for routine use, and restart the application to perform a capture.

## 5.2. Specific applications notes

### 5.2.1. CATIA V4

When capturing a CATIA v4 display, it may happen that the object will be badly oriented, scaled, or positioned.

Workaround:

Before capturing, the user should load a special .model file, which contains the definition of a known and specially sized pyramid object.

The capture code will use its knowledge of the original pyramid orientation to set the Raider3D coordinates system, thus restoring correct orientation (the pyramid is then removed from the captured data).

The pyramid model file is named `ALIGN_PYRAMIDE_OKYZ.model` and is located in the `$R3D_HOME/share/r3dview/resources/` directory. This file should not be removed from this directory, but it may be copied to any location convenient for the users.

### 5.2.2. CATIA V4 on SGI machines

On SGI machines CATIA V4 will sometimes perform hidden parts removal in software. Such parts will not appear in the OpenGL instruction flow and will not be captured. Two environment variables may be set to prevent this:

    grffSoftFaceCull=No
    grffSoftTwoSided=No
    export grffSoftFaceCull grffSoftTwoSided

### 5.2.3. 4D Navigator

Two specific problems may occur when capturing a 4D Navigator display:

- Orientation issues, similar to what occurs with CATIA V4 (see above).

- Missing parts: 4D Navigator will sometimes perform hidden parts removal in software instead of sending all the data to OpenGL. Such parts will of course not be captured by Raider3D.

Workaround:

A specific 4D Navigator remote control script has been written, and will be loaded before the capture to ensure correct orientation and completeness.

This script is named `r3d4dnav` and is located in the `$R3D_HOME/bin` directory.

The script is automatically executed by Raider3D when capturing 4D Navigator. No specific user action is required.

> Note: The `catn4dlc` 4D Navigator remote control command called from the scripts may not be found or not work since its location and needed environment depend on the local configuration.

> The system administrator installing Raider3D should check that `catn4dlc` can be called on the command line from a user account. Else, the `r3d4dnav` script should be modified to include the adequate PATH and environment settings. To do so, find the following piece of code inside the script and modify it.

>     CATN4DLC_PATH=#Replace this comment with the catn4dlc path
>     export PATH=$PATH:$CATN4DLC_PATH

> If things still do not work, your 4D Navigator installation probably needs special environment variables to be set (ie: library path). Please contact Okyz support in order to solve the problem.

# 6. Notes

### Notes

[1] | OpenGL is a registered trade mark from Silicon Graphics Inc.