Ajustar el encuadre de cámara y el rango de animación con Blender Python

¿Qué aprenderás en esta guía?

Gestionar mediante la API Python de Blender los ajustes de cámara y temporización de una escena de visualización arquitectónica ayuda a establecer un flujo de trabajo reproducible. En esta guía veremos cómo encontrar la cámara activa, cambiar la distancia focal, activar la guía de encuadre y definir los fotogramas inicial y final de la animación. En la última sección, aprenderás a establecer un intervalo de previsualización más corto y a revisar los errores más habituales.

Los ejemplos se basan en las propiedades Scene y Camera descritas en la documentación actual de la API de Blender. El objetivo no es automatizar todos los ajustes de render, sino aplicar de forma controlada en la escena decisiones básicas como el encuadre de cámara y el rango de tiempo.

Requisitos

Ejecuta los ejemplos en un entorno que permita usar la API Python de Blender. En el código se da por hecho que el módulo bpy y el contexto de la escena activa están disponibles dentro de Blender. Según la documentación, se puede acceder a la escena mediante bpy.context.scene; la cámara activa de la escena se almacena en la propiedad scene.camera.

Se trata de páginas actualizadas de la API. También se indica que Scene.use_nodes está obsoleta desde Blender 5.0 y que su eliminación está prevista para la versión 6.0. Como esta guía no configura nodos de composición, esta propiedad no es necesaria en los ejemplos de cámara y rango de fotogramas. Las fuentes no especifican ningún requisito de cuenta.

Antes de aplicar el código, es una buena práctica guardar una copia del archivo del proyecto y probar los valores en una escena de prueba pequeña. Esto ayuda a evitar cambios involuntarios en los ajustes existentes, especialmente en proyectos con distintas configuraciones de cámara o rangos de animación.

1. Comprueba la cámara activa

Primero, comprueba si hay una cámara activa que se vaya a utilizar en la escena. Scene.camera indica la cámara activa utilizada para el render. El código siguiente muestra su nombre si hay una cámara; de lo contrario, informa de que la escena no tiene una cámara activa. Esta comprobación permite empezar de forma segura antes de acceder a los datos de cámara en el código posterior.

scene = bpy.context.scene
camera = scene.camera

if camera is None:
    print("Sahnede aktif kamera yok.")
else:
    print("Aktif kamera:", camera.name)

Que haya una cámara en la escena no significa que esté seleccionada como cámara activa. El código accede únicamente a la cámara activa mediante scene.camera. Si la comprobación indica que no hay ninguna cámara, selecciona la que se utilizará en la escena antes de pasar a los ajustes del lente y del encuadre.

2. Ajusta el valor del lente y la guía de encuadre

Los ajustes de la cámara se almacenan en el bloque de datos de cámara, al que se accede mediante camera.data. En una cámara en perspectiva, lens expresa la distancia focal en milímetros. El valor predeterminado documentado es 50,0 mm; en este ejemplo se establece en 35,0 mm. Se trata de un cambio numérico mediante la API; no garantiza que la escena alcance un resultado arquitectónico concreto. Revisa la imagen para elegir un valor adecuado.

scene = bpy.context.scene
camera = scene.camera

if camera is not None:
    camera.data.lens = 35.0

Para usar la guía de tercios en la vista de cámara, puedes activar la propiedad show_composition_thirds del mismo bloque de datos. La guía ayuda a evaluar la ubicación de los elementos dentro del encuadre; no modifica por sí sola la geometría ni la posición de la cámara.

scene = bpy.context.scene
camera = scene.camera

if camera is not None:
    camera.data.show_composition_thirds = True

Si no aparece la guía, comprueba que estás en la vista de cámara y que la cámara activa es la correcta. Esta propiedad forma parte de los ajustes de visualización de las guías de composición de la cámara en la API. La documentación también enumera guías de centro, proporción áurea y otras composiciones; aquí el ejemplo se limita a la guía de tercios para evaluar encuadres arquitectónicos.

3. Define el rango de fotogramas de la animación

