Esta parte do manual está organizada no espírito de um diário de “melhores práticas”. Ela lança luz sobre várias estratégias que aprendemos, por meio de experiência e pesquisa, como mais favoráveis a fluxos de trabalho paramétricos de qualidade. Como designers e programadores, nossa métrica de qualidade está preocupada principalmente com a manutenção, a dependência, a usabilidade e a eficiência de nossas ferramentas. Embora essas práticas recomendadas tenham exemplos específicos de scripts visuais ou baseados em texto, os princípios são aplicáveis a todos os ambientes de programação e podem informar muitos fluxos de trabalho computacionais.

Trabalhar dentro de um processo de programação visual pode ser uma poderosa atividade criativa, mas muito rapidamente o fluxo do programa e as principais entradas do usuário podem ser ofuscadas pela complexidade e/ou layout do espaço de trabalho. Vamos rever algumas práticas recomendadas para o gerenciamento do programa.

Alinhamento

Depois de adicionar alguns nós ao espaço de trabalho, convém reorganizar o layout dos nós por uma questão de clareza. Se selecionar mais de um nó e clicar com o botão direito do mouse no espaço de trabalho, a janela pop-up incluirá um menu Alinhar seleção com opções de justificação e distribuição em X e Y.

1. Selecione mais de um nó

2. Clique com o botão direito do mouse no espaço de trabalho

3. Use as opções Alinhar seleção

Observações

Com alguma experiência, podemos “ler” o programa visual, revisando os nomes dos nós e seguindo o fluxo do programa. Para usuários de todos os níveis de experiência, também é uma boa prática incluir descrições e legendas em linguagem simples. O Dynamo tem um nó Notas com um campo de texto editável para fazer isso. É possível adicionar notas ao espaço de trabalho de duas maneiras:

1. Navegue até o menu Editar > Criar nota

2. Use o atalho de teclado Ctrl+W

Após a nota ser adicionada ao espaço de trabalho, será exibido um campo de texto, permitindo editar o texto na nota. Após serem criadas, é possível editar as notas clicando duas vezes ou clicando com o botão direito do mouse no nó Nota.

Agrupamento

Quando nosso programa visual cresce, é útil identificar as etapas maiores que serão executadas. Podemos destacar conjuntos maiores de nós com um Grupo para incluir legendas com um retângulo colorido em segundo plano e um título. Existem três maneiras de criar um grupo com mais de um nó selecionado:

1. Navegue até o menu Editar > Criar grupo

2. Use o atalho de teclado Ctrl+G

3. Clique com o botão direito do mouse no espaço de trabalho e selecione “Criar grupo”

Uma vez criado um grupo, podemos editar suas configurações, como o título e a cor.

Veja um exemplo de programa com notas e grupos adicionados:

1. Nota: “Parâmetros da grade”

2. Nota: “Pontos da grade”

3. Nota: “Criar uma grade de pontos”

4. Grupo: “Criar um ponto atrativo”

5. Nota: “Calibrar valores de distância”

6. Nota: “Grade de círculos variável”

Esta página de referência estende as melhores práticas descritas em Estratégias de script com mais detalhes sobre bibliotecas de códigos, legendagem e estilização. Usaremos o Python para ilustrar os conceitos abaixo, mas os mesmos princípios se aplicam a Python e C# (Zerotouch), mas com sintaxe diferente.

Quais bibliotecas devem ser usadas

As bibliotecas padrão são externas ao Dynamo e estão presentes nas linguagens de programação Python e C# (Zerotouch). O Dynamo também tem seu próprio conjunto de bibliotecas que correspondem diretamente à sua hierarquia de nós, permitindo que o usuário crie qualquer coisa em código que possa ser feito com nós e fios. A seguir está um guia a indicar os acessos fornecidos por cada biblioteca do Dynamo e quando usar uma biblioteca padrão.

Bibliotecas padrão e bibliotecas do Dynamo

• As bibliotecas padrão do Python e C# podem ser usadas para criar dados avançados e estruturas de fluxo no ambiente do Dynamo.

• As bibliotecas do Dynamo correspondem diretamente à hierarquia dos nós para criar geometria e outros objetos do Dynamo.

Bibliotecas do Dynamo

1. ProtoGeometry*

   • Funcionalidade: Arco de elipse, Arco, Aresta, Caixa delimitadora, Cilindro, Círculo, Cone, Cuboide, Curva Nurbs, Curva, Elipse, Esfera, Face, Geometria, Grupo de índices, Hélice, Linha, Malha, Plano, Polígono, Ponto, Retângulo, Sistema de coordenadas, Sólido, Superfície Nurbs, Superfície, Topologia, TSpline, UV, Vértice, Vetor.

   • Como importar: import Autodesk.DesignScript.Geometry

   ``

2. DSCoreNodes

   • Funcionalidade: Cor, Intervalo de Cores 2D, Data e hora, Tempo, E/S, Fórmula, Lógica, Lista, Matemática, Quadtree, Sequência de caracteres, Rosca.

   • Como importar: import DSCore

3. Tessellation

   • Funcionalidade: Casco convexo, Delaunay, Voronoi.

   • Como importar: import Tessellation

