Profiling: using kernprof in Blender add-ons

When implementing add-ons that contain very time consuming activities, profiling can be a tremendous help in pinpointing the hotspots in your code. And if you use Numpy a lot, where a lot of hard work is hidden in a few lines of code, a line profiler is a godsend. I used it for instance in researching bottlenecks in some tree related code.

Now the excellent kernprof package offers basically all we need and works fine for stand-alone Python programs but I want to use it inside Blender add-ons and this article illustrates what is needed to get it working. It's a bit fiddly but well worth it if you really want to optimize your code.

Installing the kernprof package

This works under Linux if your python3 version is the same as the one inside Blender (3.5.x as I am working with Blender 2.78a, I am not sure this works under Windows).


First we have to install the kernprof package:
pip3 install line_profiler
This will install the package in whatever location you use as default with pip, in my case /home/michel/.local/lib/python3.5/site-packages

Now currently the developer of kernprof decided to make IPython a hard requirement which in our case makes things more difficult because we want to use the profiler just in Blender and do not want to rely on any extra stuff. It is however simple enough to remove these dependencies and leave us a LineProfiler class that just works.

This stripped version is available on GitHub and you should download this version to replace the one that was installed by pip (in my case /home/michel/.local/lib/python3.5/site-packages/

Now we can start creating add-ons where functions can be profiled on a line by line basis and I will highlight the relevant pieces of code.

Because we installed the kernprof package outside Blender's Python libraries, we have to make sure we can find the modules by adding the path:


from line_profiler import LineProfiler
profile = LineProfiler()
After adding the path we can import the LineProfiler class and create an instance of it.

This instance can be used as a decorator on functions that we want to profile. Note that it is currently not possible to add this decorator to the execute() function of an operator otherwise Blender will complain. Apparently there is something weird going on when the function is wrapped.

 def expensive_stuff(self,a,b):
  for i in range(a):
   c = b * b

 def execute(self, context):
Currently I have chosen to dump the statistics when we disable the add-on. On disabling the unregister() function is called automatically and we use this to write the statistics in the same directory as where our module is located and use a filename with the same name but with a .prof extension:
def unregister():
If our addon file was called we could (after disabling the add-on) use the same line_profiler module outside of Blender to show the accumulated statistics:
python3 -m line_profiler /home/michel/.config/blender/2.78/scripts/addons/
The result for our silly example function looks like the listing below, interpreting the results is up to you (please refer to the documentation on the kernprof site.)
Timer unit: 1e-06 s

Total time: 0.002952 s
File: /home/michel/.config/blender/2.78/scripts/addons/
Function: expensive_stuff at line 33

Line #      Hits         Time  Per Hit   % Time  Line Contents
    33                                            @profile
    34                                            def expensive_stuff(self,a,b):
    35      3003         1411      0.5     47.8    for i in range(a):
    36      3000         1541      0.5     52.2     c = b * b

Full example code

The complete code for a tiny example add-on that provided the code snippets showed earlier is listed below:
bl_info = {
 "name": "Expensive Operation",
 "author": "Michel Anders (varkenvarken)",
 "version": (0, 0, 201612231212),
 "blender": (2, 78, 0),
 "location": "View3D > Add > Mesh > Expensive Op",
 "description": "A time consuming operator to test profiling options within Blender add-ons",
 "warning": "",
 "wiki_url": "",
 "tracker_url": "",
 "category": "Add Mesh"}
import bpy
import sys
from os.path import splitext

# make sure we can find (the hacked version of) line_profiler

from line_profiler import LineProfiler
profile = LineProfiler()

class ExpensiveOp(bpy.types.Operator):
 bl_idname = 'mesh.expensiveop'
 bl_label = 'Expensive Operator'
 bl_options = {'REGISTER','UNDO'}

 def poll(self, context):
  return (context.mode == 'OBJECT')

 def expensive_stuff(self,a,b):
  for i in range(a):
   c = b * b

 def execute(self, context):
  # this is just to show something happened
  bpy.ops.mesh.primitive_cube_add() = 'Expensive Cube'
  return {"FINISHED"}

def menu_func(self, context):
 self.layout.operator(ExpensiveOp.bl_idname, text=ExpensiveOp.bl_label, icon='PLUGIN')

def register():

def unregister():

Nodeset: support for ambient occlusion maps

A couple of weeks ago I created a small add-on that lets you load whole sets of texture maps as generated by Substance Painter in one go.

I left out support for ambient occlusion maps but now I have corrected that :-)

