                   Raider3D UNIX installation and usage notes

  Okyz Documentation Group

   Copyright (c) 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.

     ----------------------------------------------------------------------

   Table of Contents

   1. Introduction

   2. Installation

   3. Commands

   4. Configuration

   5. Using Raider3D

   6. Notes

     ----------------------------------------------------------------------

                                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(R) [1] instructions flow between the
   captured application and the system's OpenGL(R) 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.           

     ----------------------------------------------------------------------
