Improve quality, fix errors, update comments, update man pages, add new man pagesHEAD1.1master

Signed-off-by: Mattias Andrée <m@maandree.se>

10 files changed, 230 insertions, 103 deletions

diff --git a/Makefile b/Makefile
index ce4ce74..c7663fe 100644
--- a/Makefile
+++ b/Makefile
@@ -27,6 +27,8 @@ MAN7 = libred.7
 MAN3 =\
 	libred_get_colour.3\
 	libred_get_colour_xy.3\
+	libred_get_temperature.3\
+	libred_get_temperature_xy.3\
 	libred_solar_elevation.3
 
 
@@ -36,7 +38,9 @@ blackbody.o: 10deg-xy.i 10deg-rgb.i libred.h
 generate-table.o: blackbody.c 10deg-xy.i libred.h
 
 10deg-xy.i: 10deg
-	sed -e 's/^/{/' -e 's/ /, /' -e 's/$$/},/' < 10deg | sed '$$s/,$$//' > $@
+	sed '56s/^.*$$/0.312727 0.329023/' < 10deg |\
+		sed -e 's/^/{/' -e 's/ /, /' -e 's/$$/},/' | \
+		sed '$$s/,$$//' > $@
 
 10deg-rgb.i: generate-table 10deg
 	./generate-table > $@
diff --git a/blackbody.c b/blackbody.c
index 78608c1..1abf133 100644
--- a/blackbody.c
+++ b/blackbody.c
@@ -11,6 +11,7 @@
 # include <stddef.h>
 
 
+
 /**
  * Colour temperatures in CIE xy (xyY without Y)
  */
@@ -26,6 +27,7 @@ static struct rgb {double r, g, b;} rgb_table[] = {
 };
 
 
+
 #endif
 /**
  * Convert from CIE xyY to [0, 1] sRGB
@@ -41,9 +43,16 @@ static struct rgb {double r, g, b;} rgb_table[] = {
 static void
 ciexyy_to_srgb(double x, double y, double Y, double *r, double *g, double *b)
 {
-#define SRGB(C)  (((C) <= 0.0031308) ? (12.92 * (C)) : ((1.0 + 0.055) * pow((C), 1.0 / 2.4) - 0.055))
+#define LINEAR_TO_SRGB(C)\
+	do {\
+		double sign = (C) < 0 ? -1 : 1;\
+		(C) *= sign;\
+		(C) = (((C) <= 0.0031306684425217108) ? (12.92 * (C)) : (1.055 * pow((C), 1.0 / 2.4) - 0.055));\
+		(C) *= sign;\
+	} while (0)
+
 	double X, Z, max;
-  
+
 #if __GNUC__
 # pragma GCC diagnostic push
 # pragma GCC diagnostic ignored "-Wfloat-equal"
@@ -55,13 +64,16 @@ ciexyy_to_srgb(double x, double y, double Y, double *r, double *g, double *b)
 # pragma GCC diagnostic pop
 #endif
   
-	/* Convert CIE XYZ to [0, 1] linear RGB (ciexyz_to_linear) */
-	*r = ( 3.240450 * X) + (-1.537140 * Y) + (-0.4985320 * Z);
-	*g = (-0.969266 * X) + ( 1.876010 * Y) + ( 0.0415561 * Z);
-	*b = (0.0556434 * X) + (-0.204026 * Y) + ( 1.0572300 * Z);
-  
-	/* Convert [0, 1] linear RGB to [0, 1] sRGB */
-	SRGB(*r), SRGB(*g), SRGB(*b);
+	/* Convert CIE XYZ to [0, 1] linear RGB */
+	*r = ( 3.24044625464773750067593027779366821050643920898438 * X)
+	   + (-1.53713476182008057513428411766653880476951599121094 * Y)
+	   + (-0.49853019302272871815517873983480967581272125244141 * Z);
+	*g = (-0.96926660624467975146956177923129871487617492675781 * X)
+	   + ( 1.87601195978837020916785149893257766962051391601562 * Y)
+	   + ( 0.04155604221443006535130493261931405868381261825562 * Z);
+	*b = ( 0.05564350356435283223577314970498264301568269729614 * X)
+	   + (-0.20402617973596023914772956686647376045584678649902 * Y)
+	   + ( 1.05722656772270329206264705135254189372062683105469 * Z);
 
 	/* Adjust colours for use */
 	max = fmax(fmax(fabs(*r), fabs(*g)), fabs(*b));
