Процесс визуального программирования может быть очень увлекательным и вдохновляющим, однако работа с потоком выполнения операций и ключевыми входными данными пользователя может очень быстро зайти в тупик из-за запутанности программы или неудачной компоновки рабочего пространства. Далее представлены некоторые практические советы по управлению структурой программы.

Выравнивание

Когда рабочее пространство постепенно начнет заполняться узлами, может потребоваться переупорядочить их для большей наглядности. Выберите несколько узлов и щелкните в рабочем пространстве правой кнопкой мыши. Появится всплывающее окно с меню Выбор выравнивания, содержащем параметры выравнивания и распределения по осям X и Y.

1. Выберите несколько узлов.

2. Щелкните в рабочем пространстве правой кнопкой мыши.

3. Воспользуйтесь параметрами меню Выбор выравнивания.

Примечания

По мере накопления опыта вы научитесь «считывать» содержимое визуальной программы, просматривая имена узлов и следуя последовательности выполнения операций. Чтобы дополнительно упростить работу как опытным пользователям, так и новичкам, мы рекомендуем добавлять простые текстовые метки и описания. Для этого в Dynamo можно использовать узел Notes с редактируемым текстовым полем. Добавить примечания в рабочее пространство можно двумя способами.

1. Перейдите в меню «Редактировать» > «Создать примечание».

2. Используйте клавиши быстрого вызова CTRL + W.

После добавления примечания в рабочее пространство появится текстовое поле, позволяющее отредактировать текст примечания. Созданные примечания можно изменить, щелкнув узел примечаний правой кнопкой мыши или щелкнув его дважды.

Группирование

Когда число компонентов визуальной программы становится по-настоящему большим, для упрощения работы с ними рекомендуется выделить крупные этапы процесса выполнения. Большие наборы узлов можно объединять в группы, в результате чего они помечаются цветным фоновым прямоугольником и заголовком. Создать группу на основе нескольких выбранных узлов можно тремя способами.

1. Перейдите в меню «Редактировать» > «Создать группу».

2. Используйте клавиши быстрого вызова CTRL + G.

3. Щелкните в рабочем пространстве правой кнопкой мыши и выберите «Создать группу».

После создания группы можно отредактировать ее параметры, например название и цвет фона.

Далее представлен пример программы с добавленными примечаниями и группами.

1. Примечание: «Параметры сетки»

2. Примечание: «Точки сетки»

3. Группа: «Создать сетку из точек»

4. Группа: «Создать точку аттрактора»

5. Примечание: «Откалибровать значения расстояния»

6. Примечание: «Переменная сетка окружностей»

Данный справочник представляет собой дополнение к практическим советам, рассмотренным в главе «Методы создания сценариев». В нем содержатся дополнительные сведения о библиотеках кодов, метках и стиле. Для иллюстрации будет использоваться язык Python, однако принципы являются общими для Python и C# (Zero Touch) с учетом различий в синтаксисе.

Используемые библиотеки

Стандартные библиотеки не входят в состав Dynamo и написаны на языках программирования Python и C# (Zero Touch). В Dynamo также имеется собственный набор библиотек, которые точно отражают иерархию узлов модуля. Благодаря этому пользователи могут создавать программы с помощью узлов и проводов в форме кода. В представленном ниже руководстве описано содержимое каждой из библиотек Dynamo и случаи использования стандартных библиотек.

Стандартные библиотеки и библиотеки Dynamo

• Для формирования данных и процессов со сложной структурой в среде Dynamo можно использовать стандартные библиотеки Python и C#.

• Библиотеки Dynamo в точности следуют иерархии узлов, что удобно при создании геометрических и других объектов Dynamo.

Библиотеки Dynamo

1. ProtoGeometry\*

   • Функции: дуга, ограничивающая рамка, окружность, конус, система координат, кубоид, кривая, цилиндр, ребро, эллипс, дуга эллипса, грань, геометрия, спираль, группа индексов, линия, сеть, NURBS-кривая, NURBS-поверхность, плоскость, точка, полигон, прямоугольник, тело, сфера, поверхность, топология, T-сплайн, UV, вектор, вершина.

   • Импорт: import Autodesk.DesignScript.Geometry

   ``

2. DSCoreNodes

   • Функции: цвет, диапазон цветов 2D, дата и время, интервал времени, ввод/вывод, формула, логика, список, математическое вычисление, квадрадерево, строка, поток.

   • Импорт: import DSCore

3. Tessellation

   • Функции: выпуклая оболочка, Делоне, Вороной.

   • Импорт: import Tessellation

4. DSOffice

   • Функции: Excel.

   • Импорт: import DSOffice

Осторожное использование меток

При написании сценариев постоянно используются идентификаторы, которые служат для обозначения переменных, типов, функций и других элементов. Благодаря этой системе условных обозначений можно строить алгоритмы, ссылаясь на данные посредством меток, которые обычно представляют собой последовательность символов. Правильное присвоение имен очень важно при написании кода, так как позволяет сделать его понятным не только другим пользователям, но и самому автору в будущем. Ниже приводятся рекомендации по присвоению имен элементам сценария.

Использование сокращений допускается, но с поясняющим комментарием:

### BAD
csfX = 1.6
csfY= 1.3
csfZ = 1.0

### GOOD
# column scale factor (csf)
csfX = 1.6
csfY= 1.3
csfZ = 1.0

Избегайте избыточных меток:

### BAD
import car
seat = car.CarSeat()
tire = car.CarTire()

### GOOD
import car
seat = car.Seat()
tire = car.Tire()

В именах переменных используйте положительную, а не отрицательную логику:

