LGT(1)

NAME
lgt - produce a shaded image of an mged model

SYNOPSIS
lgt [ options... ] model.g objects...

DESCRIPTION

Lgt is an image rendering tool for the mged(1) solids modeling data base. The program can run interactively or detached from a terminal session (batch mode). The interactive user interface consists of a terminal independent pop-up hierarchical menu system (though IRIS users have the option of using the mouse-driven graphics menus instead). The experienced user may wish to exit this menu system (by typing a `q') and use the single-letter command interface as described below. For information on the hierarchical menus and detailed information on the commands and overall usage of lgt please refer to the paper The ``lgt'' Lighting Model which is included in the BRL-CAD documentation. Note that specifying the viewing direction involves setting up light source zero, see the L command below for more information. There are numerous command-line options.

  Options

-an Set the number of degrees of roll on the grid to n. This is a rotation of the viewing grid about the viewing axis.

-An Set over-sampling factor to n. This is a simple anti-aliasing technique which ray traces an n by n array of pixels and then outputs a linear average of the result.

-b``R G B''
    Set the background color to R G B which are intensity values from 0 to 255 of the red, green, and blue channels respectively.

-cn Set the tracking-cursor flag to n. When set to non-zero, this causes an arrow cursor to point at the current scan line being ray traced, assuming that a graphics device is being used. The default is to disable the tracking-cursor.

-d``x y''
    Set automatic mapping offsets to x and y in the IR Module.

-t``x y''
    Set the grid translation to x and y. This offsets the grid within the grid plane (perpendicular to the viewing axis).

-D``x y''
    Set the image translation to x and y. This offsets the image relative to the display origin.

-en Set the debug flag to n. This flag is for the developer/maintainer of lgt(1) and librt(3), and sets a hexidecimal bitmask to turn on or off diagnostics.

-fn Specify the distance from the origin of the grid to the model centroid as n millimeters. This command will interact with the -p option. If perspective is set to a positive number, the user-specified grid distance is ignored, because automatic perspective adjusts both the grid and observer distances according to the desired degree of perspective. Conversely, if perspective is negative, the user-specified grid distance, coupled with the observer distance and the view size, will effect the apparent degree of perspective. If perspective is set to zero, the grid distance will be used to position the grid; if the distance is small enough so that the grid intersects the model, the model will appear sliced, that is, only the portion of the model beyond the grid will be visible.

-G``n cflag gflag vsize''
    Configure the grid. If cflag is set to zero, n refers to the grid size. The grid is square, so this number represents the number of rays (or cells) across the grid in both the X and Y directions. However, if cflag is set to non-zero, n refers to the cell size (ray separation) in millimeters. If gflag is set to zero, the grid origin will be aligned with respect to the model RPP, otherwise it will be aligned with the model origin. Vsize is a floating-point number which represents the view size. If it is greater than zero, the field of view will be set to take in an object of that size. Otherwise, the view size will be set relative to the model RPP. The grid size and cell size are related; when perspective is set to zero (see the -p option), grid size times cell size equals view size. When perspective is non-zero, the grid and eye distance are also involved, so the relationship is less pertinent. The defaults for this command are; G 32 0 0 0.0, which means grid size of 32, centered WRT the model RPP and view size set relative to the model RPP.

-in Set noise threshold for the Infrared (IR) Module to n.

-Ifile
    Read and display infrared data from file.

-kn Set hidden-line flag to n. When set to non-zero, this causes a hidden-line drawing to be produced rather than the usual shaded color image. If n is set to 1, the drawing will be black-on-white, and if set to 2, white lines will be drawn on a black background. The default is to disable this feature.

-Kn Set maximum number of bounces (levels of recursion) in ray tracing. For instance, it requires one bounce to get the first reflection off of a mirrored surface, and several to get through a transparent object. If no transparent objects or mirrors are modeled, it is more efficient to leave this at the default of zero, but, if such objects are modeled, it is best to be safe and use at least 6 bounces, better yet a dozen or so since multiple mirrors or critical angles encountered in refraction can lead to many bounces for a given ray.

-jfile
    Input key-frame from file. This command reads a saved view as output by mged(1) when using the savekey command. When using savekey the user must be sure not to specify the time field, otherwise he must remove the resultant lines from the output file either manually or as a side-effect of running an interpolation program. If these time stamps remain in the file, lgt will likely get sick as the input gets out of phase. Specifying this command without a file argument will disable key-frame input.

-nn Set number of processors to use for ray tracing to n. This parameter is only meaningful when running in a parallel processing environment. The default is set, in a host-dependent manner, to the maximum number of processors available in a parallel configuration.

-ofile
    Write image output in file or display on device. By default the output is displayed on a frame buffer. The default frame buffer is configured by the frame buffer library (see libfb(3B)), based on available graphics devices. The default may be overridden more generally with the environment variable FB_FILE (see brlcad(1)).

-Ofile
    Write errors to file rather than the terminal. The default is to write to the standard output in a scrolling window (sub-section of the terminal screen), if the standard input is attached to the terminal; or to standard error, if input has been redirected.

-pn Set the relative perspective to n. When this number is positive, the relative distance of the grid and the observer from the model centroid (or origin) will be adjusted automatically to yield the specified ray divergence factor (rays emanating from a point, the observer position, to the respective grid cells). When set to zero, there is no perspective (parallel rays). Perspective increases in direct proportion to this number; the default is 0.25. When n is negative, perspective is governed by the position of the observer (eye) and the grid, and by the view size.

-sn If n is non-zero, enter the Infrared Module.

-vfile
    Read light source data base from file.

-wfile
    Read material data base from file.

-x``a b''
    Set the starting and ending pixel to a and b. This sets up left and right boundaries within the grid to limit the ray trace to a rectangular sub-grid.

-Xn Set the overlap reporting flag to n. When set to non-zero, this causes overlaps to be reported to the log file or terminal (see the -O option). The default is to report overlaps.

-y``a b''
    Set the starting and ending scan line to a and b in the sub-grid.

-zn Set shadow computation to n. When set to zero, no shadows will be computed. This is useful when computing a view from inside the model.

Required arguments to the program are model.g which is the name of the mged(1) data base, followed by one or more objects which are names of regions or groups in the geometry hierarchy which are to be rendered. Commands are read from the standard input, whether in batch mode or interactive. In general, all command-line options can be invoked as commands, by using the identical option letter, but there are a few commands that are not available as command-line options.

  Commands (not available as options)
Arguments that appear in brackets are optional. In general, when an optional file argument is left out, the user will be prompted; and if a flag is omitted, the state will be toggled (unless otherwise specified below):

?   Print the menu of available commands.

! [command [arg...]]
    Execute command from the shell. If the environment variable $SHELL is set, it will be executed, otherwise /bin/sh is the default shell. If a command is specified, the shell will be fed it as input (along with any arguments), otherwise, an interactive shell is spawned.

. [flag]
    Set buffered pixel I/O to flag. The values for specifying the buffering scheme are as follows:

    0   Programmed I/O. Each pixel is output immediately after it is calculated.

    1   Paged I/O. This is generally the most efficient I/O scheme, but only updates the image as it crosses a page boundary. Page sizes vary with the graphics device and host, but range from 8 to 42 scan lines.

    2   Scan line I/O. Each row of pixels is output when ready.

    In the absence of flag, the state is cyclicly incremented.

# [comment]
    This is the comment command, useful for preparing input files. The entire line is copied to the log file or terminal (see the -O option).

B   Submit a batch run. The current parameters are used to build a script in a temporary file, and this is submitted to the batch queue (see batch(1)), subject to MDQS availability. The user will be sent mail when the job is finished.

C   Enter cursor input module. The user can manipulate the cursor to specify rectangular portions of the screen or specific pixels to ray trace. This module has a help facility, accessible by typing a `?'.

    When using the Silicon Graphics IRIS in local mode, the user can use the mouse to position the cursor and sweep out rectangular areas. These operations require the user to press the middle mouse button to control sweeping operations and the selection of positions. The cursor module implementation on the IRIS also has a window-in and window-out command which allows the user to specify a translation and scaling of the grid to include a smaller or larger, respectively, area of the model to ray trace.

E   Erase frame buffer. Fill grid area of frame buffer with black.

F   Animate on-screen movie. This command is currently only implemented on the IRIS, and displays movies such as those generated with this program (see the J command).

H [file]
    Save frame buffer image. Stores the image on the current frame buffer in file. This can also be used to transfer the image to another graphics device.

h [file]
    Restore a saved image from file. Reads the image from the specified file or device and displays it on the current frame buffer.

J   Make a movie. This command prompts for information necessary to set up a movie. Both full-screen and postage-stamp movies are supported. In specifying the number and size of frames to shoot for a postage-stamp movie, the user is limited by the graphics device's display memory (the entire movie must fit in the frame buffer). Full-screen movies are saved on the disk, 1 frame per file, so they can be any displayable size given you have the disk space.

L id
    Modify light source data base entry id. The user will be prompted for information necessary to position and describe the light source. Light source zero has special significance and a dual purpose. It simulates an ambient light source and, its position specifies the position of the observer (the eye). Note that only the program's (in-core) copy of the data base is modified until another command (see the V command) is used to write it to a file.

l id
    Print light source data base entry id. Display the current copy of the specified entry on the terminal's screen. If no entry is specified, all entries will be displayed.

M id
    Modify the material data base entry id. The user will be prompted for information necessary to describe the properties of the material necessary for the lighting model calculations. As with the light source data base, a seperate command (see the W command) is used to save the current modifications in a file.

m id
    Print material data base entry id. Display the current copy of the specified entry. The id should match the material id in the mged(1) data base. If no entry is specified, all entries will be displayed.

N [temperature]
    Specify temperature for IR painting.

P   Print mged(1) regions and associated IR temperature mappings.

Q   Assign IR temperature to mged(1) region or group.

q or ^D
    Quit. Normal exit from the program.

R   Ray trace current view. Initiate a run. During a batch mode run, this command will be given automatically on encountering an end-of-file if it hasn't been given explicitly. Note that if an explicit quit command is given, an end-of-file condition will not be encountered.

r   Redraw the terminal screen.

S [file]
    Save an executable script in file. Writes out a Bourne shell script which will restart the program with the current set of options. Note that the user should also use the commands (see below) to save the light source and material data bases before quitting.

T [fbsize]
    Specify the frame buffer size as fbsize. On windowing systems, a frame buffer window will, by default, be opened which just fits the image. This command allows one to specify a larger window. If the window is a multiple of the image size, zooming will be used to enlarge the image to fit the window. It is desirable to specify an exact multiple, so that the image will fill the window. On graphics hardware that does not have a windowed environment, there may be only fixed window sizes such as 512 and 1024, in which case, you will get the best match. Specifying zero for fbsize will restore the default behavior.

U [file]
    Save IR data base in file.

u [file]
    Read IR data base from file.

V [file]
    Save light source data base in file.

W [file]
    Save material data base in file.

Z   Display pseudo-color IR mapping scale.

HINTS
This program is designed to be used in two modes; interactively for setting up parameters, and in batch mode for rendering high-resolution images. First, the user should invoke the program in the interactive mode without options. While in this mode, the user should set up parameters for a low resolution ray trace, perhaps by using the default resolution (32x32 grid), ray trace that view, tweak parameters as necessary, and iterate. As the user converges on the acceptable combination of parameters, there is a command which will save a UNIX shell script. This command generates a shell script that will invoke the program with the current set of parameters, data bases, objects, etc. When everything is to the user's liking, he or she should increase the resolution, change the output device to a file name so as not to tie up a graphics device, make sure that the error output is being re-directed to a file as well, and that all changes to the material or light data bases have been written out. Finally, the user can either spawn a batch run with a command, or use the above mentioned command to save a shell script and either quit or proceed to set up another view. The command to create a batch run actually executes the batch(1) command (subject to MDQS availability), with the current set of parameters, etc. As an alternative to generating a batch run from the program, the script files can be fed by hand to the batch(1) command or can just be detached as background jobs (see EXAMPLES for the proper method) with their input redirected from a file or /dev/null. If the program is detached without re-directing its input, the full-screen display will be generated which will tie up that terminal or layer (in a windowed environment). If the program is running in batch mode, and it detects an end-of-file before the command is given to generate an image, it will generate one automatically.

EXAMPLES
The following command will start up an interactive session which will use the Silicon Graphics IRIS's default frame buffer device (/dev/sgi) on a host address viva.brl.mil to display the hull and turret of the target description in file tank.g.
    $ lgt -o viva.brl.mil: tank.g hull turret

This command will start up an interactive session on an alternate device on a remote host and will begin at the 251st scan line and complete a 512x512 image (handy in the event that the computer goes down in the middle of ray tracing an image). Note that since the -y and -G options take multiple arguments, they must appear in double-quotes.
    $ lgt -G ``512 0 0 0.0'' -o vgr.brl.mil:/dev/ik1l -y ``250 511'' tank.g hull turret

This will run the program as a detached process by executing a saved script called tankscript.
    $ tankscript < /dev/null &

SEE ALSO
The ``lgt'' Lighting Model, mged(1), pix-fb(1), librt(3), libfb(3)

AUTHOR
Gary S. Moss