4. DSOffice

   • Funcionalidade: Excel.

   • Como importar: import DSOffice

Rotular cuidadosamente

Enquanto cria scripts, estamos constantemente usando identificadores para indicar coisas como variáveis, tipos, funções e outras entidades. Por meio desse sistema de notação simbólica, ao criar algoritmos, podemos convenientemente nos referir às informações através de rótulos, geralmente compostos de uma sequência de caracteres. Atribuir nomes a coisas desempenha um papel importante em códigos de escrita que podem ser facilmente lidos e compreendidos por outras pessoas, bem como por você no futuro. Veja algumas dicas para se ter em mente ao nomear os itens no script:

É aceitável usar abreviações, mas explique a abreviação com um comentário:

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

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

Evite a legendagem redundante:

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

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

Use lógica positiva para os nomes de variáveis em vez de lógica negativa:

### 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'

Prefira a “notação inversa”:

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

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

É mais sensível, em termos estruturais.

Os alias devem ser usados para abreviar cadeias muito longas e frequentemente repetidas:

### 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

O uso de alias pode gerar rapidamente programas muito confusos e não padrão.

Use somente as palavras necessárias:

### 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)

“Tudo deve ser feito tão simples quanto possível, mas não mais simples”. – Albert Einstein

Estilo consistente

Em termos gerais, há mais de uma maneira de programar qualquer coisa; portanto, seu “estilo pessoal” de scripts é o resultado das inúmeras decisões pequenas que você tomar (ou não tomar) durante o processo. Mesmo assim, a legibilidade e a manutenção do código são um resultado direto de sua consistência interna, bem como sua adesão às convenções estilizadas gerais. Como regra geral, o código com a mesma aparência em dois lugares deve funcionar da mesma maneira também. Aqui estão algumas dicas para escrever código claro e consistente.

Convenções de nomenclatura: (selecione uma das convenções abaixo para cada tipo de entidade no código e a mantenha.)

• Variáveis, funções, métodos, pacotes, módulos: lower_case_with_underscores

• Classes e exceções: CapWords

• Funções internas e métodos protegidos: _single_leading_underscore(self, ...)

• Métodos privados: __double_leading_underscore(self, ...)

• Constantes: ALL_CAPS_WITH_UNDERSCORES

Dica: Evite variáveis de uma só letra (especialmente l, O, I), exceto em blocos muito curtos, quando o significado estiver claramente visível no contexto imediato.

Use linhas em branco:

• Defina a função de nível superior e as definições de classe com duas linhas em branco.

  • As definições de método dentro de uma classe são cercadas por uma única linha em branco.

  • É possível usar linhas em branco adicionais (com moderação) para separar grupos de funções relacionadas.

Evite espaços em branco desnecessários:

• Imediatamente dentro dos parênteses, colchetes ou chaves:

  Copy

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

  Copy

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

• Imediatamente antes de uma vírgula, ponto e vírgula ou dois pontos:

  Copy

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

  Copy

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

• Imediatamente antes do parêntese de abertura que inicia a lista de argumentos de uma chamada de função:

  Copy

  ### BAD
  function (1)

  Copy

  ### GOOD
  function(1)

• Imediatamente antes do parêntese de abertura que inicia uma indexação ou fatiamento:

  Copy

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

  Copy

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

• Sempre coloque esses operadores binários com um único espaço em cada lado:

  Copy

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

Comprimento da linha de inspeção:

• Não se estresse com isso, aproximadamente 79 caracteres.

• Limitar a largura da janela do editor necessária possibilita ter vários arquivos abertos lado a lado e funciona bem ao usar as ferramentas de revisão de código que apresentam as duas versões em colunas adjacentes.

• Linhas longas podem ser divididas em várias linhas colocando expressões entre parênteses:

Evite comentários óbvios e redundantes:

• Às vezes, menos comentários resultam em um código mais legível. Especialmente se isso forçar o uso de nomes de símbolos significativos.

• Adotar bons hábitos de codificação reduz a dependência de comentários:

  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()

Dica: Os comentários informam o porquê, o código informa como.

Confira o código-fonte aberto:

• Os projetos em código aberto foram desenvolvidos com base nos esforços de colaboração de muitos desenvolvedores. Esses projetos precisam manter um alto nível de legibilidade de código para que a equipe possa trabalhar em conjunto da maneira mais eficiente possível. Portanto, é aconselhável procurar o código fonte desses projetos para observar o que esses desenvolvedores estão fazendo.

• Melhore as convenções:

  • Questione se cada convenção está ou não funcionando para as necessidades em questão.

  • A funcionalidade/eficiência está sendo comprometida?

Padrões C# (Zerotouch)

Confira estas páginas wiki para obter ajuda sobre como escrever em C# para Zerotouch e contribuir para o Dynamo:

• Este wiki aborda alguns padrões gerais de codificação para documentar e testar o código: https://github.com/DynamoDS/Dynamo/wiki/Coding-Standards

• Este wiki aborda especificamente os padrões de nomenclatura para bibliotecas, categorias, nomes de nós, nomes de porta e abreviações: https://github.com/DynamoDS/Dynamo/wiki/Naming-Standards

Objetos não gerenciados:

