=========================================
HowTo: Create a Polygon in a Geometry MSR
=========================================

.. include:: ..\version.h
.. include:: howto-reference.h

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


-------
Preface
-------

This document describes the process of creating a Polygon within a geometry MSR
via the embedded grail.ms3d.datamanager_ module. We will review the steps that
are required to in order to create an polygon element, a geometry object and
inserting that element into the geometry object.

This document *will not* cover using the grail.data.geometry_ module for
manipulating a geometry file. Instead it will concentrate on using the MS3D
datamanager.

Related Links
-------------

 * `HowTo: Create an Embedded Script`_ 
 * grail.ms3d.element_
 * grail.ms3d.datamanager_

Assumptions
-----------

It is assumed that you are familar with MineSightŪ 3D, and have an
understanding of the basic mechanics behind python scripting.

To execute a MineSightŪ Grail embedded script you must run the script
inside the MineSightŪ 3D. Any script that references the grail.ms3d
module, has this requirement.

See `HowTo: Create an Embedded Script`_ for more details on MineSightŪ
Grail Embedded scripting.


---------------
Getting Started
---------------

The easiest way to tackle this is to show a little example that inserts a small
polygon triangle. It will also apply a name and material to that element. 

.. python::

    from grail.ms3d import datamanager
    from grail.ms3d import element
        
    # (1)
    pointlist = [[100, 0, 0], [0, 100, 0], [0, 0, 100]]
    polygon = element.create_polygon(pointlist)

    # (2)
    polygon.set_name_and_material(
        "pit base", "pit base", create_if_not_exist=True
        )
        
    # (3)
    geo = datamanager.create_or_open_geometry("\\geometry1")

    # (4)
    geo.add_elements([polygon])

    geo.close()

Now lets go over each of the major features,

  - **(1)** The first thing we do is create a :c:`Element` object with our
    point list. The Geometry MSR's talk in :c:`Element` objects so we need to
    make sure we wrap our data properly.

  - **(2)** Attributed element's should have a name *and* a material. By using
    the :f:`set_name_and_material` we ensure both of them are set at the same
    time. The :a:`create_if_not_exist` flag is useful for automatically
    generating a material if it is not already in the material table.

  - **(3)**: Getting our :c:`GeometryMOB` (Geometry MineSight Object). This
    object is where we will place our elements. The
    :f:`create_or_open_geometry` will either create a new one or open an
    existing one within the datamanager. All paths are relative to the
    datamanager. 

  - **(4)**: Add the elements. We now use the :f:`add_elements` to add our
    element to the :c:`GeometryMOB` object. The :f:`add_elements` can take a
    list of multiple elements, but in this case we only have one so we just
    create a list on the fly.

After the above code is executed, you should have a "geometry1" object within
your datamanager, and in that object you will have a triangle that will have a
name and material of "pit base".

The grail.ms3d.element_ module as the ablity to create labels, shells
(surfaces), markers and polylines. The same logic shown above can be applied to
these modules.