.. role:: blue
   :class: blue

MbCharacterCurve3D Character Curve
==================================
.. _MbCharacterCurve3D_Character_Curve_:

.. kernel version: 

The :blue:`MbCharacterCurve3D` class is declared in the *cur_character_curve3d.h* file.

A symbolic curve is defined by the coordinate functions *xFunction*,
*yFunction*, *zFunction*, the local coordinate system
:ref:`MbPlacement3D <MbPlacement3D_Local_Coordinate_System_>` **position** of the functions, the transformation matrix
**transform**, the boundary values of the parameter domain
*tmin* and *tmax*, the periodicity flag of the curve
*closed*, and the type of the coordinate system (Cartesian, cylindrical,
spherical) *coordinateType* in which the coordinate
functions are specified. The curve also has some additional data that is optional
and is used to speed up the curve methods.

The coordinate functions *xFunction*\(t), *yFunction*\(t), *zFunction*\(t)
of the symbolic curve are scalar functions of the common parameter
*t* and are given as symbolic expressions. For each symbolic
expression, lexical analysis is performed and a tree is built that
computes the value of the symbolic expression for a given parameter and
the derivatives of the symbolic expression with respect to the parameter. The curve
parameter *t* takes values on the segment *tmin* ≤ *t* ≤ *tmax*.

In the :blue:`PointOn`\( double & *t*,
:ref:`MbCartPoint3D <MbCartPoint3D_Radius_Vector_of_Point_in_3D_Space_>` & **r**) method, the radius vector of the curve **r** is described by the vector function

.. math::

   \mathbf{r}(t) = [xFunction(t)\ yFunction(t)\ zFunction(t)].

The character curve is shown in Fig. 1:

.. figure:: /MODELER/CURVES/pictures/O.4.13.1.png
   :width: 15cm
   :align: center

   Fig. 1

The curve can be periodic. The symbolic expressions on the curve domain
must represent continuous, finite, and single-valued
functions.

The parser of input expressions recognizes basic
mathematical operations with respect to priorities and parentheses: addition (+),
subtraction (-), multiplication (*), division (/), exponentiation (^),
and unary minus (-). Operations are performed on variables,
constants, and functions.

The parser recognizes the names of basic mathematical
functions listed in Table 1:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - **Function name**
     - **Description**
   * - sin
     - Sine
   * - cos
     - Cosine
   * - tan
     - Tangent
   * - sind
     - Sine, input argument in degrees
   * - cosd
     - Cosine, input argument in degrees
   * - tand
     - Tangent, input argument in degrees
   * - asin
     - Arc sine
   * - acos
     - Arc cosine
   * - atan
     - Arc tangent
   * - asind
     - Arc sine, output value in degrees
   * - acosd
     - Arc cosine, output value in degrees
   * - atand
     - Arc tangent, output value in degrees
   * - sqrt
     - Square root
   * - exp
     - Exponential
   * - ln
     - Natural logarithm
   * - lg
     - Decimal logarithm
   * - deg
     - Function converting radians to degrees
   * - rad
     - Function converting degrees to radians
   * - abs
     - Absolute value

Unnamed constants (numbers) can be specified as floating-point numbers
(a string of digits separated by a dot) or as integers.

Named constants can be used in symbolic expressions and are listed in
Table 2:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - **Constant name**
     - **Description**
   * - M_PI
     - *π* — ratio of the circle circumference to its diameter
   * - M_PI_2
     - *π / 2*
   * - M_PI_4
     - *π / 4*
   * - M_SQRT2
     - *√2*
   * - M_E
     - *e* — base of the natural logarithm
   * - M_FI
     - *φ* — golden ratio
   * - M_RADDEG
     - *180 / π* — conversion factor from radians to degrees
   * - M_DEGRAD
     - *π / 180* — conversion factor from degrees to radians

The name of a variable in an analytical expression can be a
sequence of string and numeric literals (the first character
is a string literal) that does not coincide with function names
or constant names.

Constraints for creating a symbolic curve:

- Maximum variable length — 512 characters.
- Maximum expression length — 2048 characters.
- No operations of integration, differentiation, or limit
  evaluation.
- No simplification of mathematical expressions (for example,
  fraction reduction).

Due to these constraints, correct evaluation of an analytical
expression can be obtained only for relatively simple mathematical
expressions and functions. For example, the value of
*sin*\(\ *x*\ )/\ *x* at zero may be computed incorrectly.

Below is a code example demonstrating how to create
a symbolic three-dimensional curve.

.. code-block:: cpp

   MbCharacterCurve3D * CreateAnalyticalCurve3D()
   {
       MbCharacterCurve3D * curve( nullptr );

       // String representations of the given coordinate functions.
       string_t xFunction = _T( "100*cos(t)-20*cos(4*t)" );
       string_t yFunction = _T( "100*sin(t)-20*sin(4*t)" );
       string_t zFunction = _T( "t*10" );
       string_t argument  = _T( "t" );

       double t1 = 0.0, t2 = 5.0 * M_PI;

       // Creating analytical coordinate functions using the function factory.
       MbFunctionFactory factory;

       SPtr<MbFunction> x( factory.CreateAnalyticalFunction( xFunction, argument, t1, t2, true ) );
       SPtr<MbFunction> y( factory.CreateAnalyticalFunction( yFunction, argument, t1, t2, true ) );
       SPtr<MbFunction> z( factory.CreateAnalyticalFunction( zFunction, argument, t1, t2, true ) );

       if ( x != nullptr && y != nullptr && z != nullptr ) {
           MbCartPoint3D point( 0.0, 0.0, 0.0 );           // Origin of the local coordinate system.
           MbVector3D    axisX( 1.0, 0.0, 0.0 );
           MbVector3D    axisY( 0.0, 1.0, 0.0 );

           MbPlacement3D place( point, axisX, axisY );     // Local coordinate system.

           MbeLocalSystemType3D cs = ls_CartesianSystem;   // Type of the local coordinate system.

           // Creating a symbolic three-dimensional curve.
           curve = new MbCharacterCurve3D( *x, *y, *z, cs, place, t1, t2 );
       }

       return curve;
   }