Ao usar a biblioteca de geometria do Dynamo (ProtoGeometry) do Python ou C#, os objetos de geometria que você criar não serão gerenciados pela máquina virtual, e a memória de muitos desses objetos precisará ser limpa manualmente. Para limpar objetos nativos ou não gerenciados, é possível usar o método Descartar ou usar a palavra-chave. Consulte esta entrada do wiki para obter uma visão geral: https://github.com/DynamoDS/Dynamo/wiki/Zero-Touch-Plugin-Development#dispose--using-statement.

Você só precisa descartar os recursos não gerenciados aos quais não retorne no gráfico ou para os quais não armazene uma referência. Para o restante desta seção, chamaremos esses objetos geometria intermediária. É possível ver um exemplo dessa classe de objeto no exemplo de código abaixo. Essa função C# zerotouch singleCube retorna um único cubo, mas cria 10.000 cubos extras durante sua execução. É possível simular que usamos essa outra geometria como alguma geometria de construção intermediária.

Essa função zerotouch provavelmente causará um erro fatal no Dynamo. Como criamos 10.000 sólidos, mas somente um deles foi armazenado, só esse será devolvido. Devemos, em vez disso, descartar todos os nossos cubos intermediários, exceto o que retornamos. Não queremos descartar o que retornamos, pois será propagado no gráfico e usado por outros nós.

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;
}

O código fixo deve ter o seguinte aspecto:

 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;
 }

Em geral, basta descartar a geometria como Surfaces, Curves e Solids. Para estar seguro, no entanto, é possível descartar todos os tipos de geometria (Vectors, Points, CoordinateSystems).

Antes deste capítulo, a introdução abordou como implementar os recursos avançados de scripts visuais do Dynamo. Uma boa compreensão desses recursos é uma base sólida e a primeiro etapa para criação de programas visuais robustos. Quando usamos nossos programas visuais no campo, os compartilhamos com colegas, solucionamos erros ou testamos limites adicionais com os quais você precisa lidar. Se outra pessoa usar seu programa no futuro ou se você estiver esperando abri-lo daqui a seis meses, ele precisará ter uma clareza gráfica e lógica imediata. O Dynamo tem muitas ferramentas para gerenciar a complexidade do programa, e este capítulo fornecerá diretrizes sobre quando usá-las.

Reduzir a complexidade

À medida que você desenvolve o gráfico do Dynamo e testa ideias, ele pode aumentar rapidamente em tamanho e complexidade. Embora seja importante criar um programa funcional, é igualmente importante o tornar o mais simples possível. Assim, além de o gráfico ser executado de forma mais rápida e previsível, você e outros usuários compreenderão a lógica posteriormente. Confira a seguir diversas formas que ajudarão você a esclarecer a lógica do gráfico.

Modularizar com grupos

• Os grupos permitem criar partes funcionalmente distintas enquanto você cria um programa

• Os grupos permitem mover grandes partes do programa enquanto a modularidade e o alinhamento são mantidos

• É possível alterar a cor do grupo para diferenciar o que os grupos estão fazendo (entradas versus funções)

• É possível usar grupos para iniciar a organização do gráfico para simplificar a criação do nó personalizado

As cores deste programa identificam o propósito de cada grupo. Essa estratégia pode ser usada para criar hierarquia em qualquer norma gráfica ou modelo que você desenvolver.

1. Grupo de funções (azul)

2. Grupo de entradas (laranja)

3. Grupo de scripts (verde)

Para saber como usar Grupos, consulte Como gerenciar o programa.

Desenvolver com eficiência usando blocos de código

• Às vezes, é possível usar um bloco de código para digitar um método de nó ou número mais rapidamente do que pesquisando (Point.ByCoordinates, Number, String, Formula)

• Os blocos de código são úteis quando você deseja definir funções personalizadas no DesignScript para reduzir o número de nós em um gráfico

Tanto 1 quanto 2 executam a mesma função. Era muito mais rápido escrever algumas linhas de código do que procurar e adicionar cada nó individualmente. O bloco de código também é muito mais conciso.

1. DesignScript escrito no bloco de código

2. Programa equivalente nos nós

Para saber como usar o bloco de código, consulte O que é um bloco de código?

Condensar com Nó para código

• É possível reduzir a complexidade de um gráfico com a opção Nó para código, que usa um conjunto de nós simples e grava o DesignScript correspondente em um único bloco de código

• O Nó para código pode** condensar o código sem eliminar a clareza do programa**

• Vantagens do uso de Nó para código:

  • Condensa facilmente o código em um componente que ainda é editável

  • Pode simplificar uma parte significativa do gráfico

  • Será útil se o “miniprograma” não for editado com frequência

  • É útil para incorporar outras funcionalidades de bloco de código, como funções

• Desvantagens do uso de Nó para código:

  • A nomenclatura genérica o torna menos legível

  • É mais difícil de entender para outros usuários

  • Não há uma forma fácil de retornar à versão de programação visual

1. Programa existente

2. Bloco de código criado usando Nó para código

Para saber como usar Nó para código, consulte Sintaxe do DesignScript.

Acessar os dados de forma flexível com List@Level

