Minor bugfixes, improved documentation

Author: castarco

ColorSharp/src/ColorSpaces/ColorStrategy.cs

@@ -40,17 +40,45 @@ namespace ColorSpaces
 		[Flags]
 		public enum ColorStrategy
 		{
+			/// <summary>If the color can't be represented in the new color space, an exception will be thrown.</summary>
 			NoForce           = 0,
+
+			/// <summary>
+			/// "Truncates" component values in the new color space if they're lower than the new color space's lower boundaries.
+			/// </summary>
 			ForceLowTruncate  = 2,
+
+			/// <summary>
+			/// "Stretches" component values in the new color space if they're lower than the new color space's lower boundaries.
+			/// </summary>
 			ForceLowStretch   = 4,
+
+			/// <summary>
+			/// "Truncates" component values in the new color space if they're lower than the new color space's upper boundaries.
+			/// </summary>
 			ForceHighTruncate = 8,
+
+			/// <summary>
+			/// "Stretches" component values in the new color space if they're lower than the new color space's upper boundaries.
+			/// </summary>
 			ForceHighStretch  = 16,
+
+			/// <summary>Combination of ForceLowStretch and ForceLowTruncate</summary>
 			ForceLow          = ForceLowStretch | ForceLowTruncate,
+
+			/// <summary>Combination of ForceHighStretch and ForceHighTruncate</summary>
 			ForceHigh         = ForceHighStretch | ForceHighTruncate,
+
+			/// <summary>Combination of ForceLowTruncate and ForceHighTruncate</summary>
 			ForceTruncate     = ForceLowTruncate | ForceHighTruncate,
+
+			/// <summary>Combination of ForceLowStretch and ForceHighStretch</summary>
 			ForceStretch      = ForceLowStretch | ForceHighStretch,
+
+			/// <summary>Combination of ForceLow and ForceHigh</summary>
 			Force             = ForceLow | ForceHigh,
 
+			/// <summary>NoForce</summary>
 			Default = NoForce
 		}
 	}

ColorSharp/src/LightSpectrums/AInterpolatedLightSpectrum.cs

@@ -28,7 +28,6 @@
 
 
 using Litipk.ColorSharp.ColorSpaces;
-using Litipk.ColorSharp.MatchingFunctions;
 using Litipk.ColorSharp.InternalUtils;
 
 
@@ -41,10 +40,16 @@ namespace LightSpectrums
 		 */
 		public abstract class AInterpolatedLightSpectrum : ALightSpectrum, IRealInterpolatedFunctionWithFiniteSupport
 		{
+			/**
+			 * <inheritdoc />
+			 */
 			protected AInterpolatedLightSpectrum(AConvertibleColor dataSource=null) : base(dataSource) { }
 
+			/**
+			 * <summary>Gives us the number of data points used to construct the spectrum object.</summary>
+			 */
 			public abstract int GetNumberOfDataPoints();
 		}
 	}
 }
-
+	

ColorSharp/src/LightSpectrums/ALightSpectrum.cs

