.. _basic_coor_tut:

.. role::  raw-html(raw)
    :format: html



*****************************
Coordinates and Functions
*****************************

There are four basic surface classes, each with a native coordinate system.
These surfaces provide a basic network of points which can be mapped using functional, image
or data methods.

Mapping for any surface is done in the respective native coordinates:

=======================    ==============================        ===================
Class                      Native Coordinates                    Geometric Shape
=======================    ==============================        ===================
PlanarSurface              x,y,z                                 square plate
PolarSurface               r, :raw-html:`θ`, z             circular disk
CylindricalSurface         r, :raw-html:`θ`, z             cylinder
SphericalSurface           r, :raw-html:`θ , φ`        sphere
=======================    ==============================        ===================

Surfaces are normalized to be contained within a x,y,z domain, with
center at the (0,0,0) and extending from -1 to 1 on each axis.  Scaling can be performed
either through the mapping methods or by a transform or scaling class methods.

.. note::

   The four surface classes are derived from the same base class and use the same
   mapping method names with the same arguments, only differing in the native coordinates
   which are used in function definitions. 

   Arguments passed to user-defined functions and their return values are Numpy arrays.


Each of the ...Surface classes have a class method which returns transformed coordinates ABC::

   ABC = ...Surface.coor_convert(abc,tocart)

where *abc* is a 3XN numpy array of coordinates. When *tocart* is False (default value), *abc*
is interpreted as native coordinates and returns the native coordinates.  Otherwise,
when set to True, *abc* is interpreted as native coordinates and the return is in *xyz*
coordinates.




Function Coordinates
=========================================================================================

In the previous tutorial, the example surface was of type PlanarSurface.  As a result,
the function used to define the surface geometry used x,y,z Cartesian coordinates.
The argument and return values of that function used the same xyz coordinates.
This function was::

    def planarfunc(xyz) :
        x,y,z = xyz
        r = np.sqrt( x**2 + y**2)
        Z = np.sin( 6.0*r )/2
        return x,y,Z

To use polar coordinates, a PolarSurface object is used with a function defined in
polar coordinates as:

.. literalinclude:: source/hw_polar.py
   :language: python
   :linenos:
   :emphasize-lines: 14,15

The only changes from the previous example are the use of a PolarSurface, line 14, and to use
the *polarfunc* function for the mapping operation, line 15.  The resulting plot is:

.. image:: images/hw_polar.png


.. _planar_coor_tut:

Planar
-----------------------------------------------------------------------------------------

The coordinate system for the PlanarSurface object is shown below. The
initial surface coordinates before mapping all have z=0.

.. image:: images/tut_plate.png
   :class: sphx-glr-single-img

For a PlanarSurface, the geometric mapping function will have the form:

.. literalinclude:: source/tut_codefrag_1.py
   :language: python
   :lines: 1-6




.. _polar_coor_tut:

Polar
-----------------------------------------------------------------------------------------

The coordinate system for the PolarSurface object is shown below. The
initial surface coordinates before mapping all have z=0 with
the radial coordinate domain :raw-html:`0 ≤ r ≤ 1`.



.. image:: images/tut_disk.png
   :class: sphx-glr-single-img

For a PolarSurface, the geometric mapping function will have the form:


.. literalinclude:: source/tut_codefrag_1.py
   :language: python
   :lines: 11-16



.. _cylindrical_coor_tut:

Cylindrical
-----------------------------------------------------------------------------------------

The coordinate system for the CylindricalSurface object is shown below. The
initial surface coordinates before mapping all have r = 1 with
the angular coordinate domain :raw-html:`0 ≤ θ < 2π` and the vertical
domain :raw-html:`0 ≤ z ≤ 1`.



.. image:: images/tut_cylinder.png
   :class: sphx-glr-single-img

For a CylindricalSurface, the geometric mapping function will have the form:


.. literalinclude:: source/tut_codefrag_1.py
   :language: python
   :lines: 21-26




.. _spherical_coor_tut:

Spherical
-----------------------------------------------------------------------------------------

The coordinate system for the SphericalSurface object is shown below. The
initial surface coordinates before mapping all have r = 1 with
the angular coordinate domain :raw-html:`0 ≤ θ < 2π` and the vertical
domain :raw-html:`0 ≤ φ ≤ π`.

.. image:: images/tut_sphere.png
   :class: sphx-glr-single-img

For a SphericalSurface, the geometric mapping function will have the form:


.. literalinclude:: source/tut_codefrag_1.py
   :language: python
   :lines: 31-36




.. _param_function:


Parametric Functions
=========================================================================================


To exemplify plotting parametric functions, first consider a 2D line plot of
a simple power function based on the
`Simple Plot <https://matplotlib.org/stable/tutorials/introductory/quick_start.html#coding-styles>`_
example from matplotlib.


.. image:: images/tut_simple_plot.png
   :class: sphx-glr-single-img


Write the script in a three-step process: define the function, create the 'pseudo' line objects, 'add' the lines
to the plot axis.


.. literalinclude:: source/tut_simple_plot.py
   :language: python


For 3D surfaces, use an analogous function definition:  the first argument is a coordinate location, the second
argument is the function parameter.

.. literalinclude:: source/tut_codefrag_1.py
   :language: python
   :lines: 41-47


So, to plot a parametric function of the previous 3D example using the three-step process:

.. literalinclude:: source/tut_parametric_3D.py
   :language: python
   :emphasize-lines: 17,19,21

Which produces:

.. image:: images/tut_parametric_3D.png
   :class: sphx-glr-single-img

Both the 2D and 3D plots first necessitate the construction of coordinates at which the function is to be
evaluated.  The 2D plot explicitly uses the Numpy *linspace* method.  The 3D plot uses the predefined
network of coordinates for a PlanarSurface object. 

Using polor coordinates, the mathematical expression can be more clearly expressed
as a function in native coordinates as:

.. literalinclude:: source/tut_parametric_3D_p.py
   :language: python
   :lines: 16-18

then polar surface objects are similarly constructed:

.. literalinclude:: source/tut_parametric_3D_p.py
   :language: python
   :lines: 20-25
   :emphasize-lines: 2,4,6

with results:

.. image:: images/tut_parametric_3D_p.png
   :class: sphx-glr-single-img

This example demonstrates the object-oriented approach to 3D surface plotting.  In Matplotlib, the
axis is an object.  With S3Dlib, surfaces are also considered objects and can be operated on
separately from the axis object.  In this example, one surface object was created from three 
surface objects through simple addition.  Then, that single surface object was added to the axis object.


This method of using a parametric function is demonstrated in numerous :ref:`example`.
The :ref:`dipole` example uses multiple surfaces on a single 3D axis.  The :ref:`param_set` example
plots each surface on an individual 3D axis.