.. _hw_example:


***********************
Hello World Example
***********************

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

The function description is from the
`Image demo <https://matplotlib.org/stable/gallery/images_contours_and_fields/image_demo.html>`_ 
Matplotlib example.

This example demonstrates the basics of setting object resolution (rez), functional geometric mapping, surface color mapping,
shading, highlighting, creating a color bar, string representation of a surface object, setting axis limits,
axes view orientation, and finally, adding the surface object to the 3D viewing axis.
Also, defaults are used for the surface object name, color value name and the colormap.


.. literalinclude:: source/ex_hw_example.py
   :language: python
   :linenos:

object information
--------------------------------------------------

A string representation of the surface object using Python *str* provides the object
class, rez and basetype.  The number of vertices and faces are also included.
In this example, the figure text at the lower left of the figure
shows this object's information.  See line 37. 

The coordinate limits for the object may be determined from the object
dictionary property *bounds*.  The key,value pairs of this dictionary are
given in the :ref:`Surface3DCollection API <API_Surface3DCollection>` to the geometry properties.

The *bounds* object property may be useful for setting the Matplotlib axis
limits. For example in this case, line 33 may be replaced by::

    ax.set(xlim=0.8*surface.bounds['xlim'],
           ylim=0.8*surface.bounds['ylim'],
           zlim=0.8*surface.bounds['zlim'] )

For this figure, the factor *0.8* was used to enlarge the surface in the axes view.

object name
--------------------------------------------------

The surface *name* identifier is assigned, by default, to the geometry mapping function name.
In this example case, *Image_demo*.  Alternatively, the identifier can be directly assigned in the
object constructor, line 24, as::

    surface = s3d.PlanarSurface(rez, name='Image_demo' )

or using the geometry mapping method argument, line 25 , as::

    surface.map_geom_from_op( Image_demo, name='Image_demo' )

In this example, the object *name* property is used in the axis title on line 38.



color operation
--------------------------------------------------

This example uses colormapping in the z-direction.  The simple *vertical_position* function
was defined to demonstrate the use of the function name for the colorbar label on line 40.  
Alternatively, *lambda* functions could be used instead on line 26.
Using the surface geometry, line 26 could be written as::

    surface.map_cmap_from_op( lambda c: c[2] , cname='vertical_position' )

Or, using the z coordinate directly from the function, this line can be replaced by::

    surface.map_cmap_from_op( lambda c: Image_demo(c)[2] , cname='vertical_position' )    

Both approaches will produce identical results.  The second approach can be used prior to
geometric mapping.  The colormapping identifier, *cname*, is now explicitly assigned
by the method argument and can be used for the colorbar label.


colormap
--------------------------------------------------

The default colormap is used for this figure, which is *viridis*.
The Matplotlib example uses a *RdYlGn* colormap.  To use this colormap instead of the default, change
the default colormap on line 24 of the surface constructor as::

    surface = s3d.PlanarSurface(rez,cmap='RdYlGn')

or set the colormap used for mapping on line 26 as::

    surface.map_cmap_from_op( vertical_position, 'RdYlGn' )

Both approaches will produce the following:

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

2D 'image' plot
--------------------------------------------------

When the surface is viewed from the top using::

    ax.view_init(90,-90)

instead of line 35,  and **removing** line 27 for shading and highlighting, the view is similar
to the Matplotlib image demo.

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