Guida Revit API — Primi Passi con l'Automazione BIM

Benvenuti nel Revit API#

Il Revit API (Application Programming Interface) è un potente toolkit che permette agli sviluppatori di creare applicazioni personalizzate, automatizzare attività ed estendere le funzionalità di Revit. Che tu stia lavorando con script Dynamo, creando add-in o sviluppando applicazioni standalone, il Revit API fornisce le basi per l'automazione BIM avanzata.

Questo è il primo articolo di una serie in tre parti sullo sviluppo con Revit API:

1. Primi Passi con l'Automazione BIM (questo articolo)
2. Raccolta Elementi con FilteredElementCollector
3. Metodi di Selezione UI

Prerequisiti#

Prima di immergerti nello sviluppo con Revit API, assicurati di avere:

• Autodesk Revit installato (2020 o successivo consigliato)
• Conoscenze Base di Programmazione (preferibilmente C# o Python)
• Dynamo for Revit (per approcci di programmazione visuale - vedi sezione sotto)
• Visual Studio o Visual Studio Code (solo se desideri creare add-in in C#)

Dynamo e Revit API: Quale Scegliere?#

Prima di scrivere codice, è importante capire i diversi modi per automatizzare Revit e quando usare ciascuno.

Cos'è Dynamo?#

Dynamo è una piattaforma di programmazione visuale integrata in Revit. Invece di scrivere linee di codice, connetti nodi grafici che rappresentano operazioni. Ogni nodo ha input, esegue un'azione specifica e produce output che può essere collegato ad altri nodi.

Pensa a Dynamo come costruire con blocchi LEGO — ogni blocco (nodo) ha una funzione chiara, e li colleghi per creare soluzioni complesse.

Quando Usare Dynamo#

Dynamo è ideale quando:

• Stai iniziando con l'automazione BIM
• La logica è lineare e visuale (pannellatura di facciata, posizionamento famiglie)
• Vuoi prototipare rapidamente un'idea
• Il workflow richiede modifiche frequenti da parte di utenti non programmatori
• Serve documentazione visiva del processo

Quando Usare Python in Dynamo#

All'interno di Dynamo, puoi inserire nodi "Python Script" per scrivere codice. Questo è utile quando:

• Hai bisogno di loop complessi (cicli annidati)
• Devi manipolare liste in modi non disponibili con nodi standard
• Il grafico Dynamo sta diventando illeggibile per troppe connessioni
• Vuoi accedere a funzionalità Revit API non disponibili tramite nodi

Quando Usare Add-in C##

Creare un add-in Revit completo in C# è necessario quando:

• Vuoi distribuire uno strumento professionale con interfaccia personalizzata
• Serve massima performance (elaborazione di grandi modelli)
• Devi integrare con database esterni, API web, o sistemi aziendali
• Il tool sarà usato da team multipli e richiede aggiornamenti controllati

Percorso Raccomandato per Principianti#

1. Inizia con nodi Dynamo — impara i concetti base (elementi, parametri, filtri)
2. Aggiungi Python quando necessario — loop, logica condizionale complessa
3. Passa a C# quando il tool matura — solo se diventa un prodotto aziendale

La maggior parte delle automazioni BIM quotidiane può essere risolta con Dynamo + Python.

Il Tuo Primo Script Revit API#

Iniziamo con un semplice esempio per Dynamo che dimostra la struttura base di un'operazione Revit API. Questo script Python raccoglie tutti i muri nel tuo modello e li conta.

Come usare questo codice:

1. Apri Dynamo in Revit
2. Crea un nodo "Python Script" (dalla libreria Core > Scripting)
3. Copia questo codice nel nodo
4. Connetti un nodo "Watch" all'output per vedere il risultato

1# Esempio Python per Dynamo
2import clr
3clr.AddReference('RevitAPI')
4clr.AddReference('RevitServices')
5
6from Autodesk.Revit.DB import *
7from RevitServices.Persistence import DocumentManager
8
9# Ottieni il documento Revit corrente
10doc = DocumentManager.Instance.CurrentDBDocument
11
12# Crea un FilteredElementCollector per ottenere tutti i muri
13collector = FilteredElementCollector(doc)
14walls = collector.OfClass(Wall).ToElements()
15
16# Output del numero di muri trovati
17wall_count = len(walls)
18print(f"Trovati {wall_count} muri nel progetto")
19
20# Dynamo richiede che l'output sia assegnato a OUT
21OUT = wall_count

Cosa fa questo codice, passo per passo:

1. Import delle librerie (clr.AddReference) — dice a Python quali funzionalità Revit caricare
2. Ottiene il documento (DocumentManager) — collega lo script al file Revit aperto
3. Crea un collector (FilteredElementCollector) — strumento per cercare elementi
4. Filtra per muri (OfClass(Wall)) — limita la ricerca solo ai muri
5. Converte in lista Python (.ToElements()) — trasforma i risultati in formato utilizzabile
6. Conta gli elementi (len()) — funzione Python standard per contare items in una lista
7. Restituisce il risultato (OUT =) — questa è la variabile speciale che Dynamo legge

Questo semplice script dimostra tre operazioni fondamentali:

1. Connessione al documento Revit
2. Raccolta degli elementi usando FilteredElementCollector
3. Elaborazione dei risultati (conteggio muri)

Concetti Chiave per Principianti#

Comprendere questi cinque concetti è essenziale per qualsiasi sviluppo Revit API:

1. Document (Documento)#

Il Document è il cuore di tutto — rappresenta il file Revit aperto (.rvt). Contiene tutti gli elementi, viste, famiglie e impostazioni del progetto.

Analogia pratica: Pensa al Document come al contenitore principale. Se Revit fosse una libreria, il Document sarebbe l'intero edificio — contiene tutti i libri (elementi), gli scaffali (viste), e il sistema di catalogazione (parametri).

Nel codice, ottieni sempre il document così:

1doc = DocumentManager.Instance.CurrentDBDocument

Perché è importante: Ogni operazione Revit API richiede un riferimento al document. Senza questo, il codice non sa su quale file lavorare.

2. Elements (Elementi)#

Tutto in Revit è un elemento — muri, porte, finestre, viste, tavole, quote, perfino le impostazioni di progetto.

Ogni elemento ha tre componenti fondamentali:

• Un ElementId univoco — come il numero di serie di un prodotto. Mai due elementi hanno lo stesso Id.
• Parametri — le "proprietà" che vedi nel pannello Proprietà (altezza, larghezza, materiale, ecc.)
• Una categoria — il "tipo generale" (Muri, Porte, Finestre, ecc.)

Esempio pratico:

1# Ottieni un elemento dal suo Id
2elemento = doc.GetElement(ElementId(1234567))
3
4# Leggi il suo nome
5nome = elemento.Name
6
7# Leggi la sua categoria
8categoria = elemento.Category.Name  # es: "Muri"

3. FilteredElementCollector#

Il FilteredElementCollector è il tuo motore di ricerca per il modello Revit. Permette di trovare elementi specifici senza doverli selezionare manualmente.

Analogia: Come usare un filtro su Amazon — puoi cercare "tutti i laptop" (categoria), poi filtrare per "prezzo < 1000€" (parametro), poi per "marca Dell" (altro filtro).

1# Trova tutti i muri
2tutti_i_muri = FilteredElementCollector(doc).OfClass(Wall).ToElements()
3
4# Trova solo le porte
5tutte_le_porte = FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Doors).ToElements()

Imparerai molto di più sui collector nella Parte 2: Raccolta Elementi.

4. Transactions (Transazioni)#

Regola d'oro: Per modificare qualsiasi cosa in Revit, serve una transazione.

Puoi leggere dati senza transazioni (contare muri, leggere parametri), ma modificare richiede sempre una transazione (creare elementi, cambiare parametri, eliminare oggetti).

Perché esistono le transazioni?

• Revit tiene traccia di tutte le modifiche per permettere Undo/Redo
• Le transazioni raggruppano modifiche multiple in un'unica azione annullabile
• Se qualcosa va storto, Revit può "rollback" (annullare) tutto automaticamente

Struttura corretta:

1from Autodesk.Revit.DB import Transaction
2
3# Inizia una transazione
4t = Transaction(doc, "Nome dell'Operazione")  # Il nome appare in Undo
5t.Start()
6
7try:
8    # Tutte le modifiche vanno qui dentro
9    parametro.Set("nuovo valore")
10    # ... altre modifiche ...
11    
12    t.Commit()  # Conferma e salva le modifiche
13except:
14    t.RollBack()  # Annulla tutto se c'è un errore

Attenzione: In Dynamo, spesso le transazioni sono gestite automaticamente. Ma se usi nodi Python per modifiche complesse, devi gestirle manualmente.

5. Parameters (Parametri)#

I parametri sono i "dati" attaccati agli elementi — tutto ciò che vedi nel pannello Proprietà.

Esistono tre tipi:

• Parametri built-in — creati da Revit (altezza, larghezza, volume, materiale)
• Parametri di progetto — creati per quel progetto specifico
• Parametri condivisi — possono essere riutilizzati tra progetti diversi

Leggere un parametro:

1# Metodo 1: Per parametri built-in (raccomandato)
2altezza = elemento.get_Parameter(BuiltInParameter.WALL_USER_HEIGHT_PARAM)
3valore_altezza = altezza.AsDouble()  # Restituisce numero
4
5# Metodo 2: Per parametri personalizzati (cerca per nome)
6commento = elemento.LookupParameter("Commenti")
7testo_commento = commento.AsString()  # Restituisce testo

Modificare un parametro (richiede transazione):

1t = Transaction(doc, "Modifica Parametro")
2t.Start()
3try:
4    parametro.Set("nuovo valore")
5    t.Commit()
6except:
7    t.RollBack()

Flusso di Lavoro Essenziale del Revit API#

Ogni operazione Revit API segue questo schema:

11. CONNETTI    →  Ottieni riferimento al Document
22. RACCOGLI    →  Trova elementi usando FilteredElementCollector
33. ELABORA     →  Leggi o modifica le proprietà degli elementi
44. CONFERMA    →  Salva le modifiche in una Transaction
55. GESTISCI    →  Gestisci gli errori in modo elegante

Guide Specializzate#

Ora che conosci le basi, approfondisci aree specifiche dello sviluppo Revit API:

🔍 Raccolta Elementi#

Padroneggia l'arte di trovare e filtrare elementi nei tuoi modelli Revit. La Guida Completa alla Raccolta Elementi copre:

• Fondamenti del FilteredElementCollector
• Filtraggio per categoria e classe
• Filtraggio per valori dei parametri
• Filtraggio geometrico (BoundingBox, intersezioni)
• Tecniche di ottimizzazione delle prestazioni
• 35+ esempi dettagliati di filtraggio

🖱️ Metodi di Selezione UI#

Crea applicazioni interattive che rispondono all'input dell'utente. La Guida ai Metodi di Selezione UI copre:

• Selezione di elemento singolo e multiplo
• Selezione di facce e spigoli
• Filtri di selezione personalizzati
• Pattern avanzati di interazione utente
• Best practice per l'esperienza utente

Consigli per Iniziare#

1. Inizia in Piccolo: Comincia con semplici attività di raccolta elementi prima di passare a operazioni complesse

2. Usa Dynamo: Ottimo per prototipazione e apprendimento visuale dei concetti API

3. Leggi la Documentazione: Consulta sempre la documentazione ufficiale Autodesk Revit API

4. Pratica Regolarmente: Più programmi, più l'API diventa intuitiva

5. Unisciti alla Community: Connettiti con altri sviluppatori attraverso forum e gruppi utenti

Risorse Aggiuntive#

• Documentazione Autodesk Revit API
• Dynamo Primer
• Blog Building Coder
• Forum Revit API

Prossimamente#

Stiamo costantemente espandendo questa guida con argomenti più avanzati:

📐 Geometria e Modellazione#

• Creazione e modifica di elementi geometrici
• Lavoro con curve, superfici e solidi
• Operazioni geometriche avanzate
• Creazione e modifica di famiglie

🏗️ Integrazione con Analisi Strutturale#

• Lavoro con elementi strutturali
• Creazione di modelli di analisi
• Applicazione di carichi ed elaborazione risultati
• Integrazione con software di analisi strutturale

📊 Tabelle e Documentazione#

• Creazione automatica di abachi
• Gestione di parametri personalizzati
• Automazione delle tavole di disegno
• Generazione di report

Prossimi Passi#

Pronto per iniziare il tuo viaggio con Revit API? Continua con i prossimi articoli di questa serie:

• Prossimo: Raccolta Elementi con FilteredElementCollector
• Anche: Metodi di Selezione UI