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.
  • Possuir uma compreensão dos tipos primitivos da sintaxe da linguagem Python (tais como: inteiros, boolianas, variáveis texto, listas, tuplas, dicionários, conjuntos, etc…).
  • 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 seções (1, 2, 3, 4, e 7). (Em Inglês)
  • Blender API Quickstart para ajudar a se familiarizar com os fundamentos do funcionamento do Blender em conjunto com a linguagem de programação Python.

Para a melhor depuração e solucionamento de quaisquer das mensagens de erros que o Python possa vir a imprimir durante a escrita de scripts.

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", "category": "Object"}
def register():
    print("Hello World")
def unregister():
    print("Goodbye World")
bl_info
é um dicionário contendo os meta-dados do complemento tais como o título, a versão e o autor a ser mostrados na lista de complementos presente no editor de preferências de usuário.
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 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 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

Executar este script internamente dentro do editor de textos não irá imprimir qualquer saída. Para ver as suas saídas, ele deve ser instalado através das preferências de usuário. As mensagens serão impressas durante a ativação e desativação do mesmo.

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

Clique no botão com a opção Executar Script, e todos os objetos presentes na cena ativa serão movidos por uma (1.0) unidade Blender.

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",
    "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 register():
    bpy.utils.register_class(ObjectMoveX)


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.

../../_images/advanced_scripting_addon-tutorial_operator-search-menu.png

O menu de pesquisa de operadores.

Faça isso pressionando Barra de espaço para fazer com que apareça o diálogo de pesquisa de operadores e digite na caixa «Move X by One» (o bl_label), então Enter.

Os objetos deverão ser movidos como anteriormente.

Mantenha este complemento aberto no Blender para o próximo passo - Instalação.

Instalando o complemento

Uma vez que você tenha seu complemento dentro do editor de textos do Blender, você irá desejar instalá-lo para que possa ser habilitado nas preferências de usuário para ser carregado na inicialização.

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.

Para instalar o texto presente no Blender como um complemento, primeiramente você deverá salvá-lo para o disco. Tome cuidado em relação a obediência das restrições de nomes (nomenclatura adequada) que se aplica aos módulos Python e assegure-se que termina com a extensão .py.

Uma vez que o arquivo esteja gravado, você poderá realizar a sua instalação usando os mesmos procedimentos que deve realizar, de maneira similar aos que são baixados pela internet.

Abra a janela de Arquivo ‣ Preferências de usuário, selecione a aba Complementos, pressione Instalar complemento… e selecione o arquivo.

Agora o complemento será listado e você poderá habilitá-lo (ativá-lo) clicando na caixa de marcação. Caso queira que o mesmo seja habilitado nas próximas vezes que (re)iniciar o Blender, pressione o botão Salvar como padrão.

Nota

A destinação do complemento depende de sua configuração do Blender. Ao instalar um complemento os caminhos de origtem e destino são impressos no console. Você também pode encontrar os caminhos de localização dos complementos através da execução deste comando no console interativo Python:

import addon_utils
print(addon_utils.paths())

Mais informações sobre este assunto estão presentes na seguinte página: Esquema de diretórios.

Seu segundo complemento

Para o nosso segundo complemento, nós iremos focar nas instâncias de objetos – ou seja – criar cópias vinculadas de um objeto de maneira similar aquela que você provavelmente já deva ter visto com o modificador do tipo Matriz.

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
cursor = scene.cursor_location

# Get the active object (assume we have one)
obj = scene.objects.active

# Now make a copy of the object
obj_new = obj.copy()

# The object won't automatically get into a new scene
scene.objects.link(obj_new)

# Now we can place the object
obj_new.location = cursor

Agora, tente copiar este script no Blender e executá-lo no cubo padrão. Certifique-se de ter clicado com o cursor 3D em outra localização antes de executar o script, já que a duplicata irá aparecer na posição do cursor.

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 = scene.objects.active

# 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.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))

Tente executar este script com o objeto ativo e o cursor espaçados com bastante distância entre si para ver o resultado.

Através deste script, você irá notar que nós estamos fazendo alguma matemática usando a localização do objeto e o cursor, isto funciona pois ambos são 3D expostos para instâncias do módulo mathutils. Vector, uma classe conveniente provida pelo módulo mathutils que permite que vetores sejam multiplicados por números e matrizes.

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",
    "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 = scene.objects.active

        total = 10

        for i in range(total):
            obj_new = obj.copy()
            scene.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.

As duas coisas mais óbvias que estão faltando são – consertar o total que está fixo no valor de 10, e também, convenhamos que ter acesso ao operador apenas pela barra de espaço não é lá muito conveniente.

Ambas destas adições são explicadas no próximo passo, com o script final mostrado logo em seguida.

Propriedades de operador(es)

Estas são uma variedade de tipos de propriedades que são usadas para as definições das ferramentas, e os mais comuns tipos de propriedades incluem: int (inteiro), float (flutuante), vector (vetor), color (cor), boolean (booliana) e string (variável texto).

Estas propriedades são manipuladas diferentemente m relação aos atributos de classe Python típicos, pois o Blender necessita exibi-los na interface, guardar as suas definições em mapas de teclas e manter estas definições para reutilização.

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

bpy.props.IntProperty

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.

Mapa de teclas

No Blender, os complementos possuem os seus próprios mapas de tecla de maneira que não interfiram com os mapas de teclas embutidos no Blender.

No exemplo abaixo, um novo modo de objeto bpy.types.KeyMap é adicionado, então um bpy.types.KeyMapItem é adicionado ao mapa de teclas que referencia nosso recém adicionado operador, usando Shift-Ctrl-Espaço como a tecla de atalho para ativá-lo.

# 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, 'SPACE', '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

Mesmo que o atalho Ctrl-Shift-Espaço não seja um atalho padrão do Blender, é difícil certificar-se de que os complementos não irão sobrescrever os mapas de teclas entre si. Portanto, certifique-se de tomar cuidado ao atribuir teclas de atalho de maneira que estas não conflitem com funcionalidades importantes no Blender.

Para a documentação da API sobre as funções listadas acima, veja:

Conectando todas as partes

bl_info = {
    "name": "Cursor Array",
    "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 = scene.objects.active

        for i in range(self.total):
            obj_new = obj.copy()
            scene.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, 'SPACE', '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()
../../_images/advanced_scripting_addon-tutorial_in-menu.png

Dentro do menu.

Execute o script (ou salve-o e o adicione através das preferências de usuário, como anteriormente) e ele então aparecerá no menu.

../../_images/advanced_scripting_addon-tutorial_op-prop.png

Propriedades do operador.

Após selecioná-lo a partir do menu, você poderá escolher quantas instâncias do cubo você deseja criar.

Nota

A execução direta do script múltiplas vezes também irá adicionar o menu a cada execução. Mesmo que este não seja o comportamento mais útil para esta tarefa, não há nada que seja preocupante sobre isso, já que os complementos não registram a si mesmos múltiplas vezes quando habilitados através das preferências de usuário.

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.

Leituras recomendadas para aprofundamento

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.