@@ -48,8 +48,6 @@ protected ALightSpectrum(AConvertibleColor dataSource=null) : base(dataSource) {
 
 			#region abstract methods
 
-			#region IRealFunctionWithFiniteSupport methods
-
 			/**
 			 * <inheritdoc />
 			 */
@@ -72,16 +70,6 @@ protected ALightSpectrum(AConvertibleColor dataSource=null) : base(dataSource) {
 
 			#endregion
 
-			/**
-			 * <summary>
-			 * Supposing the light spectrum we have is a discrete sample, this gives us the next data point.
-			 * If the method returns -1.0 , then we suppose we have an "analytic" spectrum, so we don't have samples.
-			 * </summary>
-			 */
-			//public abstract double GetNextAmplitudeSample (double waveLength);
-
-			#endregion
-
 
 			#region AConvertibleColor methods
 
@@ -94,6 +82,10 @@ public override CIEXYZ ToCIEXYZ (ColorStrategy strategy=ColorStrategy.Default)
 				return ToCIEXYZ (SpectrumStrategy.Default);
 			}
 
+			/**
+			 * <see cref="ToCIEXYZ(ColorStrategy)"/>
+			 * <param name="strategy">Strategy used to obtain the tristimulous values</param>
+			 */
 			public CIEXYZ ToCIEXYZ (SpectrumStrategy strategy=SpectrumStrategy.Default)
 			{
 				AMatchingFunction[] MFs;

ColorSharp/src/LightSpectrums/BlackBodySpectrum.cs

@@ -34,76 +34,80 @@ namespace Litipk.ColorSharp
 {
 	namespace LightSpectrums
 	{
+		/**
+		 * <summary>Class to represent black body spectrums at a given temperature.</summary>
+		 */
 		public sealed class BlackBodySpectrum : ALightSpectrum
 		{
 			#region properties
 
+			/**
+			 *
+			 */
 			public readonly double CCT;
 
-			public readonly double MinWaveLength;
-			public readonly double MaxWaveLength;
-
 			#endregion
 
 			#region constructors
 
-			public BlackBodySpectrum (double cct) : this (cct, 380.0, 780.0)
-			{
-				// Nothing to do here
-			}
-
-			public BlackBodySpectrum (double cct, double minWaveLength, double maxWaveLength)
+			/**
+			 * <param name="cct">Black body's temperature (in Kelvin degrees).</param>
+			 */
+			public BlackBodySpectrum (double cct)
 			{
-				if (minWaveLength <= 0.0) {
-					throw new ArgumentOutOfRangeException ("minWaveLength", "minWaveLength must be greater than 0");
-				}
-
-				if (maxWaveLength <= minWaveLength) {
-					throw new ArgumentException("maxWaveLength must be greater than minWaveLength", "maxWaveLength");
-				}
-
 				if (cct <= 1) {
 					throw new ArgumentOutOfRangeException ("cct", "cct must be greater than 1");
 				}
 
 				CCT = cct;
-				MinWaveLength = minWaveLength;
-				MaxWaveLength = maxWaveLength;
 			}
 
 			#endregion
 
 			#region inherited methods
 
+			/**
+			 * <inheritdoc />
+			 */
 			public override double EvaluateAt (double waveLength)
 			{
-				// 2*h*c² = 2 * 299792458 * 1.98644568e-25 = 1.1910428661813628e-16
-				return (1.1910428661813628e19 /*1.1910428661813628e-16*/ / (
-					Math.Pow(waveLength/* * 1e-7*/, 5.0) * (Math.Exp(0.014387769576158687 / (waveLength * CCT)) - 1.0)
+				// Conversion from nanometers to meters
+				waveLength *= 1e-9;
+
+				// Applying Plank's Law : https://en.wikipedia.org/wiki/Planck's_law
+				return (1.1910428661813628e-16 * Math.Pow(waveLength, -5.0) / (
+					Math.Exp(0.014387769576158687 / (waveLength * CCT)) - 1.0
 				));
 			}
 
+			/**
+			 * <inheritdoc />
+			 */
 			public override double GetMaxValueOnSupport ()
 			{
-				double result = Double.NegativeInfinity;
-
-				for (int i = 0; i + MinWaveLength < MaxWaveLength; i++) {
-					result = Math.Max (EvaluateAt (MinWaveLength + i), result);
-				}
-
-				return result;
+				// https://en.wikipedia.org/wiki/Wien's_displacement_law
+				return EvaluateAt (2.8977721e6/CCT);
 			}
 
+			/**
+			 * <inheritdoc />
+			 */
 			public override double GetSupportMinValue ()
 			{
-				return MinWaveLength;
+				return 1e-6;
 			}
 
+			/**
+			 * <inheritdoc />
+			 */
 			public override double GetSupportMaxValue ()
 			{
-				return MaxWaveLength;
+				return double.PositiveInfinity;
 			}
 
+			/**
+			 * <inheritdoc />
+			 */
 			public override bool IsInsideColorSpace (bool highPrecision = false)
 			{
 				return true;

ColorSharp/src/LightSpectrums/RegularLightSpectrum.cs

@@ -47,19 +47,38 @@ public sealed class RegularLightSpectrum : AInterpolatedLightSpectrum
 		{
 			#region properties
 
-			// Needed values to interpret the data points
+			/**
+			 * <value>Nanometers between each data point.</value>
+			 */
 			public readonly double NmPerStep;
+
+			/**
+			 * <value>Minimum wavelength for which we have information on this spectrum.</value>
+			 */
 			public readonly double MinWaveLength;
+
+			/**
+			 * <value>Maximum wavelength for which we have information on this spectrum.</value>
+			 */
 			public readonly double MaxWaveLength;
 
-			// Data points
+			/**
+			 * <value>Equidistant data points (usually relative values)</value>
+			 */
 			public readonly ReadOnlyCollection<double> Amplitudes;
 			#endregion
 
 
 			#region constructors
 
-			// Constructor
+			/**
+			 * <param name="minWaveLength">Associated wavelength to the first value of 'amplitudes'.</param>
+			 * <param name="maxWaveLength">Associated wavelength to the last value of 'amplitudes'.</param>
+			 * <param name="amplitudes">Equidistant data points.</param>
+			 * <param name="dataSource">
+			 *     Reference to a AConvertibleColor instance from which this object has been generated.
+			 * </param>
+			 */
 			public RegularLightSpectrum (double minWaveLength, double maxWaveLength, IList<double> amplitudes, AConvertibleColor dataSource=null) : base(dataSource)
 			{
 				MinWaveLength = minWaveLength;
@@ -68,7 +87,14 @@ public RegularLightSpectrum (double minWaveLength, double maxWaveLength, IList<d
 				Amplitudes = new ReadOnlyCollection<double> (amplitudes);
 			}
 
-			// Constructor
+			/**
+			 * <param name="minWaveLength">Associated wavelength to the first value of 'amplitudes'.</param>
+			 * <param name="amplitudes">Equidistant data points.</param>
+			 * <param name="nmPerStep">Nanometers between each data point in 'amplitudes'.</param>
+			 * <param name="dataSource">
+			 *     Reference to a AConvertibleColor instance from which this object has been generated.
+			 * </param>
+			 */
 			public RegularLightSpectrum (double minWaveLength, IList<double> amplitudes, double nmPerStep, AConvertibleColor dataSource=null) : base(dataSource)
 			{
 				NmPerStep = nmPerStep;
@@ -77,12 +103,19 @@ public RegularLightSpectrum (double minWaveLength, IList<double> amplitudes, dou
 				Amplitudes = new ReadOnlyCollection<double> (amplitudes);
 			}
 
-			// Constructor
-			public RegularLightSpectrum (IList<double> amplitudes, double nmPerStep, double maxWavelength, AConvertibleColor dataSource=null) : base(dataSource)
+			/**
+			 * <param name="amplitudes">Equidistant data points.</param>
+			 * <param name="nmPerStep">Nanometers between each data point in 'amplitudes'.</param>
+			 * <param name="maxWaveLength">Associated wavelength to the last value of 'amplitudes'.</param>
+			 * <param name="dataSource">
+			 *     Reference to a AConvertibleColor instance from which this object has been generated.
+			 * </param>
+			 */
+			public RegularLightSpectrum (IList<double> amplitudes, double nmPerStep, double maxWaveLength, AConvertibleColor dataSource=null) : base(dataSource)
 			{
 				NmPerStep = nmPerStep;
-				MaxWaveLength = maxWavelength;
-				MinWaveLength = maxWavelength - nmPerStep * (amplitudes.Count - 1);
+				MaxWaveLength = maxWaveLength;
+				MinWaveLength = maxWaveLength - nmPerStep * (amplitudes.Count - 1);
 				Amplitudes = new ReadOnlyCollection<double> (amplitudes);
 			}
 

ColorSharp/src/LightSpectrums/SpectrumStrategy.cs

@@ -40,18 +40,32 @@ namespace LightSpectrums
 		[Flags]
 		public enum SpectrumStrategy
 		{
+			/// <summary>Use the 1nm step matching functions to obtain the chromaticity components of the spectrum.</summary>
 			WaveLength1NmStep = 0,
+
+			/// <summary>Use the 5nm step matching functions to obtain the chromaticity components of the spectrum.</summary>
 			WaveLength5NmStep = 1,
 
+			/// <summary>Use the 2º matching functions to obtain the chromaticity components of the spectrum.</summary>
 			TwoDegs = 2,
+
+			/// <summary>Use the 10º matching functions to obtain the chromaticity components of the spectrum.</summary>
 			TenDegs = 4,
 
+			/// <summary>Combination of WaveLength1NmStep and TwoDegs</summary>
 			Nm1Deg2 = WaveLength1NmStep | TwoDegs,
+
+			/// <summary>Combination of WaveLength5NmStep and TwoDegs</summary>
 			Nm5Deg2 = WaveLength5NmStep | TwoDegs,
+
+			/// <summary>Combination of WaveLength1NmStep and TenDegs</summary>
 			Nm1Deg10 = WaveLength1NmStep | TenDegs,
+
+			/// <summary>Combination of WaveLength5NmStep and TenDegs</summary>
 			Nm5Deg10 = WaveLength5NmStep | TenDegs,
 
-			Default = WaveLength5NmStep | TwoDegs
+			/// <summary>Nm5Deg2</summary>
+			Default = Nm5Deg2
 		}
 	}
 }

ColorSharp/src/LightSpectrums/TabularLightSpectrum.cs

@@ -128,28 +128,6 @@ public override double EvaluateAt(double waveLength)
 				return (1.0-alpha)*RawAmplitudes [index].Value + alpha*RawAmplitudes [index+1].Value;
 			}
 
-			/**
-			 * <inheritdoc />
-			 */
-			/*
-			public override double GetNextAmplitudeSample (double waveLength)
-			{
-				if (waveLength < RawAmplitudes[0].Key || waveLength >= RawAmplitudes[RawAmplitudes.Count-1].Key) {
-					// TODO: Add extrapolation?
-					throw new ArgumentOutOfRangeException();
-				}
-
-				int index = RawAmplitudes.BinarySearch(
-					new KeyValuePair<double, double>(waveLength, 0), new KeyValuePairComparer()
-				);
-
-				if (index < 0)
-					index = ~index;
-
-				return RawAmplitudes [index + 1].Key;
-			}
-			*/
-
 			#endregion
 
 

ColorSharp/src/MatchingFunctions/CIE1931XYZ1Nm2DegX.cs

@@ -36,6 +36,9 @@ namespace MatchingFunctions
 		 */
 		sealed public class CIE1931XYZ1Nm2DegX : RegularMatchingFunction
 		{
+			/**
+			 * <summary>Component X of CIE's 1931 2º matching functions (1nm of precision)</summary>
+			 */
 			public static readonly CIE1931XYZ1Nm2DegX Instance = new CIE1931XYZ1Nm2DegX (
 				360.0, new [] {
 					0.000129900000,

ColorSharp/src/MatchingFunctions/CIE1931XYZ1Nm2DegY.cs

@@ -36,6 +36,9 @@ namespace MatchingFunctions
 		 */
 		sealed public class CIE1931XYZ1Nm2DegY : RegularMatchingFunction
 		{
+			/**
+			 * <summary>Component Y of CIE's 1931 2º matching functions (1nm of precision)</summary>
+			 */
 			public static readonly CIE1931XYZ1Nm2DegY Instance = new CIE1931XYZ1Nm2DegY (
 				360.0, new [] {
 					0.000003917000,

ColorSharp/src/MatchingFunctions/CIE1931XYZ1Nm2DegZ.cs

@@ -36,6 +36,9 @@ namespace MatchingFunctions
 		 */
 		sealed public class CIE1931XYZ1Nm2DegZ : RegularMatchingFunction
 		{
+			/**
+			 * <summary>Component Z of CIE's 1931 2º matching functions (1nm of precision)</summary>
+			 */
 			public static readonly CIE1931XYZ1Nm2DegZ Instance = new CIE1931XYZ1Nm2DegZ (
 				360.0, new [] {
 					0.000606100000,