Yamyam: 1版をインポートしました

2018-06-28T19:44:31Z

1版をインポートしました

wiki>Genio84: /* Introdução à Blender/Python API */

2011-06-12T08:44:56Z

‎Introdução à Blender/Python API

新規ページ

= Introdução à Blender/Python API =

Esta API está em desenvolvimento mas está estável o suficiente para começar a ser usada com apenas pequenas mudanças a serem feitas até à primeira versão estável do Blender 2.5.

A Blender/Python API pode fazer o seguinte:
* Editar qualquer data de User Interface(Scenes, Meshes, Particles etc.)
* Modificar as preferências do utilizador, atalhos do teclado e temas
* Correr ferramentas com as próprias definições
* Criar elementos do User Interface como menus, cabeçalhos e painéis
* Criar novas ferramentas
* Criar ferramentas interactivas
* Criar novas Render Engines que se integram com o Blender
* Definir novas definições na Blender data existente
* Desenhar na 3D view usando comandos OpenGL do Python

A Blender/Python API '''não consegue''' (por enquanto)...
* Criar novos space types
* Atribuir Custom Properties a todos os tipos
* Definir Callbacks quando as Python-defined properties estão ajustadas
== Antes de começar ==
Este documento não pretende cobrir totalmente cada tópico. O seu propósito é dar-lhe a conhecer a Blender 2.5 Python API.

Uma rápida lista the coisas a saber antes de começar:
* O Blender usa o Python 3.1; algumas 3rd party extensions não estão disponíveis por enquanto.
* A consola do Blender 2.5 foi melhorada; testar one-liners na consola é uma boa maneira de aprender.
* Para tópicos específicos, veja {{Link/API}}
* Button tooltips mostram atributos Python e nomes de operadores.
* Right clicking em butões e em menu items ligam directamente à documentação da API.
* Para mais exemplos, o text menu tem uma templates section onde alguns exemplos de operadores podem ser encontrados.
* Para examinar outros scripts distribuídos com o Blender, veja '''.blender/scripts/ui''' para o User Interface e '''.blender/scripts/op''' para operadores.

== Conceptos chave ==

=== Data Access ===

==== Accessing datablocks ====

Python accesses Blender's data in the same way as the animation system and user interface, which means any setting that is changed via a button can also be changed from Python.

Accessing data from the currently loaded blend file is done with the module '''bpy.data'''. This gives access to library data. For example:

<source lang="python">
>>> bpy.data.objects
<bpy_collection[6], BlendDataObjects>

>> bpy.data.scenes
<bpy_collection[1], BlendDataScenes>

>>> bpy.data.materials
<bpy_collection[1], BlendDataMaterials>
</source>

==== About Collections ====

You'll notice that an index as well as a string can be used to access members of the collection.

Unlike Python's dictionaries, both methods are acceptable; however, the index of a member may change while running Blender.

<source lang="python">
>>> list(bpy.data.objects)
[bpy.data.objects["Cube"], bpy.data.objects["Plane"]]

>>> bpy.data.objects['Cube']
bpy.data.objects["Cube"]

>>> bpy.data.objects[0]
bpy.data.objects["Cube"]

</source>

==== Accessing attributes ====

Once you have a datablock such as a material, object, groups etc., its attributes can be accessed just like changing a setting in the interface; in fact, the button tooltip also displays the Python attribute which can help in finding what settings to change in a script.

<source lang="python">
>>> bpy.data.objects[0].name
"Cube"

>>> bpy.data.scenes["Scene"]
<bpy_struct Scene("Scene")>

>>> bpy.data.materials.new("MyMaterial")
<bpy_struct Material("MyMaterial")>
</source>

For testing what data to access it's useful to use the "Console", which is its own space type in Blender 2.5.
This supports auto-complete, giving you a fast way to dig into different data in your file.

Example: data path that can be quickly found via the console:
<source lang="python">
# scene.render_data - > scene.render (since rev 27104)
#>>> bpy.data.scenes[0].render_data.resolution_percentage

>>> bpy.data.scenes[0].render.resolution_percentage
100
>>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x
1.0
</source>

==== Custom Properties ====
Python can access properties on any datablock that has an ID (data that can be linked in and accessed from bpy.data.*).

When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist.

This data is saved with the blend file and copied with objects.

Example:
<source lang="python">
bpy.context.object["MyOwnProperty"] = 42

if "SomeProp" in bpy.context.object:
print("Property found")

# Use the get function like a Python dictionary which can have a fallback value.
value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")

# dictionaries can be assigned as long as they only use basic types.
group = bpy.data.groups.new("MyTestGroup")
group["GameSettings"] = {"foo": 10, "bar": "spam", "baz": {}}