• O uso do recurso List@Level pode ajudar a reduzir a complexidade do gráfico substituindo os nós List.Map e List.Combine, que podem ocupar um volume considerável de espaço da tela

• O recurso List@Level oferece uma** forma mais rápida do que List.Map/List.Combine para criar a lógica do nó** permitindo acessar dados em qualquer nível de uma lista diretamente da porta de entrada de um nó

É possível verificar quantos valores verdadeiros BoundingBox.Contains retorna e em quais listas, ativando List@Level para a entrada de “lista” de CountTrue. O recurso List@Level permite que o usuário determine de qual nível a entrada extrairá os dados. O uso de List@Level é flexível, eficiente e altamente recomendável em relação a outros métodos que envolvem List.Map e List.Combine.

1. Contagem de valores verdadeiros no Nível de lista 2

2. Contagem de valores verdadeiros no Nível de lista 3

Para saber como usar List@Level, consulte Listas de listas.

Manter a legibilidade

Além de tornar o gráfico o mais simples e eficiente possível, tente obter maior clareza gráfica. Apesar de seus melhores esforços para tornar o gráfico intuitivo com agrupamentos lógicos, os relacionamentos podem não ser evidentes. Uma Nota simples dentro de um grupo ou a renomeação de um controle deslizante pode poupar confusão desnecessária ou a aplicação de pan pelo gráfico para você ou outro usuário. Confira a seguir diversas formas que ajudarão você a aplicar consistência gráfica nos gráficos e entre eles.

Continuidade visual com o alinhamento de nós

• Para reduzir o trabalho após terminar de criar o gráfico, você deve tentar garantir que o layout dos nós seja legível alinhando os nós com frequência e conforme você avança

• Se outras pessoas estiverem trabalhando com o gráfico, você deverá garantir que o layout fio/nó flua com facilidade antes do envio

• Para ajudar com o alinhamento, use o recurso “Limpeza do layout do nó” para alinhar automaticamente o gráfico, porém de forma menos precisa do que se você fizesse isso manualmente

1. Gráfico não organizado

2. Gráfico alinhado

Para saber como usar o alinhamento de nós, consulte Gerenciar o programa.

Legendagem descritiva por meio de renomeação

• A renomeação de entradas poderá ajudar outras pessoas a entender facilmente o gráfico, principalmente se o item a que elas se conectam estiver fora da tela

• Tenha cuidado ao renomear nós que não sejam entradas. Uma alternativa para isso é criar um nó personalizado de um cluster de nós e renomeá-lo; assim, ficará subentendido que ele contém outra coisa

1. Entradas para manipulação de superfície

2. Entradas para parâmetros arquitetônicos

3. Entradas para o script de simulação de drenagem

Para renomear um nó, clique com o botão direito do mouse no nome e selecione “Renomear nó...”.

Explicar com notas

• Adicione uma nota se algo no gráfico necessitar de uma explicação em linguagem simples que os nós não podem expressar

• Você deverá adicionar uma nota se um conjunto de nós ou um grupo for muito grande ou complexo e não puder ser facilmente compreendido de imediato

1. Uma nota que descreve a parte do programa que retorna as distâncias brutas de conversão

2. Uma nota que descreve o código que mapeia esses valores para uma onda sinusoidal

Para saber como adicionar uma nota, consulte Como gerenciar o programa.

Flexionar de forma contínua

Ao criar o script visual, é importante verificar se o que está sendo retornado é o que você esperava. Nem todos os erros ou problemas causarão a falha imediata do programa, principalmente valores nulos ou zero que possam afetar algo distante a jusante. Essa estratégia também é discutida no contexto de scripts de texto em Estratégias de script. A prática a seguir ajudará a garantir que você obtenha o que esperava.

Monitorar os dados com balões de visualização e inspeção

• Use balões de visualização ou inspeção durante a criação do programa para** verificar se as saídas principais estão retornando o que você esperava**

Os nós de inspeção são usados para comparar:

1. As distâncias de conversão brutas

2. Os valores passados pela equação de seno

Para saber como usar a Inspeção, consulte Biblioteca.

Garantir a reutilização

É altamente provável que outra pessoa esteja abrindo o programa em algum momento, mesmo que você esteja trabalhando de forma independente. Ela deve ser capaz de entender rapidamente o que o programa precisa e produz com base em suas entradas e saídas. Isso é especialmente importante ao desenvolver um nó personalizado para ser compartilhado com a comunidade do Dynamo e usado no programa de outra pessoa. Essas práticas resultam em programas e nós robustos e reutilizáveis.

Gerenciar as E/S

• Para garantir a legibilidade e a escalabilidade, tente minimizar as entradas e saídas o máximo possível

• Você deve tentar estabelecer uma estratégia de como criará a lógica elaborando um esboço de como a lógica poderia funcionar antes mesmo de adicionar um único nó à tela. À medida que desenvolve o esboço, você deve monitorar quais entradas e saídas farão parte de scripts

Usar predefinições para incorporar valores de entrada

• Se houver opções ou condições específicas que você queira incorporar ao gráfico, use as predefinições para obter acesso rápido

• Também é possível usar as predefinições para reduzir a complexidade armazenando em cache os valores específicos de controle deslizante em um gráfico com tempos de execução longos

