Beknopt pyRevit-handboek

pyRevit is een gratis uitbreiding op Revit waarmee scripts als gewone ribbon-knoppen beschikbaar komen. Elke knop in de toolbar is een klein Python-script dat via de Revit API met het geopende model praat: elementen verzamelen, parameters lezen of schrijven, views en sheets aanmaken.

De BDJ Toolbar bundelt de scripts die het repeterende tekenkamerwerk overnemen — taggen, opschonen, views en sheets opzetten. Deze handleiding legt uit hoe de toolbar in elkaar zit en hoe je er zelf, veilig, een knop aan toevoegt.

2.1 pyRevit installeren

1. Download de nieuwste installer van github.com/pyrevitlabs/pyRevit/releases en installeer met de standaardinstellingen.
2. Start Revit opnieuw. Er verschijnt een tabblad pyRevit in de ribbon.

2.2 De toolbar-extensie koppelen

1. Zorg dat je de map van de toolbar-extensie hebt (de map die eindigt op .extension), lokaal of op de netwerkschijf.
2. Ga naar pyRevit → Settings → Custom Extension Directories, voeg de map toe die de .extension-map bevat en klik Save Settings + Reload.
3. Het toolbar-tabblad verschijnt in de ribbon. Zie je het niet: controleer of je de bovenliggende map hebt gekozen, niet de .extension-map zelf.

pyRevit bouwt de ribbon rechtstreeks uit de mappenstructuur op schijf. De naam van de map bepaalt de tekst in Revit; de extensie van de mapnaam bepaalt het type. Zo ziet de opbouw eruit:

3.1 De bundeltypes die wij gebruiken

3.2 Naamgeving

• Panelen krijgen een nummerprefix (01_, 02_ …) — pyRevit sorteert alfabetisch, dus zo bepaal je de volgorde in de ribbon.
• Knopmappen krijgen de Nederlandse knoptekst als naam; een \n in __title__ breekt de tekst op de knop af over twee regels.
• Bestandsnamen en code: Engels. Teksten die de gebruiker ziet: Nederlands.

Elk script in de toolbar volgt hetzelfde stramien, van boven naar beneden: header → imports → variabelen → config → main → rapportage. Wie één script kan lezen, kan ze daardoor allemaal lezen. Dit is het volledige, generieke sjabloon:

# -*- coding: utf-8 -*-
__title__   = "Knopnaam"
__author__  = "Bram de Jong"
__version__ = "1.0"
__doc__     = """Version: 1.0
Date:    14 juli 2026
Author:  Bram de Jong (BDJ)
__________________________________________________________
Description:
[NL] Korte omschrijving van wat het script doet.
__________________________________________________________
How-to:
-> Stap 1
-> Stap 2
__________________________________________________________
"""

# IMPORTS
# ==================================================
import clr
clr.AddReference('RevitAPI')
clr.AddReference('RevitAPIUI')

from Autodesk.Revit.DB import *
from pyrevit import revit, forms, script

# VARIABLES
# ==================================================
doc    = revit.doc
uidoc  = revit.uidoc
output = script.get_output()

# CONFIG  (benoemde constanten - nooit losse getallen in de logica)
# ==================================================
SOME_LIMIT_MM = 1200

# MAIN
# ==================================================
elements = FilteredElementCollector(doc)\
           .OfCategory(BuiltInCategory.OST_DuctCurves)\
           .WhereElementIsNotElementType().ToElements()

if not elements:
    forms.alert("Niets gevonden.", exitscript=True)

changed, errors = 0, []

# context manager -> automatische rollback bij een fout
with revit.Transaction("Omschrijving van de actie"):
    for el in elements:
        try:
            # ... hier de bewerking per element ...
            changed += 1
        except Exception as e:
            errors.append((el.Id, str(e)))

# REPORT
# ==================================================
output.print_md("## Resultaat")
output.print_md("- Aangepast: **{}**".format(changed))
output.print_md("- Fouten: {}".format(len(errors)))
for eid, msg in errors:
    output.print_md("- {} -> {}".format(output.linkify(eid), msg))

4.1 Waarom elk blok er staat

Het doel achter alle conventies is één ding: een script mag Revit nooit laten vastlopen bij een collega. Deze vijf regels borgen dat:

1. Wijzigen alléén via de context manager — with revit.Transaction("Nederlandse omschrijving"):. Gaat er iets mis, dan rolt Revit automatisch terug in plaats van in een open transactie te blijven hangen.
2. Per element try/except Exception as e: in elke loop met een risicovolle actie. Eén kapot element mag nooit de hele batch afbreken; verzamel fouten en rapporteer ze.
3. Cancel-check na elke keuzelijst. Klikt iemand op Annuleren, dan geeft forms.SelectFromList.show(...) None terug — controleer daarop en stop netjes met script.exit().
4. Rapportage via output.print_md, niet via een pop-up per actie. Eén overzicht aan het einde, met output.linkify(element_id) zodat je naar elementen kunt doorklikken.
5. Benoemde constanten in het CONFIG-blok — geen magische getallen of familienamen verstopt in de logica.

Drie opdrachten, oplopend in moeilijkheid. Werk in een eigen oefen-extensie (hoofdstuk 03) en test op een kopie van een project — nooit op het echte model.

from pyrevit import forms
forms.alert("Hallo tekenkamer! Dit is mijn eerste knop.")

from pyrevit import revit, forms

doc = revit.doc
forms.alert("Je werkt nu in: {}".format(doc.Title))

from Autodesk.Revit.DB import FilteredElementCollector, BuiltInCategory
from pyrevit import revit, script

doc    = revit.doc
output = script.get_output()

ducts = FilteredElementCollector(doc, doc.ActiveView.Id)\
        .OfCategory(BuiltInCategory.OST_DuctCurves)\
        .WhereElementIsNotElementType().ToElements()

output.print_md("## Telling actieve view")
output.print_md("- Ducts gevonden: **{}**".format(len(ducts)))

7.1 De knop verschijnt niet

• Mapnaam eindigt exact op .pushbutton (of ander geldig type) en bevat een script.py.
• De bovenliggende structuur klopt: .extension → .tab → .panel → .pushbutton.
• Je hebt pyRevit → Reload gedaan na de wijziging.

7.2 Rode foutmelding (traceback)

Lees een traceback altijd van onder naar boven: de onderste regel zegt wat er misging, de regels erboven waar. De drie IronPython 2.7-klassiekers:

7.3 "Er gebeurt niets"

Controleer het output-paneel (verschijnt achter het Revit-venster) — de meeste knoppen rapporteren daar in plaats van met een pop-up. Vindt een script niets om te doen, dan meldt het dat daar ook.