Renderer Command Language

Overview

This file documents the command language used to control the RIVA renderer.

Command Syntax

Commands are text strings no more than 255 characters in length. When commands are read from a disk file, each line is a separate command. When commands are read from the net, i.e., messages from Flexible Flyer rounted by the Router, each message is a separate command.

 Blank lines and lines with a pound sign ('#') in the first column are ignored. All other lines are assumed to be commands.

 Each command begins with a one-word command name, e.g., "BYE", "INCLUDE:", or "RV:". The command name and its arguments must be white-space delimited. If the renderer does not recognize the command name, then an error status message is written, and the command is ignored.

 Case is significant in command names. Thus, "BYE" is a valid command, but "bye" is not. By convention, commands with arguments have a colon in their name, e.g., "PRINT:", "RV:"; commands with no arguments do not, e.g., "BYE".
 

Communications Issues

The renderer can read command messages from disk files or from a net router. All net messages should have type "render_update". By default, the renderer will look for "render_update" messages from resource "RENDERER"; however, any resource name may be used.

When reading messages from the net, the renderer also writes status messages to the net. Status messages are null-terminated ASCII strings. All status messages have type "render_status". By default, status messages will be sent using resource name "RENDER_STATUS", but any resource name may be used.
 

Command Dictionary

This section describes each command the renderer knows. Each command description includes the purpose of the command, a description of each argument, and any important implementation details.
 

Command Processing

Commands are received by hfb_host, and sent to flit for processing. flit always sends a response back to hfb_host, which might do additional processing. Unless otherwise stated, flit's response is a status message, which hfb_host outputs.
 
 

Syntax Notes

A number of the command argument types recur frequently. Rather than repeat their description under each command, they have been grouped here. For example, whenever the argument name 'surface' is used, it means the argument should be the name of a surface that's loaded into the renderer. If a command needed two surface names, the arguments would be called 'surface1' and 'surface2'.
 
surface
The name of a surface (an elevation map) loaded into the renderer. Surface names are defined in a renderer configuration file, e.g., 'earth.set'.

 
image
An image name. Used when the command applies primarily to the surface's color input image.

 
band
A single, unquoted character identifying an input band. Every surface's color input image contains some number of input bands, typically 3. Input bands are given one-character names. Either the band names are specified by the 'BANDS' field of the image file's header, or default names are assigned. The default names are the numerals 0, 1, 2, and so on.

 
color
R, G, or B. A 'color' argument refers to one of the three output color channels.

 

Basic Commands

These commands control basic, stable features of the RIVA renderer. As such, they are relatively unlikely to change. Basic commands may become obsolescent, as they are superseded by more expressive commands; such commands will be moved to the 'Obsolescent Commands' list.

APPLY_DISP: [displacement|NULL] [image|NULL] timestep

Apply the timestep of the displacement to the base elevation map and apply the timestep of the image as an surface overlay. Both displacement and image are time-varying datasets. displacement is a vertical displacement to the base terrain and image is an overlay on top of the terrain image. Either argument can be a NULL.
 

BYE

Terminates the renderer. This command is translated into an end-of-file (EOF) message by hfb_host before being sent to flit. The action of both programs upon receiving an EOF is to terminate gracefully.
 

COLORS: surface option

Selects the output color display mode for a surface, depending on the value of 'option': RGB, R, G, B, or AVG:
  • RGB: Normal display
  • R: Display the red output plane, as a shade of gray. Essentially, the red value in each RGB pixel is used for green and blue as well.
  • G: Display the green output plane, as a shade of gray.
  • B: Display the blue output plane, as a shade of gray.
  • AVG: Display the average of the three color planes, as a shade of gray.
REDRAW or RV: must be used to show the results of this command.
 

COMBINE

Recombines the rendered images making up the previous frame, and sends the result to the current destination. This is generally used after changing combination parameters, such as opacity, because it is much faster. flit must have processed at least one RV: command.

 flit's response to this command is a rendered image; hfb_host reduces the image if oversampling is turned on, and sends the image to the current destination.
 

DEST: destname

Chooses a new image destination, by name. Image destinations are defined in the file flitrc. The initial image destination is specified on the command line, or in the render script.
 

DISABLE: surface