### BAD
if 'mystring' not in text:
    print 'not found'
else:
    print 'found'
    print 'processing'

### GOOD
if 'mystring' in text:
    print 'found'
    print 'processing'
else:
    print 'not found'

Старайтесь использовать обратный порядок слов в обозначениях:

### BAD
agents = …
active_agents = …
dead_agents ...

### GOOD
agents = …
agents_active = …
agents_dead = ...

Это более целесообразно с точки зрения структуры.

Для сокращения длинных или часто повторяющихся цепочек наименований используйте псевдонимы:

### BAD
from RevitServices.Persistence import DocumentManager

DocumentManager = DM

doc = DM.Instance.CurrentDBDocument
uiapp = DM.Instance.CurrentUIApplication

### GOOD
from RevitServices.Persistence import DocumentManager as DM

doc = DM.Instance.CurrentDBDocument
uiapp = DM.Instance.CurrentUIApplication

Однако помните, что использование псевдонимов может сделать программу непонятной и нестандартной.

Используйте только необходимые слова:

### BAD
rotateToCoord = rotateFromCoord.Rotate(solid.ContextCoordinateSystem.Origin,Vector.ByCoordinates(0,0,1),5)

### GOOD
toCoord = fromCoord.Rotate(solid.ContextCoordinateSystem.Origin,Vector.ByCoordinates(0,0,1),5)

«Все должно быть изложено так просто, как только возможно, но не проще» (Альберт Эйнштейн)

Единообразие стиля

Любую программу можно написать несколькими способами, то есть персональный стиль создания сценариев формируется в результате принятия (или непринятия) бесчисленных мелких решений по ходу работы. Это означает, что читаемость и возможность доработки кода — прямой результат внутренней согласованности и соблюдения общих стилистических правил. Главное правило: одинаковый код в двух разных местах должен работать одинаково. Ниже приводятся советы по созданию понятного единообразного кода.

Правила именования (выберите одно из следующих правил для каждого типа объекта в коде и придерживайтесь его)

• Переменные, функции, методы, пакеты, модули: lower_case_with_underscores

• Классы и исключения: CapWords

• Защищенные методы и внутренние функции: _single_leading_underscore(self, ...)

• Собственные методы: __double_leading_underscore(self, ...)

• Константы: ALL_CAPS_WITH_UNDERSCORES

Совет. Следует избегать использования переменных из одной буквы (особенно l, O, I), Исключением могут быть очень короткие блоки, когда значение легко понять из ближайшего контекста.

Использование пустых строк

• До и после определения функции верхнего уровня или класса следует оставлять две пустые строки.

  • До и после определения метода внутри класса следует оставлять одну пустую строку.

  • Для разделения групп связанных функций можно использовать дополнительные пустые строки (в разумных количествах).

Избегайте ненужных пробелов

• После открывающейся или перед закрывающейся круглой скобкой, квадратной скобкой или фигурной скобкой:

  Copy

  ### BAD
  function( apples[ 1 ], { oranges: 2 } )

  Copy

  ### GOOD:
  function(apples[1], {oranges: 2})

• Перед запятой, точкой с запятой или двоеточием:

  Copy

  ### BAD
   if x == 2 : print x , y ; x , y = y , x

  Copy

  ### GOOD
    if x == 2: print x, y; x, y = y, x

• Перед открывающейся скобкой, за которой следует список аргументов вызываемой функции:

  Copy

  ### BAD
  function (1)

  Copy

  ### GOOD
  function(1)

• Перед открывающейся скобкой, за которой следует индексирование или членение:

  Copy

  ### BAD
  dict ['key'] = list [index]

  Copy

  ### GOOD
  dict['key'] = list[index]

• До и после следующих двоичных операторов всегда вставляйте одиночный пробел:

  Copy

  assignment ( = )
  augmented assignment ( += , -= etc.)
  comparisons ( == , < , > , != , <> , <= , >= , in , not in , is , is not )
  Booleans ( and , or , not )

Следите за длиной строки

• Она не должна превышать 79 символов.

• Если ограничить ширину окна редактора, можно открыть несколько файлов рядом. Это также удобно при использовании инструментов проверки кода, когда обе версии кода представлены в соседних столбцах.

• Длинные строки можно разбить на несколько строк, заключив выражения в круглые скобки:

Избегайте очевидных и лишних комментариев

• Иногда меньшее количество комментариев делает код более читабельным, особенно если вместо них используются понятные идентификаторы.

• Хороший стиль написания кода уменьшает зависимость от комментариев:

  Copy

  ### BAD
    # get the country code
    country_code = get_country_code(address)
  
    # if country code is US
    if (country_code == 'US'):
      # display the form input for state
      print form_input_state()

  Copy

  ### GOOD
    # display state selection for US users
    country_code = get_country_code(address)
    if (country_code == 'US'):
      print form_input_state()

Совет. Комментарии отвечают на вопрос «Почему?», код — на вопрос «Как?».

Просматривайте открытый исходный код

• Проекты с открытым исходным кодом создаются совместными усилиями многих разработчиков. Код, на котором пишутся эти проекты, должен быть максимально понятным, чтобы обеспечить эффективную работу всей группы. Поэтому рекомендуется просматривать исходный код подобных проектов, чтобы понять ход мыслей разработчиков.

• Совершенствуйте правила:

  • Задавайте вопросы о том, срабатывает ли то или иное правило в отношении текущих задач.

  • Не ухудшается ли функциональность или эффективность?

Стандарты C# (Zero Touch)

Посетите эти страницы Wiki, чтобы узнать об особенностях написания кода на C# для Zero Touch и его вставки в Dynamo.

