Making a Lumens patch


I’m considering making a patch for enabling Lumens as a unit for light strengths, because I imagine people are more familiar with Lumens than with Watts per square meter per steradian.

The change would be UI only. Basically you’d go to the Units pane in the Scene settings and indicate you want Lumens as a light unit. After that, point light strengths would show up in Lumens when you edit them, and possibly for spots as well.

But before I actually do anything about this I have some questions:

  1. Assuming the code looks fine, is this something that would likely be merged?
  2. Would it be OK to have point-lights-only merged first, and do spots in a second patch?

Brain dump here with some more details, feel free to comment in the doc:

Regards /Johan


Support for this would be welcome, but some notes:

  • Point lights only first will not work, since it shares the same property with spot lights. If you want to change the behavior of spot lights to take into account the cone angle and normalize by that, that can be done later. It will need to be an option on lights so that backwards compatibility is preserved, and because both behaviors may be useful (for animation, compatibility with other renderers or file formats).
  • Area lights should be in Lumens, and can work exactly the same as point lights as far as conversion to Watts goes.
  • Adjusting the strength so that the combined strength * color gives a particular Lumens or Watts could be useful but again would need to be an option to avoid breaking backwards compatibility.
  • This should use the Blender units system, so that the scene unit settings have a choice between Watts and Lumens. I don’t see the need to have a option per light to switch between Lumens and Watts.

For the implementation I was thinking:

  • Add a property brightness_lumens to point lights using RNA_def_property_float_funcs(). The backing store would be the energy property together with the light color. This can be done for point lights only in rna_light.c.
  • Depending on a setting in Scene / Units, the light editing pane would provide access to either Watts or Lumens.

AFAICT this should cover:

  • Point lights only
  • Compatibility with most existing things since the light storage struct is unchanged
  • Per-scene setting (not per-light setting)

I wanted to avoid spots to begin with since I’m not sure whether or not to scale brightness depending on cone angle, and postponing that conversation might simplify code / design reviews :slightly_smiling_face:.

Regarding the Blender units system, if I read unit.c correctly it converts between units by scaling by constants.

Converting between Watts and Lumens requires knowing the light color, a constant is not enough, that’s why I opted for having my own getters / setters.

Can the unit system support taking the light color into account for doing the conversion? Or should I stick with my getters / setters idea?


As explained, I think this is the wrong approach.

Scene settings should not do this, it would mean that linking lights into other scenes is unpredictable.

Importer/exporter and other add-ons that use light parameters would be broken.

Changing brightness with the cone angle is an independent problem of the Lumens / Watts distinction.

We should not have a light strength property whose value changes if the color changes. It is the renderer that may adjust parameters internally to achieve a particular Lumens value, but the user parameter should be fixed. Anything else would be incompatible with importers/exporters, animation, etc.

TIL. I just tried this and it did not do what I expected; it adds a new lights property which is not what I wanted. I just want Lumens in the UI, not in any structs.

I feel I’m missing something obvious here.

A light has:

  • Color
  • Energy (Watts)
  • Brightness (Lumens)

If the user animates the color from green to blue, with the energy fixed, the brightness visibly goes down.

What I would expect from the UI if I have a Lumens box rather than a Watts box is that as I step through the frames of the animation, the number in the Lumens box would change to reflect the change in brightness.

Does this match your expectations of how the UI should behave in this situation?

It does not, changing the value of one property should not affect the value of another property. It’s incompatible with importers/exporters, animation, etc.

If lumens was an actual property, then I totally see the problems you describe.

But if lumens is only a UI element backed by energy and color, then I can’t see how those problems would happen.

Feel free to expand on this!

Let’s get back to this.

First of all, we’re both in agreement on that the scene unit settings is where the Lumens-or-Watts setting should be.

Now, given that Lumens = Watts x Color, what are the options for using the units system here?

  1. Can the units system as it works today support the Watts x Color maths?
  2. If not, should the units system be extended to be able to support the Watts x Color maths?
  3. Something else?

This should use the Blender units system, so that the scene unit settings have a choice between Watts and Lumens.

I beg to disagree with this, from an artist perspective, doing an input in Watts or Lumens it’s a per-light option, I’m not talking about how the render engines handle this internally, but for an artist these are just different values, at some point you may want to di different things:

  • Treat a light without real world units, in a WYSIWYG idea with an purely artistic value

  • Treat other lights in the same scene with the Watt value, which is still unclear how does it relate to real light Watt values, I may have missed something about it, but in general I still have no idea about what value should I use to reproduce a real lamp from the real world where I have it’s real manufacturer values, so right now for us using Watts or any other “artistic” unit is more or less the same, we are not sure on how to co-relate values with real world.

  • Use lumens to match the luminosity of a lamp with a real worl lamp you may have in the studio for example

There are other situations but making the light values part of the scene unit settings is a bad idea. It makes no sense from an artist perspective, and no other engine does that, because you would be locked with that value, it’s inefficient and the wrong approach with lighting in 3D.

The whole problem is not-actual properties, they don’t work well with importers/exporters and animation. We should avoid them whenever possible and use actual properties instead.

Watts x Color maths should only happen in the renderer when setting the effective light intensity, not at the user interface level. The user sets a Lumens values, then the renderer does conversions as needed.

I’m fine with having it as a per-light instead of per-scene option, it still should use the Blender units system.

1 Like