Para saber como usar as predefinições, consulte Gerenciar os dados com as predefinições.

Conter programas com nós personalizados

• Você deverá usar um nó personalizado se o programa puder ser coletado em um único contêiner

• Você deverá usar um nó personalizado quando uma parte do gráfico for reutilizada com frequência em outros programas

• Você deverá usar um nó personalizado se desejar compartilhar uma funcionalidade com a comunidade do Dynamo

A coleta do programa de conversão de pontos em um nó personalizado torna portátil e muito mais fácil de entender um programa robusto e exclusivo. Portas de entrada bem nomeadas ajudarão outros usuários a entender como usar o nó. Lembre-se de adicionar descrições e tipos de dados necessários a cada entrada.

1. Programa atrativo existente

2. Nó personalizado que coleta este programa, PointGrid

Para saber como usar nós personalizados, consulte Introdução aos nós personalizados.

Modelos de construção

• É possível criar modelos para estabelecer padrões gráficos nos gráficos visuais para garantir que os colaboradores tenham um modo padronizado de entender o gráfico

• Durante a criação de um modelo, é possível padronizar as cores de grupo e os tamanhos de fonte para categorizar os tipos de fluxos de trabalho ou as ações de dados.

• Durante a criação de um modelo, é possível até mesmo padronizar como você quer definir legendas, cores ou estilos para diferenciar entre os fluxos de trabalho de front-end e back-end no gráfico.

1. A interface do usuário, ou o front-end, do programa inclui um nome de projeto, controles deslizantes de entrada e geometria de importação.

2. O back-end do programa.

3. Categorias de cor de grupo (o projeto geral, as entradas, o script do Python, a geometria importada).

Exercício – Telhado arquitetônico

Faça o download do arquivo de exemplo clicando no link abaixo.

É possível encontrar uma lista completa de arquivos de exemplo no Apêndice.

Agora que estabelecemos várias práticas recomendadas, vamos aplicá-las a um programa que foi montado rapidamente. Embora o programa seja bem-sucedido na geração do telhado, o estado do gráfico é um “mapa mental” do autor. Ele não possui nenhuma organização ou descrição de seu uso. Vamos examinar as práticas recomendadas para organizar, descrever e analisar o programa de modo que outros usuários possam entender como usá-lo.

O programa está funcionando, mas o gráfico está desorganizado.

Vamos começar determinando os dados e a geometria retornados pelo programa.

A compreensão de quando ocorrem as principais alterações nos dados é crucial para estabelecer divisões lógicas ou modularidade. Tente inspecionar o restante do programa com os nós de inspeção para ver se é possível determinar grupos antes de passar para a próxima etapa.

1. Esse bloco de código com uma equação matemática se parece com uma parte crucial do programa. Um nó de inspeção mostra que ele está retornando listas de distâncias de conversão.

2. O objetivo dessa área não é evidente. A disposição dos valores True no nível de lista L2 de BoundingBox.Contains e a presença de List.FilterByBoolMask sugerem que estamos fazendo uma amostragem de uma parte da grade de pontos.

Quando entendermos as partes elementares do programa, vamos colocá-las em grupos.

Os grupos permitem que o usuário diferencie visualmente as partes do programa.

1. Importar o modelo de terreno 3D

2. Converter a grade de ponto com base na equação de seno

3. Parte de exemplo da grade de pontos

4. Criar a superfície de telhado arquitetônico

5. Criar a parede cortina de vidro

Com os grupos estabelecidos, alinhe os nós para criar a continuidade visual no gráfico.

A continuidade visual ajuda o usuário a ver o fluxo do programa e as relações implícitas entre os nós.

Torne o programa mais acessível adicionando mais uma camada de melhorias gráficas. Adicione notas para descrever como funciona uma área específica do programa, atribua nomes personalizados às entradas e atribua cores a diferentes tipos de grupos.

Essas melhorias gráficas dão mais informações ao usuário sobre o que o programa está fazendo. As diferentes cores de grupo ajudam a diferenciar as entradas das funções.

1. Notas

2. Entradas com nomes descritivos

Antes de começarmos a condensar o programa, vamos encontrar uma localização estratégica para introduzir o simulador de drenagem do script do Python. Conecte a saída da primeira superfície de telhado dimensionado à respectiva entrada de script.

Escolhemos integrar scripts neste ponto no programa para que a simulação de drenagem possa ser executada na superfície original de telhado único. Essa superfície específica não está sendo visualizada, mas nos poupa a necessidade de escolher a superfície superior da PolySurface chanfrada.

1. Geometria de origem para entrada de script

2. Nó do Python

3. Controles deslizantes de entrada

4. “Chave” ligar/desligar

Vamos simplificar o gráfico agora que tudo está em seu devido lugar.

A condensação do nosso programa com Nó para código e Nó personalizado reduziu consideravelmente o tamanho do gráfico. Os grupos que criam a superfície do telhado e as paredes foram convertidos em código, já que são muito específicos deste programa. O grupo de conversão de pontos está contido em um Nó personalizado, pois ele pode ser usado em outro programa. No arquivo de exemplo, crie seu próprio nó personalizado com base no grupo de conversão de pontos.

