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

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="coil1">

<refmeta>
  <refentrytitle>COIL</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
  <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
</refmeta>

<refnamediv xml:id="coil_name">
  <refname>coil</refname>
  <refpurpose>
    Generate various types of coils, using pipe control points calculated
    from coil dimensions.
  </refpurpose>
</refnamediv>

<!-- body begins here -->
<refsynopsisdiv xml:id="coil_synopsis">
  <cmdsynopsis sepchar=" ">
    <command>coil</command>    
    <arg choice="opt" rep="repeat"><replaceable>options ...</replaceable></arg>
    <arg choice="opt" rep="norepeat"><replaceable>name</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection xml:id="coil_description"><info><title>DESCRIPTION</title></info>
  
  <para>
    <command>coil</command> creates a pipe shape within <emphasis remap="I">coil.g</emphasis>
    or a user supplied file that implements a coil according to user provided dimensions.  
    If no dimensions are supplied defaults are used.  
  </para>
</refsection>

<refsection xml:id="coil_options"><info><title>OPTIONS:</title></info>
  
  <variablelist remap="TP">
    <varlistentry>
      <term><option>-n number_of_turns</option></term>
      <listitem>
	<para>
	  Sets the number of turns desired in the coil.  Must be an integer
	  value greater than zero - fractional turns are not supported.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-L</option></term>
      <listitem>
	<para>
	  Instructs the coil tool to create a "left handed" coil (default
	  is "right handed").  I.e. - from the starting point of the coil,
	  the coil winding will proceed in the -x direction for a left
	  handed coil, and in the +x direction for a right handed coil.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-d outer_diameter</option></term>
      <listitem>
	<para>
	  Sets the outer diameter of the coil in terms of millimeters.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-w wire_diameter</option></term>
      <listitem>
	<para>
	  Specify the diameter of the wire to be wound into a coil in terms
	  of millimeters.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-h helix_angle</option></term>
      <listitem>
	<para>
	  Specify the helix angle of the coil in degrees.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-p pitch</option></term>
      <listitem>
	<para>
	  Specify the pitch - distance between center of wire at beginning
	  and end of a single turn in mm.  Minimum value is equal to the
	  wire diameter.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-s cap_type</option></term>
      <listitem>
	<para>
	  Specify the capping style for the start of the coil.  The default is 0, with no
	  special styling.  1 is a squared off cap, 2 is a cap ground in the plane
	  normal to the vector of the coiling direction (the x-y plane), and 3
	  squares off the coil as well as grounding it.  Any non-default cap
	  will result in extra turns being added to the coil above those specified
	  with <option>-n</option>.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-e cap_type</option></term>
      <listitem>
	<para>
	  Specify the capping style for the end of the coil.  Default and options are
	  the same as for the starting cap.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-l length</option></term>
      <listitem>
	<para>
		Clamp the length of a coil to the specified value.  This option is currently limited - it will
		work only for uncapped coils and the helix angle must be zero.  To fit length, pitch will be
		adjusted first.  If pitch adjustments aren't enough, turns will be removed.  If both of those
		variables can't be adjusted to satisfy the length, wire diameter will be adjusted.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-S number_of_turns,outer_diameter,wire_diameter,helix_angle,pitch,winding_direction</option></term>
      <listitem>
	<para>
	  An advanced option that allows specification of multiple sections, with settings specified
	  in a comma delimited list as above.  All settings are required for each section - multiple
	  sections are defined in left to right order with the left-most section being the starting
	  section at the origin.  Capping styles are supported for multiple section coils, but the
	  presence of one or more sections specified with the <option>-S</option> will cause any
	  supplied parameters other than capping styles to be ignored.  There is very little sanity
	  checking here - many inputs will result in invalid pipe primitives and generate only an
	  empty database file.
	</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsection>

<refsection xml:id="coil_examples"><info><title>EXAMPLES</title></info>
  
  <para>
    The following will create coils exercising the various options.
  </para>
  <example><info><title>Creating a tight coil with default dimensions and ground ends</title></info>
    
    <para>
      <userinput>coil -s 3 -e 3</userinput>
    </para>
  </example>
  <example><info><title>Creating a coil with large helix angle and pitch</title></info>
    
    <para>
      <userinput>coil -h 40 -p 350</userinput>
    </para>
  </example>
  <example><info><title>Creating a multi-section coil with right handed winding</title></info>
    
    <para>
      <userinput>coil -S 10,1000,50,60,800,1 -S 10,1000,50,0,100,1</userinput>
    </para>
  </example>
</refsection>

<refsection xml:id="diagnostics"><info><title>DIAGNOSTICS</title></info>
  
  <para>
    Not much error checking yet - need to add.
  </para>
</refsection>

<info>
   <author>
     <personname>Clifford Yapp</personname>
     <contrib></contrib>
   </author>
</info>

<refsection xml:id="copyright"><info><title>COPYRIGHT</title></info>
  
  <para>
    This software is Copyright (c) 2009-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>
    There are many inputs that will be accepted but will attempt to generate
    invalid pipes.
  </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;, or via the "cadbug.sh" script.
  </para>
</refsection>
</refentry>