• На этой странице рассматриваются некоторые общие стандарты, касающиеся документирования и проверки кода: https://github.com/DynamoDS/Dynamo/wiki/Coding-Standards

• На этой странице рассматриваются стандарты именования для библиотек, категорий, имен узлов, имен портов и сокращений: https://github.com/DynamoDS/Dynamo/wiki/Naming-Standards

Неуправляемые объекты

При использовании библиотеки геометрических объектов Dynamo (ProtoGeometry) в Python или C# управлять геометрическими объектами с помощью виртуальной машины будет невозможно, и память многих из этих объектов необходимо освобождать вручную. Для удаления локальных или неуправляемых объектов можно использовать метод Dispose или ключевое слово using. Дополнительные сведения см. на следующей странице Wiki: https://github.com/DynamoDS/Dynamo/wiki/Zero-Touch-Plugin-Development#dispose--using-statement.

Удалять следует только неуправляемые ресурсы, которые не возвращаются в график или на которые не указывают ссылки. Далее в этом разделе подобные объекты будут называться промежуточной геометрией. Этот класс объектов используется в примере кода, приведенном ниже. Функция C# Zero Touch c именем singleCube возвращает один куб, но в процессе выполнения создает еще 10000 кубов. Предположим, что оставшиеся геометрические объекты были использованы в качестве некой промежуточной вспомогательной геометрии.

Скорее всего, эта функция вызовет аварийное завершение работы Dynamo. В результате ее использования было создано 10000 тел, а сохранено и возвращено одно из них. В этом случае необходимо удалить все промежуточные кубы, кроме возвращаемого. Возвращаемый объект удалять не нужно, так как он будет распространен по графику и использован в других узлах.

public Cuboid singleCube(){

  var output = Cuboid.ByLengths(1,1,1);

  for(int i = 0; i<10000;i++){
    output = Cuboid.ByLengths(1,1,1);
  }
  return output;
}

Постоянный код должен выглядеть примерно так:

 public Cuboid singleCube(){

   var output = Cuboid.ByLengths(1,1,1);
   var toDispose = new List<Geometry>();

   for(int i = 0; i<10000;i++){
     toDispose.Add(Cuboid.ByLengths(1,1,1));
   }

   foreach(IDisposable item in toDispose ){
     item.Dispose();
   }

   return output;
 }

Обычно необходимо удалить только геометрию, например Surfaces, Curves и Solids. Однако в целях безопасности можно удалить все типы геометрии (Vectors, Points, CoordinateSystems).

Этот раздел данного руководства является своеобразным сборником полезных советов. В нем рассказывается о разных стратегиях, разработанных на основе опыта и результатов исследований и позволяющих повысить качество параметрических рабочих процессов. Как проектировщики и программисты, мы измеряем качество наших инструментов их стабильностью, надежностью, удобством и эффективностью. В этом разделе вы найдете отдельные примеры для визуальных и текстовых сценариев, однако основополагающие принципы являются универсальными для всех сред программирования и могут использоваться в самых разных вычислительных рабочих процессах.

В предыдущих главах было описано, как пользоваться мощными возможностями создания визуальных сценариев в Dynamo. Понимание этих возможностей является основой и первым шагом к созданию надежных визуальных программ. При работе с визуальными программами в полевых условиях, обмене ими с коллегами, устранении неполадок или проверке ограничений приходится сталкиваться и с другими проблемами. Если программа рассчитана на другого пользователя или предполагается открыть ее только через полгода, она должна обладать абсолютно понятной графикой и логикой. В Dynamo есть множество инструментов для работы со сложными программами. В этой главе приводятся рекомендации по их своевременному использованию.

Упрощение

По мере разработки графика Dynamo и проверки различных идей он увеличивается в размере и становится сложнее. Несомненно, очень важно создать работающую программу, однако столь же важно сделать ее максимально простой. Благодаря этому работа графика будет более быстрой и предсказуемой, а пользователи вместе с разработчиком смогут понять его логику по прошествии времени. Ниже представлены варианты того, как можно упорядочить логику графиков.

Модульная организация с помощью групп

• Благодаря группам можно создавать функционально автономные части при разработке программы.

• Группы позволяют перемещать крупные части программы, соблюдая при этом модульность и выравнивание.

• Можно менять цвета групп, чтобы различать их предназначение (входные данные или функции).

• С помощью групп можно структурировать график таким образом, чтобы упростить создание пользовательских узлов.

Цвета в этой программе обозначают назначение каждой группы. Этот метод может использоваться для создания иерархии в любых разрабатываемых графических стандартах или шаблонах.

1. Группа функций (синий)

2. Группа входных данных (оранжевый)

3. Группа сценариев (зеленый)

Эффективная разработка с помощью блоков кода

• Иногда с помощью блока кода можно быстрее ввести число или метод узла, чем при поиске (Point.ByCoordinates, Number, String, Formula).

• Блоки кода (узлы Code Blocks) можно использовать для настройки пользовательских функций в DesignScript, уменьшающих количество узлов в графике.

Примеры 1 и 2 выполняют одну и ту же функцию. Получилось значительно быстрее написать несколько строк кода, чем прибегать к функции поиска и добавлять каждый узел по отдельности. Кроме того, блок кода значительно меньше по объему.

1. Сценарий DesignScript, написанный с помощью блока кода

2. Аналогичная программа с использованием узлов

Сжатие узла в код

• Сложность графика можно уменьшить с помощью преобразования узла в код (Node to Code). При этом для набора простых узлов будет создан соответствующий сценарий DesignScript, состоящий из одного блока кода.