@@ -76,35 +88,66 @@ ciexyy_to_srgb(double x, double y, double Y, double *r, double *g, double *b)
 	*r = *r > 0.0 ? *r : 0.0;
 	*g = *g > 0.0 ? *g : 0.0;
 	*b = *b > 0.0 ? *b : 0.0;
+
+	/* Convert [0, 1] linear RGB to [0, 1] sRGB */
+	LINEAR_TO_SRGB(*r);
+	LINEAR_TO_SRGB(*g);
+	LINEAR_TO_SRGB(*b);
 }
 #ifndef LIBRED_COMPILING_PARSER
 
+
 /**
- * Perform linear interpolation (considered very good)
- * between the CIE xy values for two colour temperatures
- * and convert the result to sRGB. The two colours should
- * be the closest below the desired colour temperature,
- * and the closest above the desired colour temperature
+ * Convert from [0, 1] sRGB to CIE xyY
  * 
- * @param  x1    The 'x' component for the low colour
- * @param  y1    The 'y' component for the low colour
- * @param  x2    The 'x' component for the high colour
- * @param  y2    The 'y' component for the high colour
- * @param  temp  The desired colour temperature
- * @param  r     Output parameter for the “red” value
- * @param  g     Output parameter for the green value
- * @param  b     Output parameter for the blue value
+ * @param  r  The “red” value
+ *            (Seriously, sRGB red is orange, just look at it fullscreen)
+ * @param  g  The green value
+ * @param  b  The blue value
+ * @param  x  Output parameter for The 'x' component
+ * @param  y  Output parameter for The 'y' component
+ * @param  Y  Output parameter for The 'Y' component
  */
 static void
-interpolate(double x1, double y1, double x2, double y2, double temp, double *r, double *g, double *b)
+srgb_to_ciexyy(double r, double g, double b, double *x, double *y, double *Y)
 {
-	double weight = fmod(temp - (LIBRED_LOWEST_TEMPERATURE % LIBRED_DELTA_TEMPERATURE),
-	                     (double)LIBRED_DELTA_TEMPERATURE) / (double)LIBRED_DELTA_TEMPERATURE;
-	double x = x1 * (1 - weight) + x2 * weight;
-	double y = y1 * (1 - weight) + y2 * weight;
-	ciexyy_to_srgb(x, y, 1.0, r, g, b);
+#define SRGB_TO_LINEAR(C)\
+	do {\
+		double sign = (C) < 0 ? -1 : 1;\
+		(C) *= sign;\
+		(C) = (((C) <= 0.0031306684425217108 * 12.92) ? ((C) / 12.92) : pow(((C) + 0.055) / 1.055, 2.4));\
+		(C) *= sign;\
+	} while (0)
+
+	/* Convert [0, 1] sRGB to [0, 1] linear RGB */
+	double s, z;
+
+	SRGB_TO_LINEAR(r);
+	SRGB_TO_LINEAR(g);
+	SRGB_TO_LINEAR(b);
+
+	/* Convert [0, 1] linear RGB to CIE XYZ */
+	*x = 0.41245744558236757670854899515688885003328323364258 * r
+	   + 0.35757586524551587814357844763435423374176025390625 * g
+	   + 0.18043724782639966597308500695362454280257225036621 * b;
+	*y = 0.21267337037840827740353688568575307726860046386719 * r
+	   + 0.71515173049103175628715689526870846748352050781250 * g
+	   + 0.07217489913055986916479156434434116818010807037354 * b;
+	z  = 0.01933394276167346020889326041469757910817861557007 * r
+	   + 0.11919195508183859366635459764438564889132976531982 * g
+	   + 0.95030283855237174250873977143783122301101684570312 * b;
+	*Y = z;
+
+	/* Convert CIE XYZ to CIE xyY */
+	*Y = *y;
+	s = *x + *y + z;
+	*x /= s;
+	*y /= s;
+	if (!isfinite(*x) || !isfinite(*y))
+		*x = *y = 0;
 }
 
