# 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¶

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.

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 #!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

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

bpy.ops.mesh.primitive_cylinder_add(vertices=32,
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.