Are you saying that you want each lamp to have either a Lumens property or a Watts property but not both? And then put code in the renderers for illuminating using either Lumens or Watts, as appropriate for each lamp?

I can totally see the use case for Lumens: “I have a lamp in my hand, it says 470lm on the box, now I want to write 470 in Blender”.

But from an artist’s point of view, what’s your Watts pitch? Just like you, lots of people aren’t really friends with “Watts per square meter per steradian”; it’s just a number.

For your “light without real world numbers”, wouldn’t Lumens work just as well here? Just like with Watts you could just pull the number up and down until it looks right.

Just to be clear: I don’t want to remove the Watts; because of its long history I think too many things and people depend on it for it to be removable.

1 Like

I’m not against adding Lumens, not at all!

I’m all in favour of it, it’s way simpler than the watts value, if you understood a different thing from my post, sorry I should have miss-explained things.

All the watts thing was to explain that right now having Watts as a unit in lights it’s near to not having any unit at all, because we don’t exactly know how to interpret that for a real world light, having Lumens could make this way easier because Lumens it’s easier to get, we don’t have to deal with efficiency and other things, it just gives X lumens, and that’s it.

So not against it, all in favour, but in a per-light basies, not a per-scene basis :slight_smile:

Or is this what you’re suggesting @brecht?

Each lights gets these properties:

  • (unchanged) RGB color
  • (unchanged) energy, tagged with PROP_POWER (for Watts)
  • (new) brightness, tagged with PROP_BRIGHTNESS (for Lumens)
  • (new) a toggle property saying “I’m a Watts light” or “I’m a Brightness light” (for per-light settings as requested by @JuanGea)

Switching the toggle would decide:

  • whether the renderers use energy or brightness when doing the maths for the light
  • which property is displayed in the UI. The other one would be hidden to the user.

This implementation would:

  • use only actual propertied as you suggest
  • would add no connection between the energy and the brightness properties, as you suggested above

It would also involve the units system somewhat, but I’m not sure if it’s in the way you were shooting for. But the units system wouldn’t be doing any maths here, which is something you did request.

So is this what you’re suggesting?

Regards /Johan


This thread seems stalled.

Before any coding goes into this, having a potential reviewer OK a design would be super. Conversely, having the code shot down in review because of design reasons would be an unnecessary cost IMO.

I don’t know which committers / reviewers should be the ones agreeing on a design.

@brecht you commented at first, but if you’re not the right person here, do you have any suggestions for who could represent the committers / reviewers in this conversation? Or is this simply a bad time for having this conversation? If so, when would be a better time?

Regards /Johan


I think regarding Cycles it’s actually @brecht but he may be busy or in vacation, I’m not sure.
But I imagine you will have to take into account Eevee also, and for that it’s @Hypersomniac, and the same thing goes for him, not sure if he will be available right now or if he is on vacation :slight_smile:

But I agree, a design approval before coding should be the proper way to go :slight_smile:


I think that ideally there would be just a single property, and the unit system would convert between Lumens and Watts with a fixed multiplier. That way importers and exporters can continue to work without any changes, and take into account the Lumens settings if they want.

The problem is that the user interface / unit code do not currently support specifying the unit per light, it’s a scene global setting. So we either need to add two properties, or add a way in the user interface code to specify that the property needs to be displayed with a particular unit.

If I was implementing this I would try the latter.

1 Like

Yes, that was what I was thinking.
If it’s possible to convert directly from current watts to proper lumens, the conversion may be made at object level, that way internally the scene would always be in watts, and it’s just a display number, an object property that will have an input in lumens, but internally it’s treated in watts, that could work and may be less problematic in general I think.

1 Like

Assuming that most lights are white or almost white, this would work.

If people tried this on blue lights the light intensities would be off by a factor of 5x, and about 2x for red lights.

Is off by a factor of 5x acceptable for blue lights?

IMO we should then go for making this a per-scene setting initially. If it turns out that having it per-light is important, then that can be dealt with later.

Artistically speaking… I don’t think so, if we may rely on Lumens it’s because we could be able to input a value that mimics a real life lamp value, something that we cannot do right now, so if there is such deviation it makes no sense, we are in the same situation we are right now with Watts.

If this is the only solution could be good enough if it correctly converts from Watts to Lumens when you change the setting.

But this is just my opinion from a user stand point :slight_smile:

1 Like

It would be a rather large bummer. Would it be possible to have the unit conversion be fixed and then have a per-light option to account for color? The use case is this: One lamp is emulating a color changing rgb bulb (like a Phillips Hue) set to blue and another lamp is emulating a very low color temp tungsten bulb. The first should not take the color into account if using the value listed by the manufacturer but the second one should, because that number refers to the maximum possible lumens output. Without a per-light option, the difference in resulting energy output would be wrong in any such situation.

1 Like

My guess would be that color changing RGB bulbs actually contain three light sources; one red, one green and one blue.

Given proper Lumens support in Blender, and a need to accurately model such a lamp I would:

  • Pick my physical RGB lamp apart
  • Figure out the specs of the three internal light sources
  • Add three different lamps to Blender, one for each internal light source

For inaccurately modelling that thing, I think winging it until it looks good would be just fine, just like I’m guessing most people would do today.

Personally I think having something in Blender called “Lumens”, but which isn’t really Lumens, or only sometimes if you flip the right switch, would be confusing.

But that’s why we’re having this conversation :).

1 Like