+
 /**
  * Perform linear interpolation (considered very good)
  * between the CIE xy values for two colour temperatures.
@@ -121,7 +164,7 @@ interpolate(double x1, double y1, double x2, double y2, double temp, double *r,
  * @param  y     Output parameter for the CIE y value
  */
 static void
-interpolate_xy(double x1, double y1, double x2, double y2, double temp, double *x, double *y)
+interpolate(double x1, double y1, double x2, double y2, double temp, double *x, double *y)
 {
 	double weight = fmod(temp - (LIBRED_LOWEST_TEMPERATURE % LIBRED_DELTA_TEMPERATURE),
 	                     (double)LIBRED_DELTA_TEMPERATURE) / (double)LIBRED_DELTA_TEMPERATURE;
@@ -129,8 +172,9 @@ interpolate_xy(double x1, double y1, double x2, double y2, double temp, double *
 	*y = y1 * (1 - weight) + y2 * weight;
 }
 
+
 int
-libred_get_colour(long int temp, double *r, double *g, double *b)
+libred_get_colour_xy(long int temp, double *x, double *y)
 {
 	double x1, y1, x2, y2;
 	size_t i;
@@ -152,18 +196,18 @@ libred_get_colour(long int temp, double *r, double *g, double *b)
 		y1 = xy_table[i].y;
 		x2 = xy_table[i + 1].x;
 		y2 = xy_table[i + 1].y;
-		interpolate(x1, y1, x2, y2, (double)temp, r, g, b);
+		interpolate(x1, y1, x2, y2, (double)temp, x, y);
 	} else {
-		*r = rgb_table[i].r;
-		*g = rgb_table[i].g;
-		*b = rgb_table[i].b;
+		*x = xy_table[i].x;
+		*y = xy_table[i].y;
 	}
 
 	return 0;
 }
 
+
 int
-libred_get_colour_xy(long int temp, double *x, double *y) /* TODO test */
+libred_get_colour(long int temp, double *r, double *g, double *b)
 {
 	double x1, y1, x2, y2;
 	size_t i;
@@ -181,25 +225,29 @@ libred_get_colour_xy(long int temp, double *x, double *y) /* TODO test */
 
 	i = (size_t)(tmp / LIBRED_DELTA_TEMPERATURE);
 	if (tmp % LIBRED_DELTA_TEMPERATURE) {
+		double x, y;
 		x1 = xy_table[i].x;
 		y1 = xy_table[i].y;
 		x2 = xy_table[i + 1].x;
 		y2 = xy_table[i + 1].y;
-		interpolate_xy(x1, y1, x2, y2, (double)temp, x, y);
+		interpolate(x1, y1, x2, y2, (double)temp, &x, &y);
+		ciexyy_to_srgb(x, y, 1, r, g, b);
 	} else {
-		*x = xy_table[i].x;
-		*y = xy_table[i].y;
+		*r = rgb_table[i].r;
+		*g = rgb_table[i].g;
+		*b = rgb_table[i].b;
 	}
 
 	return 0;
 }
 
+
 double
-libred_get_temperature_xy(double x, double y, double *x_error, double *y_error) /* TODO man, test */
+libred_get_temperature_xy(double x, double y, double *x_error, double *y_error)
 {
-	size_t i, j;
+	size_t i = 0, j;
 	double x1, y1, x2, y2, dx, dy, xd, yd, t, d2;
-	double best_temp = 0, best_d2 = INFINITY;
+	double best_temp = -1, best_d2 = INFINITY;
 
 	if (!x_error)
 		x_error = &dx;
@@ -232,55 +280,23 @@ libred_get_temperature_xy(double x, double y, double *x_error, double *y_error)
 			t *= (double)(j - i);
 			best_temp = (double)i + t;
 		}
