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

2018-06-28T18:47:30Z

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

wiki>Iluvblender: Fixed more broken links

2014-03-28T07:39:20Z

Fixed more broken links

新規ページ

{{Page/Header||}}

== Properties, ID-Properties and their differences ==
----
There are several ways to define custom properties in Blender using Python. One of them is to add a new property to an existing datablock. Another is to define a new ID-property for a datablock. This might seem to be the same, but there are some differences. So when to use what?

This document assumes that the reader has a basic knowledge of Python and Blender. Any code examples can be tested successfully in the default scene. Any user-interface elements that are created will be displayed in the properties sidebar of the 3d-view (toggle with N-key). As they show up at the bottom of this bar, it might be useful to collapse the panels above it (like Transform, View, etc.)

== Properties ==
----
=== Basics ===
By default these are the normal properties that Blender itself uses. For instance, an object has a [http://www.blender.org/documentation/blender_python_api_2_70_release/bpy.types.Object.html#bpy.types.Object.location location] property. This is a vector which contains information on the location of the object. This property can be both read and written. Other properties, like for instance [http://www.blender.org/documentation/blender_python_api_2_70_release/bpy.types.Object.html#bpy.types.Object.users users] are read-only.

<source lang="python">
import bpy

ob = bpy.context.active_object # get the active object
print("Location:", ob.location) # print its location
ob.location = [1,1,1] # set it to a new location

print("Users:", ob.users) # print its number of users
#ob.users = 3 # this will raise an error
</source>

=== Custom properties ===
You can also add a new property yourself. The first thing you need to decide is the property type: a boolean, float, string, etc. Here is the [http://www.blender.org/documentation/blender_python_api_2_70_release/bpy.props.html full list]. Simply add the new property (a string in this case) by using:

<source lang="python">bpy.types.Object.myProperty = bpy.props.StringProperty()</source>

This adds the property myProperty to all objects.

Once you've added the property you can interact with it just like it were any other normal property.

<source lang="python">ob = bpy.context.active_object # get the active object
bpy.types.Object.foo = bpy.props.StringProperty() # add a new property, called "foo"
ob.foo = "bar" # assign a value to the property
print("foo:", ob.foo) # prints "foo: bar"
print("foo:", ob['foo']) # also prints "foo: bar"

class myPanel(bpy.types.Panel): # panel to display new property
bl_space_type = "VIEW_3D" # show up in: 3d-window
bl_region_type = "UI" # show up in: properties panel
bl_label = "My Panel" # name of the new panel

def draw(self, context):
# display value of "foo", of the active object
self.layout.prop(bpy.context.active_object, "foo")

bpy.utils.register_class(myPanel) # register panel
</source>

{{SideNote|1=right|2=Spaces|3=[[image:Blender3D_FreeTip.png|left]]If you have spaces in your property name you can't call it with ob.foo bar Use getattr(ob, "foo bar") instead}}
One thing to keep in mind is that after saving and reloading your blend-file, your new property will have disappeared. So print(ob.foo) won't work anymore. Any object that had a value assigned to the property will still have it available though, but only as an ID-property. For more information on those, look further down this page. 
To make the values you assigned in a previous session available again, you need to redefine the property. So after reopening the blend-file you need to rerun:

<source lang="python">bpy.types.Object.myProperty = bpy.props.StringProperty()</source>

This will also reassign the values to the property that were assigned to it in a previous session (they are retrieved from the corresponding ID-properties), so you don't need to reassign those. print(ob.foo) will still return bar

=== Dynamic custom properties ===
The previous method will work fine for cases in which you wish to store static information on certain datablocks, but won't be of much help when you want the property to be dynamic. In that case you need to assign a function to the property. The way to do this is to use python's built-in [http://docs.python.org/library/functions.html#property property()] function. For example:

<source lang="python">bpy.types.Lamp.foo = property(bar)</source>

A further difference is that dynamic custom properties aren't stored when saving a blend-file. Not even as an ID-property.

Below is a full example of creating a new dynamic property, called distance

<source lang="python">
import bpy #needed in a script-text-window!
def fget(self): # custom get function
"""Distance from origin""" # description of property
loc = self.location # location of object
distance = loc.length # distance from origin
return distance # return value

def fset(self, value): # custom set function
if self.location.length < 1E-6: # if object is at origin
self.location = [1, 0, 0] # direction to move in
self.location.length = value # set distance from origin

bpy.types.Object.distance = property(fget, fset)# assign function to property

ob = bpy.context.active_object # get the active object
print(ob.distance) # print distance to the console
ob.distance = 2 # set the distance

class myPanel(bpy.types.Panel): # panel to display new property
bl_space_type = "VIEW_3D" # show up in: 3d-window
bl_region_type = "UI" # show up in: properties panel
bl_label = "My Panel" # name of the new panel

def draw(self, context):
# display "distance" of the active object
self.layout.label(text=str(bpy.context.active_object.distance))

bpy.utils.register_class(myPanel) # register panel
</source>

To have your property available across different blend-files (even after saving and reloading), you'll have to add your property in ../.blender/scripts/modules/bpy_types.py (where .. is the folder in which blender is installed).
Find the class to which you wish to add your property and simply add the functions that define your property. There are two small differences, concerning the syntax. The first one is the use of a [http://docs.python.org/glossary.html#term-decorator decorator]. The second one (resulting from this) is that the function name is used as the property name. 
Here's the same example as above, but now added to bpy_types.py

<source lang="python">
@property # decorator
def distance(self): # attribute name
"""Distance from origin"""
loc = self.location
distance = loc.length
return distance

@distance.setter # decorator
def distance(self, value):
if self.location.length < 1E-6:
self.location = [1, 0, 0]
self.location.length = value
</source>

== ID-Properties ==
----
=== Basics ===
ID-properties are properties that are assigned to individual datablocks. And not just any datablock, but only datablocks that are subclassed from the ID-type. Examples are Lamps, Meshes, Objects and WindowManagers. Look at the [http://www.blender.org/documentation/blender_python_api_2_70_release/bpy.types.ID.html full list] for more information about ID subclasses.

Creating a new ID-property is very easy:

<source lang="python">
ob = bpy.context.active_object # get the active object
ob["foo"] = "bar" # create and assign an ID-property

print(ob["foo"]) # prints "bar"
# print(ob.foo) # won't work, as foo isn't an attribute
print(ob.items()) # prints all ID-properties of ob
</source>

Creating the ID-property and assigning it a value is all done at the same time. The ID-properties are stored as a dictionary on the datablock.

Besides the types of datablocks they can be assigned to, ID-properties have another limitation to be aware of. You can only assign strings, integers, floats, and lists to an ID-property. And the lists are limited, because they may only contain floats and integers.

=== Referencing ===
[[image:Crouch-custom-properties.png |right|250px|]]
ID-properties have the advantages that they are stored in a blend-file when it is saved, and that they are easy to keep track of. The main reason they are easy to track, is that by default they are shown in the user interface. They show up in the appropriate Custom Properties panel. So if you add an ID-property to a lamp, it will show up in the Custom Properties panel in the Lamp window. This makes it very easy to change their values, even for normal users. This can also be used to add new ID-properties, without having to use python.

To display an ID-property using [http://www.blender.org/documentation/blender_python_api_2_70_release/bpy.types.UILayout.html#bpy.types.UILayout.prop UILayout.prop()], you can't simply pass "foo" as the property, but you need to pass a one-item list as a string. So '["foo"]'

<source lang="python">
class myPanel(bpy.types.Panel): # panel to display new property
bl_space_type = "VIEW_3D" # show up in: 3d-window
bl_region_type = "UI" # show up in: properties panel
bl_label = "My Panel" # name of the new panel

def draw(self, context):
# display "foo" ID-property, of the active object
self.layout.prop(bpy.context.active_object, '["foo"]')

bpy.utils.register_class(myPanel) # register panel
</source>

Note that this won't work if the active object hasn't got the ID-property, so make sure that you have a fallback in your code instead of raising an error.

So far ID-properties were pretty straightforward, but it gets a bit more tricky when you wish to set parameters for the ID-property. For instance the minimum and maximum value of an integer. These parameters are stored in a special property called _RNA_UI It can be accessed like any other ID-property and is a dictionary with the other ID-properties as key and their parameters as values.

<source lang="python">
ob = bpy.context.active_object # get the active object
ob["foo"] = 7 # create the ID-property
ob["_RNA_UI"] = {"foo": {"min":3, "max":42}} # set parameters
</source>
To keep this example script short it simply overwrites _RNA_UI and thus erases any already existing parameters. In normal scripts it's better to insert a new key for your new parameters.

== Summary ==
----
{| {{Css/prettytable}}
!
! align="center" style="width:28%;" | Property (static)
! align="center" style="width:28%;" |Property (dynamic)
! align="center" style="width:28%;" | ID-Property
|-
!align=center|Creation
|align=center|bpy.types.Object.foo = bpy.props.StringProperty()
|align=center|bpy.types.Object.foo = property(bar)
|align=center|ob["foo"] = "bar"
|-
!align=center|Declared for
|align=center|all datablocks of same type
|align=center|all datablocks of same type
|align=center|single datablock
|-
!align=center|Assigning values
|align=center|ob.foo = "bar"
|align=center|ob.foo = "bar"
|align=center|ob["foo"] = "bar"
|-
!align=center|Accepted values
|align=center|Any [http://www.blender.org/documentation/blender_python_api_2_70_release/bpy.props.html property]
|align=center|Functions
|align=center|Floats, integers, lists*, strings
|-
!align=center|Stored in .blend
|align=center|Yes**
|align=center|No
|align=center|Yes
|}
<nowiki>*</nowiki> List may only contain floats and integers. 
<nowiki>**</nowiki> Datablocks that have a value assigned to the property, save that value as an ID-property.

[[Category:Script]]

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

Doc:2.6/Manual/Extensions/Python/Properties - 版の履歴

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

wiki>Iluvblender: Fixed more broken links

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