======================================
HowTo: Use the Geometry Plane Equation
======================================
.. include:: ..\version.h
.. include:: howto-reference.h


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

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

Discusses how to define a plane equation within MineSightŪ Grail.
Specifically how to define a plane equation for use in the
grail.data.geometry_ module.

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

The Plane Equation appears frequently within the MineSightŪ Grail
library. One of those places is the grail.data.geometry_ module, which
is what this discussion focuses on.

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

This HowTo assumes that you are familiar with,

  - The Cartesian plane equation.
  - The grail.data.msr_ module.
  - How to insert data into the grail.data.msr_ module.

---------------------------
Defining the Plane Equation
---------------------------

The plane equation within MineSightŪ Grail is typically referred to via a
four float tuple. The four float tuples refer to the equation for a
plane, where each element in the tuple corresponds to the coefficients
of the actual equation,

::

 Ax+By+Cz+D=0 

The coefficients in the tuple are represented as,

::

 (A, B, C, D,) 

The A, B, and C define the direction of the normal to the plane. So for
a typical Plan view, where we want each plane to be horizontal, the
normal would point in the Z direction. Now D specifies the "height" for
the plane equation. However, in the plane equation that is used in the
grail.data.msr_ module the height is really -D. Therefore, we need
to negate D when we are specifying the plane equation. Thus to get a
plane of 2015.0, we would specify the coefficients to be,

::

 (0, 0, 1, -2015.0) 

That would correspond to a plane equation of,

::

 0x+0y+1z-2015.0 = 0 
        0x+0y+1z = 2015.0 
               z = 2015.0

More complex planes can be described by shifting the A, B, and C values
such to create a normal to the desired plane.