+
+		i = j;
 	}
 
 	return best_temp * LIBRED_DELTA_TEMPERATURE + LIBRED_LOWEST_TEMPERATURE;
 }
 
-/**
- * Convert from [0, 1] sRGB to CIE xyY
- * 
- * @param  r  The “red” value
- *            (Seriously, sRGB red is orange, just look at it fullscreen)
- * @param  g  The green value
- * @param  b  The blue value
- * @param  x  Output parameter for The 'x' component
- * @param  y  Output parameter for The 'y' component
- * @param  Y  Output parameter for The 'Y' component
- */
-static void
-srgb_to_ciexyy(double r, double g, double b, double *x, double *y, double *Y)
-{
-	double s, z;
-
-	r *= s = r < 0 ? -1 : 1;
-	r = s * (r <= 0.0031306684425217108 * 12.92 ? r * 12.92 : pow((r + 0.055) / 1.055, 2.4));
-	g *= s = g < 0 ? -1 : 1;
-	g = s * (g <= 0.0031306684425217108 * 12.92 ? g * 12.92 : pow((g + 0.055) / 1.055, 2.4));
-	b *= s = b < 0 ? -1 : 1;
-	b = s * (g <= 0.0031306684425217108 * 12.92 ? b * 12.92 : pow((b + 0.055) / 1.055, 2.4));
-
-	*x = (0.41245744558236758 * r) + (0.35757586524551588 * g) + (0.18043724782639967 * b);
-	*y = (0.21267337037840828 * r) + (0.71515173049103176 * g) + (0.07217489913055987 * b);
-	z  = (0.01933394276167346 * r) + (0.11919195508183859 * g) + (0.95030283855237174 * b);
-
-	*Y = *y;
-	s = *x + *y + z;
-	*x /= s;
-	*y /= s;
-	if (!isfinite(*x) || !isfinite(*y))
-		*x = *y = 0;
-}
 
 double
