API de Revit: crea herramientas con criterio BIM

El script funciona, pero solo cuando su autor elige los elementos, prepara el modelo y explica qué botón no hay que tocar. Podríamos distribuirlo junto con el autor, aunque el departamento de compras quizá tenga alguna objeción. Crear herramientas con la API de Revit exige convertir esas condiciones en comportamiento explícito: qué entra, qué comprueba, qué puede modificar y qué explica cuando algo falla. El código que hace la operación es importante; la ceremonia que lo rodea también necesita desarrollo.

Ahí es donde empieza a tener sentido la API de Revit. No porque programar sea automáticamente mejor que hacer clic, sino porque permite convertir una regla conocida en una herramienta que pueda repetirla sin cansarse y, sobre todo, sin improvisar. La API nos deja consultar elementos, leer datos, modificar el modelo y añadir funciones que Revit no ofrece tal como las necesita nuestro equipo.

Ahora bien: tener acceso a la API no convierte una mala idea en una buena automatización. Si nadie se pone de acuerdo sobre qué puertas deben llevar un código, el script tampoco lo sabrá. Y si una tarea tarda cinco minutos al mes, quizá no necesites un complemento, un instalador y tres reuniones de soporte. Vamos a seguir la diferencia con ejemplos hipotéticos y decisiones que puedas contrastar en tu equipo.

La API empieza cuando el criterio se puede explicar

Revit guarda un proyecto como un conjunto de elementos relacionados. Un muro no es solo lo que ves en planta: tiene una categoría, un tipo, parámetros de instancia, geometría y vínculos con otros objetos. Las vistas, las láminas y las tablas también son elementos. La API es el contrato que permite a nuestro código trabajar con esa estructura sin tener que simular clics por la interfaz.

Esto cambia la forma de plantear el problema. Cuando una persona selecciona “las puertas del núcleo” puede apoyarse en lo que ve y corregir sobre la marcha. Un programa necesita criterios explícitos: categoría, fase, nivel, familia, parámetro o cualquier combinación que realmente identifique ese conjunto. Si la selección está mal definida, la herramienta hará exactamente lo que le hemos pedido. Incluidos los disparates.

La guía de filtrado de Autodesk muestra cómo construir conjuntos de elementos a partir de filtros. Una vez expresado bien el criterio, podemos volver a aplicarlo. Podemos saber qué elementos se han revisado, qué regla ha fallado y qué valor se encontró. Esa trazabilidad suele valer más que el ahorro de clics, especialmente cuando el modelo debe pasar controles periódicos o el mismo proceso se repite en varios proyectos.

Un buen candidato tiene entradas claras, una regla relativamente estable y un resultado que puedes comprobar. Detectar espacios sin código, crear vistas a partir de una convención o preparar una exportación con opciones acordadas son ejemplos razonables. “Mejorar la calidad del modelo” no lo es todavía. Suena bien en una reunión, pero no dice qué debe hacer el programa.

Yo empezaría escribiendo el proceso como si se lo fueras a pasar a una persona que no conoce el proyecto. Qué documentos intervienen, qué elementos entran, qué excepciones existen, qué cambia y cómo se revisa el resultado. Si dos compañeros interpretan la instrucción de forma distinta, no abras aún el editor de código. Primero hay que resolver esa conversación.

También conviene echar una cuenta sencilla. Frecuencia, tiempo manual, número de personas y coste de equivocarse. Una revisión de diez minutos que hace todo el equipo cada semana puede compensar. Una tarea de cuatro horas que ocurre una vez quizá se resuelva antes con un procedimiento. Y si el error puede modificar mil elementos, el ahorro previsto debe incluir pruebas, vista previa y mantenimiento; no solo el minuto glorioso en el que pulsas “Ejecutar”.

Elige un entorno que encaje con el recorrido de la herramienta

Dynamo encaja muy bien cuando la lógica se entiende como una cadena visual: recoges elementos, filtras, transformas datos y produces un resultado. Puedes construir un prototipo rápido y enseñar el grafo a otro perfil BIM. El problema aparece cuando ese grafo crece hasta ocupar tres pantallas, depende de varios paquetes y contiene cables que cruzan como una instalación sin coordinar. Sigue siendo programación, aunque no haya muchas líneas de texto.

