Equation for Lux calculation does not reflect Library

[Rvice]

The calculations in this project (CircuitPython) reference the AdatFruit_TSL2591_Library, but the equations do not match.

https://github.com/adafruit/Adafruit_TSL2591_Library/blob/master/Adafruit_TSL2591.cpp#L220

This project does take into account the max_count for saturation and sensor overflow, but the source project does not.

[tannewt]

What should be changed in the CircuitPython library?

[Rvice]

Yes, but I am not sure which equation is right given the following open issue: adafruit/Adafruit_TSL2591_Library#24

[tannewt]

@caternuson Do you know what the correct equation is?

[caternuson]

@tannewt TLDR - no

It looks like the disagreement between the libraries is a result of this commit:
adafruit/Adafruit_TSL2591_Library@2b3b098
made after the CircuitPython library was written and was a response to this issue:
adafruit/Adafruit_TSL2591_Library#14
which was closed but has ongoing discussion. The additional issue linked above by @Rvice may be related.

I am having trouble finding a definitive lux equation for the TSL2591. The datasheet for the TSL2591 does not have one:
https://ams.com/documents/20143/36005/TSL2591_DS000338_6-00.pdf
Given that the TSL2591 is a high dynamic range variant, it's not clear if the information in the datasheets and application notes which cover the TSL2561 and TSL2581 (both replaced by TSL2571) apply. This particular AN seems to contain the necessary technical details and is even linked to from the TSL2591 product page:
https://ams.com/documents/20143/36005/AmbientLightSensors_AN000170_2-00.pdf
but the verbiage in it says it applies to the TSL2571 only. There is no mention anywhere in it of the TSL2591. Do we consider the link enough evidence that the information applies to the TSL2591?

[tannewt]

I'd be tempted to follow the AN since its linked. Maybe try it out and see?

[caternuson]

Let's ignore the disparity between the libraries for now and try to determine what is the most correct implementation for both.

@Rvice Where did you get your information to come up with the changes you made in #6 ?

[Rvice]

The datasheet table for ATIME Max Count in "Control Register (0x01)" and findings from issue #5 created.

[caternuson]

Thanks. Looks like the same info is contained in the summary table as well. For the TSL2591 there's this:

but for the TSL2561 there's a different behavior:

These values are used to check for digital and analog saturation prior to computing lux. Since the values are different, this check will be done differently between the TSL2591 and TSL2561. I believe this check is being done correctly in this library.

Now for lux...

Back to my question from above. I can't figure out where this came from:
https://github.com/adafruit/Adafruit_TSL2591_Library/blob/master/Adafruit_TSL2591.cpp#L284
and the equation currently being used:
https://github.com/adafruit/Adafruit_TSL2591_Library/blob/master/Adafruit_TSL2591.cpp#L290
is still being debated:
adafruit/Adafruit_TSL2591_Library#14 (comment)
Let me investigate the behavior of the various equations. Will report back here.

[caternuson]

Well, they (TSL2561 vs. TSL2591) behave differently. So anecdotally, I think the TSL2591 is different. I sent a request to AMS (they bought TAOS) to ask them for what they consider the proper lux equation for the TSL2591. This was via a web form accessed from here:
https://ams.com/tsl25911
Will give that a few days before continuing with the available documentation.

Has anyone taken an actual Lux meter and compared the values? I've been reading a little bit on these formulas and haven't seen anyone mention it.

[Rvice]

We've done a little with a lux meter and scale based on the difference of the reading. Also, clipping to 0 if the lux value is negative.

[microbuilder]

There is unfortunately a bit of complexity in deriving lux in the case of the TSL2591, partly because the required information isn't terribly clear in the datasheet.

Trying to do some reading on this (not being an expert in the domain myself!), there are some important points to consider talking about lux:

