===============================================
HowTo: Efficiently Swapping Y and Z Coordinates
===============================================

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

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

-------
Problem
-------

You need to swap Y and Z coordinates (indices 1 and 2) quickly in a
point or point list.

--------
Solution
--------

In the grail.mstype_ module there are two utilities for quickly
swapping points. 

.. _grail.mstype: ../Library_Reference/lib-grail-mstype.html

If you want to quickly swap points in a pointlist you would use the
:f:`mstype.nPointList_YZSwap` as follows,

   .. Python::

      >>> from grail import mstype
      >>> pointList = [[1, 2, 3], [10, 20, 30], [100, 200, 300]]
      >>> mstype.nPointList_YZSwap(pointList)
      >>> print pointList
      [[1, 3, 2], [10, 30, 20], [100, 300, 200]]

   and if we re-run the routine we will get back our original point list.

   .. Python::

       >>> mstype.nPointList_YZSwap(pointList)
       >>> print pointList
       [[1, 2, 3], [10, 20, 30], [100, 200, 300]]

if you wanted to run it just on a point, you would do the following
using :f:`mstype.nPoint_YZSwap`,

   .. Python::

      >>> from grail import mstype
      >>> point = [1, 2, 3]
      >>> mstype.nPoint_YZSwap(point)
      >>> print point
      [1, 3, 2]

Both routines modify the contents of the point or pointlist *in place*.
If you don't want to modify your data you can use the less efficient
:f:`mstype.Point_YZSwap` and :f:`mstype.PointList_YZSwap` functions.


---------
Dicussion
---------

The reason you may have to swap these values is due to the fact that you
are working closer to the graphical subsystem. In graphics the "z"
coordinate corresponds to a direction that points out of the screen.
Making this swap gives elevation its natural direction when viewing the
data.