• Функция «Узел для кодировки» позволяет** сжать код, не усложняя восприятие программы**.

• Далее перечислены преимущества использования функции Node to Code.

  • Простое сжатие кода в один редактируемый компонент.

  • Упрощение значительной части графика.

  • Удобство применения к мини-программам, которые редко редактируются.

  • Возможность встраивания других типов блоков кода, таких как функции.

• Ниже представлены недостатки использования функции Node to Code.

  • Типовые имена ухудшают удобочитаемость.

  • Сложность восприятия для других пользователей.

  • Нет простого способа вернуться к визуальной версии программы.

1. Существующая программа

2. Блок кода, созданный с помощью функции Node to Code

Гибкий доступ к данным с помощью функции List@Level

• С помощью функции List@Level можно упростить график, заменив узлы List.Map и List.Combine, которые могут занимать значительное место рабочей области.

• При построении логики узла List@Level работает быстрее**, чем List.Map/List.Combine**, так как предоставляет доступ к данным любого уровня в списке непосредственно с порта ввода узла.

Активировав функцию List@Level для входных данных списка CountTrue, можно проверить, сколько истинных значений и в каких списках возвращает функция BoundingBox.Contains. List@Level позволяет определить, с какого уровня данные будут подаваться на ввод. Работа с List@Level отличается гибкостью, эффективностью и более предпочтительна по сравнению с другими методами, где используются функции List.Map и List.Combine.

1. Подсчет истинных значений на 2 уровне списка.

2. Подсчет истинных значений на 3 уровне списка.

Обеспечение наглядности

Помимо простоты и эффективности графиков, необходимо позаботится об их максимальной наглядности. Несмотря на все усилия по созданию интуитивного графика за счет логических группировок, взаимосвязи могут быть видны недостаточно хорошо. Лишних поисков и неопределенности можно избежать благодаря простому примечанию внутри группы или переименованному регулятору. Описанные ниже способы помогут обеспечить визуальное единообразие в одном или нескольких графиках.

Достижение визуальной целостности посредством выравнивания узлов

• Чтобы уменьшить количество доработок после построения графика, попытайтесь сделать компоновку узлов удобочитаемой, периодически выравнивая их.

• Если с графиком будут работать другие пользователи, убедитесь, что компоновка проводов и узлов имеет четкую логику.

• Для упрощения выравнивания используйте функцию «Очистить компоновку узла», чтобы автоматически выровнять график (однако в таком случае точность будет меньше, чем при выравнивании вручную).

1. Неупорядоченный график

2. Выровненный график

Использование описательных меток при переименовании

• Переименование входных данных сделает график более понятным другим пользователям, особенно если требуется подсоединиться к узлу, который не будет виден на экране.

• При переименовании любых узлов, кроме узлов входных данных, будьте максимально осторожны. Можно также создать пользовательский узел из кластера узлов и переименовать его: при этом будет понятно, что в нем содержится нечто другое.

1. Входные данные для управления поверхностью

2. Входные данные архитектурных параметров

3. Входные данные в сценарии моделирования водоспуска

Чтобы переименовать узел, щелкните его имя правой кнопкой мыши и выберите «Переименовать узел...».

Разъяснения в примечаниях

• Примечание добавляется, если для какой-либо части графика требуется пояснение на простом языке, которое не может быть выражено с помощью узла.

• Примечание добавляется, если набор узлов или группа имеют слишком большой размер, сложную структуру или логику.

1. Примечание, описывающее часть программы, которая возвращает примерные расстояния переноса.

2. Примечание, описывающее код, который сопоставляет эти значения с синусоидальной волной.

Зондирование на всех этапах работы

Мониторинг данных с помощью марок наблюдения (Watch) и предварительного просмотра (Preview)

• При создании программы используйте марки Watch и Preview, чтобы** убедиться в правильности ключевых выходных данных**.

Узлы Watch используются для сравнения следующих данных:

1. примерные расстояния переноса;

2. значения, проходящие через уравнение синусоиды.

Повторное использование

Весьма вероятно, что рано или поздно вашу программу откроет другой пользователь, даже если вы работаете самостоятельно. На основе входных и выходных данных этому пользователю нужно будет быстро понять, что требуется для работы программы и каковы результаты этой работы. Это особенно важно при разработке пользовательских узлов, которые будут применяться сообществом Dynamo и добавляться в программы других разработчиков. Следующие рекомендации помогут создавать надежные, многократно используемые программы и узлы.

Управление вводом/выводом

• Чтобы обеспечить удобочитаемость и масштабируемость, попробуйте минимизировать входные и выходные данные.

• Перед тем, как добавить первый узел в рабочую область, необходимо определить метод построения логики, создав примерный план ее действия. При создании примерного плана отслеживайте, какие входные и выходные данные войдут в сценарии.

Использование наборов параметров при добавлении входных значений

• При наличии определенных вариантов или условий, которые требуется включить в график, для быстрого доступа к ним следует использовать наборы параметров.

• Наборы параметров можно также использовать для уменьшения сложности путем кэширования определенных значений регулятора на графике с длительным временем выполнения.

Упаковка программ с пользовательскими узлами в контейнеры

• Пользовательский узел применяется, если программу можно объединить в одном контейнере.

• Еще пользовательский узел применяется, если часть графика будет повторно использоваться в других программах.

• И, наконец, пользовательский узел применяется, если необходимо сделать функцию доступной сообществу Dynamo.

Если собрать программу преобразования точек в пользовательский узел, получится более надежная и оригинальная переносная программа, в которой легко разобраться. Правильно обозначенные порты ввода помогут другим пользователям понять, как применять узел. Не забудьте добавить описания и требуемые типы данных для каждого входного элемента.

