Parameter and functions

Objectives

You learned about the structure of a script and how to run it. Now we define a new function with a parameter. This increases the flexibility of our own code and programms.

Instructions

Tasks:

1. Create a new scrtipt and save it as bprint.py in your project folder.

2. Run the script and check the output in the 3D View.

3. Rewrite the script, the output function should set the text on a given position in the 3D-View. Use a second parameter for this task.

4. How is the function call for the mascot of Blender, the monkey named »Suzanne«?

   

bprint – output into the 3D view

How can you create text in a 3D world? With our own function we can add new functionality. A new function named bprint (b stands for Blender) will be created and used. Have a look at the complete script.

#!bpy
"""
Name: 'bprint.py'
Blender: 2.69
Group: 'Experiment'
Tooltip: 'Output of text in a scene'
"""

import bpy


def bprint(print_text):
    """Places a given text in the 3D view """

    bpy.ops.object.text_add(location=(0, 0, 0), rotation=(0, 0, 0))
    bpy.ops.object.editmode_toggle()
    bpy.ops.font.delete()
    bpy.ops.font.text_insert(text=print_text)
    bpy.ops.object.editmode_toggle()
    

if __name__ == '__main__':
    # Stop edit mode
    if bpy.ops.object.mode_set.poll():
        bpy.ops.object.mode_set(mode='OBJECT')

    # delete all mesh objects from a scene
    bpy.ops.object.select_by_type(type='MESH')
    bpy.ops.object.delete()

    # delete all text objects from a scene
    bpy.ops.object.select_by_type(type='FONT')
    bpy.ops.object.delete()

    # call the new function
    bprint("If in doubt, just do it")

Defining parameters

In our template we used a parameter with the function print:

print(__name__)

The definition of the new funktion bprint defines a parameter as well. The parameter is named »print_text« - the name of the parameter(s) can be choosen freely.

#!bpy
"""
Name: 'bprint.py'
Blender: 2.69
Group: 'Experiment'
Tooltip: 'Output of text in a scene'
"""

import bpy


def bprint(print_text):
    """Places a given text in the 3D view """

    bpy.ops.object.text_add(location=(0, 0, 0), rotation=(0, 0, 0))
    bpy.ops.object.editmode_toggle()
    bpy.ops.font.delete()
    bpy.ops.font.text_insert(text=print_text)
    bpy.ops.object.editmode_toggle()
    

if __name__ == '__main__':
    # Stop edit mode
    if bpy.ops.object.mode_set.poll():
        bpy.ops.object.mode_set(mode='OBJECT')

    # delete all mesh objects from a scene
    bpy.ops.object.select_by_type(type='MESH')
    bpy.ops.object.delete()

    # delete all text objects from a scene
    bpy.ops.object.select_by_type(type='FONT')
    bpy.ops.object.delete()

    # call the new function
    bprint("If in doubt, just do it")

Note:Parameters are placed between the rounded braces behind the name of the function.

Optional parameters

If you define a function like in the example above, you can not call the function without passing an argument into the function. If you want to make the parameter optional you can give the parameter a default value. If that parameter does not get fed an argument when the function is called, the default value is used instead. This is useful if many parameters are possible but not all are mandatory. Examples for optional parameters:

def my_functions(location=(0,0,0))
def my_function(rotation=(0,1,1))
def my_function(text="hello, world")

note:An optional parameter is defined as a key-value-pair, as shown in the examples above.

Blender showcase for parameters

Now let’s have a look at an example in Blender. First of all enlarge the info window in Blender:

You are now able to see all functioncalls that your are doing. If you add

a cylinder, selecting the menu Add » Mesh » Cylinder you will see a very

long function call.

You can select a line by right clicking it - then you can copy and paste the line

to your text window.

For better readability of this »ASCII-tapeworm« all parameters are broken up to separate lines:

bpy.ops.mesh.primitive_cylinder_add(vertices=32,
                                    radius=1,
                                    depth=2,
                                    end_fill_type='NGON',
                                    view_align=False,
                                    enter_editmode=False,
                                    location=(-4.93998, -5.74176, 4.41665),
                                    rotation=(0, 0, 0),
                                    layers=(True,
                                            False, False, False, False,
                                            False, False, False, False,
                                            False, False, False, False,
                                            False, False, False, False,
                                            False, False, False))

Most of the lines are optional. The shortest version is:

bpy.ops.mesh.primitive_cylinder_add(location=(-4.93998, -5.74176, 4.41665))

And with some better readable parameter values:

bpy.ops.mesh.primitive_cylinder_add(location=(2, 2, 2))

Now you have a new way to discover useful and/or new function in Blender.