• First, lux is not a 'scientific' value based on a concrete physical phenomenon, it's an estimation based on a model of human vision and is calculated using the CIE Photopic Luminosity Function (part of CIE 1931). There is an improved CIE 1981 version (50 years later!) that should be used since it has a better response curve for low light, but most people still use the older CIE1931 curve.
• Lux is a photometric measurement, based on human vision and a model derived from a limited number of human test samples.
• Sensors can only accurately be used to measure radiometric units, which involves photons and quantifiable physics.
• There are, however, equivalent units for both photometric and radiometric values. In the case of lux they are:
  • Photometric unit: Illuminance (lux) = lumens/m^2
  • Equivalent radiometric unit: Irradiance (W/m^2)

The goal then, to derive lux, is to convert from irradiance (a radiometric measurement) to illuminance (a photometric value based on an estimation of human vision), which is done using the CIE 1931 photopic curve.

NOTE: To confuse matters further there are actually two luminosity functions defined by the CIE, the photopic curve for normal light levels, and the scotopic curve for low light levels, but we'll only look at the photopic curve for simplicity sake.

You can see the CIE 1931 photopic curve here, image taken from the wikipedia page for Luminous Function:

Normal human vision can detect wavelengths from 380-780nm, but our sense of 'brightness' is very heavily concentrated in the green to yellow range in the middle. It comes down to the design our our eyes which are made of of codes and rods.

Our eyes have three 'cones' that roughly are sensitive to red, green and blue wavelengths. The red cones (higher nm values) are most sensitive to light and are more abundant (64% red cones, 32% green cones and only 2% blue cones), but 'brightness' is more associated with the green cones than red and blue. (Bonus fact: Now you know why there are two green photodiodes to every 1 red and blue in bayer pattern sensors. 🙂).

This is why the photopic luminous curve that forms the basis of lux (the black curve above) is heavily biased by the green to yellow wavelengths (the peak in the middle).

Anyway ... enough botched anatomy I'm surely mischaracterizing. :P The problem is taking radiometric values that we can accurately measure and converting them to the equivalent photometric units based on this estimation of human vision.

The TSL2591 datasheet lists irradiance, the radiometric response, at two wavelengths:

At 4000K (what they are calling White light, though the idea of 'White' light is highly complex and a colorimetry tutorial in itself), with ATIME=100ms and GAIN=MAX (~9876x):

• 1uW/cm^2 of irradiance would give you a value of 6024 on CH0 and 1003 on CH1

At 850nm, which is OUTSIDE HUMAN VISION and in the non-visible infrared range, we would get:

• 1uW/cm^2 = 5338 on CH0 and 3474 on CH1

This makes sense since CH1 is more concentrated towards the IR range, as shown below:

In order to calculate lux, you will need to find a way to map the spectral responsivity of the sensor's photodiode(s) to the photopic curve mentioned earlier.

Interesting sidenote: An RGB sensor is actually more capable of delivering accurate 'lux' values in this situation, since it has three separate photodiodes and values to use when mapping radiometric sensor output to the photometric luminous curve!

While accurate 'lux' values don't 'really' exist since it's a somewhat arbitrary 'estimation' to begin with, to get the closest match we can to the photopic curve, it helps to know the spectral density of your light source. As the two datasheet values show, infrared heavy light will give different output than light more concentrated in the visual range, but both may have a very strong radiometric response.

Converting Radiance (Radiometric) to Irradiance (Photometric)

To try to make something useful out of this giant response, we can take the 4000K white LED light as a starting point, and calculate counts per uW/cm^2 based on the following values:

• 6024 on CH0 = 1uW/cm^2 = 0.000166002656 uW/cm^2 per lsb (at 100mS and max gain!)

It seems to me the best we can do to convert this to an equivalent photometric unit (lux) is to correlate the peak responsivity of the sensor, which looks to be ~650nm in the normalised spectral responsivity in the DS with the same position on the photopic curve.

Here is an overlay of the two curves:

I don't have an instant answer on the coefficients to map these two values, and it depends largely on the spectral composition of the light source you are measuring, but I think this at least explains all the science behind lux and how to calculate it since AMS apparently doesn't want to make life easy for us. :P

I'll have to think about this some more and follow up, but hopefully this gets the ball rolling towards better lux values, and establishes a solid 'scientific' bases for future calculations.

to be continued ...

PS: I'm not an expert in this domain, so please feel free to correct me on any mischaracterisations above if you're more knowledgable on the subject matter!