1. Nó personalizado para conter o grupo “converter grade de pontos”

2. Nó para código para condensar os grupos “criar superfície de telhado arquitetônico e parede cortina”

Como etapa final, crie predefinições de formas de telhado exemplares.

Essas entradas são os principais acionadores da forma do telhado e ajudarão os usuários a ver o potencial do programa.

Nosso programa com vistas de duas predefinições.

Os padrões de drenagem do telhado fornecem ao usuário uma vista analítica das predefinições respectivas.

Os scripts baseados em texto no ambiente de scripts visuais permitem relacionamentos visuais avançados usando o DesignScript, o Python e o ZeroTouch (C#). O usuário pode expor elementos como os controles deslizantes de entrada, condensar grandes operações no DesignScript e acessar ferramentas e bibliotecas avançadas por meio do Python ou do C#, tudo isso no mesmo espaço de trabalho. Se gerenciada de forma eficaz, a combinação dessas estratégias pode fornecer uma grande quantidade de personalização, clareza e eficiência a todo o programa. A seguir, há um conjunto de diretrizes para ajudar a ampliar o script visual com script de texto.

Como saber quando criar scripts

Os scripts de texto podem estabelecer relacionamentos de maior complexidade do que a programação visual, mas há uma quantidade significativa de sobreposição de recursos entre ambos. Isso faz sentido porque os nós são essencialmente um código pré-empacotado e é provável que possamos escrever um programa inteiro do Dynamo em DesignScript ou Python. No entanto, usamos scripts visuais porque a interface dos nós e dos fios cria um fluxo intuitivo de informações gráficas. O conhecimento de que os recursos de script de texto vão além do script visual oferece pistas importantes de quando ele deve ser usado sem sacrificar a natureza intuitiva dos nós e dos fios. A seguir, encontram-se as diretrizes sobre quando inserir um script e qual linguagem usar.

Use os scripts de texto para:

• Loops

• Recursão

• Acessar bibliotecas externas

Escolha uma linguagem:

Pensar de forma paramétrica

Ao criar scripts no Dynamo, um ambiente inevitavelmente paramétrico, é aconselhável estruturar o código em relação à estrutura de nós e do fios na qual ele residirá. Considere o nó que contém o script de texto como se fosse qualquer outro nó no programa com algumas entradas específicas, uma função e uma saída esperada. Isso imediatamente fornece ao código no nó um pequeno conjunto de variáveis com o qual é possível trabalhar, a chave para um sistema paramétrico limpo. Aqui estão algumas diretrizes para uma melhor integração do código em um programa visual.

Identifique as variáveis externas:

• Tente determinar os parâmetros fornecidos no problema do projeto para que você possa construir diretamente um modelo com base nesses dados.

• Antes de escrever o código, identifique as variáveis:

  • Um conjunto mínimo de entradas

  • A saída pretendida

  • Constantes

Diversas variáveis foram estabelecidas antes de escrever o código.

1. A superfície na qual simularemos as águas pluviais.

2. O número de gotas de chuva (agentes) que desejamos.

3. A distância que desejamos que as gotas de chuva percorram.

4. Alterne entre descer o caminho mais inclinado e percorrer a superfície.

5. Nó do Python com o respectivo número de entradas.

6. Um bloco de código para tornar azuis as curvas retornadas.

Projete os relacionamentos internos:

• O parametricismo permite que determinados parâmetros ou variáveis sejam editados para manipular ou alterar o resultado final de uma equação ou de um sistema.

• Sempre que as entidades do script estão logicamente relacionadas, é preciso defini-las como funções umas das outras. Dessa forma, quando uma é modificada, a outra pode ser atualizada proporcionalmente.

• Minimize o número de entradas expondo somente os parâmetros chave:

  • Se for possível derivar um conjunto de parâmetros de mais parâmetros principais, somente exponha os parâmetros principais como entradas de script. Isso aumenta a usabilidade reduzindo a complexidade da interface do script.

1. Entradas.

2. Variáveis internas do script.

3. Um loop que usa essas entradas e variáveis para executar sua função.

Não se repita (o princípio DRY):

• Quando você tem várias maneiras de expressar o mesmo no script, em algum momento as representações duplicadas não estarão sincronizadas, o que pode provocar uma grande dificuldade de manutenção, má fatoração e contradições internas.

• O princípio DRY é declarado como “Cada conhecimento deve ter uma representação única, inequívoca e confiável dentro de um sistema”:

  • Quando esse princípio é aplicado com êxito, todos os elementos relacionados ao script mudam de forma previsível e uniforme, e todos os elementos não relacionados não têm consequências lógicas entre si.

### 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)

Estruturar de forma modular

Conforme seu código fica cada vez mais complexo, a “ideia geral”, ou o algoritmo abrangente, se torna cada vez mais ilegível. Também é mais difícil controlar o que (e onde) coisas específicas acontecem, encontrar falhas quando as coisas dão errado, integrar outro código e atribuir tarefas de desenvolvimento. Para evitar essas dores de cabeça, é preciso escrever código em módulos, uma estratégia organizacional que divide o código com base na tarefa que ele executa. Aqui estão algumas dicas para tornar os scripts mais gerenciáveis por meio da modularização.

Escreva código em módulos:

• Um “módulo” é um grupo de códigos que executa uma tarefa específica, similar a um nó do Dynamo no espaço de trabalho.

• Isso pode ser qualquer item que deva ser visualmente separada do código adjacente (uma função, uma classe, um grupo de entradas ou as bibliotecas que você esteja importando).

• O desenvolvimento de código em módulos aproveita a característica visual e intuitiva dos nós, bem como as relações complexas que somente os scripts de texto podem obter.

Esses loops chamam uma classe nomeada “agente” que desenvolveremos no exercício.

1. Um módulo de código que define o ponto inicial de cada agente.

2. Um módulo de código que atualiza o agente.

3. Um módulo de código que desenha um rastro para o caminho do agente.

Identificação da reutilização de código:

• Se você achar que seu código faz a mesma coisa (ou algo muito similar) em mais de um lugar, encontre maneiras de agrupá-lo em uma função que possa ser chamada.

• As funções de “gerenciador” controlam o fluxo do programa e contêm principalmente chamadas para funções de “trabalho” que lidam com detalhes de baixo nível, como mover dados entre estruturas.

Este exemplo cria esferas com raios e cores com base no valor Z dos pontos centrais.

1. Duas funções principais de “trabalho”: uma que cria esferas com raios e exibe cores com base no valor Z do ponto central.

2. Uma função principal de “gerenciador” que combina as duas funções de trabalho. Chamar essa função chamará as duas funções no interior dela.

Mostre somente o que precisa ser visto:

• Uma interface de módulo expressa os elementos que são fornecidos e requeridos pelo módulo.

• Quando as interfaces entre as unidades tiverem sido definidas, o projeto detalhado de cada unidade poderá prosseguir separadamente.

Capacidade de separação/substituição:

• Os módulos não sabem ou são indiferentes quanto à existência uns dos outros.

Formas gerais de modularização:

• Agrupamento de código:

  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]