Python puede facilitar la expresión de condiciones, separar funciones y manejar estructuras de datos sin montar desde el primer día un complemento completo. Es una buena opción para scripts de equipo, controles y prototipos con cierta lógica. Pero “Python para Revit” no es un entorno único. El motor, las bibliotecas disponibles y la forma de ejecutar el código dependen de la herramienta que utilices. Antes de copiar un ejemplo, comprueba dónde se ejecuta y para qué versión fue escrito.

C# es una opción habitual para construir complementos cuando interesa una integración cuidada, distribución controlada y mantenimiento entre versiones. Esos requisitos no son exclusivos del lenguaje: también hay que resolverlos al distribuir herramientas en otros entornos. La guía de registro de complementos de Autodesk explica el papel del manifiesto que registra comandos o aplicaciones en Revit. Empaquetar añade trabajo y tiene sentido cuando responde al uso previsto. Un pequeño grafo bien documentado puede ser más profesional que un complemento enorme que nadie mantiene.

Si dudas, empieza con la opción más pequeña que permita comprobar la idea. No necesitas diseñar la herramienta definitiva para descubrir que el parámetro que ibas a automatizar se llama de tres maneras distintas.

De la lectura a una propuesta que el equipo pueda revisar

La primera versión de una herramienta debería observar. Imagina que quieres normalizar el código de clasificación de las puertas. Empieza recuperando las puertas afectadas, leyendo el valor y generando un informe. Esa fase te obliga a descubrir si el dato vive en el tipo o en la instancia, si hay familias que lo guardan en otro sitio y cuántos valores inesperados existen.

La salida debe ayudar a tomar una decisión. Incluye el elemento, la regla aplicada, el valor encontrado y el motivo por el que aparece. “37 errores” es un dato espectacularmente poco útil. La persona que corrige necesita volver al objeto y entender si falta información, si el formato es incorrecto o si la herramienta no ha podido evaluar el caso.

Separa precisamente esos estados. Un elemento que incumple una regla no es lo mismo que uno que el programa no ha podido leer. Si ambos terminan en la misma columna —o peor, si el segundo se considera correcto— el control transmite una seguridad que no tiene. En BIM ya tenemos suficientes tablas con celdas verdes como para añadir otra que no sabemos interpretar.

La petición inicial podría ser “rellena el código de todas las puertas”. Antes de escribir el bucle, necesitamos varias respuestas. ¿Todas significa también las existentes y demolidas? ¿El código depende del tipo o de la instancia? ¿Qué hacemos con los valores ya informados? ¿Hay puertas de armarios o paneles que deben quedar fuera? El código de la operación es sencillo; el criterio no.

Un flujo responsable puede dividirse en dos fases. La primera analiza y clasifica cada puerta como actualizable, omitida o dudosa. La segunda muestra el resumen y modifica solo los casos confirmados. Al terminar, genera un informe con el identificador del elemento, el valor anterior, el nuevo y la regla utilizada. Después de comprobar los valores afectados, esa salida permite revisar lo ocurrido sin reconstruir mentalmente la intención del script. Propuesta, intento de escritura y resultado confirmado deben distinguirse: una fila preparada no acredita una modificación aplicada.

Para probarlo, crea casos deliberadamente incómodos: una puerta sin valor, otra con un código válido, un parámetro bloqueado, un elemento dentro de un grupo y una familia que usa una convención diferente. Esos ejemplos enseñan más que ejecutar directamente sobre el modelo grande y celebrar que no haya aparecido un mensaje de error. Que Revit siga abierto es un requisito bastante modesto para una herramienta de calidad.

Modificar exige comprobar qué se confirma y qué se revierte

Revit controla los cambios mediante transacciones documentadas por Autodesk. Dicho de forma práctica: tu herramienta agrupa una serie de modificaciones y Revit necesita saber si debe confirmarlas o revertirlas. La gestión debe respetar el contexto de la API y del entorno que aloja el código; no puede iniciarse una escritura arbitraria sobre un documento vinculado o en un estado de solo lectura. Es una protección útil, pero no sustituye una buena selección. Si eliges el conjunto equivocado y la operación es válida, puedes aplicar perfectamente el cambio incorrecto.

Por eso prepararía una vista previa antes de escribir nada. Cuántos elementos van a cambiar, cuáles se omiten y algunos ejemplos de valor actual y valor propuesto. Si ya existe información, la herramienta no debería sobrescribirla salvo que esa decisión sea explícita. Antes de comenzar la aplicación, el usuario debe poder rechazar la propuesta sin introducir cambios. Si necesitas cancelación durante una operación larga, hay que definirla y verificar cómo se recupera el estado; no viene garantizada por añadir un botón con ese nombre.

