<!-- Converted by db4-upgrade version 1.0 -->

<article xmlns="http://docbook.org/ns/docbook" version="5.0"
  xmlns:xi="http://www.w3.org/2001/XInclude"
>
  <info><title>Creating Primitive Shapes in <application>MGED</application></title>
    

    <xi:include href="../../books/en/tutorial_series_authors.xml" xpointer="Intro_MGED_Tutorial_Series_II_authors"/>

    <legalnotice>
       <para>Approved for public release; distribution is unlimited</para>
   </legalnotice>
  </info>

    <para xml:id="creating_primitive_shapes_overviewlist">
      In this lesson, you will:
      
      <itemizedlist mark="bullet">
	<listitem>
	  <para>Launch the <application>MGED</application> program.</para>
	</listitem>
	<listitem>
	  <para>Enter commands at the <application>MGED</application> prompt in the Command Window.</para>
	</listitem>
	<listitem>
	  <para>Use the <application>MGED</application> Graphical User Interface (GUI).</para>
	</listitem>
	<listitem>
	  <para>Open or create a new database when launching <application>MGED</application>.</para>
	</listitem>
	<listitem>
	  <para>Use the GUI to open or create a new database.</para>
	</listitem>
	<listitem>
	  <para>Title a database.</para>
	</listitem>
	<listitem>
	  <para>Select a unit of length for your design.</para>
	</listitem>
	<listitem>
	  <para>Select a primitive shape.</para>
	</listitem>
	<listitem>
	  <para>Create a primitive shape using the make command.</para>
	</listitem>
	<listitem>
	  <para>Use the Z command to clear the Graphics Window.</para>
	</listitem>
	<listitem>
	  <para>Draw a previously created shape using the draw command.</para>
	</listitem>
	<listitem>
	  <para>Use the erase command to delete an item in the Graphics Window display.</para>
	</listitem>
	<listitem>
	  <para>Create a sphere using the GUI menu.</para>
	</listitem>
	<listitem>
	  <para>Use the l command to list a shape's attributes or parameters.</para>
	</listitem>
	<listitem>
	  <para>Use the ls command to list the contents of the database.</para>
	</listitem>
	<listitem>
	  <para>Eliminate a shape or object from the database using the kill command.</para>
	</listitem>
	<listitem>
	  <para>Edit a command.</para>
	</listitem>
	<listitem>
	  <para>Use the q or exit commands to quit the program.</para>
	</listitem>
      </itemizedlist>  
    </para>
    <section xml:id="launching_mged"><info><title>Launching the <application>MGED</application> Program</title></info>
       

      <para>
	To launch the <application>MGED</application> program, type mged at the Terminal (tty) prompt and
	then press the ENTER key. This brings up two main windows: the <application>MGED</application>
	Command Window and the <application>MGED</application> Graphics Window (sometimes called the Geometry
	Window). Both windows will initially be blank, awaiting input from you. To
	leave the program at any time, at the Command Line type either the letter
	q or the word quit and then press the ENTER key.
      </para>


    </section>
    <section xml:id="entering_commands"><info><title>Entering Commands in the Command Window</title></info>
       
      
      <para>
	You can type in commands at the <prompt>mged&gt;</prompt> prompt. Many experienced UNIX users
	prefer this method because it allows them to quickly create a model (which
	we sometimes refer to as a "design") without having to point and click on
	a lot of options. The complete listing of editing commands and what they
	do can be found in Appendix A.
      </para>
      
      <caution>
	<para>
	  Check all typed entries before you press the ENTER key. If you find   
	  you made a mistake, simply press the BACKSPACE key until you have     
	  erased over the mistake and then re-type the information. Later you   
	  will get more experience editing text using <application>vi</application> and <application>emacs</application> command      
	  emulation.
	</para>
      </caution>
      
    </section>
    
    <section xml:id="using_gui"><info><title>Using the GUI</title></info>
      
      
      <para>
	Users who are more familiar with Microsoft Windows may prefer to use the
	GUI pull-down menus at the top of the Command or Graphics Window (they are
	the same in either window). The menus are divided into logical groupings
	to help you navigate through the <application>MGED</application> program.
      </para>
      
      <para>
	Before you can create a model, you need to open a new database either
	through the Terminal Window when starting <application>MGED</application> or through the GUI after
	starting <application>MGED</application>.
      </para>
    </section>
   
    <section xml:id="open_new_database"><info><title>Opening or Creating a New Database when Launching <application>MGED</application></title></info>
      
    
      <para>
	When launching <application>MGED</application>, you can open or create a database at the same time.
	At the shell prompt (usually a $ or %), in the Terminal Window, type mged
	followed by a new or existing database name with a .g extension. For
	example:
	
	<command>mged sphere.g[ENTER]</command>

      <informalfigure>
	<mediaobject>
	  <imageobject role="html">
	    <imagedata
               align="center"
               contentwidth="3.9in"
               scalefit="1"
               fileref="../../lessons/en/images/mged01_terminal.png"
               format="PNG"
             />
	  </imageobject>
	  <imageobject role="fo">
	    <imagedata
               align="center"
               width="3.9in"
               scalefit="1"
               fileref="../../lessons/en/images/mged01_terminal.png"
               format="PNG"
             />
	  </imageobject>


	  <caption>
	    <para>
	      Terminal Window
	    </para>
	  </caption>
	</mediaobject>
      </informalfigure>
	
	If you are creating a new database, a small dialog box asking if you want
	to create a new database named sphere.g will appear. Click on Yes, and a
	new database will be created. If sphere.g already exists, <application>MGED</application> will open
	the sphere.g database as the program is launched.
      </para>
    </section> 

    <section xml:id="create_new_database"><info><title>Using the GUI to Open or Create a Database</title></info>
      
  
      <para>
	Alternatively, once you have launched <application>MGED</application>, you can open an existing
	database or create a new database using the GUI menus (at the top of the
	Command or Graphics Window) by clicking on File and then either Open or
	New. Both options bring up a small dialog box. The Open dialog box will
	ask you to type in the name of an existing database. The New dialog box
	will ask you to type in the name of a new database. Click on OK to accept
	the database.
      </para>
      
      <para>
	For this lesson, create a new database called sphere.g. To do this, type
	sphere.g at the end of the path name, as shown in the following
	illustration. Click on OK to accept the database name.

      <informalfigure>
	<mediaobject>
	  <imageobject>
	    <imagedata align="center" fileref="../../lessons/en/images/mged01_commandwindow.png" format="PNG"/>
	  </imageobject>
	  <caption>
	    <para>
	      <application>MGED</application> Command Window with Database Dialog Box
	    </para>
	  </caption>
	</mediaobject>
      </informalfigure>

      <informalfigure>
	<mediaobject>
	  <imageobject>
	    <imagedata align="center" fileref="../../lessons/en/images/mged01_graphicswindow.png" format="PNG"/>
	  </imageobject>
	  <caption>
	    <para>
	      <application>MGED</application> Graphics Window
	    </para>
	  </caption>
	</mediaobject>
      </informalfigure>

	
	One advantage to using the GUI, if you aren't familiar with UNIX file
	management, is that this will show you your current path name, so you will
	know exactly where your database is going to be located. This can be
	especially helpful if you have a lot of directories or files to manage.
      </para>  
    </section>

    <section xml:id="assign_title"><info><title>Assigning a Title to Your Database</title></info>
      

      <para>
	You can title your new database to provide an audit trail for you or
	others who might use your database. After the prompt, in the Command
	Window, type title followed by a space and a name that reflects the
	database you are going to make. When you are done, press the ENTER key.
	For example:

	<userinput><prompt>mged&gt;</prompt> title MySphere[ENTER]</userinput>
	
	Note that in <application>BRL-CAD</application> versions prior to release 6.0, the title is limited
	to 72 characters.
      </para>  
    </section>
    
    <section xml:id="set_units"><info><title>Selecting a Unit of Length</title></info>
      
      
      <para>
	<application>MGED</application> uses millimeters for all internal mathematical processes; however,
	you can create your design using some other unit, such as feet. For this
	lesson, inches is used. To select inches, move your mouse pointer to the
	File menu at the top of the Command Window. Click on File and then
	Preferences. A new menu will appear. Select Units and then Inches. If you
	are not a "point-and-click" type of person and prefer a Command Line, then
	just type units in after the <application>MGED</application> prompt in the Command Window, followed
	by the ENTER key. The Command Line looks like:
	
	<userinput><prompt>mged&gt;</prompt> units in[ENTER]</userinput>
      </para>  
    </section>

    <section xml:id="select_primitive"><info><title>Selecting a Primitive Shape</title></info>
      
      
      <para>
	<application>MGED</application> provides a variety of primitive shapes (sometimes referred to as
	simply shapes or primitives) that you can use to build models. Each type
	of shape has parameters that define its position, orientation, and size. A
	listing of these shapes and their respective parameters is given in
	Appendix C.
      </para>
      
      <note>
	<para>
	  Historically, the word solid was used for what we now refer to as a   
	  primitive shape. This older terminology was sometimes difficult for   
	  new users to understand. If you see the word solid used in any        
	  <application>BRL-CAD</application> programs, documentation, or commands (e.g., in Appendix A),   
	  think primitive shape.  
	</para>
      </note>  
    </section>

    <section xml:id="create_sphere_cmd_line"><info><title>Creating a Sphere from the Command Line</title></info>
      

      <para>
	For this lesson, you are going to create a single sphere. There are two
	ways you can create a primitive shape. You can create all shapes through
	the Command Window and most shapes through the GUI.
      </para>
      
      <para>
	You can easily create a sphere from the prompt in the Command Window by
	typing just a few commands. At the <application>MGED</application> prompt, type:
	
	<command>make sph1.s sph[ENTER]  [Note: Use the digit 1, not the letter l] </command>

      </para>
      
      <para>
	This command tells the <application>MGED</application> program to:
	
	<informaltable frame="all">
	  <tgroup cols="3">
	    <tbody>
	      <row><entry>make</entry><entry>sph1.s</entry><entry>sph</entry></row>
	      <row><entry>Make a primitive shape</entry><entry>Name it sph1.s</entry>
	           <entry>Make the shape a sphere</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

      </para>

      <para>
	A default sphere will be created, and a wireframe representation of the
	primitive shape will appear in the Graphics Window. In Lesson 4, you will
	give your sphere a solid, three-dimensional look.
      </para>
      
      <para>
	This command will draw the primitive shape in the Graphics Window.
      </para>
    </section>

    <section xml:id="clear_window"><info><title>Clearing the Graphics Window</title></info>
      
      
      <para>
	To build another object or work on another primitive shape, you can easily
	clear the Graphics Window through the Command Window. At the Command Line
	prompt, type an uppercase Z (for zap) followed by ENTER.
      </para>
      
      <note>
	<para>
	  Before using the zap option, make sure you "activate" (i.e.,    
	  set the focus on) the Command Window. If you type a z and your cursor 
	  is still in the Graphics Window, you will send your design spinning.  
	  Typing a zero (0) will stop the spin.
	</para>
      </note>
    </section> 
    
    <section xml:id="draw_object"><info><title>Drawing a Previously Created Object</title></info>
      
      
      <para>
	To recall the sphere, type the command on the Command Line as follows:
	
	<command>draw sph1.s[ENTER]</command>
	
	This command tells the <application>MGED</application> program to:
	
	<informaltable frame="all">
	  <tgroup cols="2">
	    <tbody>
	      <row><entry>draw</entry><entry>sph1.s</entry></row>
	      <row><entry>Draw a previously created primitive shape</entry>
	           <entry>named sph1.s</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </para>
    </section> 
    
    <section xml:id="erase_from_window"><info><title>Erasing an Item from the Graphics Window</title></info>
      
      
      <para>
	You may occasionally want to erase a particular item from the display in
	the Graphics Window. You can use the erase command to remove the item
	without any file operation being performed; the item remains in the
	database. To delete the sph1.s object from the display, at the Command
	Window prompt, type:
	
	<command>erase sph1.s[ENTER]</command>
      </para>
    </section>     

    <section xml:id="create_sphere_gui"><info><title>Creating a Sphere Using the GUI</title></info>
      
      
      <para>
	Another way to create a sphere is to use the GUI menu system duplicated at
	the top of the Command and Graphics windows. Clear your Graphics Window by
	using the previously described Z command. Then, in the Graphics Window,
	select Create, and a drop-down menu will appear with the various
	primitive shape types available. Select sph (for sphere) under the
	Ellipsoids category. This will bring up a dialog box. Click in the empty
	text box and type sph2.s. Click on Apply  or press ENTER. A new sphere
	will be created and drawn in the Graphics Window. When you create a shape
	through the GUI, the shape will automatically be in edit mode so that you
	can change it as needed, and the shape's parameters-which define its
	position, orientation, and size-will be in view.
      </para>
    </section>

    <section xml:id="view_params"><info><title>Viewing a Shape's Parameters</title></info>
      

      <para>
	Sometimes when you are making a model, you might want to view a shape's
	parameters, such as height, width, or radius, in the Command Window. You
	can easily list the attributes of a shape by typing the l (for "list")
	command at the Command Window prompt as follows:
	
	<command>l shape_name[ENTER]</command><footnote><para>Note: The command is the lowercase letter l, NOT the number one.</para></footnote>
      </para>
      
      <note>
	<para>
	  Note: If you attempt to type in the Command Window and you see no     
	  words appearing there, chances are the focus has not been set on that 
	  window (i.e., keyboard input is still directed to another window).    
	  Depending on your system's configurations, the focus is set to a      
	  window either by moving the cursor into the window or clicking on the 
	  window.                           
	</para>
      </note>
      
      <para>
	An example of the dialog that might occur in the Command Window for the
	parameters or attributes of the first sphere you created is as follows:
	
	<literallayout class="normal">
