Evaluate Surface
================

Functionality
-------------

This node calculates points on the Surface corresponding to provided values of
U and V surface parameters. The values of U and V can be either provided
explicitly, or generated by the node to generate carthesian (rectangular) grid.

Inputs
------

This node has the following inputs:

* **Surface**. The surface to evaluate. This input is mandatory.
* **U**, **V**. Values of U and V surface parameter. These inputs are available
  only when the **Evaluate** parameter is set to **Explicit**, and **Input
  mode** parameter is set to **Separate**. The default value is 0.5.
* **Vertices**. Points at which the surface should be evaluated. Only two of
  three coordinates will be used; the coordinates used are defined by
  **Orientation** parameter. This input is available and mandatory if the
  **Evaluation mode** parameter is set to **Explicit**, and **Input mode** is
  set to **Vertices**.
* **SamplesU**, **SamplesV**. Number of samples along U and V direction, used
  to generate carthesian grid. These inputs are available only when the
  **Evaluate** parameter is set to **Grid**. The default value is 25.

Parameters
----------

This node has the following parameters:

* **Evaluate**. This determines how the values of surface's U and V parameters
  are defined. The available options are:

  * **Explicit**. U and V parameters are to be provided in inputs of this node.
    Depending on **Input mode** parameter, either **U** and **V** inputs, or
    **Vertices** input will be used.
  * **Grid**. The node will generate evenly-spaced carthesian grid with number
    of samples along U and V direction defined by **SamplesU** and **SamplesV**
    inputs, correspondingly.
   
  The default mode is **Grid**.

* **Input mode**. This parameter is available only when **Evaluate** parameter
  is set to **Explicit**. The available options are:

   * **Separate**. The values of U and V surface parameters will be provided in
     **U** and **V** inputs, correspondingly.
   * **Vertices**. The values of U and V surface parameters will be provided in
     **Vertices** input; only two of three coordinates of the input vertices
     will be used.
   
   The default mode is **Separate**.

* **Input orientation**. This parameter is available only when **Evaluate**
  parameter is set to **Explicit**, and **Input mode** parameter is set to
  **Vertices**. This defines which coordinates of vertices provided in the
  **Vertices** input will be used. The available options are XY, YZ and XZ. For
  example, if this is set to XY, then the X coordinate of vertices will be used
  as surface U parameter, and Y coordinate will be used as V parameter. The
  default value is XY.
* **Clamp**. This parameter is available only when **Evaluate** parameter is
  set to **Explicit**. This defines how the node will process the values of
  surface U and V parameters which are out of the surface's domain. The
  available options are:

   * **As is**. Do not do anything special, just pass the parameters to the
     surface calculation algorithm as they are. The behaviour of the surface
     when the values of parameters provided are out of domain depends on
     specific surface: some will just calculate points by the same formula,
     others will give an error.
   * **Clamp**. Restrict the parameter values to the surface domain: replace
     values that are greater than the higher bound with higher bound value,
     replace values that are smaller than the lower bound with the lower bound
     value. For example, if the surface domain along U direction is `[0 .. 1]`,
     and the value of U parameter is 1.05, calculate the point of the surface
     at U = 1.0.
   * **Wrap**. Wrap the parameter values to be within the surface domain, i.e.
     take the values modulo domain. For example, if the surface domain along U
     direction is `[0 .. 1]`, and the value of U parameter is 1.05, evaluate
     the surface at U = 0.05.

   The default mode is **As is**.

Outputs
-------

This node has the following outputs:

* **Vertices**. The calculated points on the surface.
* **Edges**. The edges of carthesian grid on the surface. This output is only
  available when the **Evaluate** parameter is set to **Grid**.
* **Faces**. The faces of carthesian grid on the surface. This output is only
  available when the **Evaluate** parameter is set to **Grid**.

Examples of usage
-----------------

The node used in **Grid** node to generate rectangular grid on the plane:

.. image:: https://user-images.githubusercontent.com/284644/78699409-4b25c380-791d-11ea-8671-2b304e108ed1.png

An example of **Explicit** mode usage:

.. image:: https://user-images.githubusercontent.com/284644/79249080-2dfd7180-7e96-11ea-810a-4a188536adc0.png

