RTWIZARD(1)

NAME

rtwizard - composite BRL-CAD images from color, ghost, and edge-line renderings

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

rtwizard [options] [-i] _geometry.g_ [-o] _output.{pix|png}_ [object ...]

rtwizard orchestrates several BRL-CAD utilities to produce composite images of geometry in prescribed styles. Full-color ray tracings are produced by rt(1), "hidden-line" edge drawings by rtedge(1), and semi-transparent greyscale "ghost" renderings by rt(1) combined with BRL-CAD image-manipulation tools. These layers are composited into a single image written to a pix(5) or PNG file, or displayed on a framebuffer.

When --cut-steps is supplied, rtwizard produces an animation in which a cutting plane advances through the rendered objects. The output may be APNG or MJPEG, and every full-color, ghost, and edge pass uses the same cutting plane for each frame.

rtwizard has two modes. With no arguments (or with --gui) it launches a wizard-style graphical interface that guides the user through building an image interactively. Given sufficient options on the command line it runs non-interactively, which is useful for scripting and bulk rendering. If a command line invocation lacks enough information to produce the requested image, rtwizard falls back to the GUI unless --no-gui is given.

The kind of image produced is governed by the --type option, or inferred from which object lists are supplied. The six picture types are:

Table 1. RtWizard Image Types
Type	Name	Description
A	Simple Full-Color Image	Standard rt image.
B	Simple Line Drawing	Standard rtedge image.
C	Highlighted Image	Full color rt image enhanced with rtedge lines.
D	Mixed Full Color and Edges	Like C, but objects are selectively edge-enhanced.
E	Ghost Image with Inserts	Full color elements over faded greyscale context.
F	Ghost Image with Inserts and Edges	A Type E image further enhanced with rtedge lines.

For compatibility with rt(1), the first unflagged argument naming an existing .g file is taken as the input geometry, and the first unflagged argument with a supported image extension (.pix, .png, .ppm, .bw, .dpix) is taken as the output file. Any remaining unflagged arguments are treated as color objects. Because this can be ambiguous, the -i and -o flags are preferred.

OPTIONS

-h, --help: Print the options summary and exit.
--help-dev: Print the developer/programmatic options and exit.
-i filename, --input-file filename: Input .g geometry database. Overrides any unflagged .g argument.
-o filename, --output-file filename: Output image file. A .png extension produces a PNG image; otherwise a BRL-CAD pix(5) image is written. Other supported extensions are .ppm, .bw, and .dpix. In cutting-plane animation mode, .png and .apng produce APNG while .avi and .mjpg produce MJPEG.
-s , --size: Width and height of a square output image, in pixels (default 512). Overridden per-axis by -w and -n.
-w , --width: Output image width in pixels (overrides the width from -s).
-n , --height: Output image height in pixels (overrides the height from -s).
--cut-steps #: Produce a cutting-plane animation containing exactly this many frames. The value must be at least 2. The first frame is just before clipping begins and the last is just before the rendered bounds are fully clipped.
--cut-direction x/y/z: Model-space direction in which the cutting plane advances. The vector is normalized internally; reversing it reverses the animation. If omitted, the plane advances from the eye into the resolved render view.
--animation-fps #: Animation playback rate in frames per second (default 10).
-t A|B|C|D|E|F, --type A|B|C|D|E|F: Picture type to produce (see the table above). If a type is requested but the supplied object lists are insufficient for it, rtwizard exits with an error.
-c obj[,…], --color-objects obj[,…]: Comma-separated list of objects to render in full color. Quote the list if names contain spaces (e.g. -c "obj1,obj 2").
-l obj[,…], --line-objects obj[,…]: Comma-separated list of objects to render as edge lines.
-g obj[,…], --ghost-objects obj[,…]: Comma-separated list of objects to render as ghosted (faded) context.
-a angle, --azimuth angle: Set the azimuth view angle, in degrees.
-e angle, --elevation angle: Set the elevation view angle, in degrees.
--twist angle: Set the twist view angle, in degrees.
-z value, --zoom value: Zoom factor as a multiplier on the default view size. Values greater than one enlarge the object; values less than one shrink it.
--center x/y/z: Set the xyz coordinates of the view center.
--eye_pt x/y/z: Set the eye point. Part of a complete low-level view specification (with --viewsize and --orientation); a complete low-level specification overrides the high-level view options.
--viewsize value: Set the view size directly (low-level view specification).
--orientation x/y/z/w: Set the view orientation quaternion (low-level view specification).
-P angle, --perspective angle: Set the perspective angle, in degrees.
-C color, --background-color color: Background color for full-color ray tracing, as R/G/B or hex (default white).
--line-color color: Color for edge lines, as R/G/B or hex. The keyword "region" uses each region’s own color for its lines.
--non-line-color color: Color used for the non-line areas of edge renderings.
-G value, --ghost-intensity value: Visibility of ghosted objects (default 6.0).
-O , --occlusion: Occlusion mode (1 to 3) for line rendering (default 1). See rtedge(1).
--ao-samples #: Number of ambient-occlusion samples per ray. Zero disables ambient occlusion (default 0).
--ao-radius value: Maximum ambient-occlusion radius. Zero uses rt's unbounded default.
--gui: Force the graphical interface even when the command line specifies enough information to produce an image.
--no-gui: Force command-line operation even when the supplied information is insufficient. Overridden by --gui if both are given.
-d device, --fbserv-device device: Framebuffer device for fbserv(1) to use instead of the default memory-only interface (e.g. -d /dev/wgl). See fbhelp(1) for available devices. A framebuffer started by rtwizard is closed automatically after image generation.
-p , --fbserv-port: TCP port for the fbserv(1) framebuffer. An existing framebuffer server may be reused; in that case rtwizard leaves it open after rendering.
--benchmark: Benchmark mode: disable randomness for reproducible timing.
--cpu-count #: Number of CPUs to use.
--pid-file filename: File used for tracking process IDs.
--log-file filename: Write debugging output to this file.
-v , --verbose: Set the verbosity level.

EXAMPLES

Example 1. Highlighted color-plus-edge image at a custom view

rtwizard -i m35.g -c component/power.train -g component -l component \
         -a -35 -e 15 -z 1.6 -o m35.png

Render the m35 sample model with its power train highlighted in full color over a ghosted, edge-lined truck body, viewed from azimuth -35 and elevation 15 and zoomed in 1.6x, saving the result as a PNG image.

Example 2. Bulk rendering on the command line

for g in *.g; do
    rtwizard --no-gui -t A -i "$g" -c all -s 1024 -o "${g%.g}.png"
done

Non-interactively produce a 1024x1024 full-color image of the "all" object in every .g file in the current directory, naming each output after its database. --no-gui ensures the script never blocks on the GUI.

Example 3. Live preview on a framebuffer

rtwizard -d /dev/wgl -i m35.g -l component

Display a line drawing of the m35 truck in an OpenGL framebuffer window rather than writing it to a file.

Example 4. Cutting-plane animation

rtwizard --no-gui -i model.g -c all -o cutaway.apng \
         --cut-steps 30 --cut-direction 0/0/-1 --animation-fps 12

Creates a 30-frame APNG with the cutting plane advancing in the negative Z direction. Use a .png or .apng output for APNG and .avi or .mjpg for MJPEG. Picture types using edge lines and the ambient-occlusion options may be combined with the animation options.