Guia Revit API — Primeiros Passos com Automação BIM

Bem-vindo ao Revit API#

O Revit API (Application Programming Interface) é um kit de ferramentas poderoso que permite aos desenvolvedores criar aplicações customizadas, automatizar tarefas e estender as funcionalidades do Revit. Seja trabalhando com scripts Dynamo, criando add-ins ou desenvolvendo aplicações standalone, o Revit API fornece a base para automação BIM avançada.

Este é o primeiro artigo de uma série de três partes sobre desenvolvimento com Revit API:

1. Primeiros Passos com Automação BIM (este artigo)
2. Coleta de Elementos com FilteredElementCollector
3. Métodos de Seleção de UI

Pré-requisitos#

Antes de mergulhar no desenvolvimento com Revit API, certifique-se de ter:

• Autodesk Revit instalado (2020 ou posterior recomendado)
• Conhecimento Básico de Programação (C# ou Python de preferência)
• Dynamo for Revit (para abordagens de programação visual - veja seção abaixo)
• Visual Studio ou Visual Studio Code (apenas se desejar criar add-ins em C#)

Dynamo e Revit API: Qual Escolher?#

Antes de escrever código, é importante entender as diferentes formas de automatizar o Revit e quando usar cada uma.

O que é Dynamo?#

Dynamo é uma plataforma de programação visual integrada ao Revit. Em vez de escrever linhas de código, você conecta nós gráficos que representam operações. Cada nó tem entradas, executa uma ação específica e produz saídas que podem ser conectadas a outros nós.

Pense no Dynamo como construir com blocos LEGO — cada bloco (nó) tem uma função clara, e você os conecta para criar soluções complexas.

Quando Usar Dynamo#

Dynamo é ideal quando:

• Você está começando com automação BIM
• A lógica é linear e visual (panelização de fachada, posicionamento de famílias)
• Você quer prototipar rapidamente uma ideia
• O workflow requer modificações frequentes por usuários não programadores
• Precisa de documentação visual do processo

Quando Usar Python no Dynamo#

Dentro do Dynamo, você pode inserir nós "Python Script" para escrever código. Isso é útil quando:

• Você precisa de loops complexos (ciclos aninhados)
• Deve manipular listas de formas não disponíveis com nós padrão
• O gráfico Dynamo está ficando ilegível devido a muitas conexões
• Quer acessar funcionalidades do Revit API não disponíveis via nós

Quando Usar Add-ins C##

Criar um add-in completo do Revit em C# é necessário quando:

• Você quer distribuir uma ferramenta profissional com interface customizada
• Precisa de máxima performance (processamento de modelos grandes)
• Deve integrar com bancos de dados externos, APIs web ou sistemas corporativos
• A ferramenta será usada por múltiplas equipes e requer atualizações controladas

Caminho Recomendado para Iniciantes#

1. Comece com nós Dynamo — aprenda os conceitos básicos (elementos, parâmetros, filtros)
2. Adicione Python quando necessário — loops, lógica condicional complexa
3. Migre para C# quando a ferramenta amadurecer — apenas se se tornar um produto corporativo

A maioria das automações BIM do dia a dia pode ser resolvida com Dynamo + Python.

Seu Primeiro Script Revit API#

Vamos começar com um exemplo simples para Dynamo que demonstra a estrutura básica de uma operação Revit API. Este script Python coleta todas as paredes do seu modelo e as conta.

Como usar este código:

1. Abra o Dynamo no Revit
2. Crie um nó "Python Script" (da biblioteca Core > Scripting)
3. Copie este código no nó
4. Conecte um nó "Watch" à saída para ver o resultado

1# Exemplo Python para Dynamo
2import clr
3clr.AddReference('RevitAPI')
4clr.AddReference('RevitServices')
5
6from Autodesk.Revit.DB import *
7from RevitServices.Persistence import DocumentManager
8
9# Obter o documento Revit atual
10doc = DocumentManager.Instance.CurrentDBDocument
11
12# Criar um FilteredElementCollector para obter todas as paredes
13collector = FilteredElementCollector(doc)
14walls = collector.OfClass(Wall).ToElements()
15
16# Exibir o número de paredes encontradas
17wall_count = len(walls)
18print(f"Encontradas {wall_count} paredes no projeto")
19
20# Dynamo requer que a saída seja atribuída a OUT
21OUT = wall_count

O que este código faz, passo a passo:

1. Import de bibliotecas (clr.AddReference) — diz ao Python quais funcionalidades Revit carregar
2. Obtém o documento (DocumentManager) — conecta o script ao arquivo Revit aberto
3. Cria um collector (FilteredElementCollector) — ferramenta para buscar elementos
4. Filtra por paredes (OfClass(Wall)) — limita a busca apenas às paredes
5. Converte em lista Python (.ToElements()) — transforma os resultados em formato utilizável
6. Conta os elementos (len()) — função padrão do Python para contar itens em uma lista
7. Retorna o resultado (OUT =) — esta é a variável especial que o Dynamo lê

Este script simples demonstra três operações fundamentais:

1. Conectar ao documento Revit
2. Coletar elementos usando FilteredElementCollector
3. Processar os resultados (contando paredes)

Conceitos Essenciais para Iniciantes#

Entender estes cinco conceitos é fundamental para qualquer desenvolvimento com Revit API:

1. Document (Documento)#

O Document é o coração de tudo — representa o arquivo Revit aberto (.rvt). Ele contém todos os elementos, vistas, famílias e configurações do projeto.

Analogia prática: Pense no Document como o container principal. Se o Revit fosse uma biblioteca, o Document seria todo o edifício — contém todos os livros (elementos), as estantes (vistas), e o sistema de catalogação (parâmetros).

No código, você sempre obtém o document assim:

1doc = DocumentManager.Instance.CurrentDBDocument

Por que é importante: Toda operação com Revit API requer uma referência ao document. Sem isso, o código não sabe em qual arquivo trabalhar.

2. Elements (Elementos)#

Tudo no Revit é um elemento — paredes, portas, janelas, vistas, pranchas, cotas, até as configurações de projeto.

Cada elemento tem três componentes fundamentais:

• Um ElementId único — como o número de série de um produto. Nunca dois elementos têm o mesmo Id.
• Parâmetros — as "propriedades" que você vê no painel Propriedades (altura, largura, material, etc.)
• Uma categoria — o "tipo geral" (Paredes, Portas, Janelas, etc.)

Exemplo prático:

1# Obter um elemento pelo seu Id
2elemento = doc.GetElement(ElementId(1234567))
3
4# Ler seu nome
5nome = elemento.Name
6
7# Ler sua categoria
8categoria = elemento.Category.Name  # ex: "Paredes"

3. FilteredElementCollector#

O FilteredElementCollector é seu mecanismo de busca para o modelo Revit. Permite encontrar elementos específicos sem precisar selecioná-los manualmente.

Analogia: Como usar um filtro na Amazon — você pode buscar "todos os notebooks" (categoria), depois filtrar por "preço < R$5000" (parâmetro), depois por "marca Dell" (outro filtro).

1# Encontrar todas as paredes
2todas_as_paredes = FilteredElementCollector(doc).OfClass(Wall).ToElements()
3
4# Encontrar apenas as portas
5todas_as_portas = FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Doors).ToElements()

Você aprenderá muito mais sobre collectors na Parte 2: Coleta de Elementos.

4. Transactions (Transações)#

Regra de ouro: Para modificar qualquer coisa no Revit, é necessária uma transação.

Você pode ler dados sem transações (contar paredes, ler parâmetros), mas modificar sempre requer uma transação (criar elementos, alterar parâmetros, deletar objetos).

Por que transações existem?

• O Revit rastreia todas as modificações para permitir Desfazer/Refazer
• As transações agrupam múltiplas modificações em uma única ação reversível
• Se algo der errado, o Revit pode fazer "rollback" (desfazer) tudo automaticamente

Estrutura correta:

1from Autodesk.Revit.DB import Transaction
2
3# Iniciar uma transação
4t = Transaction(doc, "Nome da Operação")  # O nome aparece em Desfazer
5t.Start()
6
7try:
8    # Todas as modificações vão aqui dentro
9    parametro.Set("novo valor")
10    # ... outras modificações ...
11    
12    t.Commit()  # Confirma e salva as modificações
13except:
14    t.RollBack()  # Desfaz tudo se houver erro

Atenção: No Dynamo, frequentemente as transações são gerenciadas automaticamente. Mas se você usa nós Python para modificações complexas, deve gerenciá-las manualmente.

5. Parameters (Parâmetros)#

Parâmetros são os "dados" anexados aos elementos — tudo que você vê no painel Propriedades.

Existem três tipos:

• Parâmetros built-in — criados pelo Revit (altura, largura, volume, material)
• Parâmetros de projeto — criados para aquele projeto específico
• Parâmetros compartilhados — podem ser reutilizados entre projetos diferentes

Ler um parâmetro:

1# Método 1: Para parâmetros built-in (recomendado)
2altura = elemento.get_Parameter(BuiltInParameter.WALL_USER_HEIGHT_PARAM)
3valor_altura = altura.AsDouble()  # Retorna número
4
5# Método 2: Para parâmetros personalizados (busca por nome)
6comentario = elemento.LookupParameter("Comentários")
7texto_comentario = comentario.AsString()  # Retorna texto

Modificar um parâmetro (requer transação):

1t = Transaction(doc, "Modificar Parâmetro")
2t.Start()
3try:
4    parametro.Set("novo valor")
5    t.Commit()
6except:
7    t.RollBack()

Fluxo de Trabalho Essencial do Revit API#

Toda operação Revit API segue este padrão:

11. CONECTAR   →  Obter referência ao Document
22. COLETAR    →  Encontrar elementos usando FilteredElementCollector
33. PROCESSAR  →  Ler ou modificar propriedades dos elementos
44. CONFIRMAR  →  Salvar alterações dentro de uma Transaction
55. TRATAR     →  Gerenciar erros graciosamente

Guias Especializados#

Agora que você entende o básico, aprofunde-se em áreas específicas do desenvolvimento Revit API:

🔍 Coleta de Elementos#

Domine a arte de encontrar e filtrar elementos nos seus modelos Revit. O Guia Completo de Coleta de Elementos cobre:

• Fundamentos do FilteredElementCollector
• Filtragem por categoria e classe
• Filtragem por valores de parâmetros
• Filtragem geométrica (BoundingBox, interseções)
• Técnicas de otimização de performance
• 35+ exemplos detalhados de filtragem

🖱️ Métodos de Seleção de UI#

Crie aplicações interativas que respondem à entrada do usuário. O Guia de Métodos de Seleção de UI cobre:

• Seleção de elemento único e múltiplo
• Seleção de faces e arestas
• Filtros de seleção customizados
• Padrões avançados de interação com usuário
• Melhores práticas para experiência do usuário

Dicas para Começar#

1. Comece Pequeno: Inicie com tarefas simples de coleta de elementos antes de partir para operações complexas

2. Use o Dynamo: Ótimo para prototipagem e aprendizado visual de conceitos da API

3. Leia a Documentação: Sempre consulte a documentação oficial do Autodesk Revit API

4. Pratique Regularmente: Quanto mais você programa, mais intuitiva a API se torna

5. Junte-se à Comunidade: Conecte-se com outros desenvolvedores através de fóruns e grupos de usuários

Recursos Adicionais#

• Documentação Autodesk Revit API
• Dynamo Primer
• Blog Building Coder
• Fórum Revit API

Em Breve#

Estamos constantemente expandindo este guia com tópicos mais avançados:

📐 Geometria e Modelagem#

• Criação e modificação de elementos geométricos
• Trabalho com curvas, superfícies e sólidos
• Operações geométricas avançadas
• Criação e modificação de famílias

🏗️ Integração com Análise Estrutural#

• Trabalho com elementos estruturais
• Criação de modelos de análise
• Aplicação de cargas e processamento de resultados
• Integração com software de análise estrutural

📊 Tabelas e Documentação#

• Criação automática de tabelas
• Gerenciamento de parâmetros customizados
• Automação de pranchas de desenho
• Geração de relatórios

Próximos Passos#

Pronto para iniciar sua jornada com Revit API? Continue para os próximos artigos desta série:

• Próximo: Coleta de Elementos com FilteredElementCollector
• Também: Métodos de Seleção de UI