• Funções:

  Copy

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

• Classes:

  Copy

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

Flexionar de forma contínua

Ao desenvolver scripts de texto no Dynamo, é recomendável garantir constantemente que o que está sendo realmente criado esteja de acordo com as suas expectativas. Isso garante que eventos imprevistos, como erros de sintaxe, discrepâncias lógicas, imprecisões de valor, saídas anômalas, etc., sejam rapidamente descobertos e tratados conforme surgirem, em vez de todos ao mesmo tempo no final. Como os scripts de texto residem nos nós internos da tela, eles já estão integrados no fluxo de dados do programa visual. Isso torna o monitoramento sucessivo do script tão simples quanto a atribuição dos dados a serem gerados, a execução do programa e a avaliação do que flui do script usando um nó de inspeção. Confira aqui algumas dicas para inspecionar continuamente os scripts ao construí-los.

Teste conforme o uso:

• Sempre que você concluir um conjunto de funcionalidades:

  • Volte e inspecione o código.

  • Seja crítico. Um colaborador conseguiria entender o que ele está produzindo? Preciso fazer isso? Essa função pode ser feita de forma mais eficiente? Estou criando dependências ou duplicatas desnecessárias?

  • Teste rapidamente para garantir que ele esteja retornando dados que “façam sentido”.

• Atribua os dados mais recentes com os quais você está trabalhando em seu script como a saída, de forma que o nó sempre produza dados relevantes quando o script for atualizado:

1. Verifique se todas as arestas do sólido estão sendo retornadas como curvas para criar uma caixa delimitadora em torno dele.

2. Verifique se nossas entradas de contagem estão sendo convertidas com êxito em intervalos.

3. Verifique se os sistemas de coordenadas foram corretamente convertidos e rotacionados neste loop.

Antecipe “casos de aresta”:

• Durante a criação dos scripts, coloque os parâmetros de entrada nos valores mínimo e máximo de seus domínios alocados para verificar se o programa ainda funciona em condições extremas.

• Mesmo que o programa funcione em seus extremos, verifique se ele está retornando valores nulos/vazios/zero não pretendidos.

• Às vezes, as falhas e os erros que revelam um problema subjacente com seu script só surgirão durante esses casos de aresta.

  • Compreenda o que está causando o erro e, em seguida, decida se ele precisa ser corrigido internamente ou se um domínio de parâmetro precisa ser redefinido para evitar o problema.

Depurar de forma eficiente

A depuração é o processo de eliminação de falhas do script. As falhas podem ser erros, ineficiências, imprecisões ou qualquer resultado não pretendido. A solução de uma falha pode ser tão simples quanto corrigir um nome de variável com erros de grafia ou problemas estruturais mais abrangentes no script. Idealmente, a flexibilização do script à medida que você o cria ajudará a detectar esses possíveis problemas no início, embora isso não seja uma garantia de que ele estará livre de falhas. A seguir, apresentamos uma revisão das várias práticas recomendadas acima para ajudar a solucionar falhas de forma sistemática.

Use a bolha de inspeção:

• Verifique os dados retornados em diferentes locais no código ao atribuí-los à variável OUT, de forma semelhante ao conceito de flexibilização do programa.

Insira comentários significativos:

• Será muito mais fácil depurar um módulo de código se seu resultado pretendido for claramente descrito.

