Tutorial sobre complementos#
Público alvo#
Este tutorial é projetado para ajudar artistas técnicos ou desenvolvedores na aprendizagem para estender o Blender. Espera-se uma compreensão dos fundamentos da linguagem de programação Python de parte das pessoas que estejam seguindo através deste tutorial.
Pré-requisitos#
Antes de seguir através deste tutorial, você deverá…
Estar familiarizado com os fundamentos do funcionamento do Blender.
Saber como executar um script dentro do editor de textos do Blender.
Have an understanding of Python primitive types (integer, Boolean, string, list, tuple, dictionary, and set).
Estar familiarizado com o conceito dos módulos Python.
Possuir uma compreensão básica sobre classes (programação orientada a objetos) em Python.
Uma leitura sugerida antes de começar a acompanhar este tutorial.
Dive Into Python sections (1, 2, 3, 4, and 7).
Blender API Quickstart to help become familiar with Blender/Python basics.
To best troubleshoot any error message Python prints while writing scripts, you run Blender from a terminal. See Use The Terminal.
Dica
You can enable Developer Extras in the preferences to enable features that make developing add-ons easier.
Ligações para a documentação#
Enquanto estiver acompanhando o tutorial, talvez você queira pesquisar dentro de nossa documentação de referência.
Blender API Overview: This document is rather detailed but helpful if you want to know more on a topic.
bpy.context
API reference – Handy to have a list of available items your script may operate on.bpy.types.Operator
– The following add-ons define operators, these docs give details and more examples of operators.
O que é um complemento ?#
Um complemento é simplesmente um módulo escrito em Python contendo alguns requerimentos adicionais de execução, de maneira que o Blender possa exibi-lo em uma lista juntamente com informações úteis.
Para fornecer um exemplo, aqui está o tipo de complemento mais simples possível:
bl_info = {
"name": "My Test Add-on",
"blender": (2, 80, 0),
"category": "Object",
}
def register():
print("Hello World")
def unregister():
print("Goodbye World")
bl_info
is a dictionary containing add-on metadata such as the title, version and author to be displayed in the Preferences add-on list. It also specifies the minimum Blender version required to run the script; older versions won’t display the add-on in the list.
register
é uma função que somente será executada quando o complemento for habilitado, e isto significa que o módulo pode ser carregado sem a ativação do complemento.
unregister
é uma função para descarregar quaisquer das configurações definidas pela função
register
. Isto é chamado quando o complemento é desabilitado.
Note que este complemento não faz nada relacionado ao Blender em si (o módulo blender_api:bpy
não é importado dentro do mesmo, por exemplo).
Este é um exemplo abreviado da construção de um complemento, e serve apenas para ilustrar a ideia de que os requerimentos básicos dos complementos são simples.
Um complemento irá tipicamente registrar operadores, painéis, itens de menu, etc, mas não valerá de nada pois qualquer script pode fazer isto, quando executado a partir do editor de textos ou mesmo a partir do console interativo Blender – não há nada inerentemente diferente sobre um complemento que permite a sua integração com o Blender, pois estas funcionalidades são simplesmente fornecidas pelo módulo blender_api:bpy
, que qualquer script tem acesso.
Portanto um complemento é simplesmente uma maneira de encapsular um módulo Python de uma maneira que o usuário possa facilmente utilizá-lo.
Nota
Running this script within the Text editor won’t print anything, to see the output it must be installed through the Preferences. Messages will be printed when enabling and disabling.
Seu primeiro complemento#
O mais simples complemento demonstrado acima é útil como um exemplo mas não muito mais que isso. Este próximo complemento é simples mas mostra como integrar um script no Blender usando um Operator
, o que é a maneira típica de definir uma ferramenta acessada a partir de menus, botões e atalhos de teclado.
Para o primeiro exemplo, nós iremos criar um script que simplesmente move todos os objetos dentro de uma cena.
Escrevendo o script#
Adicione o seguinte script ao editor de textos dentro do Blender:
import bpy
scene = bpy.context.scene
for obj in scene.objects:
obj.location.x += 1.0
Click the Run Script button, all objects in the active scene are moved by 1.0 unit.
Escrevendo o complemento (Simples)#
Este complemento recebe o corpo estrutural do script acima, e o adiciona para uma função execute()
do operador
bl_info = {
"name": "Move X Axis",
"blender": (2, 80, 0),
"category": "Object",
}
import bpy
class ObjectMoveX(bpy.types.Operator):
"""My Object Moving Script""" # Use this as a tooltip for menu items and buttons.
bl_idname = "object.move_x" # Unique identifier for buttons and menu items to reference.
bl_label = "Move X by One" # Display name in the interface.
bl_options = {'REGISTER', 'UNDO'} # Enable undo for the operator.
def execute(self, context): # execute() is called when running the operator.
# The original script
scene = context.scene
for obj in scene.objects:
obj.location.x += 1.0
return {'FINISHED'} # Lets Blender know the operator finished successfully.
def menu_func(self, context):
self.layout.operator(ObjectMoveX.bl_idname)
def register():
bpy.utils.register_class(ObjectMoveX)
bpy.types.VIEW3D_MT_object.append(menu_func) # Adds the new operator to an existing menu.
def unregister():
bpy.utils.unregister_class(ObjectMoveX)
# This allows you to run the script directly from Blender's Text editor
# to test the add-on without having to install it.
if __name__ == "__main__":
register()
Nota
bl_info
está espalhado sobre múltiplas linhas, e esta é apenas uma convenção de estilo usada para adicionar itens com mais facilidade.
Nota
Ao invés de usar o argumento bpy.context.scene
, nós utilizamos o argumento context.scene
passado para a função execute()
. Na maioria dos casos, estes argumentos terão os mesmos resultados. Contudo, em alguns casos, os operadores serão passados de uma maneira que ajam sobre contextos personalizados, e portanto, os autores de scripts deverão preferir a passagem do argumento context
aos operadores.
Para testar o script, você poderá copiar e colar seu conteúdo no editor de textos do Blender e então executá-lo. Isto irá executar o script diretamente e chamará as funções de registro imediatamente.
Contudo, a execução do script não moverá quaisquer objetos. Para isto, você precisará executar o operador recentemente registrado.
Open the Operator Search menu
and type in «Move X by One» (the bl_label
), then Return.
Os objetos deverão ser movidos como anteriormente.
Mantenha este complemento aberto no Blender para o próximo passo - Instalação.
Instalando o complemento#
Once you have your add-on within in Blender’s Text editor, you will want to be able to install it so it can be enabled in the Preferences to load on startup.
Mesmo que o complemento acima seja um teste, de qualquer maneira teremos de caminhar novamente através dos passos de maneira que você saiba como fazer isso posteriormente.
To install the Blender text as an add-on, you will first have to save it on drive. Take care to obey the naming
restrictions that apply to Python modules and end with a .py
extension.
Once the file is on drive, you can install it as you would for an add-on downloaded online.
Open the
and select the file.Now the add-on will be listed and you can enable it by pressing the checkbox, if you want it to be enabled on restart, press Save as Default. The operator can be run in the same way as described in the previous section.
When the add-on is enabled, Blender executes the code and runs the register()
function.
When the add-on is disabled, Blender runs the unregister()
function.
Nota
The destination of the add-on depends on your Blender configuration. When installing an add-on the source and destination paths are printed in the console. You can also find add-on path locations by running this in the Python Console:
import addon_utils
print(addon_utils.paths())
More is written on this topic here: Directory Layout.
Seu segundo complemento#
For our second add-on, we will focus on object instancing – this is – to make linked copies of an object in a similar way to what you may have seen with the Array modifier.
Escrevendo o script#
Como anteriormente, primeiramente iniciaremos com um script, então o desenvolveremos, e então o converteremos para um complemento.
import bpy
from bpy import context
# Get the current scene
scene = context.scene
# Get the 3D cursor location
cursor = scene.cursor.location
# Get the active object (assume we have one)
obj = context.active_object
# Now make a copy of the object
obj_new = obj.copy()
# The new object has to be added to a collection in the scene
scene.collection.objects.link(obj_new)
# Now we can place the object
obj_new.location = cursor
Now try copying this script into Blender and run it on the default Cube. Make sure you click to move the 3D cursor before running as the duplicate will appear at the cursor’s location.
Após a execução, note que quando você entrar no Modo de edição para alterar o cubo – todas cópias mudam. No Blender, isto é conhecido como Duplicatas vinculadas.
No próximo passo, nós tornaremos este trecho de código em um ciclo repetitivo, para fazer com que uma matriz de objetos entre o objeto ativo e o cursor apareçam:
import bpy
from bpy import context
scene = context.scene
cursor = scene.cursor.location
obj = context.active_object
# Use a fixed value for now, eventually make this user adjustable
total = 10
# Add 'total' objects into the scene
for i in range(total):
obj_new = obj.copy()
scene.collection.objects.link(obj_new)
# Now place the object in between the cursor
# and the active object based on 'i'
factor = i / total
obj_new.location = (obj.location * factor) + (cursor * (1.0 - factor))
Try running this script with the active object and the cursor spaced apart to see the result.
With this script you’ll notice we’re doing some math with the object location and cursor,
this works because both are 3D mathutils.Vector
instances,
a convenient class provided by the mathutils
module which
allows vectors to be multiplied by numbers and matrices.
Caso você esteja interessado nesta área, leia dentro da documentação sobre mathutils.Vector
– lá estão muitas funções utilitárias úteis como a obtenção de ângulos entre vetores, produto vetorial, produto escalar bem como outras funções mais avançadas em :mod:`blender_api:mathutils.geometry`como a interpolação de Splines Bézier e intersecção entre raios e triângulos.
Por enquanto, nós iremos colocar nosso foco em transformar este script em um complemento, mas é bom saber de antemão que este módulo de matemática 3D está disponível e pode ajudar você com funcionalidades mais avançadas posteriormente.
Escrevendo o complemento#
O primeiro passo é converter o script no estado em que se encontra em um complemento:
bl_info = {
"name": "Cursor Array",
"blender": (2, 80, 0),
"category": "Object",
}
import bpy
class ObjectCursorArray(bpy.types.Operator):
"""Object Cursor Array"""
bl_idname = "object.cursor_array"
bl_label = "Cursor Array"
bl_options = {'REGISTER', 'UNDO'}
def execute(self, context):
scene = context.scene
cursor = scene.cursor.location
obj = context.active_object
total = 10
for i in range(total):
obj_new = obj.copy()
scene.collection.objects.link(obj_new)
factor = i / total
obj_new.location = (obj.location * factor) + (cursor * (1.0 - factor))
return {'FINISHED'}
def register():
bpy.utils.register_class(ObjectCursorArray)
def unregister():
bpy.utils.unregister_class(ObjectCursorArray)
if __name__ == "__main__":
register()
Todas as coisas aqui foram abordadas nos passos anteriores, e talvez nesse momento você queira tentar a execução do complemento do jeito que está e considerar o que poderia ser feito para torná-lo mais útil.
The two of the most obvious missing things are – having the total fixed at 10, and having to access the operator with Procurar is not very convenient.
Ambas destas adições são explicadas no próximo passo, com o script final mostrado logo em seguida.
Propriedades de operador(es)#
There are a variety of property types that are used for tool settings, common property types include: int, float, vector, color, Boolean and string.
These properties are handled differently to typical Python class attributes because Blender needs to display them in the interface, store their settings in keymaps and keep settings for reuse.
Mesmo que isso seja manipulado de uma maneira amplamente «Pythonica», esteja consciente que de fato o que você está fazendo é definir as configurações de ferramentas que são carregadas no Blender e acessadas por outras partes do Blender, fora do ambiente Python.
Para se livrar do 10 literal e imutável para o total
, nós iremos utilizar uma propriedade de operador. As propriedades de operadores são definidas através do módulo bpy.props, e isto é adicionado ao corpo da classe:
# moved assignment from execute() to the body of the class...
total: bpy.props.IntProperty(name="Steps", default=2, min=1, max=100)
# and this is accessed on the class
# instance within the execute() function as...
self.total
Estas propriedades obtidas a partir do módulo bpy.props
são manipuladas de maneira especial pelo Blender quando a classe é registrada e são exibidos como botões na interface de usuário. Existem muitos argumentos que você pode passar para as propriedades para a definição de limites, alterar o padrão e mostrar uma dica de ferramenta.
Veja também
Este documento não se aprofunda muito mais nos detalhes sobre a utilização de outros tipos de propriedades. Contudo, a ligação de internet acima inclui exemplos de utilização mais avançada das propriedades.
Keymap#
In Blender, add-ons have their own keymaps so as not to interfere with Blender’s built-in keymaps.
In the example below, a new object mode bpy.types.KeyMap
is added,
then a bpy.types.KeyMapItem
is added to the keymap which references
our newly added operator, using Shift-Ctrl-T as the key shortcut to activate it.
# store keymaps here to access after registration
addon_keymaps = []
def register():
# handle the keymap
wm = bpy.context.window_manager
km = wm.keyconfigs.addon.keymaps.new(name='Object Mode', space_type='EMPTY')
kmi = km.keymap_items.new(ObjectCursorArray.bl_idname, 'T', 'PRESS', ctrl=True, shift=True)
kmi.properties.total = 4
addon_keymaps.append((km, kmi))
def unregister():
# handle the keymap
for km, kmi in addon_keymaps:
km.keymap_items.remove(kmi)
addon_keymaps.clear()
Note como o item de mapa de teclas pode ter uma definição de total
diferente do padrão definido pelo operador, e isto permite que você tenha múltiplas teclas que acessem o mesmo operador, e que possa ser configurado para diferentes definições.
Nota
While Shift-Ctrl-T is not a default Blender key shortcut, it is hard to make sure add-ons will not overwrite each other’s keymaps. Thus at least take care when assigning keys that they do not conflict with important functionality of Blender (see also is key free add-on).
Para a documentação da API sobre as funções listadas acima, veja:
Conectando todas as partes#
bl_info = {
"name": "Cursor Array",
"blender": (2, 80, 0),
"category": "Object",
}
import bpy
class ObjectCursorArray(bpy.types.Operator):
"""Object Cursor Array"""
bl_idname = "object.cursor_array"
bl_label = "Cursor Array"
bl_options = {'REGISTER', 'UNDO'}
total: bpy.props.IntProperty(name="Steps", default=2, min=1, max=100)
def execute(self, context):
scene = context.scene
cursor = scene.cursor.location
obj = context.active_object
for i in range(self.total):
obj_new = obj.copy()
scene.collection.objects.link(obj_new)
factor = i / self.total
obj_new.location = (obj.location * factor) + (cursor * (1.0 - factor))
return {'FINISHED'}
def menu_func(self, context):
self.layout.operator(ObjectCursorArray.bl_idname)
# store keymaps here to access after registration
addon_keymaps = []
def register():
bpy.utils.register_class(ObjectCursorArray)
bpy.types.VIEW3D_MT_object.append(menu_func)
# handle the keymap
wm = bpy.context.window_manager
# Note that in background mode (no GUI available), keyconfigs are not available either,
# so we have to check this to avoid nasty errors in background case.
kc = wm.keyconfigs.addon
if kc:
km = wm.keyconfigs.addon.keymaps.new(name='Object Mode', space_type='EMPTY')
kmi = km.keymap_items.new(ObjectCursorArray.bl_idname, 'T', 'PRESS', ctrl=True, shift=True)
kmi.properties.total = 4
addon_keymaps.append((km, kmi))
def unregister():
# Note: when unregistering, it's usually good practice to do it in reverse order you registered.
# Can avoid strange issues like keymap still referring to operators already unregistered...
# handle the keymap
for km, kmi in addon_keymaps:
km.keymap_items.remove(kmi)
addon_keymaps.clear()
bpy.utils.unregister_class(ObjectCursorArray)
bpy.types.VIEW3D_MT_object.remove(menu_func)
if __name__ == "__main__":
register()
Run the script (or save it and add it through the Preferences like before) and it will appear in the Object menu.
Após selecioná-lo a partir do menu, você poderá escolher quantas instâncias do cubo você deseja criar.
Nota
Directly executing the script multiple times will add the menu each time too. While not useful behavior, there is nothing to worry about since add-ons will not register themselves multiple times when enabled through the Preferences.
Conclusões#
Os complementos podem encapsular muito bem certas funcionalidades para se escrever ferramentas para melhorar o seu fluxo de trabalho ou para a escrita de utilidades para outros usar.
Mesmo que haja limites para o que a linguagem de programação Python pode fazer internamente no Blender, existem certamente muitas coisas que podem ser feitas sem ter de mergulhar nos códigos em C ou C++ do Blender.
O exemplo fornecido neste tutorial é limitado, mas mostra a API do Blender usada para tarefas comuns, que você posteriormente poderá expandir para escrever as suas próprias ferramentas.
Further Reading#
O Blender vem com diversos modelos de scripts comentados acessíveis a partir do cabeçalho do editor de textos. Se você tem áreas específicas as quais você deseja ver exemplos de códigos, este é um bom local para começar.
Aqui apresentamos alguns sites que você provavelmente gostará de verificar logo após completar os passos deste tutorial.
Blender/Python API Overview – For more background details on Blender/Python integration.
How to Think Like a Computer Scientist – Great info for those who are still learning Python.
Blender Development – Blender Development, general information and helpful links.
Blender Developer Forum – Forum where people ask Python development questions.