FIguring out how to scale the illuminant energy

The reflectance basis and illuminant need to be scaled correctly together.  This might be a general issue (bug) in using the natural reflectance data.  I may have to go back and fix this somewhere.

displays/displayReflectance.m

@@ -30,18 +30,18 @@
  
 %}
 
-%%
+%%  Read in the natural surface reflectance basis
+
 wave = 400:1:700;
 basis = ieReadSpectra('reflectanceBasis.mat',wave);
 basis(:,1) = -1*basis(:,1);
 % plotReflectance(wave,basis(:,1:3));
 
-%% Load the standard CIE daylight illuminant
+%% Load the blackbody radiator at the specified color temperature
 
-% Loaded as energy.
 illEnergy = blackbody(wave,ctemp,'energy');
 
-%% Radiance basis - 3D
+%% The spectral radiance basis for this illuminant
 %
 % The radiance basis must be  described by these three columns if the light
 % is D65 and the surfaces are within the space spanned by the first three
@@ -50,29 +50,42 @@
 radianceBasis = diag(illEnergy(:,1))*basis(:,1:3);
 % plotRadiance(wave,radianceBasis);
 
+%% To preserve the reflectance scale, we need to scale the illuminant.
+%
+% In principle, a reflectance of 1's should be represented by a radiance of
+% illEnergy.  How do we set the scale?
+%
+%  reflectanceBasis = diag(1./(illEnergy*(100/peakL))*rgbPrimaries*100/peakL
+%
+illEnergy = illEnergy*(100/peakL);
+
+
 %% Find the sRGB XYZ values
 
-% Suppose a point in the rgb file we read is represented by the row vector,
+% Suppose a point in the rgb file is represented by the row vector,
 %
 %    p = [R,G,B]. 
 %
 % The matrix lrgb2xyz transforms the row vector, XYZ = p*lrgb2xyz;
 %
 lrgb2xyz = colorTransformMatrix('lrgb2xyz');
 
-% Transposing the matrix gives us the XYZ values of the XYZ values of the
-% sRGB display in the columns.
+% Transposing the matrix gives us the XYZ values of the sRGB display in the
+% columns.
 %
 lXYZinCols = lrgb2xyz';
 
-%% Find a 3x3 T such that the reflectance display and sRGB primaries match
+%% Find a 3x3 T to match the reflectance display and sRGB primaries
 %
 % The match is with respect to XYZ.  The matrix lXYZinCols has the sRGB
 % primaries in the columns.  So we want T that satisfies
 %
 %    lXYZinCols = XYZ'*radianceBasis*T
 %
-%  We will assign the reflectance-display primaries to be radianceBasis*T
+%  By making the reflectance-display primaries to be radianceBasis*T, the
+%  lRGB (linearized sRGB) values produce a radiance that matches the XYZ
+%  values in the new display that they would have produced in the sRGB
+%  display.
 %
 
 % Read in the XYZ functions with respect to energy.
@@ -89,21 +102,13 @@
 theDisplay = displaySet(theDisplay,'spd',rgbPrimaries);
 
 %% Set the display to a luminance of 100
-
-peakL = displayGet(theDisplay,'peak luminance');
-
 % Scale the primaries and the illuminant.  Before this scaling,
 %
 %   reflectanceBasis = diag(1./illEnergy)*rgbPrimaries
 %
+peakL = displayGet(theDisplay,'peak luminance');
 theDisplay = displaySet(theDisplay,'spd',rgbPrimaries*(100/peakL));
 
-% To preserve the reflectance
-%
-%  reflectanceBasis = diag(1./(illEnergy*(100/peakL))*rgbPrimaries*100/peakL
-%
-illEnergy = illEnergy*(100/peakL);
-
 %% Set the gamma of the display
 
 % When we read in the image we will be applying the gamma correction for

scripts/display/s_displayReflectanceCtemp.m

@@ -2,6 +2,9 @@
 %
 % DEBUG:  The scale factor on the illuminant is not quite right
 % the reflectances 
+
+%% Make an sRGB image
+
 scene = sceneCreate('macbeth tungsten');
 oi = oiCreate; oi = oiCompute(oi,scene);
 sensor = sensorCreate; 
@@ -12,6 +15,8 @@
 
 rgb = ipGet(ip,'srgb');
 
+%% Analyze the sRGB image with the new tools
+
 ctemp = srgb2colortemp(rgb);
 [d,spd,illE] = displayReflectance(ctemp);
 

scripts/display/s_displaySurfaceReflectance.m

@@ -73,14 +73,17 @@
 %
 lXYZinCols = lrgb2xyz';
 
-%% Find a 3x3 T such that the reflectance display and sRGB primaries match
+%% Find a 3x3 T to match the reflectance display and sRGB primaries
 %
 % The match is with respect to XYZ.  The matrix lXYZinCols has the sRGB
-% primaries in the columns.  So we want T that satisfies
+% primaries in its columns.  We want T that satisfies
 %
 %    lXYZinCols = XYZ'*radianceBasis*T
 %
-%  We will assign the reflectance-display primaries to be radianceBasis*T
+%  By making the reflectance-display primaries to be radianceBasis*T, the
+%  lRGB (linearized sRGB) values produce a radiance that matches the XYZ
+%  values in the new display that they would have produced in the sRGB
+%  display.
 %
 
 % Read in the XYZ functions with respect to energy.