Los puntos inicial y final del rango de reproducción y render de una escena se definen con las propiedades frame_start y frame_end. El ejemplo siguiente establece el rango del fotograma 1 al 120 y lleva el fotograma actual de la escena al fotograma inicial. Los valores son solo ejemplos; adáptalos a la duración de tu animación.

scene = bpy.context.scene

scene.frame_start = 1
scene.frame_end = 120
scene.frame_set(scene.frame_start)

Al establecer el fotograma actual, frame_set() también actualiza los objetos y las capas de vista. Por eso, puedes usar este método para actualizar el fotograma de la escena en lugar de limitarte a guardar el número de fotograma en una variable. La documentación de la API señala que el método frame_set() también puede recibir un valor de subfotograma; en esta guía nos limitamos al uso básico de fotogramas enteros.

También es posible definir un rango inicial y final independiente para la previsualización. La propiedad use_preview_range determina si se usa un rango alternativo, mientras que frame_preview_start y frame_preview_end definen sus límites.

scene = bpy.context.scene

scene.use_preview_range = True
scene.frame_preview_start = 20
scene.frame_preview_end = 40

En este ejemplo, el rango de previsualización va de los fotogramas 20 a 40. Según la descripción de la API, el rango alternativo puede utilizarse para la reproducción de animaciones y los renders de vista. Esta opción puede ser útil cuando no quieres modificar el rango principal de la animación. Comprueba en la escena que el ajuste de previsualización funciona como esperas.

Errores habituales

• Pasar por alto que no hay una cámara activa: Si scene.camera está vacío, no podrás acceder al bloque de datos de cámara. Ejecuta primero la comprobación del primer ejemplo.

• Buscar el ajuste en el objeto equivocado: El lente y la guía de composición de la cámara están en la sección data del objeto de cámara. El rango de fotogramas, en cambio, es una propiedad de la escena.

• Confundir el rango de previsualización con el rango principal: frame_preview_start y frame_preview_end son independientes de los valores principales frame_start y frame_end. Comprueba también el ajuste use_preview_range, que activa el rango alternativo.

• Usar el ajuste de composición antiguo: La documentación indica que la propiedad Scene.use_nodes está obsoleta desde Blender 5.0, que configurarla no tiene efecto y que está previsto eliminarla en la versión 6.0. Para activar o desactivar la composición, utiliza la propiedad scene.render.use_compositing.

• Aplicar sin más los valores de ejemplo al proyecto: 35 mm o 120 fotogramas no son la opción adecuada para todas las escenas. Evalúa el encuadre y la duración de la animación según las necesidades del proyecto.

Próximos pasos en el flujo de trabajo de arquitectura y visualización

Este método puede ser útil para equipos de visualización que repiten los mismos ajustes de encuadre y temporización en una escena, así como para estudiantes que están aprendiendo a configurar cámaras. Por ejemplo, estos fragmentos breves de código pueden servir como punto de partida para volver a un rango fijo de la escena o activar de nuevo la guía de composición. Sin embargo, estos ejemplos no aceleran el render ni ofrecen información sobre requisitos de hardware específicos. En proyectos grandes, prueba los cambios primero en la estación de trabajo utilizada y en una copia del proyecto.

Como siguiente paso, aplica los fragmentos de código uno por uno en tu escena y verifica el encuadre de cámara y el rango de fotogramas. Si más adelante quieres convertir estos ajustes en un flujo de trabajo compartible con el equipo, consulta los objetos y propiedades correspondientes de la API de Blender. Si necesitas modificar los ajustes de composición, utiliza la propiedad actual de la API scene.render.use_compositing; no escribas código nuevo basado en la propiedad antigua scene.use_nodes.

Fuentes y licencia

Esta guía se ha adaptado a partir de las propiedades de la documentación de la API de Blender Scene y Camera. Ambas fuentes se ofrecen bajo la licencia CC BY-SA 4.0: bpy.types.Scene y bpy.types.Camera. Los ejemplos de código se han escrito para esta guía a partir de los nombres de API descritos en la documentación.