The latest version is available on GitHub.

It now also loads textures that end in _ambient_occlusion (if present). This suffix is of course configurable in the user preferences, just like all other suffixes.

ColorRampPicker, a new Blender add-on

Got this idea from Substance Designer which offers an option to sample a whole palette of colors from a reference image for their gradient node. Now you can do the same for Blender's color ramp node. With a color ramp node selected, just go to the Node menu and select Color Ramp Picker. An eye dropper will appear and you can sample from anywhere within your Blender window by clicking and dragging. Unfortunately it is not possible to sample outside the Blender window so you should have your reference image loaded in BlendeĊ› uv-image editor.

I have also made a small video that illustrates the proces:


You can download the add-on from GitHub. (click right on the Raw button and save the python file anywhere you like and then in Blender select File->User preference, Add-ons, Install from file... Don't forget to enable the add-on as well after installing it.)

If you would like to write add-ons yourself, you might want to take a look a my books on BlenderMarket.


After publication I learned about a similar and much more versatile tool to generate (and sample) gradients. Check this BlenderArtists thread to learn more.

Add-on: Selecting similar vertices

If you select the Similar sub menu when in vertex edit mode Blender already offers a few options to extend your current selection of vertices.

And although useful I frequently find myself in a situation where the available options are not sufficient. Especially in hard edge modeling of objects with identical sub parts I often want to be able to select vertices that not just share the same number of faces but where the these shared faces have something else in common. For example in the object shown below we have two different collections of bumps but the is no way to select just all the spiky tips in one go.

The simple add-on I present here fills this gap: it checks not only if vertices have the same number of surrounding faces but also whether the average angle between the face normals and the vertex normals is similar. This will allow you to distinguish between flat and spiky. The amount of similarity can be tweaked to allow for round-off errors or non smooth meshes.

Availability and usage

After downloading, installing and enabling the add-on from GitHub, the new selection option is available in vertex edit mode from the Select -> Select_similar -> Neighborhood

Black Friday - Cyber Monday at Blender Market

Goods news for cost conscious Blenderheads: from november 25th - november 28th Blender Market will host the yearly Black Friday - Cyber Monday sale!

I will participate will all my products, including my new IDMapper add-on. So if you want to save 25% on WeightLifter, SpaceTree, IDMapper (video) or one of my books, head over to my shop on Blender Market this weekend. Of course many other creators will be participating as well so you might want to shop around a bit more :-)

[For Europeans: remember Blender Market runs on Chicago time, so don't start shopping too early next Friday :-) ]

IDMapper - create ID-maps the easy way

it's always exiting to announce a new product on Blender Market and today I am pleased to announce IDMapper.

IDMapper is a Blender add-on that lets you create a vertex color layer that can be used as an ID-map by texture paint tools like Substance Painter.

When creating textures for models you often want to reduce the actual number of textures, for example because your GPU can only handle a limited number of textures or maybe simply because juggling a large number of textures for a single model is such a hassle.

Whatever your motivation, texture painting software lets you apply different materials to a texture with ease but you still need to identify areas. An ID-map makes it very simple to apply a material to faces that have a certain color, often by letting you pick a color from the ID-map with an eye-dropper tool.

You will still need to create the vertex color layer that can be used as an ID-map and that's where IDMapper can help.

The first thing it offers are powerful heuristics to assign a unique vertex color to regions consisting of related faces. What is considered related can be tweaked interactively and any resulting distinct regions with very similar geometry can still be assign the same vertex color, simplifying for example the assignment of colors in hard-ops modelling in situations where your mesh contains repeated features like handles or bolts.

The second feature is an operator that acts like a new face paint mode. Instead of applying blended colors to vertices in a painterly manner as with Blender's vertex paint mode, this operator keeps colors uniform across a face, something often desirable when assign materials to mesh parts. It also lets you assign new colors to colored regions and resize or smooth these regions interactively.

And finally it offers some convenience functions to combine different vertex color layers and copy vertex color layers from one mesh to another, probably more high poly, mesh.

A short video showcasing the main features is available on Youtube:

IDMapper is available in my Blender Market shop