# 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))

Normalmente, isso seria uma quantidade excessiva de linhas de comentário e em branco; mas, ao depurar, pode ser útil dividir os itens em partes gerenciáveis.

Aproveite a modularidade do código:

• É possível isolar a origem de um problema em determinados módulos.

• Quando o módulo com falha for identificado, a correção do problema será consideravelmente mais simples.

• Quando um programa precisa ser modificado, é muito mais fácil alterar o código que foi desenvolvido nos módulos:

  • É possível inserir módulos novos ou depurados em um programa existente com a segurança de que o restante do programa não será alterado.

1. A geometria de entrada está retornando uma caixa delimitadora maior que ela mesma, como podemos ver ao atribuir xDist e yDist a OUT.

2. As curvas de aresta da geometria de entrada retornam uma caixa delimitadora apropriada com as distâncias corretas para xDist e yDist.

3. O “módulo” do código que inserimos para resolver o problema dos valores xDist e yDist.

Exercício: Caminho mais inclinado

Faça o download do arquivo de exemplo clicando no link abaixo.

É possível encontrar uma lista completa de arquivos de exemplo no Apêndice.

Considerando as nossas melhores práticas para os scripts de texto, vamos escrever um script de simulação de chuva. Embora seja possível aplicar as práticas recomendadas a um programa visual desorganizado em Estratégias de gráfico, é muito mais difícil fazer isso com scripts de texto. As relações lógicas estabelecidas no script de texto são menos visíveis e pode ser quase impossível decifrá-las em um código confuso. O poder dos scripts de texto é acompanhado por uma responsabilidade maior na organização. Vamos detalhar cada etapa e aplicar as práticas recomendadas durante o percurso.

Nosso script aplicado a uma superfície deformada por atrativos.

A primeira coisa que precisamos fazer é importar as bibliotecas do Dynamo necessárias. Fazer isso fornecerá acesso global à funcionalidade do Dynamo no Python.

Todas as bibliotecas que pretendemos usar precisam ser importadas aqui.

Em seguida, precisamos definir as entradas e a saída do script, que serão exibidas como portas de entrada no nó. Essas entradas externas são a base do nosso script e a chave para estabelecer um ambiente paramétrico.

Precisamos definir entradas que correspondam a variáveis no script do Python e determinar a saída desejada:

1. A superfície que queremos percorrer.

2. O número de agentes pelos quais queremos percorrer.

3. O número máximo de etapas que os agentes podem assumir.

4. Uma opção para obter o caminho mais curto pela superfície ou para percorrê-la.

5. O nó do Python com identificadores de entrada que correspondem às entradas no script (IN[0], IN[1]).

6. As curvas de saída que podem ser exibidas com uma cor diferente.

Agora, vamos empregar a prática da modularidade e criar o corpo do nosso script. A simulação do caminho mais curto por uma superfície de vários pontos iniciais é uma tarefa significativa que exigirá diversas funções. Em vez de chamar as diferentes funções por todo o script, podemos modularizar nosso código coletando-as em uma única classe, nosso agente. As diferentes funções dessa classe ou “módulo” podem ser chamadas com diferentes variáveis ou até mesmo reutilizadas em outro script.

Precisaremos definir uma classe ou blueprint para um agente com a intenção de percorrer uma superfície, escolhendo o deslocamento na direção mais inclinada possível sempre que ele assumir uma etapa:

1. Nome.

2. Atributos globais compartilhados por todos os agentes.

3. Atributos de instância exclusivos para cada agente.

4. Uma função para realizar uma etapa.

5. Uma função para catalogar a posição de cada etapa em uma lista de rastros.

Vamos inicializar os agentes definindo sua localização inicial. Esta é uma boa oportunidade para flexibilizar nosso script e garantir que a classe de agente esteja funcionando.

Precisaremos instanciar todos os agentes que desejamos observar pela superfície e definir seus atributos iniciais:

1. Uma nova lista de rastros vazia.

2. Onde eles iniciarão sua jornada na superfície.

3. Atribuímos a lista de agentes como saída para verificar o que o script está retornando aqui. O número correto de agentes está sendo retornado, mas precisamos flexionar o script novamente mais tarde para verificar a geometria que ele retorna.

Atualize cada agente em cada etapa. Em seguida, precisaremos inserir um ciclo aninhado onde, para cada agente e para cada etapa, atualizamos e registramos sua posição na lista de rastros. Em cada etapa, também garantiremos que o agente não tenha alcançado um ponto na superfície em que ele não possa avançar mais uma etapa, o que lhe permitirá descer. Se essa condição for atendida, encerraremos o percurso do agente.

Agora que nossos agentes foram totalmente atualizados, vamos retornar a geometria que os representa. Depois que todos os agentes tiverem atingido seu limite de descida ou o número máximo de etapas, criaremos uma policurva pelos pontos da lista de rastros e geraremos os rastros da policurva.

Nosso script para encontrar os caminhos mais inclinados.

1. Uma predefinição que simula as águas pluviais na superfície subjacente.

2. Em vez de encontrar o caminho mais inclinado, é possível alternar os agentes para percorrer a superfície subjacente.

O script de texto completo em 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