Disables a surface so that it won't be rendered. If all surfaces are disabled, the base surface is automatically enabled.

 REDRAW or RV: must be used to show the results of this command.
 

ENABLE: surface

Enables a surface so that it will be rendered.

REDRAW or RV: must be used to show the results of this command.
 

FRAMENUM: number

Sets the current output frame number. The frame number is used to construct frame file names when writing to disk. This is generally used in batch mode to produce frame file names in a particular range.

 Frame output is handled by hfb_host. Thus, this command is passed through flit to maintain synchronization, but the processing is done by hfb_host.
 

INCLUDE: filename

Reads commands from 'filename' until the end of the file is reached, and then resumes reading commands from the previous source. If there is no previous source, an end-of-file signal is sent to flit.
 
 

LIGHT: image ON/OFF azimuth altitude

Turns on or off a light illuminating the image from an altitude and azimuth angle in degree, as specified by 'altitude' and 'azimuth', respectively. This feature only works properly with global dataset.  The light source is assumed to be located at infinite distace and the surface normal is assumed to be perpendicular to the tangent plane of the surface.  Only the ambient light and the diffuse light are calculated.  The lighting parameter of the surface can be defined using MATERIAL command.
 

MAPAUTORATIO: image color band1 band2 %low %high logging atmos1 atmos2

Maps the ratio of an image's band1 and band2 to an output color. Either the ratio or the log of the ratio between the bands can be used, based on 'logging', which is a boolean flag. The result ratio is stretched such that the output has the given '%high' and '%low' saturation. The atmospheric correction factors 'atmos1' and 'atmos2' are subtracted from the bands before computing the ratio.

 'logging' is an integer, either 0 or 1. '%high' and '%low' are decimal fractions between 0.0 and 100.0. The sum of '%high' and '%low' must be less than 100.0. 'atmos1' and 'atmos2' are integers between 0 and 255, inclusive.

 REDRAW or RV: must be used to show the results of this command.
 

MAPCOPY: image color band

Maps one band of an image to an output color without any additional processing.
 

MAPGAUSS: image color band %low %high

Maps one band of an image to an output color, using Gaussian stretching. The input band is stretched to give a certain percent dark saturation and a certain percent light saturation.

 REDRAW or RV: must be used to show the results of this command.
 

MAPINDEX: image band colormap

Maps one band of an image to a RGB color by using the band value as an index to a colormap defined in a file named colormap. colormap is a binary file that contains 256 RGB colors (3 bytes per color).
 

MAPRATIO: image color band1 band2 gain offset logging atmos1 atmos2

Maps the ratio of an image's band1 and band2 to an output color. Either the ratio or the log of the ratio between the bands can be used, based on 'logging', which is a boolean flag. The result ratio is stretched; the amount of stretching is determined by the 'gain' and 'offset'. The atmospheric correction factors 'atmos1' and 'atmos2' are subtracted from the bands before computing the ratio.

 'logging' is an integer, either 0 or 1. 'gain' is a positive real number. 'offset' can be any real number. 'atmos1' and 'atmos2' are integers between 0 and 255, inclusive.

 REDRAW or RV: must be used to show the results of this command.
 

MATERIAL: image ka kd

'ka' is the light ambient coefficient and 'kd' is the diffusion reflection coefficient. This command simulates the light interaction of image if it were made of a material of coefficients 'ka' and 'kd'.
 

OPACITY: fraction [surface]

Sets the opacity fraction for a surface. If no surface is specified, the opacity is set globally. 'fraction' must be between 0.0 and 1.0, inclusive.

 COMBINE, REDRAW or RV: must be used to show the results of this command.
 

PREFIX: prefix

Sets the output file prefix used when writing frames to the disk. Frame file names are constructed from the prefix and the current frame number. This command is generally used in batch mode.  The output file prefix can also be set as a command argument of hfb_host using -O switch.

Frame output is handled by hfb_host. Thus, this command is passed through flit to maintain synchronization, but the processing is done by hfb_host.
 

PRINT: text to be output

Outputs the 'text to be output' as a status message. This command would generally be used for debugging, and for marking progress in command files.

 Status message output is handled by hfb_host. Thus, this command is passed through flit to maintain synchronization, but the processing is done by hfb_host.
 

REDRAW

