============================
``grail.ip.geometry`` Module
============================
.. include:: ../../version.h

.. contents:: Table of Contents
   :backlinks: top

--------
Overview
--------

Provides a script writer with the ability to quickly add a geometry to
the current Edit geometry.  A geometry is composed by setting
specifications within a dictionary and then passing those specifications
to the :f:`vSetGeometry` function.

The :file:`ip-label.py` illustrates the creation of labels using this
module.

--------
Function
--------

:df:`vSetGeometry(geometrydict)`
  Creates a geometry with the specifications outlined in the
  :a:`geometrydict`. This function will insert the geometry into an
  existing Edit Object. If an Edit Object does not exist, a Edit Object
  Browser will appear asking the user to select the object to make an
  Edit Object.
  
  :f:`vSetGeometry` will return :d:`1` if the it successfully added the
  geometry to a user selected edit object. It will return :d:`0` if the
  user selected CANCEL when they were presented the Edit Object Browser
  dialog.

  The geometry dictionary should have the following key-value pairs,

     :a:`Type`
       Can be either one of the following strings: "Polyline", "Polygon"
       "Marker", "Label", and "Shell". String value is case sensitive.

     :a:`PointList`
       The standard list of point triplets of the form::

        [[x0, y0, z0], ..., [xN, yN, zN]]

     :a:`FaceList`
       A list of vertex indice triples. In the form::

         [[v0_0, v0_1, v0_2], ..., [vN_M, ...]]

       where the first each triplet corresponds to a face. The face list
       definition used above is *not* the same as the one used in the
       grail.ag_ module.

.. _grail.ag: ../lib-grail-ag.html                

     :a:`NumFaces`
       The length of the list supplied to :a:`FaceList`.

     :a:`NumPoints`
       The length of the list supplied to :a:`PointList`.

     :a:`Values`
       If the :a:`Type` is a "Label", then the list of strings in this
       location will be used as individual lines for the label.

     :a:`UpVect`
       If the :a:`Type` is a "Label", then the *up* direction for the
       label is defined as a three point list of the form,

          [xi, zi, yi]

       Generally you will use the value: [0., 1., 0.].

     :a:`RightVect`
       If the :a:`Type` is a "Label", then the *right* direction for the
       label is defined as a three point list of the form,
       
          [xi, zi, yi]
          
       Generally you use the value: [1., 0., 0.].

     :a:`Planar`
       Set to 1 if the geometry is planar, otherwise set to 0.