Units in Blender add-ons

It might not be immediately obvious how to make Blender to show units along with the properties you define in your add-ons, but fortunately it is not all that difficult.

There are two aspects to the display of units, representation and definition.

Representation

This determines how property values are displayed and is something that is is controlled by the end user.

It is configured in the Scene properties, specifically in the Units panel.

The main choice here is between Metric and Imperial, but you can also choose specific units for certain quantities, for example, you might prefer Celsius instead of Kelvin.

The Unit Scale property is convenient if you are working to scale. I work with model trains in the H0 scale and sometimes make visualizations in Blender. Then I set the unit scale to 87 (because H0 is 1:87 scale) and then building dimensions etc. will show up with their real world dimensions. 

Definition

This determines what kind of quantity we are talking about.

This is something you configure in you property definitions. For a FloatProperty for example, you have subtype and unit parameters. If you leave unit at NONE, Blender will not show any units!

Let's say you want to define add a property called floorarea to your add-on, you might want to configure it like this:

	floorarea = FloatProperty(
    	    name='Floor area',
    	    subtype='DISTANCE',
            unit='AREA')

So the subtype defines what quantity we're dealing with, and DISTANCE is used for anything that can be expressed as a length (or in the case of an area, length squared). Some other options for subtype are ANGLE and TIME.

The subtype determines the widget that is used too, which is especially important for properties that are lists of things, like a FloatVectorProperty, that shows a color picker when the subtype is COLOR and other widgets when the subtype is for example a DIRECTION.

Each type of property has its own set of possible subtypes and units.

The unit parameter defines the actual unit to use. For example, for a DISTANCE subtype you could use LENGTH, AREA or VOLUME. For an AREA the value of the property would be displayed as m²  or ft², depending on the Unit System selected in the Scene properties.