[PYTHON] [Blender] How to allow users to control plugins from toolshelf options

Do you know Blender's tool shelf?

The ** Tool Shelf ** is a menu that can be shown / hidden with the T key, and is the ** Toolbar ** displayed on the left edge of the screen. There are many tools on the tool shelf, but below there is a ** option **, a setting item ** that gives the user finer control over the last operation. For example, Level in "Subdivision Set" is one example.

This time, I will introduce how to add a function to enable user control from the tool shelf option to the last operation.

sample

I think it's easier to understand if you give a sample rather than explain it in detail, so I will introduce a sample plug-in that rotates the object around the X axis by the angle of the value set in the option.

rotate_around_x_axis.py

import bpy
import mathutils
from math import radians
from bpy.props import *

bl_info = {
    "name" : "Property sample",
    "author" : "Nutti",
    "version" : (1, 0),
    "blender" : (2, 7, 0),
    "location" : "UV Mapping > Property sample",
    "description" : "Property sample",
    "warning" : "",
    "wiki_url" : "",
    "tracker_url" : "",
    "category" : "UV"
}

class PropertySample(bpy.types.Operator):
    """"""
    
    bl_idname = "uv.property_samle"
    bl_label = "Property Sample"
    bl_description = "Property Sample"
    bl_options = {'REGISTER', 'UNDO'}

    #Value to be displayed on the tool shelf
    #Angle to rotate around the X axis (integer value from 0 degrees to 360 degrees can be selected)
    rot = IntProperty(
        name = "Rotate X",                #Label name displayed on the tool shelf
        description = "Rotate X ...",     #Description displayed on the tool shelf
        default = 0,                      #Default value
        min = 0,                          #Minimum selectable value
        max = 360)                        #Maximum selectable value
    
    base_euler = None                     #Initial angle
    
    #Initialization process
    # __init__Is only executed when selected from the menu
    #If you do not save the initial state here, there will be a problem with the amount of rotation
    def __init__(self):
        active_obj = bpy.context.active_object
        mode = active_obj.rotation_mode
        active_obj.rotation_mode = 'QUATERNION'
 
        #Save the initial state of the object
        self.base_euler = active_obj.rotation_quaternion.to_euler()
        active_obj.rotation_mode = mode
        
        #When selected from the menu the second time or later
        #Must be manually set to default value
        self.rot = 0   
    
    #In addition to when selected from the menu
    # "When changing the value on the tool shelf"Also called
    def execute(self, context):
        active_obj = bpy.context.active_object
        mode = active_obj.rotation_mode
        active_obj.rotation_mode = 'QUATERNION'
        
        #Set the state of a new object
        new_euler = self.base_euler.copy()
        new_euler.x = self.base_euler.x + radians(self.rot)
        active_obj.rotation_quaternion = new_euler.to_quaternion()
        
        active_obj.rotation_mode = mode
        
        return {'FINISHED'}


# registration
def menu_func(self, context):
    self.layout.operator(PropertySample.bl_idname)

def register():
    bpy.utils.register_module(__name__)
    bpy.types.VIEW3D_MT_uv_map.append(menu_func)

def unregister():
    bpy.utils.unregister_module(__name__)
    bpy.types.VIEW3D_MT_uv_map.remove(menu_func)


if __name__ == "__main__":
    register()

How to use the sample

Please see Blender Wiki Page for how to install the sample.

The usage of the sample is shown below.

1. Change to "EDIT" mode
2. Press the "U" button and select "Property Sample"
3. On the tool shelf, you will see an option called "Rotate X". Set it to an appropriate value and make sure the object rotates.

An example of the execution result of the sample is shown below.

Sample explanation

The basic source code is explained in [\ Blender ] How to make a Blender plugin, so I will omit it.

The following parts specify the value of the option.

set_option.py

#Value to be displayed on the tool shelf
#Angle to rotate around the X axis (integer value from 0 degrees to 360 degrees can be selected)
rot = IntProperty(
    name = "Rotate X",                #Label name displayed on the tool shelf
    description = "Rotate X ...",     #Description displayed on the tool shelf
    default = 0,                          #Default value
    min = 0,                               #Minimum selectable value
    max = 360)                          #Maximum selectable value

A function called ** IntProperty ** allows the user to set the value as an option. In this sample, the angle to rotate around the X axis can be specified from 0 degrees to 360 degrees. For other details, please refer to the comments in the source code as appropriate.

List of values that can be specified for options

In the sample, integer values can be set as options, but other types of option values can also be set. The values that can be set and the corresponding functions are summarized, so please refer to them.

Specify the range of values that can be specified for the option

You can also limit the values that can be specified for the option. Shows how to limit the range between -100 and 400 for integer options.

max_min.py

i = IntProperty(
    name = "Integer",
    description = "Integer ...",
    default = 0,
    min = -100,
    max = 400)

Arguments that can be specified for ~ Property

List the arguments that can be specified in ~ Property. There are other arguments that can be specified, but please see the Blender official page for details.

Finally

We have shown how the user can get the value specified for an option. Options should allow users to configure features and expand the range of plugin creation.

Reference information

• http://www.blender.org/api/blender_python_api_2_66_release/bpy.props.html
• [\ Blender ] How to make a Blender plugin
• http://wiki.blender.org/index.php/Doc:JA/2.6/Manual/Extensions/Python/Add-Ons
• http://www.blender.org/api/blender_python_api_2_58_1/mathutils.html