1. Существующая программа точки притяжения

2. Пользовательский узел для размещения программы, PointGrid

Создание шаблонов

• Шаблоны используются в качестве визуальных стандартов, чтобы обеспечить общий подход к построению графиков среди пользователей, осуществляющих совместную работу.

• При создании шаблона можно стандартизировать цвета и размеры шрифтов группы, чтобы отнести типы рабочих процессов или операции с данными к определенным категориям.

• При создании шаблона можно даже стандартизировать метки, цвета или стили для обозначения различий между внешними и внутренними рабочими процессами на графике.

1. Пользовательский интерфейс (внешняя часть программы). Включает в себя имя проекта, регуляторы ввода и импортируемую геометрию.

2. Внутренняя часть программы.

3. Цветовые категории групп (проект в целом, входные данные, сценарии на языке Python, импортированная геометрия).

Упражнение «Архитектурная крыша»

Скачайте файл примера, щелкнув указанную ниже ссылку.

Полный список файлов примеров можно найти в приложении.

Ознакомившись с некоторыми практическими советами, попробуйте применить их к быстро составленной программе. Несмотря на то, что программа успешно создает крышу, график отражает «поток сознания» автора. Отсутствует какая-либо структура и руководство по использованию. Применив практические советы по организации, описанию и анализу программы, мы поможем понять другим пользователям, как ее использовать.

Программа работает, но график не структурирован.

Начните с определения данных и геометрии, возвращаемых программой.

Чтобы создать логические разделы или модули, очень важно понимать, когда данные подвергаются наибольшим изменениям. Перед переходом к следующему шагу попробуйте проверить остальную часть программы с помощью узлов Watch, чтобы убедиться в возможности определить группы.

1. Этот узел Code Block с математическим уравнением выглядит как ключевая часть программы. Узел Watch возвращает списки расстояний переноса.

2. Назначение этой области не очевидно. Расположение истинных значений на уровне списка L2 из BoundingBox.Contains и наличие List.FilterByBoolMask говорит о том, что это выборка части из сетки точек.

Разобравшись в компонентах программы, разделите их на группы.

Группы позволяют визуально дифференцировать компоненты программы.

1. Импорт 3D-модели площадки

2. Преобразование сетки точек на основе уравнения синусоиды

3. Выборка части из сетки точек

4. Создание поверхности архитектурной крыши

5. Создание стеклянного витража

После определения групп выровняйте узлы, чтобы обеспечить визуальную целостность графика.

Визуальная целостность позволяет видеть ход выполнения программы и скрытые взаимосвязи между узлами.

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

Благодаря этим улучшениям графического интерфейса пользователи лучше поймут назначение этой программы. Различные цвета групп позволяют отличать входные данные от функций.

1. Примечания

2. Входные данные с описательными именами

Перед тем как приступить к сжатию программы, определим предполагаемое место вставки сценария Python для моделирования водоспуска. Разместите выходные данные первой масштабированной поверхности крыши в соответствующих входных данных сценария.

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

1. Исходная геометрия для входных данных сценария

2. Узел Python

3. Регуляторы ввода

4. Переключатель вкл./откл.

Упростите график, чтобы расставить все по местам.

Сжатие программы с помощью функций Node to Code и Custom Node привело к значительному уменьшению размера графика. Группы, отвечающие за создание поверхности крыши и стен, преобразованы в код, так как характерны только для данной программы. Группа преобразования точек содержится в пользовательском узле, так как ее можно использовать в другой программе. Создайте в файле примера собственный пользовательский узел из группы преобразования точек.

1. Пользовательский узел для размещения группы «преобразование сетки точек»

2. Функция Node to Code для сжатия групп «Создание поверхности архитектурной крыши и виража»

В завершение создайте наборы параметров для образцов формы крыши.

Эти входные данные в существенной мере определяют форму крыши и помогут пользователям увидеть возможности программы.

Программа, где видны два набора параметров.

Аналитический вид наборов параметров, соответствующих образцам водостока крыши.