<prompt>mged&gt;</prompt> <command>l sph1.s</command>
<computeroutput>
sph1.s: ellipsoid (ELL)

     V (1, 1, 1)

     A (1, 0, 0) mag=1

     B (0, 1, 0) mag=1

     C (0, 0, 1) mag=1

     A direction cosines=(0, 90, 90)

     A rotation angle=0, fallback angle=0

     B direction cosines=(90, 0, 90)

     B rotation angle=90 fallback angle=0

     C direction cosines=(90, 90, 0)

     C rotation angle=0, fallback angle=90
</computeroutput>
	</literallayout>
      </para>

      <para>
	Don't be concerned if you notice in the preceding output that <application>MGED</application> stores
	your sphere as an ellipsoid. In actuality, the sphere is just a special
	case of the ellipsoid (see Appendix C). Also, note that it is not
	important if the numbers in your output do not match what is shown in this
	example.
      </para>
      
      <para>
	Use the l command to list both sph1.s and sph2.s before continuing with
	this lesson.
      </para>
      
    </section>

    <section xml:id="list_db_contents"><info><title>Listing the Contents of a Database</title></info>
      

      <para>
	In addition to viewing a shape's contents, you might also want to list the
	contents of the database to see what items have been created. To view the
	database contents, type at the Command Window prompt:
	
	<command>ls[ENTER]</command>
      </para>
    </section>

    <section xml:id="kill_object"><info><title>Killing a Shape or Object</title></info>
      
      
      <para>
	Sometimes when creating a model, you may need to eliminate a shape or
	object from the database. The kill command is used to do this. For
	example, if you wanted to kill the sph1.s shape, you would type at the
	Command Window prompt:
	
	<command>kill sph1.s[ENTER]</command>
	
	Make another sphere through either the Command Window or the GUI and name
	it sph3.s. Once the sphere is made, use the kill command to eliminate it
	from the database by typing at the Command Window prompt:
	
	<command>kill sph3.s[ENTER]</command>
	
	You can tell the shape has been eliminated by using the ls command in the
	Command Window to list the contents of the database. At the Command Window
	prompt, type:
	
	<command>ls[ENTER]</command>
	
	You should see two shapes listed: sph1.s and sph2.s.
      </para>

      <note>
	<para>
	  Note: All changes are immediately applied to the database, so there   
	  is no "save" or "save as" command. Likewise, there is presently no    
	  "undo" command to bring back what you have deleted, so be sure you    
	  really want to permanently delete data before using the kill command. 
	</para>
      </note>
    </section>

    <section xml:id="editing_commands"><info><title>Editing Commands in the Command Window</title></info>
      
      
      <para>
	Occasionally, when you enter commands in the Command Window, you will make
	a mistake in typing. <application>MGED</application> can emulate either the <application>emacs</application> or <application>vi</application> syntax for
	Command Line editing. By default, the <application>emacs</application> syntax is used. See Appendix B
	for a list of keystrokes, effects, and ways to select between the two
	command sets.
      </para>
      
      <para>
	You can also use the arrow keys to edit commands. The left and right arrow
	keys move the cursor in the current Command Line. Typing ENTER at any
	location on the Command Line executes the command. Note that both the
	BACKSPACE and DELETE keys will delete one character to the left of the
	cursor.
      </para>
      
      <para>
	<application>MGED</application> keeps a history of commands that have been entered. The up and down
	arrow keys allow you to select a previously executed command for editing
	and re-execution.
      </para>  
    </section>
    
    <section xml:id="quitting"><info><title>Quitting <application>MGED</application></title></info>
      
      
      <para>
	Remember, to leave the program at any time, type from the Command Line
	either the letter q or the word quit and then press the ENTER key. You may
	also quit the program by selecting Exit from the File menu.
      </para>  
    </section>
    
    <section xml:id="creating_primitive_shapes_review"><info><title>Review</title></info>
      
      
      <para>
	In this lesson, you:
	
	<itemizedlist mark="bullet">
	  <listitem>
	    <para>Started the <application>MGED</application> program.</para>
	  </listitem>
	  <listitem>
	    <para>Entered commands in the Command Window.</para>
	  </listitem>
	  <listitem>
	    <para>Used the <application>MGED</application> GUI.</para>
	  </listitem>
	  <listitem>
	    <para>Created or opened a database using <application>MGED</application> naming conventions.</para>
	  </listitem>
	  <listitem>
	    <para>Used the GUI to create or open a database.</para>
	  </listitem>
	  <listitem>
	    <para>Titled a database.</para>
	  </listitem>
	  <listitem>
	    <para>Selected a unit of measure for a design.</para>
	  </listitem>
	  <listitem>
	    <para>Selected a primitive shape.</para>
	  </listitem>
	  <listitem>
	    <para>Created a primitive shape using the make command in the Command Window.</para>
	  </listitem>
	  <listitem>
	    <para>Cleared the screen of a design using the Z command.</para>
	  </listitem>
	  <listitem>
	    <para>Drew a previously created shape using the draw command.</para>
	  </listitem>
	  <listitem>
	    <para>Used the erase command to delete a shape from the Graphics Window display.</para>
	  </listitem>
	  <listitem>
	    <para>Used the GUI to create a primitive shape.</para>
	  </listitem>
	  <listitem>
	    <para>Used the l command to view a shape's parameters.</para>
	  </listitem>
	  <listitem>
	    <para>Used the ls command to list the contents of the database.</para>
	  </listitem>
	  <listitem>
	    <para>Used the kill command to eliminate a shape from the database.</para>
	  </listitem>
	  <listitem>
	    <para>Edited commands in the Command Window.</para>
	  </listitem>
	  <listitem>
	    <para>Used the q or Exit commands to quit the program.</para>
	  </listitem>
	</itemizedlist>
      </para>
    </section>
  </article>