del group["GameSettings"]
</source>

Note that these properties can only be assigned basic Python types.
* int, float, string
* array of ints/floats
* dictionary (only string keys types on this list)

These properties are valid outside of Python. They can be animated by curves or used in driver paths.

=== Context ===
While it's useful to be able to access data directly by name or as a list, it's more common to operate on the user's selection. The context is always available from '''bpy.context''' and can be used to get the active object, scene, tool settings along with many other attributes.

Common-use cases...
<source lang="python">
>>> bpy.context.object
>>> bpy.context.selected_objects
>>> bpy.context.visible_bones
</source>

Note that the context is read-only. These values cannot be modified directly, though they may be changed by running API functions or by using the data API. So '''bpy.context.object = obj''' will raise an error. But '''bpy.context.scene.objects.active = obj''' will work as expected.

The context attributes change depending on where it is accessed. The 3D view has different context members to the Console, so take care when accessing context attributes that the user state is known.

See [http://www.blender.org/documentation/blender_python_api_2_57_release/bpy.context.html bpy.context] API reference

=== Operators (Tools) ===
Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. From the user perspective they are a tool but Python can run these with its own settings through the '''bpy.ops''' module.

Examples...
<source lang="python">
>>> bpy.ops.mesh.flip_normals()
{'FINISHED'}
>>> bpy.ops.mesh.hide(unselected=False)
{'FINISHED'}
>>> bpy.ops.object.scale_apply()
{'FINISHED'}
</source>

{{Note|Operator Cheat Sheet|"Help -> Operator Cheat Sheet" gives a list of all operators and their default values in Python syntax, along with the generated docs. This is a good way to get an overview of Blender's operators.}}

==== Operator Poll() ====
Some operators have a "poll" function which may check that the mouse is a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc).

When an operator's poll function fails within python, an exception is raised.

For example, calling bpy.ops.view3d.render_border() from the console raises the following error:
<source lang="python">
RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect
</source>

In this case the context must be the 3d view with an active camera.

== Integration ==
Python scripts can integrate with Blender in the following ways:

* By defining a rendering engine
* By defining operators
* By defining menus, headers and panels
* By inserting new buttons into existing menus, headers and panels

In Python, this is done by defining a class, which is a subclass of an existing type.

=== Example Operator ===
<source lang="python">
import bpy

class OpHelloWorld(bpy.types.Operator):
bl_idname = "screen.hello_world"
bl_label = "Hello World"

def execute(self, context):
self.report({'WARNING'}, "Hello World")
return {'FINISHED'}

# registering and menu integration
def register():
bpy.utils.register_class(OpHelloWorld)

# unregistering and removing menus
def unregister():
bpy.utils.unregister_class(OpHelloWorld)

if __name__ == "__main__":
register()
</source>

Once this script runs, ''HelloWorld'' is registered with Blender and can be called from the operator search popup or added to the toolbar.

To run the script:

# Highlight the above code then press {{shortcut|ctrl|c}} to copy it
# Start Blender
# Press {{shortcut|ctrl|right}} twice to change to the Scripting layout
# Press {{shortcut|ctrl|v}} to paste the code into the text panel (the upper left frame)
# Click '''Run Script''' or press {{shortcut|alt|p}} to run the script
# Click in the 3dview, press spacebar for the search menu, and type "hello"
# click on the "Hello World" item found in search

Notice the class members with the bl_ prefix, these are documented in the Python API.
http://www.blender.org/documentation/blender_python_api_2_57_release/bpy.types.Operator.html

=== Example Panel ===
Panels register themselves as a class, like an operator. Notice the extra variables used to set the context they display in.

<source lang="python">
import bpy

class OBJECT_PT_hello(bpy.types.Panel):
bl_label = "Hello World Panel"
bl_space_type = "PROPERTIES"
bl_region_type = "WINDOW"
bl_context = "object"

def draw(self, context):
layout = self.layout

obj = context.object

row = layout.row()
row.label(text="Hello world!", icon='WORLD_DATA')

row = layout.row()
row.label(text="Active object is: " + obj.name)
row = layout.row()
row.prop(obj, "name")

# registering and menu integration
def register():
bpy.utils.register_class(OBJECT_PT_hello)

# unregistering and removing menus
def unregister():
bpy.utils.unregister_class(OBJECT_PT_hello)

if __name__ == "__main__":
register()
</source>

To run the script:

# Highlight the above code then press {{shortcut|ctrl|c}} to copy it
# Start Blender
# Press {{shortcut|ctrl|right}} twice to change to the Scripting layout
# Press {{shortcut|ctrl|v}} to paste the code into the text panel (the upper left frame)
# Click '''Run Script''' or press {{shortcut|alt|p}} to run the script

To view the results:

# {{shortcut|RMB}}-click on the default cube to select it
# {{shortcut|LMB}}-click the Object properties icon in the buttons panel (far right; appears as a tiny cube)
# Scroll down to see a panel named '''Hello World Panel'''
# Changing the object name also updates '''Hello World Panel''''s '''Name:''' field

Note the row distribution and the label and properties that are available through the code.

See also [http://www.blender.org/documentation/250PythonDoc/bpy.types.Panel.html#bpy.types.Panel the Panel class documentation]

== Types ==
Blender defines a number of Python types but also uses Python native types.

Blender's Python API can be split up into 3 categories.

==== Native Types ====

In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal python types.

* blender float/int/boolean -> float/int/boolean
* blender enumerator -> string
<source lang="python">
>>> C.object.rotation_mode = 'AXIS_ANGLE'
</source>
* blender enumerator (multiple) -> set of strings
<source lang="python">
# within an operator
self.report({'WARNING', 'INFO'}, "SomeMessage")
</source>

==== Internal Types ====
''used for Blender datablocks and collections.'' 
Reference: http://www.blender.org/documentation/250PythonDoc/bpy.types.bpy_struct.html

For data that contains its own attributes groups/meshes/bones.

There are 2 main types that wrap Blenders data, one for datablocks (known internally as bpy_struct), another for properties.
<source lang="python">
>>> C.object
bpy.data.objects["Cube"]

>>> C.scene.objects
bpy.data.scenes["Scene"].objects
</source>

Note that these types keep a reference to Blender's data so modifying them should be immediately visible.

==== Mathutils Types ====
''used for vectors, quaternion, eulers, matrix and color types.'' 
Reference: http://www.blender.org/documentation/250PythonDoc/mathutils.html

Some attributes such as object.location, bone.rotation_euler and scene.cursor_location can be accessed as special math types which can be added together and manipulated in useful ways.

Example of a matrix, vector multiplication:
<source lang="python">
bpy.context.object.data.verts[0].co * bpy.context.object.matrix_world
</source>

Note: Mathutils types keep a reference to Blender's internal data so changes can be applied back.

Examples
<source lang="python">
# modifies Z in place.
bpy.context.object.location.z += 2.0

# location variable holds a reference to the object too.
location = bpy.context.object.location
location *= 2.0

# Copying the value drops the reference.
location = bpy.context.object.location.copy()
</source>

== Animation ==
There are 2 ways to add keyframes through Python. The first is through key properties directly, which is similar to inserting a keyframe as a user.
You can also manually create the curves and keyframe data, then set the path to the property. Here are examples of both methods.

These 2 examples insert a keyframe on the active object's Z axis.

Simple example:
<source lang="python">
obj = bpy.context.object
obj.location[2] = 0.0
obj.keyframe_insert(data_path="location", frame=10.0, index=2)
obj.location[2] = 1.0
obj.keyframe_insert(data_path="location", frame=20.0, index=2)
</source>

Using Low-Level Functions:
<source lang="python">
obj = bpy.context.object
obj.animation_data_create()
obj.animation_data.action = bpy.data.actions.new(name="MyAction")
fcu_z = obj.animation_data.action.fcurves.new(data_path="location", index=2)
fcu_z.keyframe_points.add(2)
fcu_z.keyframe_points[0].co = 10.0, 0.0
fcu_z.keyframe_points[1].co = 20.0, 1.0
</source>

== Style Conventions ==
For Blender 2.5 we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python from other projects.

Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender.

This style guide is known as pep8 and can be found [http://www.python.org/dev/peps/pep-0008/| here].

A brief listing of pep8 criteria.
* camel caps for class names: MyClass
* all lower case underscore separated module names: my_module
* indentation of 4 spaces (no tabs)
* spaces around operators. 1 + 1, not 1+1
* only use explicit imports, (no importing '*')
* don't use single line: <code>if val: body</code>, separate onto 2 lines instead.

As well as pep8 we have other conventions used for blender python scripts.
* Use single quotes for enums, and double quotes for strings. Both are of course strings but in our internal API enums are unique items from a limited set. eg. <code>bpy.context.scene.render.file_format = 'PNG'</code> <code>bpy.context.scene.render.filepath = "//render_out"</code>
* pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script.

Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script.
# <pep8 compliant>

To enable line length checks use this instead.
# <pep8-80 compliant>

← 古い版	2018年6月28日 (木) 19:44時点における版
(相違点なし)

Dev:PT/2.5/Py/API/Intro - 版の履歴

Yamyam: 1版 をインポートしました

wiki>Genio84: /* Introdução à Blender/Python API */

Yamyam: 1版をインポートしました