-libred_get_temperature(double r, double g, double b, double *y, /* TODO man, test */
+libred_get_temperature(double r, double g, double b, double *y,
                        double *r_error, double *g_error, double *b_error)
 {
 	double tx, ty, luma, x_error, y_error, ret;
 
 	srgb_to_ciexyy(r, g, b, &tx, &ty, &luma);
 	ret = libred_get_temperature_xy(tx, ty, &x_error, &y_error);
-	ciexyy_to_srgb(x_error, y_error, luma, &r, &g, &b);
+	ciexyy_to_srgb(x_error, y_error, 1, &r, &g, &b);
 
 	if (y)
 		*y = luma;
diff --git a/generate-table.c b/generate-table.c
index c5c0ca3..a8cde38 100644
--- a/generate-table.c
+++ b/generate-table.c
@@ -18,7 +18,7 @@ static struct xy {double x, y;} xy_table[] = {
 #include "10deg-xy.i"
 };
 
-/* define ciexyy_to_srgb() and adjust_luma() */
+/* define ciexyy_to_srgb() */
 #define LIBRED_COMPILING_PARSER
 #include "blackbody.c"
 
diff --git a/libred.7 b/libred.7
index f7d3141..f81445b 100644
--- a/libred.7
+++ b/libred.7
@@ -7,6 +7,9 @@ is a C library for calculating the Sun's apparent elevation
 and colours temperatures.
 .SH SEE ALSO
 .BR libred.h (0),
+.BR libred_get_colour (3),
+.BR libred_get_temperature (3),
+.BR libred_solar_elevation (3),
 .BR solar-python (7),
 .BR radharc (1),
 .BR redshift (1),
diff --git a/libred.h b/libred.h
index 29a00cd..21920ff 100644
--- a/libred.h
+++ b/libred.h
@@ -250,21 +250,6 @@ int libred_get_colour(long int, double *, double *, double *);
 int libred_get_colour_xy(long int, double *, double *);
 
 /**
- * Calculate the colour temperature from its CIE xy values
- * 
- * @param   x        The CIE x value for the colour temperature
- * @param   y        The CIE y value for the colour temperature
- * @param   x_error  Output parameter for the absolute error in
- *                   the CIE x value of the returned colour
- *                   temperature; may be `NULL`
- * @param   y_error  Output parameter for the absolute error in
- *                   the CIE y value of the returned colour
- *                   temperature; may be `NULL`
- * @return           The closest matching colour temperature
- */
-double libred_get_temperature_xy(double, double, double *, double *);
-
-/**
  * Calculate the colour temperature from its [0, 1] sRGB values
  * 
  * @param   r        The sRGB “red” value for the colour temperature
@@ -288,6 +273,21 @@ double libred_get_temperature_xy(double, double, double *, double *);
  */
 double libred_get_temperature(double, double, double, double *, double *, double *, double *);
 
+/**
+ * Calculate the colour temperature from its CIE xy values
+ * 
+ * @param   x        The CIE x value for the colour temperature
+ * @param   y        The CIE y value for the colour temperature
+ * @param   x_error  Output parameter for the absolute error in
+ *                   the CIE x value of the returned colour
+ *                   temperature; may be `NULL`
+ * @param   y_error  Output parameter for the absolute error in
+ *                   the CIE y value of the returned colour
+ *                   temperature; may be `NULL`
+ * @return           The closest matching colour temperature
+ */
+double libred_get_temperature_xy(double, double, double *, double *);
+
 
 
 #endif
diff --git a/libred.h.0 b/libred.h.0
index 3dd97b8..c4f8a93 100644
--- a/libred.h.0
+++ b/libred.h.0
@@ -8,7 +8,8 @@ libred.h \- Solar elevation and blackbody colour calculation
 .fi
 .PP
 Link with
-.IR -lred .
+.I -lred
+.IR -lm .
 .SH DESCRIPTION
 The
 .I <libred.h>
@@ -116,11 +117,21 @@ It is night only if the Sun's apparent elevation is negative.
 This header defines the following functions:
 .TP
 *
-.BR libred_solar_elevation (3)
+.BR libred_get_colour (3)
 .TP
 *
-.BR libred_get_colour (3)
+.BR libred_get_colour_xy (3)
+.TP
+*
+.BR libred_get_temperature (3)
+.TP
+*
+.BR libred_get_temperature (3)
+.TP
+*
+.BR libred_solar_elevation (3)
 .SH SEE ALSO
 .BR libred (7),
-.BR libred_solar_elevation (3),
-.BR libred_get_colour (3)
+.BR libred_get_colour (3),
+.BR libred_get_temperature (3),
+.BR libred_solar_elevation (3)
diff --git a/libred_get_colour.3 b/libred_get_colour.3
index 61a62ff..d6649d2 100644
--- a/libred_get_colour.3
+++ b/libred_get_colour.3
@@ -1,6 +1,6 @@
 .TH LIBRED_GET_COLOUR 3 LIBRED
 .SH NAME
-libred_get_colour \- Calculate a colour temperature
+libred_get_colour \- Calculate the colour of a temperature
 .SH SYNOPSIS
 .nf
 #include <libred.h>
@@ -10,7 +10,8 @@ int \fBlibred_get_colour_xy\fP(long int \fItemp\fP, double *\fIx\fP, double *\fI
 .fi
 .PP
 Link with
-.IR -lred .
+.I -lred
+.IR -lm .
 .SH DESCRIPTION
 .BR libred_get_colour ()
 gets or interpolates the colour temperature for
@@ -100,4 +101,5 @@ is less than
 .SH SEE ALSO
 .BR libred.h (0),
 .BR libred (7),
-.BR libred_get_solar_elevation (3)
+.BR libred_get_temperature (3),
+.BR libred_solar_elevation (3)
diff --git a/libred_get_temperature.3 b/libred_get_temperature.3
new file mode 100644
index 0000000..f5e8883
--- /dev/null
+++ b/libred_get_temperature.3
@@ -0,0 +1,89 @@
+.TH LIBRED_GET_TEMPERATURE 3 LIBRED
+.SH NAME
+libred_get_temperature \- Calculate the temperature of a colour
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+
+double \fBlibred_get_temperature\fP(double \fIr\fP, double \fIg\fP, double \fIb\fP, double *\fIY\fP,
+                              double *\fIr_error\fP, double *\fIg_error\fP, double *\fIb_error\fP);
+double \fBlibred_get_temperature_xy\fP(double \fIx\fP, double \fIy\fP, double *\fIx_error\fP, double *\fIy_error\fP);
+.fi
+.PP
+Link with
+.I -lred
+.IR -lm .
+.SH DESCRIPTION
+The
+.BR libred_get_temperature ()
+function parses
+.RI ( r ,
+.IR g ,
+.IR b )
+as a colour encoded in sRGB with values between 0 and 1
+and with the sRGB transfer function applied. From that
+it calculates the CIE Y (luminosity) of the colour and
+stores it in
+.I *Y
+and then normalises the the colour to have Y = 1 and
+calculates the closest matching colour temperature,
+which is returned.
+.PP
+The calculated temperature may not line perfectly with
+the colour so the difference between the colour of the
+returned temperature and the input colour (after
+normalisation to Y = 1) is returned in sRGB as
+.RI ( *r_error ", " *g_error ", " *b_error ),
+interpreted the same way as
+.IR r ,
+.IR g ,
+and
+.IR b .
+.PP
+The
+.BR libred_get_temperature_xy ()
+function is a variant of the
+.BR libred_get_temperature ()
+function that uses the CIE xy colour space
+(CIE xyY with Y = 1). Unlike sRGB, CIE xy
+does not have a transfer function, so the values
+are linear, and the values also do not have any
+limits and does have a natural interpretation.
+.PP
+Any of
+.IR Y ,
+.IR r_error ,
+.IR g_error ,
+.IR b_error ,
+.IR x_error ,
+and
+.IR y_error
+that is
+.I NULL
+is ignored.
+.SH RETURN VALUE
+The
+.BR libred_get_temperature ()
+and
+.BR libred_get_temperature_xy ()
+functions return the colour temperature in Kelvins.
+.SH ERRORS
+None.
+.SH NOTES
+The sRGB transfer function is applied to
+.IR *r_error ,
+.IR *g_error ,
+and
+.IR *b_error .
+One cannoy simply subtract them from
+.IR r ,
+.IR g ,
+and
+.IR b ,
+without first undoing the transfer function,
+to get the colour or the calculated temperature.
+.SH SEE ALSO
+.BR libred.h (0),
+.BR libred (7),
+.BR libred_get_temperature (3),
+.BR libred_solar_elevation (3)
diff --git a/libred_get_temperature_xy.3 b/libred_get_temperature_xy.3
new file mode 120000
index 0000000..b7a4244
--- /dev/null
+++ b/libred_get_temperature_xy.3
@@ -0,0 +1 @@
+libred_get_temperature.3
\ No newline at end of file
diff --git a/libred_solar_elevation.3 b/libred_solar_elevation.3
index 70587ca..f72f8e5 100644
--- a/libred_solar_elevation.3
+++ b/libred_solar_elevation.3
@@ -9,7 +9,8 @@ int \fBlibred_solar_elevation\fP(double \fIlatitude\fP, double \fIlongitude\fP,
 .fi
 .PP
 Link with
-.IR -lred .
+.I -lred
+.IR -lm .
 .SH DESCRIPTION
 .BR libred_solar_elevation ()
 calculates the Sun's elevation, and stores it, measured in degrees, in