temperature/TemperatureCache.java - platform/external/libmonet - Git at Google

 /*
  * Copyright 2022 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package com.google.ux.material.libmonet.temperature;

 import com.google.ux.material.libmonet.hct.Hct;
 import com.google.ux.material.libmonet.utils.ColorUtils;
 import com.google.ux.material.libmonet.utils.MathUtils;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

 /**
  * Design utilities using color temperature theory.
  *
  * <p>Analogous colors, complementary color, and cache to efficiently, lazily, generate data for
  * calculations when needed.
  */
 public final class TemperatureCache {
   private final Hct input;

   private Hct precomputedComplement;
   private List<Hct> precomputedHctsByTemp;
   private List<Hct> precomputedHctsByHue;
   private Map<Hct, Double> precomputedTempsByHct;

   private TemperatureCache() {
     throw new UnsupportedOperationException();
   }

   /**
    * Create a cache that allows calculation of ex. complementary and analogous colors.
    *
    * @param input Color to find complement/analogous colors of. Any colors will have the same tone,
    * and chroma as the input color, modulo any restrictions due to the other hues having lower
    * limits on chroma.
    */
   public TemperatureCache(Hct input) {
     this.input = input;
   }

   /**
    * A color that complements the input color aesthetically.
    *
    * <p>In art, this is usually described as being across the color wheel. History of this shows
    * intent as a color that is just as cool-warm as the input color is warm-cool.
    */
   public Hct getComplement() {
     if (precomputedComplement != null) {
       return precomputedComplement;
     }

     double coldestHue = getColdest().getHue();
     double coldestTemp = getTempsByHct().get(getColdest());

     double warmestHue = getWarmest().getHue();
     double warmestTemp = getTempsByHct().get(getWarmest());
     double range = warmestTemp - coldestTemp;
     boolean startHueIsColdestToWarmest = isBetween(input.getHue(), coldestHue, warmestHue);
     double startHue = startHueIsColdestToWarmest ? warmestHue : coldestHue;
     double endHue = startHueIsColdestToWarmest ? coldestHue : warmestHue;
     double directionOfRotation = 1.;
     double smallestError = 1000.;
     Hct answer = getHctsByHue().get((int) Math.round(input.getHue()));

     double complementRelativeTemp = (1. - getRelativeTemperature(input));
     // Find the color in the other section, closest to the inverse percentile
     // of the input color. This is the complement.
     for (double hueAddend = 0.; hueAddend <= 360.; hueAddend += 1.) {
       double hue = MathUtils.sanitizeDegreesDouble(
           startHue + directionOfRotation * hueAddend);
       if (!isBetween(hue, startHue, endHue)) {
         continue;
       }
       Hct possibleAnswer = getHctsByHue().get((int) Math.round(hue));
       double relativeTemp =
           (getTempsByHct().get(possibleAnswer) - coldestTemp) / range;
       double error = Math.abs(complementRelativeTemp - relativeTemp);
       if (error < smallestError) {
         smallestError = error;
         answer = possibleAnswer;
       }
     }
     precomputedComplement = answer;
     return precomputedComplement;
   }

   /**
    * 5 colors that pair well with the input color.
    *
    * <p>The colors are equidistant in temperature and adjacent in hue.
    */
   public List<Hct> getAnalogousColors() {
     return getAnalogousColors(5, 12);
   }

   /**
    * A set of colors with differing hues, equidistant in temperature.
    *
    * <p>In art, this is usually described as a set of 5 colors on a color wheel divided into 12
    * sections. This method allows provision of either of those values.
    *
    * <p>Behavior is undefined when count or divisions is 0. When divisions < count, colors repeat.
    *
    * @param count The number of colors to return, includes the input color.
    * @param divisions The number of divisions on the color wheel.
    */
   public List<Hct> getAnalogousColors(int count, int divisions) {
     // The starting hue is the hue of the input color.
     int startHue = (int) Math.round(input.getHue());
     Hct startHct = getHctsByHue().get(startHue);
     double lastTemp = getRelativeTemperature(startHct);

     List<Hct> allColors = new ArrayList<>();
     allColors.add(startHct);

     double absoluteTotalTempDelta = 0.f;
     for (int i = 0; i < 360; i++) {
       int hue = MathUtils.sanitizeDegreesInt(startHue + i);
       Hct hct = getHctsByHue().get(hue);
       double temp = getRelativeTemperature(hct);
       double tempDelta = Math.abs(temp - lastTemp);
       lastTemp = temp;
       absoluteTotalTempDelta += tempDelta;
     }

     int hueAddend = 1;
     double tempStep = absoluteTotalTempDelta / (double) divisions;
     double totalTempDelta = 0.0;
     lastTemp = getRelativeTemperature(startHct);
     while (allColors.size() < divisions) {
       int hue = MathUtils.sanitizeDegreesInt(startHue + hueAddend);
       Hct hct = getHctsByHue().get(hue);
       double temp = getRelativeTemperature(hct);
       double tempDelta = Math.abs(temp - lastTemp);
       totalTempDelta += tempDelta;

       double desiredTotalTempDeltaForIndex = (allColors.size() * tempStep);
       boolean indexSatisfied = totalTempDelta >= desiredTotalTempDeltaForIndex;
       int indexAddend = 1;
       // Keep adding this hue to the answers until its temperature is
       // insufficient. This ensures consistent behavior when there aren't
       // `divisions` discrete steps between 0 and 360 in hue with `tempStep`
       // delta in temperature between them.
       //
       // For example, white and black have no analogues: there are no other
       // colors at T100/T0. Therefore, they should just be added to the array
       // as answers.
       while (indexSatisfied && allColors.size() < divisions) {
         allColors.add(hct);
         desiredTotalTempDeltaForIndex = ((allColors.size() + indexAddend) * tempStep);
         indexSatisfied = totalTempDelta >= desiredTotalTempDeltaForIndex;
         indexAddend++;
       }
       lastTemp = temp;
       hueAddend++;

       if (hueAddend > 360) {
         while (allColors.size() < divisions) {
           allColors.add(hct);
         }
         break;
       }
     }

     List<Hct> answers = new ArrayList<>();
     answers.add(input);

     int ccwCount = (int) Math.floor(((double) count - 1.0) / 2.0);
     for (int i = 1; i < (ccwCount + 1); i++) {
       int index = 0 - i;
       while (index < 0) {
         index = allColors.size() + index;
       }
       if (index >= allColors.size()) {
         index = index % allColors.size();
       }
       answers.add(0, allColors.get(index));
     }

     int cwCount = count - ccwCount - 1;
     for (int i = 1; i < (cwCount + 1); i++) {
       int index = i;
       while (index < 0) {
         index = allColors.size() + index;
       }
       if (index >= allColors.size()) {
         index = index % allColors.size();
       }
       answers.add(allColors.get(index));
     }

     return answers;
   }

   /**
    * Temperature relative to all colors with the same chroma and tone.
    *
    * @param hct HCT to find the relative temperature of.
    * @return Value on a scale from 0 to 1.
    */
   public double getRelativeTemperature(Hct hct) {
     double range = getTempsByHct().get(getWarmest()) - getTempsByHct().get(getColdest());
     double differenceFromColdest =
         getTempsByHct().get(hct) - getTempsByHct().get(getColdest());
     // Handle when there's no difference in temperature between warmest and
     // coldest: for example, at T100, only one color is available, white.
     if (range == 0.) {
       return 0.5;
     }
     return differenceFromColdest / range;
   }

   /**
    * Value representing cool-warm factor of a color. Values below 0 are considered cool, above,
    * warm.
    *
    * <p>Color science has researched emotion and harmony, which art uses to select colors. Warm-cool
    * is the foundation of analogous and complementary colors. See: - Li-Chen Ou's Chapter 19 in
    * Handbook of Color Psychology (2015). - Josef Albers' Interaction of Color chapters 19 and 21.
    *
    * <p>Implementation of Ou, Woodcock and Wright's algorithm, which uses Lab/LCH color space.
    * Return value has these properties:<br>
    * - Values below 0 are cool, above 0 are warm.<br>
    * - Lower bound: -9.66. Chroma is infinite. Assuming max of Lab chroma 130.<br>
    * - Upper bound: 8.61. Chroma is infinite. Assuming max of Lab chroma 130.
    */
   public static double rawTemperature(Hct color) {
     double[] lab = ColorUtils.labFromArgb(color.toInt());
     double hue = MathUtils.sanitizeDegreesDouble(Math.toDegrees(Math.atan2(lab[2], lab[1])));
     double chroma = Math.hypot(lab[1], lab[2]);
     return -0.5
         + 0.02
             * Math.pow(chroma, 1.07)
             * Math.cos(Math.toRadians(MathUtils.sanitizeDegreesDouble(hue - 50.)));
   }

   /** Coldest color with same chroma and tone as input. */
   private Hct getColdest() {
     return getHctsByTemp().get(0);
   }

   /**
    * HCTs for all colors with the same chroma/tone as the input.
    *
    * <p>Sorted by hue, ex. index 0 is hue 0.
    */
   private List<Hct> getHctsByHue() {
     if (precomputedHctsByHue != null) {
       return precomputedHctsByHue;
     }
     List<Hct> hcts = new ArrayList<>();
     for (double hue = 0.; hue <= 360.; hue += 1.) {
       Hct colorAtHue = Hct.from(hue, input.getChroma(), input.getTone());
       hcts.add(colorAtHue);
     }
     precomputedHctsByHue = Collections.unmodifiableList(hcts);
     return precomputedHctsByHue;
   }

   /**
    * HCTs for all colors with the same chroma/tone as the input.
    *
    * <p>Sorted from coldest first to warmest last.
    */
   // Prevent lint for Comparator not being available on Android before API level 24, 7.0, 2016.
   // "AndroidJdkLibsChecker" for one linter, "NewApi" for another.
   // A java_library Bazel rule with an Android constraint cannot skip these warnings without this
   // annotation; another solution would be to create an android_library rule and supply
   // AndroidManifest with an SDK set higher than 23.
   @SuppressWarnings({"AndroidJdkLibsChecker", "NewApi"})
   private List<Hct> getHctsByTemp() {
     if (precomputedHctsByTemp != null) {
       return precomputedHctsByTemp;
     }

     List<Hct> hcts = new ArrayList<>(getHctsByHue());
     hcts.add(input);
     Comparator<Hct> temperaturesComparator =
         Comparator.comparing((Hct arg) -> getTempsByHct().get(arg), Double::compareTo);
     Collections.sort(hcts, temperaturesComparator);
     precomputedHctsByTemp = hcts;
     return precomputedHctsByTemp;
   }

   /** Keys of HCTs in getHctsByTemp, values of raw temperature. */
   private Map<Hct, Double> getTempsByHct() {
     if (precomputedTempsByHct != null) {
       return precomputedTempsByHct;
     }

     List<Hct> allHcts = new ArrayList<>(getHctsByHue());
     allHcts.add(input);

     Map<Hct, Double> temperaturesByHct = new HashMap<>();
     for (Hct hct : allHcts) {
       temperaturesByHct.put(hct, rawTemperature(hct));
     }

     precomputedTempsByHct = temperaturesByHct;
     return precomputedTempsByHct;
   }

   /** Warmest color with same chroma and tone as input. */
   private Hct getWarmest() {
     return getHctsByTemp().get(getHctsByTemp().size() - 1);
   }

   /** Determines if an angle is between two other angles, rotating clockwise. */
   private static boolean isBetween(double angle, double a, double b) {
     if (a < b) {
       return a <= angle && angle <= b;
     }
     return a <= angle || angle <= b;
   }
 }
	/*
	* Copyright 2022 Google LLC
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package com.google.ux.material.libmonet.temperature;

	import com.google.ux.material.libmonet.hct.Hct;
	import com.google.ux.material.libmonet.utils.ColorUtils;
	import com.google.ux.material.libmonet.utils.MathUtils;
	import java.util.ArrayList;
	import java.util.Collections;
	import java.util.Comparator;
	import java.util.HashMap;
	import java.util.List;
	import java.util.Map;

	/**
	* Design utilities using color temperature theory.
	*
	* <p>Analogous colors, complementary color, and cache to efficiently, lazily, generate data for
	* calculations when needed.
	*/
	public final class TemperatureCache {
	private final Hct input;

	private Hct precomputedComplement;
	private List<Hct> precomputedHctsByTemp;
	private List<Hct> precomputedHctsByHue;
	private Map<Hct, Double> precomputedTempsByHct;

	private TemperatureCache() {
	throw new UnsupportedOperationException();
	}

	/**
	* Create a cache that allows calculation of ex. complementary and analogous colors.
	*
	* @param input Color to find complement/analogous colors of. Any colors will have the same tone,
	* and chroma as the input color, modulo any restrictions due to the other hues having lower
	* limits on chroma.
	*/
	public TemperatureCache(Hct input) {
	this.input = input;
	}

	/**
	* A color that complements the input color aesthetically.
	*
	* <p>In art, this is usually described as being across the color wheel. History of this shows
	* intent as a color that is just as cool-warm as the input color is warm-cool.
	*/
	public Hct getComplement() {
	if (precomputedComplement != null) {
	return precomputedComplement;
	}

	double coldestHue = getColdest().getHue();
	double coldestTemp = getTempsByHct().get(getColdest());

	double warmestHue = getWarmest().getHue();
	double warmestTemp = getTempsByHct().get(getWarmest());
	double range = warmestTemp - coldestTemp;
	boolean startHueIsColdestToWarmest = isBetween(input.getHue(), coldestHue, warmestHue);
	double startHue = startHueIsColdestToWarmest ? warmestHue : coldestHue;
	double endHue = startHueIsColdestToWarmest ? coldestHue : warmestHue;
	double directionOfRotation = 1.;
	double smallestError = 1000.;
	Hct answer = getHctsByHue().get((int) Math.round(input.getHue()));

	double complementRelativeTemp = (1. - getRelativeTemperature(input));
	// Find the color in the other section, closest to the inverse percentile
	// of the input color. This is the complement.
	for (double hueAddend = 0.; hueAddend <= 360.; hueAddend += 1.) {
	double hue = MathUtils.sanitizeDegreesDouble(
	startHue + directionOfRotation * hueAddend);
	if (!isBetween(hue, startHue, endHue)) {
	continue;
	}
	Hct possibleAnswer = getHctsByHue().get((int) Math.round(hue));
	double relativeTemp =
	(getTempsByHct().get(possibleAnswer) - coldestTemp) / range;
	double error = Math.abs(complementRelativeTemp - relativeTemp);
	if (error < smallestError) {
	smallestError = error;
	answer = possibleAnswer;
	}
	}
	precomputedComplement = answer;
	return precomputedComplement;
	}

	/**
	* 5 colors that pair well with the input color.
	*
	* <p>The colors are equidistant in temperature and adjacent in hue.
	*/
	public List<Hct> getAnalogousColors() {
	return getAnalogousColors(5, 12);
	}

	/**
	* A set of colors with differing hues, equidistant in temperature.
	*
	* <p>In art, this is usually described as a set of 5 colors on a color wheel divided into 12
	* sections. This method allows provision of either of those values.
	*
	* <p>Behavior is undefined when count or divisions is 0. When divisions < count, colors repeat.
	*
	* @param count The number of colors to return, includes the input color.
	* @param divisions The number of divisions on the color wheel.
	*/
	public List<Hct> getAnalogousColors(int count, int divisions) {
	// The starting hue is the hue of the input color.
	int startHue = (int) Math.round(input.getHue());
	Hct startHct = getHctsByHue().get(startHue);
	double lastTemp = getRelativeTemperature(startHct);

	List<Hct> allColors = new ArrayList<>();
	allColors.add(startHct);

	double absoluteTotalTempDelta = 0.f;
	for (int i = 0; i < 360; i++) {
	int hue = MathUtils.sanitizeDegreesInt(startHue + i);
	Hct hct = getHctsByHue().get(hue);
	double temp = getRelativeTemperature(hct);
	double tempDelta = Math.abs(temp - lastTemp);
	lastTemp = temp;
	absoluteTotalTempDelta += tempDelta;
	}

	int hueAddend = 1;
	double tempStep = absoluteTotalTempDelta / (double) divisions;
	double totalTempDelta = 0.0;
	lastTemp = getRelativeTemperature(startHct);
	while (allColors.size() < divisions) {
	int hue = MathUtils.sanitizeDegreesInt(startHue + hueAddend);
	Hct hct = getHctsByHue().get(hue);
	double temp = getRelativeTemperature(hct);
	double tempDelta = Math.abs(temp - lastTemp);
	totalTempDelta += tempDelta;

	double desiredTotalTempDeltaForIndex = (allColors.size() * tempStep);
	boolean indexSatisfied = totalTempDelta >= desiredTotalTempDeltaForIndex;
	int indexAddend = 1;
	// Keep adding this hue to the answers until its temperature is
	// insufficient. This ensures consistent behavior when there aren't
	// `divisions` discrete steps between 0 and 360 in hue with `tempStep`
	// delta in temperature between them.
	//
	// For example, white and black have no analogues: there are no other
	// colors at T100/T0. Therefore, they should just be added to the array
	// as answers.
	while (indexSatisfied && allColors.size() < divisions) {
	allColors.add(hct);
	desiredTotalTempDeltaForIndex = ((allColors.size() + indexAddend) * tempStep);
	indexSatisfied = totalTempDelta >= desiredTotalTempDeltaForIndex;
	indexAddend++;
	}
	lastTemp = temp;
	hueAddend++;

	if (hueAddend > 360) {
	while (allColors.size() < divisions) {
	allColors.add(hct);
	}
	break;
	}
	}

	List<Hct> answers = new ArrayList<>();
	answers.add(input);

	int ccwCount = (int) Math.floor(((double) count - 1.0) / 2.0);
	for (int i = 1; i < (ccwCount + 1); i++) {
	int index = 0 - i;
	while (index < 0) {
	index = allColors.size() + index;
	}
	if (index >= allColors.size()) {
	index = index % allColors.size();
	}
	answers.add(0, allColors.get(index));
	}

	int cwCount = count - ccwCount - 1;
	for (int i = 1; i < (cwCount + 1); i++) {
	int index = i;
	while (index < 0) {
	index = allColors.size() + index;
	}
	if (index >= allColors.size()) {
	index = index % allColors.size();
	}
	answers.add(allColors.get(index));
	}

	return answers;
	}

	/**
	* Temperature relative to all colors with the same chroma and tone.
	*
	* @param hct HCT to find the relative temperature of.
	* @return Value on a scale from 0 to 1.
	*/
	public double getRelativeTemperature(Hct hct) {
	double range = getTempsByHct().get(getWarmest()) - getTempsByHct().get(getColdest());
	double differenceFromColdest =
	getTempsByHct().get(hct) - getTempsByHct().get(getColdest());
	// Handle when there's no difference in temperature between warmest and
	// coldest: for example, at T100, only one color is available, white.
	if (range == 0.) {
	return 0.5;
	}
	return differenceFromColdest / range;
	}

	/**
	* Value representing cool-warm factor of a color. Values below 0 are considered cool, above,
	* warm.
	*
	* <p>Color science has researched emotion and harmony, which art uses to select colors. Warm-cool
	* is the foundation of analogous and complementary colors. See: - Li-Chen Ou's Chapter 19 in
	* Handbook of Color Psychology (2015). - Josef Albers' Interaction of Color chapters 19 and 21.
	*
	* <p>Implementation of Ou, Woodcock and Wright's algorithm, which uses Lab/LCH color space.
	* Return value has these properties:<br>
	* - Values below 0 are cool, above 0 are warm.<br>
	* - Lower bound: -9.66. Chroma is infinite. Assuming max of Lab chroma 130.<br>
	* - Upper bound: 8.61. Chroma is infinite. Assuming max of Lab chroma 130.
	*/
	public static double rawTemperature(Hct color) {
	double[] lab = ColorUtils.labFromArgb(color.toInt());
	double hue = MathUtils.sanitizeDegreesDouble(Math.toDegrees(Math.atan2(lab[2], lab[1])));
	double chroma = Math.hypot(lab[1], lab[2]);
	return -0.5
	+ 0.02
	* Math.pow(chroma, 1.07)
	* Math.cos(Math.toRadians(MathUtils.sanitizeDegreesDouble(hue - 50.)));
	}

	/** Coldest color with same chroma and tone as input. */
	private Hct getColdest() {
	return getHctsByTemp().get(0);
	}

	/**
	* HCTs for all colors with the same chroma/tone as the input.
	*
	* <p>Sorted by hue, ex. index 0 is hue 0.
	*/
	private List<Hct> getHctsByHue() {
	if (precomputedHctsByHue != null) {
	return precomputedHctsByHue;
	}
	List<Hct> hcts = new ArrayList<>();
	for (double hue = 0.; hue <= 360.; hue += 1.) {
	Hct colorAtHue = Hct.from(hue, input.getChroma(), input.getTone());
	hcts.add(colorAtHue);
	}
	precomputedHctsByHue = Collections.unmodifiableList(hcts);
	return precomputedHctsByHue;
	}

	/**
	* HCTs for all colors with the same chroma/tone as the input.
	*
	* <p>Sorted from coldest first to warmest last.
	*/
	// Prevent lint for Comparator not being available on Android before API level 24, 7.0, 2016.
	// "AndroidJdkLibsChecker" for one linter, "NewApi" for another.
	// A java_library Bazel rule with an Android constraint cannot skip these warnings without this
	// annotation; another solution would be to create an android_library rule and supply
	// AndroidManifest with an SDK set higher than 23.
	@SuppressWarnings({"AndroidJdkLibsChecker", "NewApi"})
	private List<Hct> getHctsByTemp() {
	if (precomputedHctsByTemp != null) {
	return precomputedHctsByTemp;
	}

	List<Hct> hcts = new ArrayList<>(getHctsByHue());
	hcts.add(input);
	Comparator<Hct> temperaturesComparator =
	Comparator.comparing((Hct arg) -> getTempsByHct().get(arg), Double::compareTo);
	Collections.sort(hcts, temperaturesComparator);
	precomputedHctsByTemp = hcts;
	return precomputedHctsByTemp;
	}

	/** Keys of HCTs in getHctsByTemp, values of raw temperature. */
	private Map<Hct, Double> getTempsByHct() {
	if (precomputedTempsByHct != null) {
	return precomputedTempsByHct;
	}

	List<Hct> allHcts = new ArrayList<>(getHctsByHue());
	allHcts.add(input);

	Map<Hct, Double> temperaturesByHct = new HashMap<>();
	for (Hct hct : allHcts) {
	temperaturesByHct.put(hct, rawTemperature(hct));
	}

	precomputedTempsByHct = temperaturesByHct;
	return precomputedTempsByHct;
	}

	/** Warmest color with same chroma and tone as input. */
	private Hct getWarmest() {
	return getHctsByTemp().get(getHctsByTemp().size() - 1);
	}

	/** Determines if an angle is between two other angles, rotating clockwise. */
	private static boolean isBetween(double angle, double a, double b) {
	if (a < b) {
	return a <= angle && angle <= b;
	}
	return a <= angle \|\| angle <= b;
	}
	}