Создание сценариев на основе текста в среде разработки визуальных сценариев обеспечивает возможность построения эффективных наглядных взаимосвязей с использованием языков DesignScript, Python и ZeroTouch (C#). В DesignScript можно отображать такие элементы, как регуляторы ввода, и сжимать сложные операции. В том же рабочем пространстве с помощью Python или C# можно получить доступ к мощным инструментам и библиотекам. При грамотном использовании сочетание этих методов может обеспечить высокую степень адаптированности, ясности и эффективности всей программы. Ниже приводится набор рекомендаций по дополнению визуальных сценариев текстовыми.

Своевременное использование сценариев

Текстовые сценарии позволяют устанавливать более сложные взаимосвязи, чем визуальное программирование, хотя их возможности во многом пересекаются. Это следует учитывать, так как узлы представляют собой эффективные пакеты кода, что позволяет написать целую программу для Dynamo в DesignScript или Python. Однако визуальные сценарии используются по причине того, что интерфейс, состоящий из узлов и проводов, позволяет создать интуитивно понятный поток графической информации. Информация о том, в каких случаях возможности текстовых сценариев превосходят возможности визуальных сценариев, — ключ к их использованию без отказа от работы с интуитивно понятными узлами и проводами. Ниже приводятся рекомендации в отношении того, когда следует использовать сценарии, и какой при этом выбрать язык программирования.

Текстовые сценарии используются в следующих случаях:

• организация циклов;

• использование рекурсии;

• доступ к внешним библиотекам.

Выбор языка

Параметрическое мышление

При написании сценариев в Dynamo — параметрической среде — имеет смысл структурировать код с учетом системы узлов и проводов, в которой он будет размещен. Рассматривайте узел, содержащий текстовый сценарий, как любой другой узел в программе с некоторыми определенными входными данными, функцией и ожидаемыми выходными данными. При этом код внутри узла получает небольшой набор переменных, на основе которых можно строить работу, а это — ключ к безупречной параметрической системе. Далее приводятся некоторые рекомендации, позволяющие успешнее встроить код в визуальную программу.

Определите внешние переменные.

• Попробуйте определить заданные параметры в проектной задаче, чтобы можно было построить модель непосредственно на этих данных.

• Перед написанием кода необходимо указать следующие переменные:

  • минимальный набор входных данных;

  • ожидаемые выходные данные;

  • константы.

Перед написанием кода было определено несколько переменных.

1. Поверхность, на которую будет моделироваться выпадение осадков.

2. Желаемое количество капель дождя (агентов).

3. Расстояние перемещения капель дождя.

4. Переключение между режимом спуска по траектории с наибольшей крутизной и режимом пересечения поверхности.

5. Узел Python с соответствующим количеством входных данных.

6. Блок кода для окрашивания возвращаемых кривых синим цветом.

Проектирование внутренних взаимосвязей

• Параметрическая архитектура позволяет редактировать определенные параметры или переменные для настройки или изменения конечного результата уравнения или работы системы.

• Если объекты в сценарии логически связаны между собой, следует указать, что один является функцией другого и наоборот. Таким образом, при изменении одного объекта другой также будет обновлен.

• Сократите количество входных данных, оставив только ключевые параметры.

  • Если набор параметров может быть сформирован из дополнительных родительских параметров, в качестве входных данных сценария оставьте только эти родительские параметры. Это повышает удобство работы со сценарием за счет некоторого упрощения его интерфейса.

«Модули» кода из примера в узле Python.

1. Входные данные.

2. Внутренние переменные сценария.

3. Цикл, для выполнения функции которого используются эти входные данные и переменные.

Не повторяйтесь (следуйте принципу DRY — Don't repeat yourself)

• Если один и тот же фрагмент в сценарии выражается несколькими способами, рано или поздно произойдет рассинхронизация этих совпадений, что потребует значительных исправлений, приведет к ошибкам в расчетах и внутренним противоречиям.

• Принцип DRY звучит следующим образом: «Информация, вводимая в компьютер должна быть конкретной и однозначной».

  • При успешном применении этого принципа все взаимосвязанные элементы в сценарии будут изменяться предсказуемо и единообразно, а все несвязанные элементы не будут иметь логических последствий друг для друга.

### BAD
for i in range(4):
  for j in range(4):
    point = Point.ByCoordinates(3*i, 3*j, 0)
    points.append(point)

### GOOD
count = IN[0]
pDist = IN[1]

for i in range(count):
  for j in range(count):
    point = Point.ByCoordinates(pDist*i, pDist*j, 0)
    points.append(point)

Модульная структура

По мере расширения и усложнения кода основная идея (ключевой алгоритм) становится все менее и менее читаемой. При этом все сложнее отслеживать, что и где может произойти, выявлять ошибки при возникновении проблем, встраивать другой код и назначать задачи по разработке. Чтобы избежать этих сложностей, для написания кода рекомендуется использовать модули. При этой организационной методике код разбивается на части в зависимости от выполняемой задачи. Далее представлены некоторые советы по расширению возможностей управления сценариями благодаря модульности.

Записывайте код в виде модулей.

• «Модуль» — это группа данных кода, выполняющая определенную задачу (аналогично узлу Dynamo в рабочем пространстве).

• Это может быть любой объект, который визуально отделен от близлежащего кода (функция, класс, группа входных данных или импортируемые библиотеки).

• Разработка кода в форме модулей повышает визуальное и интуитивное качество узлов, позволяя строить сложные взаимосвязи, реализуемые только с помощью текстовых сценариев.

Эти циклы вызывают класс с именем agent (агент), который мы будем разрабатывать в упражнении.

1. Модуль кода, определяющий начальную точку каждого агента.

2. Модуль кода, обновляющий агента.

3. Модуль кода, который строит маршрут траектории агента.

Ищите повторяющийся код.

• Если выясняется, что код выполняет одно и то же (или почти одно и то же) действие в нескольких местах, рекомендуется кластеризовать его в функцию, доступную для вызова.

• Функции Manager управляют ходом выполнения программы и содержат вызовы функций Worker для обработки низкоуровневых задач, например для перемещения данных между конструкциями.

В этом примере создаются сферы с радиусами и цветом, зависящими от значения Z центров.

1. Имеются две родительские функции Worker: одна из них создает сферы с радиусами и отображает цвета в зависимости от значения Z центра.

2. В родительской функции Manager объединены две функции Worker. При ее вызове вызываются и обе находящиеся в ней функции.

Отображайте только нужные элементы.

• В интерфейсе модуля отображаются элементы, как предоставляемые самим модулем, так и необходимые ему.

• После того как интерфейсы между блоками определены, детальная разработка каждого блока может выполняться отдельно.

Разделимость и заменяемость.

• Модули никоим образом не зависимы друг от друга.

Основные формы модульной организации.

• Группировка кодов

  Copy

  # IMPORT LIBRARIES
  import random
  import math
  import clr
  clr.AddReference('ProtoGeometry')
  from Autodesk.DesignScript.Geometry import *
  
  # DEFINE PARAMETER INPUTS
  surfIn = IN[0]
  maxSteps = IN[1]

• Функции

  Copy

  def get_step_size():
    area = surfIn.Area
    stepSize = math.sqrt(area)/100
    return stepSize
  
  stepSize = get_step_size()

• Классы

  Copy

  class MyClass:
    i = 12345
  
    def f(self):
      return 'hello world'
  
  numbers = MyClass.i
  greeting = MyClass.f

Зондирование на всех этапах работы

При написании текстовых сценариев в Dynamo важно всегда быть уверенным, что создаваемое соответствует ожидаемому. Это позволит быстро обнаружить непредвиденные события, такие как синтаксические ошибки, логические несоответствия, неточности значений, аномальные выходные данные и т. д., и устранить их по мере появления, а не сразу. Так как текстовые сценарии размещаются в узлах рабочей области, они автоматически встроены в поток данных визуальной программы. Благодаря этому последующий мониторинг сценария ограничивается лишь назначением данных для вывода, запуском программы и оценкой результатов, выводимых из сценария с помощью узла наблюдения (Watch). Ниже приводятся советы по непрерывной проверке сценариев в процессе их создания.

Проверка во время работы.

• Каждый раз по завершении работы над группой функций рекомендуется выполнять следующие действия.

  • Сделайте паузу и уделите время проверке кода.

  • Проявляйте критичность. Ваши коллеги смогут понять, для чего он предназначен? Эта функция действительно необходима? Можно ли повысить ее эффективность? Не создаю ли я лишних копий или зависимостей?

  • Проведите экспресс-проверку данных на целесообразность.

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

1. Убедитесь, что все кромки тела возвращаются в виде кривых, в результате чего вокруг него создается ограничивающая рамка.

2. Проверьте, чтобы входные данные количества успешно преобразовывались в диапазоны.

3. Убедитесь, что системы координат в данном цикле правильно преобразованы и повернуты.

Учитывайте пограничные случаи.

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

• Даже если программа работает с предельными установками, проверьте, не возвращает ли она нежелательные нулевые или пустые значения.

• Иногда неисправности и ошибки, позволяющие обнаружить скрытую проблему в сценарии, проявляются только в таких пограничных случаях.

  • Определите, что вызывает ошибку, а затем решите, следует ли исправить ее изнутри или перенастроить всю область параметров, чтобы избежать проблемы.

Эффективная отладка

Отладкой называется процесс устранения ошибок в сценарии. Под ошибками подразумеваются неполадки, недоработки, неточности и любые нежелательные результаты. Иногда чтобы исправить ошибку, достаточно скорректировать неправильно написанное имя переменной. В других случаях речь может идти о более глобальной проблеме, связанной со структурой сценария. В идеале зондирование сценария в процессе его создания поможет сразу выявить потенциальные проблемы, хотя это и не гарантирует полное отсутствие ошибок. Ниже приведены некоторые практические советы, которые помогут устранять ошибки систематически.

Используйте марки наблюдения.

• Проверяйте данные, возвращаемые в различных местах кода, назначая их переменной OUT (аналогично методу зондирования программы).

Оставляйте подробные комментарии.

• Модуль кода будет намного проще отладить, если предполагаемый результат его работы будет точно описан.

# Loop through X and Y
for i in range(xCount):
  for j in range(yCount):

    # Rotate and translate the coordinate system
    toCoord = fromCoord.Rotate(solid.ContextCoordinateSystem.Origin,Vector.ByCoordinates(0,0,1),(90*(i+j%seed)))
    vec = Vector.ByCoordinates((xDist*i),(yDist*j),0)
    toCoord = toCoord.Translate(vec)

    # Transform the solid from the source coord system to the target coord system and append to the list
    solids.append(solid.Transform(fromCoord,toCoord))

Обычно это приводит к увеличению количества информации и пустых строк, но при отладке позволяет анализировать данные, разбив их на отдельные части.

Используйте модульный принцип организации кода.

• Источник проблемы можно свести к определенным модулям.

• После того как проблемный модуль определен, исправить проблему будет значительно проще.

• Если необходимо изменить программу, код, который был разработан в отдельных модулях, будет намного проще скорректировать.

  • В существующую программу можно вставить новый или отлаженный модуль с уверенностью в том, что остальная часть программы не изменится.

Отладка файла примера из узла Python.

1. Входная геометрия возвращает ограничивающую рамку слишком большого размера. Это можно видеть, назначив переменной OUT значения xDist и yDist.

2. Кривые ребра входной геометрии имеют подходящую ограничивающую рамку и правильные расстояния xDist и yDist.

3. Вставлен модуль кода, позволяющий решить проблему со значениями xDist и yDist.

Упражнение «Траектория с наибольшей крутизной»

Скачайте файл примера, щелкнув указанную ниже ссылку.

Полный список файлов примеров можно найти в приложении.

Напишем сценарий для моделирования дождевых осадков с учетом представленных здесь практических советов по созданию текстовых сценариев. Несмотря на то, что практические советы были успешно применены к плохо организованной визуальной программе в разделе «Методы создания графиков», данные операции значительно сложнее выполнять с текстовыми сценариями. Логические связи, существующие в текстовых сценариях, сложнее отслеживаются и почти не распознаются в запутанном коде. Вместе с возможностями, которые дают текстовые сценарии, повышаются и требования к организации кода. Рассмотрим каждый из этапов, применяя на деле практические советы.

Наш сценарий применялся к поверхности, деформированной точкой притяжения.

Сначала следует импортировать необходимые библиотеки Dynamo. Сделав это в первую очередь, мы предоставим глобальный доступ к функциональным возможностям Dynamo в Python.

Сюда необходимо импортировать все библиотеки, которые планируется использовать.

Затем следует определить входные и выходные данные сценария, которые будут отображаться в качестве входных портов узла. Эти внешние входные данные являются основой сценария и ключом к созданию параметрической среды.

Необходимо определить входные данные, соответствующие переменным в сценарии Python, и определить желаемый результат.

1. Поверхность, по которой будут спускаться агенты.

2. Количество движущихся агентов.

3. Максимальное количество шагов, которые могут сделать агенты.

4. Возможность использования кратчайшего пути вниз по поверхности или ее пересечения.

5. Узел Python с идентификаторами ввода, соответствующими входным данным в сценарии (IN[0], IN[1]).

6. Выходные кривые, которые могут отображаться другим цветом.

Теперь воспользуемся принципом модульной организации и создадим основную часть сценария. Важной задачей является моделирование кратчайшей траектории вниз по поверхности для нескольких начальных точек. Для этого требуется использование нескольких функций. Вместо того чтобы вызывать различные функции в сценарии, можно создать модули кода, собрав функции в одном классе (агенте). Различные функции этого класса (или модуля) можно вызывать с помощью различных переменных или даже использовать в других сценариях.

Для агента необходимо определить класс (макет), который позволит спускаться по поверхности, выбирая перемещения в направлении с наибольшей крутизной при каждом шаге.

1. Имя.

2. Глобальные атрибуты, общие для всех агентов.

3. Атрибуты экземпляра, уникальные для каждого агента.

4. Функция для выполнения шага.

5. Функция каталогизации положения каждого шага в списке маршрутов.

Теперь инициализируйте агентов, определив их начальное положение. Это хорошая возможность для зондирования сценария с целью проверки работоспособности класса агентов.

Необходимо создать экземпляры всех агентов, спуск которых по поверхности будет отслеживаться, и определить их исходные атрибуты.

1. Новый пустой список маршрутов.

2. Место начала движения по поверхности.

3. Мы назначили список агентов в качестве выходных данных, чтобы проверить результат, возвращаемый сценарием. Возвращается правильное количество агентов, но позднее потребуется снова выполнить зондирование сценария для проверки полученной с помощью него геометрии.

Обновляйте агентов при каждом шаге. Затем необходимо вставить вложенный цикл, где положение каждого агента и шага будет обновляться и записываться в списке маршрутов. Кроме того, при выполнении каждого шага нужно проверять, не достиг ли агент точки на поверхности, где невозможно выполнить следующий шаг с направлением вниз. Если это условие выполняется, движение агента прекращается.

Теперь, когда все агенты полностью обновлены, получим соответствующую им геометрию. После того как все агенты достигнут предельного значения спуска или максимального количества шагов, следует создать сложную кривую (PolyCurve), проходящую через точки в списке их маршрутов, и вывести маршруты сложной кривой.

Сценарий для поиска траекторий с наибольшей крутизной.

1. Набор параметров для моделирования осадков на базовой поверхности.

2. Вместо поиска траектории с наибольшей крутизной можно переключить агентов на пересечение базовой поверхности.

Полный текстовый сценарий Python.

### STEEPEST PATH ALGORITHM

# IMPORT LIBRARIES
import sys
sys.path.append('C:\Program Files (x86)\IronPython 2.7\Lib')
import random
import math
import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

# DEFINE PARAMETER INPUTS
surfIn = IN[0]
numAgents = IN[1]
maxSteps = IN[2]
decendBoo = IN[3]


# DEFINE AGENT CLASS
class Agent(object):
    def get_step_size():
        area = surfIn.Area
        stepSize = math.sqrt(area)/100
        return stepSize

    zVec = Vector.ZAxis()
    stepSize = get_step_size()
    dupTol = 0.001


    def __init__(self,u,v):
        self.endBoo = False
        self.U = u
        self.V = v
        self.Z = None
        self.trailPts = []
        self.update_trail()

    def update(self):
        if not self.endBoo:
            positionPt01 = self.trailPts[-1]
            normalVec = surfIn.NormalAtParameter(self.U,self.V)
            gradientVec = Vector.Cross(self.zVec, normalVec)
            if decendBoo:
            	gradientVec = gradientVec.Rotate(normalVec,-90)

            gradientVec = gradientVec.Normalized()
            gradientVec = gradientVec.Scale(self.stepSize)
            positionPt02 = positionPt01.Add(gradientVec)
            newPt = surfIn.ClosestPointTo(positionPt02)
            newUV = surfIn.UVParameterAtPoint(newPt)
            newU, newV = newUV.U, newUV.V
            newZ = newPt.Z

            if decendBoo and (self.Z <= newZ):
            	self.endBoo = True
            else:
	            if ((abs(self.U-newU) <= self.dupTol) and (abs(self.V-newV) <= self.dupTol)):
	                self.endBoo = True
	            else:
	                self.U, self.V = newU, newV
	                self.update_trail()

    def update_trail(self):
        trailPt = surfIn.PointAtParameter(self.U,self.V)
        self.trailPts.append(trailPt)
        self.Z = trailPt.Z


# INITIALIZE AGENTS
agents = []
for i in range(numAgents):
	u = float(random.randrange(1000))/1000
	v = float(random.randrange(1000))/1000
	agent = Agent(u,v)
	agents.append(agent)


# UPDATE AGENTS
for i in range(maxSteps):
	for eachAgent in agents:
		eachAgent.update()

# DRAW TRAILS
trails = []
for eachAgent in agents:
	trailPts = eachAgent.trailPts
	if (len(trailPts) > 1):
		trail = PolyCurve.ByPoints(trailPts)
		trails.append(trail)

# OUTPUT TRAILS
OUT = trails