Tampoco confiaría todo al botón Deshacer. Durante el desarrollo, trabaja con copias. En una herramienta compartida, registra qué versión se ejecutó, sobre qué documento y qué resultado produjo. Si algo falla en mitad del proceso, el mensaje debe explicar si no se aplicó ningún cambio o si hay que revisar una parte. Ocultar la excepción para que la ventana quede bonita es una forma bastante cara de fabricar misterio.

Una herramienta compartida necesita una vida después del autor

Un script personal puede depender de que tú sepas qué vista abrir, qué archivo escoger y qué aviso ignorar. En cuanto lo usa otra persona, todo ese conocimiento invisible se convierte en fallos. La herramienta debe validar sus entradas, explicar qué necesita y negarse a continuar si no puede garantizar el alcance. Ser estricta a tiempo resulta más amable que corregir el modelo después.

Conviene separar tres piezas: la lógica de negocio, el acceso a Revit y la interfaz. La regla “este código debe seguir este patrón” puede comprobarse sin abrir un proyecto. La API se ocupa de recuperar y modificar elementos. La ventana recoge opciones y muestra resultados. Si todo está mezclado en un único bloque, cualquier cambio obliga a probarlo todo a mano.

Usa control de versiones para el código, pero guarda también las configuraciones y los modelos mínimos de prueba. Documenta las versiones de Revit y los entornos que realmente has comprobado. Los ejemplos de internet envejecen y muchos materiales mezclan información técnica con promoción de cursos o herramientas. Cuando una decisión dependa de una clase, un evento o una compatibilidad concreta, contrástala con la documentación oficial de la versión que vas a soportar.

Copiar un fragmento sin entender su contexto es un clásico. Puede asumir que hay un documento activo, utilizar referencias de otra versión o depender de un entorno distinto. Reduce el ejemplo hasta entender las entradas y añade una comprobación cada vez. Si pegas cincuenta líneas y funciona, todavía no sabes qué parte necesitabas. Si deja de funcionar dentro de seis meses, tampoco.

Otro problema es automatizar la consecuencia en lugar de la causa. Si cada semana corriges el mismo parámetro porque la plantilla lo crea mal, quizá la solución no sea un script más rápido. Puede ser cambiar la plantilla, la familia o la regla de trabajo. La API es muy buena repitiendo decisiones; también repite con una eficacia admirable nuestras malas decisiones.

Y queda el mantenimiento. Cambian versiones, parámetros, nombres de familias y personas. Antes de distribuir la herramienta, decide quién la mantiene, cómo se reporta un error y qué ocurre si deja de ser compatible. Si la respuesta es “ya llamarán a quien la hizo”, no tienes una herramienta de equipo; tienes una dependencia con icono.

También hay decisiones que conviene dejar fuera de Revit

No usaría la API para una tarea excepcional que Revit ya resuelve de forma segura, ni para un proceso que cambia cada semana. Tampoco si nadie puede verificar el resultado o asumir el soporte. En esos casos, una tabla de control, un procedimiento o un prototipo de Dynamo pueden aportar más valor y menos deuda.

También hay problemas que viven fuera de Revit. Procesar IFC, sincronizar archivos en la nube o conectar un sistema empresarial puede requerir otros componentes y otras APIs. Meter toda la arquitectura dentro de Revit porque es la herramienta que tenemos abierta suele bloquear al usuario y complicar el despliegue.

La API merece la pena cuando puedes describir un problema estable, medirlo, probarlo y asignar a alguien que cuide la solución. Entonces dejas de programar una sucesión de clics y empiezas a empaquetar criterio BIM. Para mí, esa es la prueba de una buena automatización: hace una tarea concreta, cuenta lo que ha ocurrido y permite que otro profesional confíe en el resultado sin tener que llamar al autor cada martes.

El primer salto no consiste en añadir una ventana bonita, sino en que otra persona pueda entender el alcance, revisar la propuesta y reconocer un fallo. Si todavía necesitas estar presente para interpretar cada ejecución, conserva ese dato al estimar lo que falta. Que funcione en tu portátil es una buena noticia; presentarlo como herramienta compartida exige bastante más que encontrarle un icono.