RT_BOT_FACES(1)

NAME
rt_bot_faces — raytrace a model, and write a file listing all the BOT facets hit first on any shotline.

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

DESCRIPTION
Rt_Bot_Faces operates on the indicated objects in the input model.g and fires rays (the same as RT) keeping a list of all the first-hit BOT facets.

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 rt_bot_faces 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 rt_bot_faces(1) is on, i.e. -U1, but the effect of air regions may be disabled with -U0.

-o output_bot_faces
    specifies a named file to receive the list of BOT facets that appear as first surface hit on any ray. By default, the data are written to stdout. The format of the output is a header line for each BOT primitive that appeared as the first object on any ray of the form:
    	BOT: bot_primitive_name
    This is followed by a list of facet numbers for that BOT primitive (one per line). The facet numbers are indices into the list of faces (starting from zero) for that BOT primitive. If the output file is not empty, it is expected to contain data from a previous execution of rt_bot_faces, and the data in the file is read, and stored, new data is added to it during the execution, and the output file is overwritten with the accumulated data.

-x# Set librt debug flags to (hexadecimal) number.

-c "set rt_cline_radius=#"
    Tells rt_bot_faces(1) to use the provided number (in millimeters) as the additional radius to add to CLINE solids.

-c "set save_overlaps=1"
    Tells rt_bot_faces(1) to act like the FASTGEN4 raytracer. Specifically, overlap handling is changed to agree with that of FASTGEN4.

The rt_bot_faces program is a simple front-end to librt(3).

EXAMPLE
This section will acquaint the user with the ordinary usage of rt_bot_faces. the typical use is:
    rt_bot_faces -s32 model.g all.g > file
This will fire a square grid of 32 by 32 rays at the named model and the resulting list of BOT facets will be placed in "file".

OVERLAP REPORTING
RT_BOT_FACES 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.

SEE ALSO
 mged(1), rt(1), rtray(1), librt(3), plot3(5), ray(5V).

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

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