Redraws the previous frame and sends it to the current destination. flit must have processed at least one RV: command.

 flit's response to this command is a rendered image; hfb_host reduces the image if oversampling is turned on, and sends the image to the current destination.
 

RESTOREDEST

Restores saved destination. Must have a saved destination. See SAVEDEST.

RV: eye[0] eye[1] eye[2] gaze[0] gaze[1] gaze[2] up[0] up[1] up[2] fov coord_id coord_spec

Renders an image from this viewpoint, and outputs the image to the current destination. 'eye' is the camera location; 'gaze' is a point toward which the camera is looking; 'up' is a point directly above the camera. Between them, 'eye', 'gaze', and 'up' define the camera's location and orientation. 'fov' is the field of view, in decimal degrees. 'coord_id' and 'coord_spec' define the coordinate system and units for 'eye', 'gaze', and 'up'. See Renderer Coordinate Systems for more information.

 flit's response to this command is a rendered image; hfb_host reduces the image if oversampling is turned on, and sends the image to the current destination.
 

SAVEDEST

Saves current display destination. Use RESTOREDEST to restore saved destination.
 

SHADE: image ON/OFF

Turns shaded relief on or off for the image specified. If no matrix is specified by SHADEMATRIX, the default convolution matrix simulates the Sun at 45 degrees East of North:
[0 -1 -2]
[1  0 -1]
[2  1  0]

REDRAW must be used to see the effects of this command.
 

SHADEMATRIX: a b c d e f g h i

Sets the convolution matrix of the command SHADE to
[a  b  c]
[d  e  f]
[g  h  i]

 The SHADE: command must be executed for this command to take effect.
 

VIEWPORT: x y nx ny

Changes the viewport of image rendered. 'x' and 'y' define the x and y offset of the window to be rendered. 'nx' and 'ny' define window size. All values must be positive integers; x+nx and y+ny must not exceed the output dimensions.

This command was designed to render very large output images. The image can be partitioned into a 2 dimensional grid and each portion can be rendered seperately by setting the viewport. In flitrc, you can specific a destination device with multiple viewports. We used this command to render some images as big as 1024x10240 or 3860x1028 pixels.
 

ZRES: factor [surface]

Sets the vertical exaggeration. When surface is specified, it applies to the specific surface only. Otherwise, all the surfaces will be affected. 'factor' is a positive real number. When surface refers to a displacement dataset, it sets the exaggeration ratio of the displacement.

 REDRAW or RV: must be used to show the results of this command.
 

Obsolescent Commands

Commands in this list are still supported by the RIVA renderer for the sake of compatibility with old programs and command files; however, future use of these commands is deprecated.
 

VP: eye[0] eye[1] eye[2] gaze[0] gaze[1] gaze[2] fov roll coord

Renders an image from this viewpoint, and outputs the image to the current destination. Use RV: instead.
 

TS_ANIM: symbol ImgFrameNumField DEM_FrameNumField startframe endframe incframe

This command was designed to perform time step animation before the RIVA file format was augmented to handle time-varying dataset. In the past, the time-varying dataset has to be stored as multiple RIVA files, one per time step.

'symbol' is the prototype image filename, 'ImgFrameNumField' specifies how many dots in the filename are to be skipped to get to the frame number. Similarly for 'DEM_FrameNumField'. It is assumed that if a character immediately precedes or follows the frame number, it is a dot ('.'). If FrameNumField < 0, the file does not change from frame to frame. The command would look like

TS_ANIM ocean.1231.tile.riv 1 -1 1230 1260 2

 This would animate ocean.1230.tile.riv to ocean.1260.tile.riv using every other image and a fixed DEM file.

 A viewpoint must be specified by RV: or SETVP: prior to calling TS_ANIM:.
 

SETVP: eye gaze up fov coord_id coord_spec

This command sets the viewpoint without actually rendering it. See RV for detailed description of command arguments. This command is mainly designed to be used together with TS_ANIM:.

back to top       back to documentation
Privacy / Copyrights
FIRST GOV   NASA Home Page This page, http://pat.jpl.nasa.gov/RIVA//public/RIVA/flitlang.html, is maintained by Peggy Li and was last modified Tuesday, 26-Aug-2003 11:16:21 PDT, CL 03-2169
spacer