NAME

rtg3 - raytrace a model, writing a COVART (GIFT) 3-component format shotline file

SYNOPSIS

rtg3 [options...] model.g objects... > model.cov

DESCRIPTION

rtg3 operates on the indicated objects in the input model.g and produces a GIFT/COVART shotline file with three components per line, and both entrance and exit obliquity angles on standard output. The region ID field of the output file is set to the region id of each intersected region (partition). If the ray partition is followed by air, the aircode for the air region (and the line-of-sight thickness of the air) is noted on the shotline header line.

The orientation of the rays to be fired may be specified by the -a and -e options, in which case the model will be autosized, and the grid will be centered on the centroid of the model, with ray spacing chosen to span the entire set of objects. Alternatively, with the -M option, a transformation matrix may be provided on standard input which maps model-space to view-space. In this case, the grid ranges from -1.0 <= X,Y <= +1.0 in view space, with the size of the grid (number of rays fired) specified with -s. This option is most useful when rtg3 is being invoked from a shell script created by an mged(1) saveview command. Note that it conflicts with -G# and -g#; negative hit distances have been seen when this conflict was not avoided.

The following options are recognized.

-s#

Number of rays to fire in X and Y directions (square grid). Default is 512 (512x512).

-a#

Select azimuth in degrees. Used with -e and conflicts with -M.

-e#

Select elevation in degrees. Used with -a and conflicts with -M.

-M

Read model2view matrix from standard input. Conflicts with -a and -e.

-g#

Select grid cell width. Do not use with the -s# option.

-G#

Select grid cell height. If not specified, cell height equals cell width. Do not use with the -s# option.

-U #

sets the Boolean variable use_air to the given value. The default for rtg3(1) is on, i.e. -U1, but the effect of air regions may be disabled with -U0.

-o

output.cov specifies a named file for COVART-format output. By default, the shotlines are written to stdout.

-x#

Set librt debug flags to (hexadecimal) number.

-c set ray_data_file=ray_file_name

specifies a file name for ray data output. This output consists of one line of data for each shotline in the shotline output file. Each line contains azimuth, elevation; x, y, and z of the ray start point; x, y, and z of the ray direction; the corresponding line number in the shotline file; and the coordinates of the first hit point along this ray.

-c set rt_cline_radius=#

Tells rtg3(1) to use the provided number (in millimeters) as the additional radius to add to CLINE solids.

-c set save_overlaps=1

Tells rtg3(1) to act like the FASTGEN4 raytracer. Specifically, overlap handling is changed to agree with that of FASTGEN4.

The rtg3 program is a simple front-end to librt(3) which is most useful when used with mged(1) and covart(1V).

A color vector display of ray-model intersections can be written to rtg3.plot3 by specifying the -X80000000 option. The resulting plot file can be displayed with plot3-fb .

FORMAT

The general layout of the output format is:

Overall header line (one per run)

View header line (one per view)

Ray (shotline) header line (one per ray)

Component line (one for each three components in this ray)

The GIFT-3 shotline format has a different convention for the location of the start point (and thus the location of parametric distance zero) along the ray. This difference is handled automatically in rtg3 by translating the ray's zero distance to the plane containing the model origin, by adding a distance correction factor. For each ray, both the cell center coordinates and the coordinates actually fired from are output.

Obliquity angles (declensions off the normal) are computed internally in radians but output in degrees to satisfy the GIFT-3 format. Note that internally, librt normals always point outward, whereas GIFT normals point inward.

GIFT zero-fills the fields of the component card if there are less than three components. Neither COVART II nor COVART III require this zero-filling, so it is omitted by rtg3 .

EXAMPLE

This section will acquaint the user with the ordinary usage of rtg3 . A GIFT-3 output file is produced by giving the command:

rtg3 -s32 model.g all.g > file

This will make a 32 by 32 ray file of the named model. If a bounding-box plot file is to be made as part of producing visual output, use

rtg3 -s32 -x80000000 model.g

The bounding boxes for the objects in the database specified will automatically be put into a file called rtrpp.plot3. Now, to compute the color rays use

rtg3 -s32 -X80000000 model.g

The results will be automatically stored in rtg3.plot3. The rays will be colored green where they traverse solids in the model, and blue where they traverse air within the model.

The two plot files can now be combined into a single picture and displayed:

cat rtrpp.plot3 rtg3.plot3 | plot3-fb

OVERLAP REPORTING

rtg3 shares overlap handling and reporting with the rest of the RT family of applications. A brief description of the overlap reporting follows.

The first one hundred (100) overlaps are individually reported. Thereafter, only one out of each additional one hundred overlaps are reported, and the user is notified that overlap printouts are being omitted. This alerts the user that more overlaps exist, but that they are too numerous to list individually. The general overlap message takes the following form:

OVERLAP1: reg=region_name isol=solid_name
OVERLAP2: reg=region_name isol=solid_name
OVERLAP depth #mm at (x, y, z) sx# sy# lvl#

This means that OVERLAP1 and OVERLAP2 share a common space (depth) of #millimeters starting at the point x, y, z in model coordinates, and at the ray coordinates (screen coordinates) sx and sy. Level refers to the level of recursion, and will typically be zero unless glass or mirror objects are present.

DIAGNOSTICS

Numerous error conditions are possible, usually due to errors in the geometry database. Descriptive messages are printed on standard error (file descriptor 2).

BUGS

The COVART file format permits multiple views to be stored in one file. Rtg3 presently can only compute a single view.

Most deficiencies observed while using the rtg3 program are usually with the librt(3) package instead. If the -s# option is used together with the -G# and -g# options, negative hit distances will be seen.

AUTHORS

BRL-CAD Team

COPYRIGHT

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org