RTEDGE(1)

NAME
rtedge — ray-traces a model, detects edges, and writes a BRL-CAD color image (.pix) file

SYNOPSIS
rtedge [ options ... ] model.g objects ... > model.pix

DESCRIPTION
Rtedge operates on the indicated objects in the input model.g and produces a BRL-CAD .pix file that indicates the 'edges' in the model file. Rtedge produces images by drawing a boundary whenever a change in region_id is detected. It also recognizes and portrays abrupt changes in surface curvature and changes in surface height. This permits the recognition of pits, protrusions, and changes in surface curvature.

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 rtedge is being invoked from a shell script created by an mged(1) saveview command.

The following options are recognized.

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

-F framebuffer
    Indicates that the output should be sent to the indicated framebuffer. See libfb (3) for more details on the specification of a framebuffer.

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

-A# Select angle for shading. Default is 5.0 degrees. 89.0 will produce an image where only steep drops and rises are shaded.

-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.

-G# Select grid cell height. If not specified, cell height equals cell width.

-P# Specify the maximum number of processors (in a multi-processor system) to be used for this execution.

-U# sets the Boolean variable use_air to the given value.

-o output.pix
    specifies a named file for output. Note that using -o disables parallel processing.

-W  Inverts the foreground and background colors changing the default from white lines on a black background to black lines on a white background.

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

-c  Set special rtedge configuration variables.

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

ADDITIONAL OPTIONS
Rtedge replaces lgt(1). In addition to the simple white edges on a black background (or black on white) provided by lgt, rtedge allows arbitrary color combinations. It also allows rendering into an existing framebuffer and occlusion detection between two pieces of geometry. To configure its behavior, rtedge makes copious use of the -c option. Note that this approach is necessitated by the fact that librt (3) has used up nearly the entire alphabet. A transition to GNU-style long option names is planned.

-c"set foreground=#,#,#"
    and

-c"set fg=#,#,#"
    set the color of the foreground (edges) to the given r,g,b triple. The default is white (255,255,255).

-c"set background=#,#,#"
    and

-c"set bg=#,#,#"
    set the color of the background to the r,g,b triple. The default is near-black (0,0,1).

-c"set region_colors=#
    and

-c"set rc=#"
    determine whether to use the material color assigned to an object as the edge color. Valid values are 1 (on) and 0 (off). The default is off. Using region colors overides any foreground color setting.

-c"set detect_regions=#"
    and

-c"set dr=#"
    determine whether the boundary between two BRL-CAD regions is considered to be an edge. Valid values are 1 (on) and 0 (off). The default is off.

-c"set detect_distance=#"
    and

-c"set dd=#"
    determine whether a difference in hit distance between adjacent pixels defines an edge. Valid values are 1 (on) and 0 (off). The default is on.

-c"set detect_normals"
    and

-c"set dn=#"
    determine whether a difference in surface normals between adjacent pixels defines an edge. Valid values are 1 (on) and 0 (off). The default is on.

-c"set detect_ids"
    and

-c"set di=#"
    determine whether a difference in component id numbers between adjacent pixels defines an edge. Valid values are 1 (on) and 0 (off). The default is on.

-c"set overlaymode=#"
    and

-c"set ov=#"
    configure the overlay mode to be either on (1) or off (0). Overlay mode allows rtedge to write into an existing framebuffer. The framebuffer is specified with the -F option. and

-c"set max_dist=#"
    over-ride the maximum hit distance of neighboring pixels before being declared an edge. The default value is computed based on the size of the output image, approximately 1000 for the default image/fb size.

OCCLUSION CHECKING
Rtedge has ability to perform occlusion checking between two sets of BRL-CAD objects from the same database. Occlusion checking determines which set of geometry is closer to the eyepoint and thus should be rendered. The first set is that specified in the basic object list (after the database). This set will be rendered using edge detection. The second is specified using a -c option. Occlusion checking is most handy when combining rtedge renderings with rt renderings. The syntax for such compositions is daunting, but the results are cool.

-c"set occlusion_objects=
    and

-c"set oo=
    specify the second set of geometry.

-c"set occlusion_mode=#"
    and

