Search the API

Objectives

a Creating objects from a menu as with Add » Mesh » ... is easy. The same gaol is also achievable within a Python script. The API is important to get the necessary informations.

Instructions

Tasks:
  1. Create an new Python script.
  2. Create a function that lists all methods available in Blender who create a mesh objects (primitive) .
  3. Create one instance from each object in your scene. No object should touch an other.
  4. Create a figure as a composition from a cone and a sphere (UV_Sphere). There are two possible solutions. Maybe you will find a third version.

Structure of the API

All available functionality is grouped by different modules. Only the first two are required in the beginning.

Application Modules

  • Data Access (bpy.data)
  • Operators (bpy.ops)
  • Types (bpy.types)
  • Utilities (bpy.utils)
  • Path Utilities (bpy.path)
  • Application Data (bpy.app)
  • Property Definitions (bpy.props)

Standalone Modules

  • Math Types & Utilities (mathutils)
  • Font Drawing (blf)
  • Audio System (aud)

Game Engine Modules

  • Game Engine bge.types Module
  • Game Engine bge.logic Module
  • Game Engine bge.render Module
  • Game Engine bge.events module

Which »primitives« are available?

If you start creating a complex world in 3D/Blender, often a good starting point is to create simple objects. Lets create the available mesh objects. But which objects are available?

  1. First and easiest solution: have a look at the menu Add » Mesh » ... and look at the tooltip at the mouse pointer.

  2. RTFM (read the fine manuals)

    1. Online documentation, search for »mesh primitive« on Blenderdocs
    2. Search the file »OperatorList.txt«.
      You can open it in the Blender editor using the menu sequence:
      Help » Operator Sheet Sheet.
      A copy is also included in the appendix: OperatorList.txt

  3. If you are familiar with the structures in Blender, the console is a good starting point to discover the API.

  4. If your are not successful searching the API, ask the community. A linklist is available in the appendix.

Note:It is essential to work with the API, nobody is able to remember all possibilities!

Finding the right method(s)

Add mesh objects with Python instead using the menu is shown in a screenshot where the console is used. This is error prone, using a script is a good alternative.

../../../_images/for-loop.png

Create the objects

Now that we know how to create new objects lets create a script for this task. Where to place the new object, is controlled by the parameter location, a tuple (values in rounded braces) with tree Values for the x-, y- und z-aches.

Here is a fragment...

bpy.ops.mesh.primitive_cube_add(location=(2, 2, 0))
bpy.ops.mesh.primitive_cylinder_add(location=(-2, -2, 0))

And so the final solution might look like:

../../../_images/objects.png

Short video about using the API

Showcase

Try to recreate the following construct unsing only cubes and the menu Add » Mesh » ...!

Todo

create a script...