.. role:: blue
   :class: blue

Elementary Surface Construction
===============================
.. _Elementary_Surface_Construction_:

.. kernel version: 118056

The function

.. code-block:: cpp

   MbResultType ElementarySurface( const MbCartPoint3D & point0,
                                   const MbCartPoint3D & point1,
                                   const MbCartPoint3D & point2,
                                         MbeSpaceType    surfaceType,
                                         MbSurface *&    result );

constructs an elementary surface.

The input parameters of the function are:

- **point0** - a point that defines the origin of the local coordinate system of the surface.
- **point1** - a point that defines the direction of the **axisX** or **axisZ** axis (depending on the surface type) of the local coordinate system and the height of the surface.
- **point2** - a point that defines the direction of the **axisY** axis of the local coordinate system.
- **surfaceType** - a surface type.

The output parameter of the function is the constructed surface **result**.

If successful, the function returns :blue:`rt_Success`; otherwise, it returns an error code from the :ref:`MbResultType <MbResultType_>` enumeration.

The function is declared in the *action_surface.h* file.

The **surfaceType** parameter defines the type of the surface to be created.
The control points **point0**, **point1** and **point2** define the local coordinate system and dimensions of the elementary surface.
The point **point0** defines the origin of the local coordinate system.
Table shows the surface type, the axis of the local coordinate system, and the quantity defined by the point **point1** for the creation of a surface of the **surfaceType** type:

.. table:: 

   +-------------------+---------------------+--------------------------------------------+
   | **surfaceType**   | **Surface type**    | The point **point1** defines               |
   +===================+=====================+============================================+
   | st_Plane          | plane               | **axisX**                                  |
   +-------------------+---------------------+--------------------------------------------+
   | st_CylinderSurface| cylindrical surface | **axisZ**, height                          |
   +-------------------+---------------------+--------------------------------------------+
   | st_ConeSurface    | conical surface     | **axisZ**, height                          |
   +-------------------+---------------------+--------------------------------------------+
   | st_SphereSurface  | spherical surface   | **axisZ**                                  |
   +-------------------+---------------------+--------------------------------------------+
   | st_TorusSurface   | toroidal surface    | **axisX**, major radius                    |
   +-------------------+---------------------+--------------------------------------------+

The point **point1** defines the height of a cylindrical surface, the height of a conical surface, and the major radius of a toroidal surface.
The point **point2** defines the radius of a cylindrical surface, the radius of a conical surface and a cone half-angle, the radius of a sphere, and the minor radius of a toroidal surface.

When constructing a plane, the points **point0**, **point1**, and **point2** define the local coordinate system of the plane with the origin at the point **point0**.
The **axisX** axis of the local coordinate system of the plane is directed from the point **point0** to the point **point1**; the **axisY** axis of the local coordinate system of the plane is orthogonal to the **axisX** axis and directed toward the point **point2**.
The domain of the first parameter is equal to twice the distance between the points **point0** and **point1**.
The domain of the second parameter is equal to twice the distance between the point **point0** and the projection of the point **point2** onto the **axisY** axis, Fig. 1:

.. figure:: /MODELER/SURFACE_CONSTRUCTION_METHODS/pictures/M.5.1.1.png
   :width: 12cm
   :align: center

.. rst-class:: fig-caption

   Fig. 1

When constructing a cylindrical surface, the point **point0** defines the center of the bottom base of the cylinder, where the origin of the local coordinate system is located.
The point **point1** defines the center of the top base of the cylinder.
The **axisZ** axis of the local coordinate system of the surface is directed from the point **point0** to the point **point1**.
The point **point2** together with the previous points defines the plane of the **axisX** and **axisZ** axes of the local coordinate system of the surface.
The distance between the points **point0** and **point1** defines the height of the cylindrical surface; the distance from the **axisZ** axis to the point **point2** defines the radius of the cylindrical surface, Fig. 2:

.. figure:: /MODELER/SURFACE_CONSTRUCTION_METHODS/pictures/M.5.1.2.png
   :width: 12cm
   :align: center

.. rst-class:: fig-caption

   Fig. 2

The cylindrical surface is described in the section :ref:`Cylindrical Surface MbCylinderSurface <MbCylinderSurface_Cylindrical_Surface_>`.

When constructing a conical surface, the point **point0** defines the apex of the cone, where the origin of the local coordinate system is located.
The point **point1** defines the center of the cone base and the direction of the **axisZ** axis of the local coordinate system of the cone.
The point **point2** together with the previous points defines the plane of the **axisX** and **axisZ** axes of the local coordinate system of the surface.
The distance between the points **point0** and **point1** defines the height of the conical surface.
The point **point2** defines the cone half-angle, when the point **point2** lies on the conical surface, Fig. 3:

.. figure:: /MODELER/SURFACE_CONSTRUCTION_METHODS/pictures/M.5.1.3.png
   :width: 12cm
   :align: center

.. rst-class:: fig-caption

   Fig. 3

The conical surface is described in the section :ref:`Conical Surface MbConeSurface <MbConeSurface_Conical_Surface_>`.

When constructing a spherical surface, the point **point0** defines the center of the sphere, where the origin of the local coordinate system is located.
The **axisZ** axis of the local coordinate system of the surface is directed from the point **point0** to the point **point1**.
The point **point2** together with the previous points defines the plane of the **axisX** and **axisZ** axes of the local coordinate system of the surface.
The distance between the points **point0** and **point2** defines the radius of the spherical surface, Fig. 4:

.. figure:: /MODELER/SURFACE_CONSTRUCTION_METHODS/pictures/M.5.1.4.png
   :width: 12cm
   :align: center

.. rst-class:: fig-caption

   Fig. 4

The spherical surface is described in the section :ref:`Spherical Surface MbSphereSurface <MbSphereSurface_Spherical_Surface_>`.

When constructing a toroidal surface, the point **point0** defines the center of the torus, where the origin of the local coordinate system is located.
The **axisX** axis of the local coordinate system of the surface is directed from the point **point0** to the point **point1**.
The point **point2** together with the previous points defines the plane in which the **axisX** and **axisZ** axes of the local coordinate system of the surface lie.
The distance between the points **point0** and **point1** defines the major radius of the torus; the distance between the points **point1** and **point2** defines the minor radius of the torus, Fig. 5:

.. figure:: /MODELER/SURFACE_CONSTRUCTION_METHODS/pictures/M.5.1.5.png
   :width: 12cm
   :align: center

.. rst-class:: fig-caption

   Fig. 5

The toroidal surface is described in the section :ref:`Toroidal Surface MbTorusSurface <MbTorusSurface_Toroidal_Surface_>`.

In the test application *test.exe*, the construction of an elementary surface from the given points is performed by the menu command «Create→Surface→Elementary».