-c"set om=#"
    determine how rtedge behaves when performing occlusion checking. There are three valid modes. Mode 2 is the default. mode 1 - An edge detected in the first set of geometry is written to the framebuffer if and only if it occludes the second set of geometry. The edge is colored according to the foreground or region colors options. mode 2 - All pixels that hit the first set of geometry that are not occluded by the second set are written to the framebuffer. Edges are rendered in the foreground or region color, non-edges are rendered in the background color. mode 3 - Like mode 2 except non-edge pixels are dithered to make the geometry semi-transparent.

EXAMPLES
Rtedge can be somewhat complicated to configure. These examples illustrate both simple and complex examples. Hopefully they will be enough to get you started. These examples use the havoc.g target description that may be found in the source distribution. Note that in practice it will usually be easiest to use the saveview command in mged to produce a script and then modify that script to run rtedge.
	rtedge -s 1024 -Fnew.pix havoc.g havoc
results in a 1024 by 1024 BRL-CAD image file showing the edges on a Havoc helicopter. The default settings are used, so the image has white edges on a black background. Edges exist where there are differences in component id, hit distance, surface normal, or between hits and misses. The command
	rtedge -s1024 -Fnew.pix -c"set fg=0,255,0 bg=255,0,0"
	havoc.g havoc
changes the edge color to be green and the background color to be red. The command
	rtedge -s1024 -Fnew.pix -c"set rc=1 dr=1"
	havoc.g havoc
activates region detection and uses the region colors for the edges. The remaining examples will illustrate how to use rtedge in concert with rt to produce interesting images. When merging rtedge and rt images, it is best to use saveview scripts. In mged configure your view, save it, and then open the file in a editor. Dupilcate the rt command block. After duplicating the block, change the second to rtedge. This script will overlay bright orange edges on the Havoc.
#!/bin/sh
rt -M -s1280 -Fnew.pix -C255/255/255\
 $*\
 havoc.g\
 havoc\
 2>> example1.log\
 <<EOF
viewsize 8.000e+03;
orientation 2.4809e-01 4.7650e-01 7.4809e-01 3.8943e-01;
eye_pt 2.2146e+04 7.1103e+03 7.1913e+03;
start 0; clean;
end;
EOF
rtedge -M -s1280 -Fnew.pix \
 -c"set dr=1 dn=1 ov=1"\
 -c"set fg=255,200,0" \
 $*\
 havoc.g\
 havoc\
 2>> example1.log <<EOF
viewsize 8.000e+03;
orientation 2.4809e-01 4.7650e-01 7.4809e-01 3.8943e-01;
eye_pt 2.2146e+04 7.1103e+03 7.1913e+03;
start 0; clean;
end;
EOF
Finally, this script will render the Havoc weapon systems in full color, render the edges on the remainder of the aircraft in black, and render the non-edges in dithered gray to make them semi-transparent. Note that when specifying the occlusion objects, the delimiting quotes must be escaped.
#!/bin/sh
rt -M -s1280 -Fnew.pix -C255/255/255 \
 $*\
 havoc.g\
 weapons\
 2>> example2.log <<EOF
viewsize 8.000e+03;
orientation 2.4809e-01 4.7650e-01 7.4809e-01 3.8943e-01;
eye_pt 2.2146e+04 7.1103e+03 7.1913e+03;
start 0; clean;
end;
EOF
rtedge -M -s1280 -Fnew.pix \
 -c"set dr=1 dn=1 om=3"\
 -c"set fg=0,0,0 bg=200,200,200"\
 -c"set oo=\"weapons\" "\
 $*\
 havoc.g\
 havoc_front havoc_middle havoc_tail landing_gear main_rotor\
 2>> example2.log <<EOF
viewsize 8.000e+03;
orientation 2.4809e-01 4.7650e-01 7.4809e-01 3.8943e-01;
eye_pt 2.2146e+04 7.1103e+03 7.1913e+03;
start 0; clean;
end;
EOF
In general, if you are mixing rt and rtedge renderings, and the objects being rendered are different, occlusion checking should be used.

SEE ALSO
mged(1), rt(1), fbserv(1), librt(3)

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

AUTHOR
Ronald Anthony Bowers
Michael John Muuss

COPYRIGHT
This software is Copyright (c) 2001-2008 United States Government as represented by the U.S. Army Research Laboratory. All rights reserved.

BUGS

Most deficiencies observed while using the rtedge program are usually with the librt(3) package instead.

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