<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="rtwizard1">
  <refmeta>
    <refentrytitle>RTWIZARD</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">BRL-CAD</refmiscinfo>
    <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
  </refmeta>
  
  <refnamediv xml:id="rtwizard_name">
    <refname>rtwizard</refname>
    <refpurpose>Combines images from several raytracing techniques to produce complex images.</refpurpose>
  </refnamediv>
  
  <!-- body begins here -->
  <refsynopsisdiv xml:id="rtwizard_synopsis">
    <cmdsynopsis sepchar=" ">
      <command>rtwizard</command>    
      <arg choice="opt" rep="repeat"><replaceable>options</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
    
  <refsection xml:id="rtwizard_description"><info><title>DESCRIPTION</title></info>
    
    <para>
      <emphasis remap="I">rtwizard</emphasis> is a tool that automates the use of several
      BRL-CAD graphical programs to produce complex images.  There are two primary modes of operation - 
      a graphical client to guide users through the process of creating images, and
      a command line mode to allow users who already know what options they wish to
      use to quickly and automatically produce images.  Graphical
      mode is used when insufficient information is supplied to produce an image (unless
      an option specifically ruling out graphical mode is passed) and command line mode
      (used automatically when there <emphasis remap="I">is</emphasis> enough information
      to produce an image, unless GUI mode is specifically requested.)
      When in graphical mode, rtwizard is self explanatory.  This manual documents the command
      line options available when <emphasis remap="I">not</emphasis> operating in
      graphical mode.
    </para>

    <para>
      Images produced by <emphasis remap="I">rtwizard</emphasis> use three primary elements - 
      standard full color raytracings produced by <command>rt</command>, "line drawing" style
      images produced by <command>rtedge</command>, and a faded greyscale version of color
      raytracings produced with a variety of image manipulation tools included with BRL-CAD.
    </para>

    <para>
      The following options are recognized.
    </para>
    <variablelist remap="TP"><title>Input/Output Options</title>
     <varlistentry>
	<term><replaceable>geometry_file.g</replaceable></term>
	<listitem>
	  <para>
	    The first argument without an option flag (the leftmost argument is regarded as the first) that 
	    identifies an existing file with a .g suffix will be used to specify the working geometry database, 
	    unless overridden by the <option>i</option> option.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-i</option> <replaceable>geometry_file</replaceable></term>
	<term><option>--input</option> <replaceable>geometry_file</replaceable></term>
	<listitem>
	  <para>
	    Specifying the geometry database containing the objects to be raytraced.  The <option>i</option> option
            will override a non-flagged geometry file specification.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>output_file.imgformat</replaceable></term>
	<listitem>
	  <para>
	    The name and image format of the final output image generated by rtwizard.   When specifying the
	    output file name without using a flag, a .pix or .png image format extension is necessary.  The first
	    valid, unflagged output file name will be used unless overridden by the <option>o</option>.  If the 
	    output filename uses a .png image format extension, the Portable Network Graphics image format
	    will be used when writing out the file.  Otherwise, a standard BRL-CAD pix image will be generated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-o</option> <replaceable>output_file[.imgformat]</replaceable></term>
	<term><option>--output</option> <replaceable>output_file[.imgformat]</replaceable></term>
	<listitem>
	  <para>
	    The name (and optionally the image format) of the final output image generated by rtwizard.   If the 
	    output filename uses a .png file extension, the Portable Network Graphics image format
	    will be used when writing out the file.  Otherwise, a standard BRL-CAD pix image will be generated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-d</option> <replaceable>framebuffer_device</replaceable></term>
	<term><option>--fbserv-device</option> <replaceable>framebuffer_device</replaceable></term>
	<listitem>
	  <para>
	    The type of framebuffer to use when running fbserv to establish a framebuffer.  By default, 
            "/dev/mem" is used for a non-graphical framebuffer - other options include /dev/X, /dev/ogl, 
            and (Windows only) /dev/wgl. A /dev/mem framebuffer created by <command>rtwizard</command> 
            will be closed after the image generation is complete.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-p</option> <replaceable>port_number</replaceable></term>
	<term><option>--fbserv-port</option> <replaceable>port_number</replaceable></term>
	<listitem>
	  <para>
	    The number of the framebuffer port to use when running <command>fbserv</command> to establish a framebuffer.  An
            existing framebuffer may also be specified and used.  In the case of a pre-existing non-grapical framebuffer,
            <command>rtwizard</command> will not close the framebuffer automatically after the raytracing process is complete.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--gui</option></term>
	<listitem>
	  <para>
	    Run rtwizard's graphical interface, even if the command line options specify enough information 
	    to produce an image.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--no-gui</option></term>
	<listitem>
	  <para>
	    Run rtwizard on the command line, even if the command line options do not specify enough 
	    information to produce an image.  Overridden by --gui option if both are specified.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap="TP"><title>Model View Options - User Level</title>
    <para>
       When it comes to preparing the view for an RtWizard image, there are two options.  One
       is to use the "user level" controls, which reflect the view manipulations used by users
       on the command line.  The other is to use the "low level" specifiers, which are more
       typically used when <command>rtwizard</command> is run by automated scripts.  The two
       methods are mutually exclusive.
    </para>
      <varlistentry>
	<term><option>-a</option> <replaceable>angle (degrees)</replaceable></term>
	<term><option>--azimuth</option> <replaceable>angle (degrees)</replaceable></term>
	<listitem>
	  <para>Set azimuth angle.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-e</option> <replaceable>angle (degrees)</replaceable></term>
	<term><option>--elevation</option> <replaceable>angle (degrees)</replaceable></term>
	<listitem>
	  <para>
	    Set elevation angle.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--twist</option> <replaceable>angle (degrees)</replaceable></term>
	<listitem>
	  <para>
	    Set twist angle.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-P</option> <replaceable>angle (degrees)</replaceable></term>
        <term><option>--perspective</option> <replaceable>angle (degrees)</replaceable></term>
        <listitem>
          <para>                                                                                                      
            Set the perspective angle.                                                                                          
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-z</option> <replaceable>value</replaceable></term>
	<term><option>--zoom</option> <replaceable>value</replaceable></term>
	<listitem>
	  <para>
	    Set the zoom factor (smaller factor results in a smaller object in the view, and vice versa).
	  </para>
	</listitem>
      </varlistentry>
     <varlistentry>
	<term><option>--center</option> <replaceable>X Y Z</replaceable> </term>
	<listitem>
	  <para>
	    Set the xyz coordinates of the center of the view.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
 
    <variablelist remap="TP"><title>Model View Options - Low Level</title>
      <para>
         When specifying a low level view model is "all or nothing" - all options
         are required to correctly define the view.
      </para>
      <varlistentry>
         <term><option>--viewsize</option> <replaceable>view_size(mm)</replaceable></term>
        <listitem>
          <para>Set the view size.</para>
	</listitem>
	  </varlistentry>
      <varlistentry>
        <term><option>--orientation</option> <replaceable>element_1 element_2 element_3 element_4</replaceable> </term>
        <listitem>
          <para>                                                                                                      
            Set view quaternion.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--eye_pt</option> <replaceable>X Y Z</replaceable></term>
        <listitem>
          <para>                                                                                                      
            Set twist angle.                                                                                          
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>

    <variablelist remap="TP"><title>Image Generation Options</title>
      <varlistentry>
	<term><option>-c</option> <replaceable>obj1</replaceable> <replaceable>...</replaceable> </term>
	<term><option>--color-objects</option> <replaceable>obj1</replaceable> <replaceable>...</replaceable></term>
	<listitem>
	  <para>
	    Specify objects to render using full color. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-C</option> <replaceable>value</replaceable></term>
	<term><option>--background-color</option> <replaceable>value</replaceable></term>
	<listitem>
	  <para>
	    Set the background color to use when raytracing full color objects.  May use R/G/B or hex style color specification.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-g</option> <replaceable>obj1</replaceable> <replaceable>...</replaceable></term>
	<term><option>--ghost-objects</option> <replaceable>obj1</replaceable> <replaceable>...</replaceable></term>
	<listitem>
	  <para>
	    Specify objects to be rendered using ghosting.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-G</option> <replaceable>value</replaceable></term>
	<term><option>--ghosting-intensity</option> <replaceable>value</replaceable></term>
	<listitem>
	  <para>
	    Control the degree of visibility to use when rendring ghost objects.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-l</option> <replaceable>obj1</replaceable> <replaceable>...</replaceable></term>
	<term><option>--line-objects</option> <replaceable>obj1</replaceable> <replaceable>...</replaceable></term>
	<listitem>
	  <para>
	    Specify objects to render lines with using rtedge. 
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--line-color</option> <replaceable>value</replaceable></term>
	<listitem>
	  <para>
	    Specify color to use when rendering edge lines.  In addition to R/G/B and hex color specifications, the keyword "region" is also supported - in the latter case, region colors will be used for lines.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--non-line-color</option> <replaceable>value</replaceable></term>
	<listitem>
	  <para>
	    Specify color rtedge will use for non-line rendering.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-O</option> <replaceable>value</replaceable></term>
	<term><option>--occlusion</option> <replaceable>value</replaceable></term>
	<listitem>
	  <para>
	    Specify the occlusion mode rtedge will use for line rendering.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-t</option> <replaceable>image_type</replaceable></term>
	<term><option>--type</option> <replaceable>image_type</replaceable></term>
	<listitem>
	  <para>
            Specify the type of image to be rendered. The images produces by <command>rtwizard</command> 
            are categorized by <emphasis remap="I">picture type</emphasis> - there are six picture types 
            built on full color raytracing, ghosting, and <command>rtedge</command> line renderings.  
	    If a type is specified and insufficient information is supplied to generate that particular 
            image type, rtwizard will exit with an error.

          <table><info><title>RtWizard Image Types</title></info>

            <tgroup cols="3">
              <thead>
                <row>
                  <entry>Type</entry>
                  <entry>Name</entry>
                  <entry>Description</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>A</entry>
                  <entry>Simple Full-Color Image</entry>
                  <entry>Standard <command>rt</command> image.</entry>
                </row>
                <row>
                  <entry>B</entry>
                  <entry>Simple Line Drawing</entry>
                  <entry>Standard <command>rtedge</command> image.</entry>
                </row>
                <row>
                  <entry>C</entry>
                  <entry>Highlighted Image</entry>
                  <entry>Full Color <command>rt</command> image enhanced with <command>rtedge</command> lines.</entry>
                </row>
                <row>
                  <entry>D</entry>
                  <entry>Mixed Full Color and Edges</entry>
                  <entry>Like Type C, except objects may be selectively enhanced with <command>rtedge</command> lines.</entry>
                </row>
                <row>
                  <entry>E</entry>
                  <entry>Ghose Image with Inserts</entry>
                  <entry>A combination of Full Color elements and faded greyscale raytracings for context.</entry>
                </row>
                <row>
                  <entry>F</entry>
                  <entry>Ghost Image with Inserts and Edges</entry>
                  <entry>A Type E image further enhanced with <command>rtedge</command> lines.</entry>
                </row>

              </tbody>
            </tgroup>
          </table>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
   
  </refsection>

  <refsection xml:id="examples"><info><title>EXAMPLES</title></info>
    
    <para>
      Introduction
    </para>

    <example><info><title>Basic Color Image</title></info>
      
      <para>
      <userinput>rtwizard m35.g component</userinput>
      </para>
      <para>
	Results in a default color image of the m35 truck, output to rtwizard.pix
      </para>
    </example>

    <example><info><title>Line Drawing Image</title></info>
      
      <para>
      <userinput>rtwizard -d /dev/ogl m35.g -l component</userinput>
      </para>
      <para>
	Results in a line drawing of the m35 truck being display in an OpenGL framebuffer
      </para>
    </example>
   
    <example><info><title>Complex Image</title></info>
      
      <para>
      <userinput>rtwizard -d /dev/ogl -i m35.g -c component/power.train -g component -l component</userinput>
      </para>
      <para>
	Results in a view of the m35 truck highlighting the engine (in color) with the truck being shown as a ghosted, edged background.
      </para>
    </example>
 
    <example><info><title>Complex Image with Non-Default View</title></info>
      
      <para>
      <userinput>rtwizard -d /dev/ogl -i m35.g -c component/power.train -g component -l component -a -35 -e 15 -z 1.6</userinput>
      </para>
      <para>
	Same as the previous image, except viewing the truck from a different direction and zoomed in closer.
      </para>
    </example>
  </refsection>

  <refsection xml:id="see_also"><info><title>SEE ALSO</title></info>
    
    <para><citerefentry><refentrytitle>rt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>rtedge</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
  </refsection>

   <refsection xml:id="copyright"><info><title>COPYRIGHT</title></info>
    
    <para>This software is Copyright (c) 2001-2012 United States Government as
    represented by the U.S. Army Research Laboratory. All rights reserved.</para>
  </refsection>
  
  <refsection xml:id="bugs"><info><title>BUGS</title></info>
    
    <para>Most deficiencies observed while using the <command>rtwizard</command>
    program are a consequence of problems in commands used by rtwizard to generate
    images, such as rtedge</para>
  </refsection>
  
  <refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
    
    <para>Reports of bugs or problems should be submitted via electronic
    mail to &lt;devs@brlcad.org&gt;.</para>
  </refsection>
</refentry>
