Lua-интерфейс Renga
===================

Скрипты, описывающие геометрическое представление шаблона стиля, расположение портов инженерного оборудования и поведение параметров из файла описания параметров JSON, создаются в отдельном файле с расширением LUA. Описанию встроенных функций, взаимодействующих с Renga, посвященна данная часть руководства.

.. note:: Кроме использования встроенных функций, разработчики могут использовать в скриптах стандартные библиотеки Lua:

        * `package library <http://www.lua.org/manual/5.4/manual.html#6.3>`_ — базовые средства для загрузки модулей в Lua,
        * `string manipulation <http://www.lua.org/manual/5.4/manual.html#6.4>`_ — общие функции для работы со строками, такие как поиск и извлечение подстрок, а также сопоставление с шаблоном,
        * `table manipulation <http://www.lua.org/manual/5.4/manual.html#6.6>`_ — общие функции для работы с таблицами,
        * `mathematical functions <http://www.lua.org/manual/5.4/manual.html#6.7>`_ — математические функции.

**Style Template API** предоставляет средства для описания шаблонов стилей (объекты, классы, функции и системные перечисления).

Функции, создающие различные геометрические примитивы в Renga, а также системные перечисления (*enums*), доступны в любой части скрипта. Условно можно сказать, что они относятся к глобальному пространству имён (или в терминах Lua — в *глобальном окружении*). Также выделяются в отдельное пространство имён ``Style`` функции для работы с текущим стилем и в отдельное пространство имён ``Project`` функции для получения объектов и стилей проекта:

.. note:: Подробнее см. `справочное руководство Renga STDL <https://help.rengabim.com/stdl/ru/topics.html>`_

.. table:: Style Template API
   
    +-------------------------------+-------------------------------------------------------------------------------------------------------------------+
    | Namespace                     | Объекты                                                                                                           |
    +===============================+===================================================================================================================+
    | *глобальный*                  | :doc:`Модельная геометрия </modelgeometry>`                                                                       |    
    |                               +------------------------------------------------------------------+------------------------------------------------+    
    |                               | Функции, порождающие геометрические примитивы                    | :doc:`Базовые типы геометрии </basetypes>`     | 
    |                               |                                                                  +------------------------------------------------+
    |                               |                                                                  | :doc:`Графические примитивы </symbolic>`       |    
    |                               |                                                                  +------------------------------------------------+
    |                               |                                                                  | :doc:`Плоская 2D-геометрия </planar>`          |
    |                               |                                                                  +------------------------------------------------+
    |                               |                                                                  | :doc:`Твёрдотельная 3D-геометрия </geometry>`  |    
    |                               +------------------------------------------------------------------+------------------------------------------------+
    |                               | :doc:`Системные перечисления </coreenums>`                                                                        |
    |                               +-------------------------------------------------------------------------------------------------------------------+
    |                               | :doc:`Вспомогательные функции </auxiliary>`                                                                       |
    +-------------------------------+-------------------------------------------------------------------------------------------------------------------+
    | Style                         | Функции для работы с текущим стилем                                                                               |
    +-------------------+-----------+-------------------------------------------------------------------------------------------------------------------+
    |                   | Parameter | Таблица групп параметров *(определенных в JSON)*                                                                  |
    |                   +-----------+-------------------------------------------------------------------------------------------------------------------+
    |                   | Port      | :doc:`Точки подключения (порты) оборудования </ports>`                                                            |
    +-------------------+-----------+------------------------------------------------------------------+------------------------------------------------+
    | .. versionadded:: 2.0 Project | :ref:`Функции для получения объектов и стилей проекта <project>` | :ref:`Стили арматурного стержня <rebar_style>` |
    +-------------------------------+------------------------------------------------------------------+------------------------------------------------+
    
Функции для работы с текущим стилем
-----------------------------------

Пространство имён ``Style`` (или в терминах Lua - *таблица*) содержит функции, которые:

* создают различный уровень детализации стиля (детальный, условный или символьный) из :doc:`модельной геометрии <../modelgeometry>`,
* управляют доступом к :ref:`параметрам <parameter>` и :ref:`портам <access_to_ports>`,
* .. versionadded:: 2.0 добавляют в стиль :ref:`арматурные стержни <rebar>` и :ref:`наборы арматурных стержней <rebarset>`,
* .. versionadded:: 3.0 задают для стиля :ref:`остов изоляции <insulationskeleton>`.

Таблицы ``Parameters`` и ``Ports`` также являются объектами пространства имён ``Style``.

.. note:: Подробнее про уровни детализации стиля см. :doc:`модельную геометрию <../modelgeometry>`

Создать детальную геометрию стиля
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. lua:function:: SetDetailedGeometry(detailedGeometry)

    :param detailedGeometry: Задает :doc:`модельную геометрию <../modelgeometry>`.
    :type detailedGeometry: ModelGeometry

