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 the -s option. 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 (512 x 512).

-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 option and conflicts with -M option

-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 option and conflicts with -M option.

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

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

-c "set max_dist=#"
    and

-c "set md=#"
    override 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.

-c "set antialias"
    and

-c "set aa"
    configure whether to perform antialiasing on edges. Valid values are 1 (on) and 0 (off). The default is off.

-c "set both_sides"
    and

-c "set bs"
    configure whether to render both sides of an edge. result are edges twice as thick but that work well with antialiasing. Valid values are 1 (on) and 0 (off). The default is off.

OCCLUSION CHECKING

Rtedge has the 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=\"obj1 obj2 ... objN\
    and

-c"set oo=\"obj1 obj2 ... objN\
    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.

Example 1. Rtedge rendering of havoc.g

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 an 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 stderr (file descriptor 2).

COPYRIGHT

This software is Copyright (c) 2001-2012 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 a consequence of problems in librt(3).

BUG REPORTS

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

AUTHORS

Ronald Anthony Bowers

Michael John Muuss