=====================================
``grail.ms3d.highlights`` Module
=====================================
.. include:: ../../version.h
.. include:: ref.h

.. note:: New in version 7.00

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

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

This module contains functions for inserting "Virtual Elements" into the MineSight Viewer window, 
allowing one to effectively "highlight" existing elements, or create new "highlights" at arbitrary 
positions.

Note that all virtual elements created by this moudle can also be cleared and/or saved through
the Virtual Elements menu in MS3D.


-----------
Definitions
-----------

See grail.ms3d.element_ for the definitions of Point, Point List and Face List.

---------
Functions
---------

All :f:`add_*` functions return a token that can be passed to :f:`clear` to remove the new 
virtual element. 


:df:`add_marker(point)`
   Add a virtual marker.
   
  
:df:`add_polyline(pointList)`
   Add a virtual polyline.


:df:`add_polygon(pointList)`
   Add a virtual polygon.


:df:`add_shell(pointList, faceList)`
   Add a virtual shell.


:df:`from_element(element)`
   "Highlight" an existing element by creating a virtual element at the exact same position. 
   Returns a token just like the :f:`add_*` functions, which can be used to remove the new
   virtual element.

   Element must be an object of class :c:`Element` (see grail.ms3d.element_). Also note 
   that only Markers, Polylines, Polygons, Shells and Labels are supported. Passing any 
   other sort of element to this function will result in a :e:`ValueError`. 

   Labels are treated specially in that a marker is insterted at the centre of the label, 
   rather than a virtual label of the same dimensions being inserted.


:df:`clear(token)`:
   Clear a virtual element. Token is the object returned from one of the :f:`add_*` functions
   or :f:`from_element`.


:df:`clear_all()`:
   Clear all the virtual elements created by this module.


:df:`set_color(r, g, b)`:
   Set the color of the virtual elements created by this module. :a:`r`, :a:`g`, and :a:`b` must 
   be numbers between 0.0 and 1.0 (inclusive).


:df:`set_weight(weight)`:
   Set the displayed weight of the virtual elements created by this module. :a:`weight` must be a 
   positive number. 1.0 is the normal weight, so for example passing a value of 5.0 to this function
   would make all elements created by this module five times heavier than normal.