Add-om TutorialEste tutorial está diseñado para ayudar a los artistas o técnicos desarrolladores aprender a extender Blender. Se espera que una comprensión de los conceptos básicos de Python para los que trabajan a través de este tutorial.
Requisitos previos
Antes de pasar al tutorial deberías ...
- Estar familiarizado con los aspectos básicos del trabajo en Blender.
- Saber cómo ejecutar un script en el editor de texto de Blender.
- Tener una comprensión de Python tipos primitivos (int, boolean, string, lista, tupla, diccionario, y establecer).
- Estar familiarizado con el concepto de módulos de Python.
- Tener un conocimiento básico de las clases (orientación a objetos) en Python.
Sugerido la lectura antes de comenzar este tutorial.
Inmersión en Python secciones (1, 2, 3, 4, 5, 6, 7).
- Your First Python Program
- Native Datatypes
- Comprehensions
- Strings
- Regular Expressions
- Closures & Generators
- Classes & Iterators
Blender API de inicio rápido para ayudar a familiarizarse con los elementos básicos del mezclador / Python.
Para solucionar mejor las impresiones de Python mensaje de error al escribir secuencias de comandos, ejecutar Blender desde un terminal. Ver usar el terminal .
Enlaces de documentación
Mientras que pasa al tutorial, es posible que desee ver en la documentación de referencia.
- blender_api: Blender generales del API . - Este documento es bastante detallado, pero útil si desea saber más acerca de un tema.
- bpy.contextreferencia de la API. - práctico tener una lista de elementos disponibles su script puede operar.
- bpy.types.Operator. - Los siguientes complementos definen los operadores, estos documentos dan detalles y más ejemplos de operadores.
¿Qué es un Add-on?
Un add-on es simplemente un módulo de Python con algunos requisitos adicionales para Blender puede mostrar en una lista con información útil.
Para dar un ejemplo, aquí es el complemento más simple posible.
bl_info = { "name" : "Mi prueba Add-on" , "categoría" : "Objeto" }
def registro ():
print ( "Hola mundo" )
def anular el registro ():
print ( "Adiós Mundo" )
- bl_info
es un diccionario que contiene add-on meta-datos como el título, el autor y la versión que se mostrará en las preferencias de usuario de la lista. - register
es una función que sólo se ejecuta cuando se activa el complemento, esto significa que el módulo puede ser cargado sin activar el complemento. - unregister
es una función que descargar nada por la instalación register, esto se llama cuando el complemento está deshabilitado.
Nótese que este complemento no hacer nada relacionado con Blender (el bpymódulo no ha sido importada por ejemplo).
Este es un ejemplo artificial de un complemento que sirve para ilustrar el punto de que los requisitos de la base de un add-on son simples.
Un add-on normalmente se registran los operadores, paneles, elementos de menú, etc, pero vale la pena señalar que cualquier script puede hacer esto, cuando se ejecuta desde el editor de texto o incluso la consola interactiva - no hay nada intrínsecamente diferente acerca de un add-on que le permite integrarse con Blender, tal funcionalidad se acaba proporcionada por el bpymódulo para cualquier script de acceso.
Así que un add-on es sólo una forma de encapsular un módulo de Python en una forma en que un usuario puede utilizar fácilmente.
Nota:
La ejecución de esta secuencia de comandos en el editor de texto no se imprimirá nada, para ver la salida debe ser instalado a través de las preferencias del usuario. Los mensajes se imprimen cuando la activación y desactivación.Su primer Add-on
El más simple posible complemento anterior es útil como un ejemplo, pero no mucho más. Este próximo add-on es simple pero muestra cómo integrar una secuencia de comandos en Blender usando una Operator que es la forma típica de definir una herramienta que se accede desde los menús, botones y combinaciones de teclas.
Para el primer ejemplo vamos a hacer un script que simplemente se mueve todos los objetos en una escena.
Escribir el guión
Añadir la siguiente secuencia de comandos para el editor de texto en Blender.
importación bpy
escena = bpy . contexto . escena
de obj en escena . objetos :
obj . ubicación . x + = 1,0
Haga clic en el botón Ejecutar script , todos los objetos de la escena activa son movidos por 1,0 unidades de Blender.
Escribir el complemento (simple)
Este add-on toma el cuerpo del script anterior, y lo añade a un operador de execute()la función.
bl_info = {
"name" : "Mover el eje X" ,
"categoría" : "Objeto" ,
}
import bpy
clase ObjectMoveX ( bpy . tipos . Operator ):
"" "Mi objeto en movimiento escritura" "" # Use esto como una ventana de información de elementos de menú y los botones.
bl_idname = "object.move_x" Identificador único # para los botones y elementos de menú para hacer referencia.
bl_label = "Mover X en uno" # nombre a visualizar en la interfaz.
bl_options = { 'REGISTER' , 'Deshacer' } # Habilitar deshacer para el operador.
def ejecutar ( auto , contexto ): # ejecutar () se llama cuando se ejecuta el operador.
# El guión original
escena = contexto . escena
de obj en escena . objetos :
obj . ubicación . x + = 1,0
volver { 'terminado' } # Le permite Blender sabe que el operador ha finalizado correctamente.
def registro ():
bpy . utils . register_class ( ObjectMoveX )
def unregister ():
bpy . utils . unregister_class ( ObjectMoveX )
# Esto le permite ejecutar la secuencia de comandos directamente desde licuadoras editor de texto
# para probar el complemento sin tener que instalarlo.
Si __name__ == "__main__" :
registrar ()
Nota
bl_info se divide en varias líneas, esto es sólo una convención estilo utilizado para añadir más fácilmente los elementos.
Nota
En lugar de utilizar bpy.context.scene, se utiliza el context.sceneargumento pasado a execute(). En la mayoría de los casos éstos serán los mismos. Sin embargo, en algunos casos, los operadores serán pasados un contexto personalizado para autores de scripts deben preferir el contextargumento pasado a los operadores.Para probar el script, puede copiar y pegar en editor de texto licuadora y ejecutarlo. Esto ejecutará el script de forma directa y el registro de llamadas de inmediato.
Sin embargo la ejecución del script no se moverá ningún objeto. Para esto, es necesario para ejecutar el operador recién registrado.
Para ello, pulse Spacebarpara abrir el diálogo de búsqueda del operador y el tipo de «Mover X en uno» (la bl_label), a continuación Enter.
Los objetos deben moverse como antes.
Mantener este complemento abierta en Blender para el siguiente paso - Instalación.
Instalar el add-on
Una vez que usted tiene su complemento en editor de texto dentro de Blender, tendrá que ser capaz de instalarlo para que pueda ser activada en las preferencias del usuario para cargar en el arranque.
A pesar de que el add-on anterior es una prueba, vamos a ir a través de los pasos de todos modos para que sepa cómo hacerlo para más adelante.
Para instalar el texto Blender como un add-on, primero tendrá que guardarlo en el disco, tenga cuidado de obedecer las restricciones de nomenclatura que se aplican a los módulos de Python y terminar con una .pyextensión.
Una vez que el archivo está en el disco, puede instalarlo como si se tratara de un add-on descargado en línea.
Abre el usuario Archivo ‣ Preferencias de usuario , seleccione el complemento de la sección, pulse Instalar complemento ... y seleccione el archivo.
Ahora se incluirá el complemento y se puede activar pulsando la casilla de verificación, si usted quiere que sea activado en el reinicio, pulse Guardar como predeterminado .
Nota
El destino del complemento depende de la configuración del mezclador. Al instalar un complemento de las rutas de origen y de destino se imprimen en la consola. También puede encontrar el complemento ubicaciones de ruta mediante la ejecución de esto en la consola de Python.
importación addon_utils
de impresión ( addon_utils . caminos ())
Más se ha escrito sobre este tema aquí: Directorio de diseño .Su segundo Add-on
Para nuestro segundo complemento, nos centraremos en la creación de instancias de objeto - esto es - para hacer copias de un objeto vinculados de una manera similar a lo que pudo haber visto con el modificador de matriz.
Escribir el guión
Al igual que antes, en primer lugar vamos a empezar con un guión, desarrollarlo, luego convertirlo en un add-on.
import bpy
from bpy import context
# Obtener la escena actual
escena = contexto . escena
# Obtener el cursor 3D
cursor = escena . cursor_location
# Obtener el objeto activo (supongamos que tenemos uno)
obj = escena . objetos . activo
# Ahora haga una copia del objeto
obj_new = obj . copia ()
# El objeto no obtendrá automáticamente en una nueva escena
escena . objetos . enlace ( obj_new )
# Ahora podemos colocar el objeto
obj_new . ubicación = cursor
Ahora intenta copiar este script en la licuadora y ejecutarlo en el cubo por defecto. Asegúrese de hacer clic para mover el cursor 3D antes de ejecutar como el duplicado aparecerá en la posición del cursor.
Después de correr, observe que cuando se entra en el modo de edición para cambiar el Cubo - todos los cambios copias, en Blender esto se conoce como Linked-duplicados .
A continuación, vamos a hacer esto en un bucle, para hacer una matriz de objetos entre el objeto y el cursor activo.
import bpy
from bpy import context
escena = contexto . escena
del cursor = escena . cursor_location obj = escena . objetos . activo
# Utilice un valor fijo por ahora, finalmente, hacer que este ajustable por el usuario
totales = 10
# Añadir objetos 'total' en la escena
de i en rango ( totales ):
obj_new = obj . copia ()
escena . objetos . enlace ( obj_new )
# Ahora colocar el objeto en entre el cursor
# y el objeto activo basado en 'i'
factor de = i / total de
obj_new . ubicación = ( obj . ubicación * factor de ) + ( cursor * ( 1,0 - factor de ))
Trate de ejecutar este script con el objeto activo y el cursor separadas entre sí para ver el resultado.
Con este script se dará cuenta de que estamos haciendo un poco de matemática con la ubicación de objetos y el cursor, esto funciona porque ambos son 3D casos, una clase práctica proporcionados por el módulo y permite a los vectores que se multiplican por números y matrices.mathutils. Vectormathutils
Si está interesado en esta área, leer en mathutils.Vector - hay muchas funciones útiles de servicios públicos tales como conseguir el ángulo entre los vectores, producto vectorial, productos de punto, así como funciones más avanzadas en mathutils.geometry como Bézier spline de interpolación y la intersección de rayos-triángulo.
Por ahora nos centraremos en hacer este guión un add-on, pero es bueno saber que este módulo de matemáticas 3D está disponible y se puede ayudar con una funcionalidad más avanzada más adelante.
Escribir el add-on
El primer paso es convertir el guión como está en un complemento.
bl_info = {
"name" : "Cursor de arrays" ,
"categoría" : "Objeto" ,
}
import bpy
clase ObjectCursorArray ( bpy . tipos . Operador ):
"" "Cursor objeto Array" ""
bl_idname = "" object.cursor_array
bl_label = "cursor matriz"
bl_options = { 'REGISTER' , 'Deshacer' }
def ejecutar ( auto , contexto ):
escena = contexto . escena
del cursor = escena . cursor_location obj = escena . objetos . activo
total = 10
para i en gama ( total de ):
obj_new = obj . copia ()
escena . objetos . enlace ( obj_new )
factor de = i / total de
obj_new . ubicación = ( obj . ubicación * factor de ) + ( cursor * ( 1,0 - factor de ))
volver { 'terminado' }
def registro ():
bpy . utils . register_class ( ObjectCursorArray )
def unregister ():
bpy . utils . unregister_class ( ObjectCursorArray )
Si __name__ == "__main__" :
registrar ()
Todo lo que aquí se ha cubierto en los pasos anteriores, es posible que desee para tratar de ejecutar el add-on, y considera lo que se podría hacer para que sea más útil.
El dos de las cosas que faltan más obvios son - Vista del total fijado en 10, y tener que acceder al operador desde el espacio-bar no es muy conveniente.
Tanto estas adiciones se explican a continuación, con el guión final después.
propiedad del operador
Hay una variedad de tipos de propiedades que se utilizan para los ajustes de herramientas, tipos de propiedad común incluyen: int, float, vector, color, booleano y la cadena.
Estas propiedades se manejan de manera diferente a los atributos de clase típica de Python porque Blender necesita para mostrarlos en la interfaz, almacenar sus ajustes en mapas clave y mantener la configuración para su reutilización.
Si bien esto se maneja de una manera bastante Pythonic, ser conscientes de que está en la definición de ajustes de herramientas informativas que se cargan en Blender y acceder otras partes de Blender, fuera del pitón.
Para deshacerse de lo literal 10 para total, vamos a utilizar una propiedad del operador. Propiedades de operadores se definen a través del módulo bpy.props, esta se añade a la cuerpo de la clase.
# Trasladó encargo de ejecutar () al cuerpo de la clase ...
totales = bpy . apoyos . IntProperty ( nombre = "pasos" , por defecto = 2 , min = 1 , max = 100 )
# Y esto se accede a la clase
ejemplo # dentro de la función de ejecutar () como ...
sí . total
Estas propiedades de bpy.propsse maneja de forma especial por Blender cuando la clase se ha registrado por lo que se muestran como botones de la interfaz de usuario. Hay muchos argumentos se pueden pasar a las propiedades de los límites establecidos, cambiar las preferencias y mostrar una ventana de información.
Ver también
bpy.props.IntPropertyEste documento no entra en detalles sobre el uso de otros tipos de propiedad, sin embargo, el enlace anterior incluye ejemplos del uso de la propiedad más avanzada.
Opción del menú
Los complementos pueden añadir a la interfaz de usuario de paneles, encabezados y menús existentes definidos en Python.
Para este ejemplo vamos a añadir a un menú existente.
Para encontrar el identificador de un menú, puede colocar el ratón sobre el elemento del menú y se muestra el identificador.
El método utilizado para añadir un elemento de menú es añadir una función de extracción en una clase existente.
def menu_func ( auto , contexto ):
sí . diseño . operador ( ObjectCursorArray . bl_idname )
def registro ():
bpy . tipos . VIEW3D_MT_object . append ( menu_func )
Para documentos en los menús que se extienden, consulte: Menú (bpy_struct) .
mapa de teclado
En Blender, los complementos tienen sus propios mapas de teclas a fin de no interferir con los mezcladores construidas en los mapas de teclas.
En el ejemplo siguiente, un nuevo objeto en modo bpy.types.KeyMapse añade, a continuación, una bpy.types.KeyMapItemse añade a la clave-mapa que hace referencia a nuestro operador recién agregado, utilizando Ctrl-Shift-Spacecomo la tecla de acceso directo para activarlo.
# Tienda de mapas de teclas aquí para acceder después de registro
addon_keymaps = []
def registro ():
# Manejar el mapa de teclado
wm = bpy . contexto . window_manager
km = wm . keyconfigs . complemento . mapas de teclas . nueva ( nombre = 'Object Mode' , space_type = 'vacío' )
kmi = km . keymap_items . nueva ( ObjectCursorArray . bl_idname , 'espacio' , 'Pulse' , ctrl = Verdadero , cambiar = Verdadero )
kmi . propiedades . total de = 4
addon_keymaps . append (( km , KMI ))
def unregister ();
# Manejar el mapa de teclas
de km , kmi en addon_keymaps :
km . keymap_items . eliminar ( KMI )
addon_keymaps . claro ()
Nótese cómo el elemento de mapa de teclado puede tener un diferente totalajuste el valor por defecto fijado por el operador, esto le permite tener varias claves que accedan al mismo operador con diferentes configuraciones.
Nota
Si bien Ctrl-Shift-Spaceno es un defecto de Blender tecla de acceso directo, es difícil asegurar que los complementos no se sobreponen a los demás mapas de teclas, por lo menos tener cuidado al asignar teclas que no entren en conflicto con la funcionalidad importante dentro de Blender.