.. code-block:: lua
    :caption: Пример 1. Добавление детальной модельной геометрии в стиль:
    :linenos:

    local detailedGeometry = ModelGeometry()    -- создание экземпляра модельной геометрии
    ..                       -- наполнение модельной геометрии геометрическими примитивами

    Style.SetDetailedGeometry(detailedGeometry) -- создание детальной геометрии стиля

Создать условную геометрию стиля
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. lua:function:: SetSymbolicGeometry(symbolicGeometry)

    :param symbolicGeometry: Задает :doc:`модельную геометрию <../modelgeometry>`.
    :type detailedGeometry: ModelGeometry

.. code-block:: lua
    :caption: Пример 2. Добавление условной модельной геометрии в стиль:
    :linenos:

    local symbolicGeometry = ModelGeometry()    -- создание экземпляра модельной геометрии
    ..                       -- наполнение модельной геометрии геометрическими примитивами

    Style.SetSymbolicGeometry(symbolicGeometry) -- создание условной геометрии стиля

Создать символьную геометрию стиля
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. lua:function:: SetSymbolGeometry(symbolGeometry)

    :param symbolGeometry: Задает :doc:`модельную геометрию <../modelgeometry>`.
    :type detailedGeometry: ModelGeometry

.. code-block:: lua
    :caption: Пример 3. Добавление символьной модельной геометрии в стиль:
    :linenos:

    local symbolGeometry = ModelGeometry()    -- создание экземпляра модельной геометрии
    ..                     -- наполнение модельной геометрии геометрическими примитивами

    Style.SetSymbolGeometry(symbolGeometry)   -- создание символьной геометрии стиля

.. _rebar:

Добавить арматурный стержень в стиль
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 2.0

    .. lua:function:: AddRebar(id, curve)

        :param id: Задает идентификатор стиля.
        :type id: Number
        :param curve: Задает базовую трёхмерную кривую.
        :type curve: :ref:`Curve3D <curve3d>`

    .. code-block:: lua
        :caption: Пример 4. Добавление арматурного стержня в стиль:
        :linenos:

        local parameters = Style.GetParameterValues()
        local RebarStyleId = parameters.Reinforcement.RebarStyleId
        local rebarCurve = CreateLineSegment3D(Point3D(0,0), Point3D(height,0))

        Style.AddRebar(RebarStyleId, rebarCurve)

.. _rebarset:

Добавить набор арматурных стержней в стиль
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 2.0

    .. lua:function:: AddRebarSet(id, curve, direction, step, count)

        :param id: Задает идентификатор стиля.
        :type id: Number
        :param curve: Задает базовую трёхмерную кривую.
        :type curve: :ref:`Curve3D <curve3d>`
        :param direction: Задает направление расположения стержней.
        :type direction: :ref:`Vector3D <vector3d>`
        :param step: Задает расстояние между стержнями.
        :type step: Number
        :param count: Задает количество стержней.
        :type count: Number

    .. code-block:: lua
        :caption: Пример 5. Добавление набора арматурных стержней в стиль:
        :linenos:

        local parameters = Style.GetParameterValues()
        local RebarStyleId = parameters.Reinforcement.RebarStyleId
        local rebarCurve = CreateLineSegment3D(Point3D(0,0), Point3D(height,0))

        Style.AddRebarSet(RebarStyleId, rebarCurve, Vector3D(0, 1, 0), 200, 10)

.. _insulationskeleton:

Задать остов изоляции для стиля
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.0

    .. lua:function:: SetInsulationSkeleton({parts})

        :param {parts}: Задает таблицу участков изоляции.
        :type {parts}: table of :ref:`Parts <insulationparts>`
           
    .. code-block:: lua
        :caption: Пример 6. Задание для стиля остова изоляции, состоящего из 3-х частей:
        :linenos:

        Style.SetInsulationSkeleton({{part1}, {part2}, {part3}})

.. _project:

Функции для получения объектов и стилей проекта
-----------------------------------------------

Пространство имён ``Project`` содержит функции для получения сущностей (**Entity**) проекта Renga.

.. _entity:

Класс **Entity** — базовый элемент проекта Renga. Это может быть объект или стиль. Из данного типа можно получать другие типы с помощью вызовов функций Cast*, например, :ref:`контейнер параметров <params_container>`

.. _rebar_style:

Получить стиль арматурного стержня
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 2.0

    .. lua:function:: GetRebarStyle	(id)	

        :param id: Задает идентификатор стиля.
        :type id: Number
        :return: Стиль арматурного стержня
        :rtype: :ref:`Entity <entity>`

    .. code-block:: lua
        :caption: Пример 7. Получение стиля арматурного стержня из параметра ``RebarStyleId`` группы ``Reinforcement``:
        :linenos:

        local parameters = Style.GetParameterValues()
        local rebarStyleId = parameters.Reinforcement.RebarStyleId
        
        local style = Project.GetRebarStyle(rebarStyleId)