Class ColorUtils

java.lang.Object
com.github.darksoulq.abyssallib.common.color.ColorUtils
public final class ColorUtils extends Object
A comprehensive utility class for color manipulation, conversion, and generation.

This class provides methods to interface between Bukkit Color objects and various color spaces including RGB, HEX, HSB, CMYK, XYZ, Lab, Lch, and OkLab. It also includes advanced blending, mixing, and color theory palette generation.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ColorUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<org.bukkit.Color>
    analogous(org.bukkit.Color color)
    Generates an analogous color scheme.
    static org.bukkit.Color
    average(Collection<org.bukkit.Color> colors)
    Calculates the mathematical average of a collection of colors.
    static org.bukkit.Color
    blend(org.bukkit.Color c1, org.bukkit.Color c2, BlendMode mode)
    Blends two colors using a specific BlendMode.
    static org.bukkit.Color
    brighten(org.bukkit.Color color, float factor)
    Adjusts the brightness of a color.
    static org.bukkit.Color
    closest(org.bukkit.Color target, Collection<org.bukkit.Color> palette)
    Finds the color in a palette that is closest to the target color.
    static org.bukkit.Color
    cmyk(float c, float m, float y, float k)
    Creates a Color using the CMYK color model.
    static org.bukkit.Color
    complementary(org.bukkit.Color color)
    Finds the complementary color (180-degree hue shift).
    static org.bukkit.Color
    contrast(org.bukkit.Color bg)
    Determines whether black or white provides better contrast against a background.
    static org.bukkit.Color
    darken(org.bukkit.Color color, float factor)
    Reduces the brightness of a color.
    static org.bukkit.Color
    desaturate(org.bukkit.Color color, float factor)
    Reduces the saturation of a color.
    static double
    distanceLab(org.bukkit.Color c1, org.bukkit.Color c2)
    Computes the perceptual Delta-E distance between two colors in Lab space.
    static double
    distanceSq(org.bukkit.Color c1, org.bukkit.Color c2)
    Computes the squared Euclidean distance between two colors in RGB space.
    static org.bukkit.Color
    fromInt(int rgb)
    Creates a Color object from a packed RGB integer.
    static org.bukkit.Color
    fromName(String name)
    Retrieves a color by its common English name.
    static List<org.bukkit.Color>
    gradient(org.bukkit.Color start, org.bukkit.Color end, int steps)
    Generates a list of colors representing a gradient between two colors.
    static org.bukkit.Color
    grayscale(org.bukkit.Color color)
    Converts a color to its grayscale equivalent using a simple average.
    static org.bukkit.Color
    hex(String hex)
    Parses a hexadecimal string into a Bukkit Color.
    static org.bukkit.Color
    hsb(float hue, float saturation, float brightness)
    Creates a Color using the HSB (Hue, Saturation, Brightness) color model.
    static org.bukkit.Color
    hueShift(org.bukkit.Color color, float degrees)
    Shifts the hue of a color by a specific degree on the hue circle.
    static org.bukkit.Color
    invert(org.bukkit.Color color)
    Inverts the RGB components of a color.
    static org.bukkit.Color
    lab(double l, double a, double b)
    Creates a Color from CIE Lab coordinates.
    static org.bukkit.Color
    lch(double l, double c, double h)
    Creates a Color from Lch (Lightness, Chroma, Hue) coordinates.
    static org.bukkit.Color
    mix(org.bukkit.Color c1, org.bukkit.Color c2, double ratio)
    Performs a linear RGB interpolation (Lerp) between two colors.
    static org.bukkit.Color
    mixLch(org.bukkit.Color c1, org.bukkit.Color c2, double ratio)
    Interpolates two colors within the Lch color space.
    static org.bukkit.Color
    mixOkLab(org.bukkit.Color c1, org.bukkit.Color c2, double ratio)
    Interpolates two colors within the OkLab color space.
    static List<org.bukkit.Color>
    monochromatic(org.bukkit.Color color)
    Generates a monochromatic color scheme by varying brightness and saturation.
    static List<org.bukkit.Color>
    palette(BufferedImage image, int maxColors)
    Extracts a color palette from an image using a sparse sampling method.
    static org.bukkit.Color
    random()
    Generates a random RGB color.
    static org.bukkit.Color
    saturate(org.bukkit.Color color, float factor)
    Adjusts the saturation of a color.
    static List<org.bukkit.Color>
    splitComplementary(org.bukkit.Color color)
    Generates a split-complementary color scheme.
    static List<org.bukkit.Color>
    tetradic(org.bukkit.Color color)
    Generates a tetradic (double-complementary) color scheme.
    static float[]
    toCMYK(org.bukkit.Color color)
    Converts a Color to CMYK components.
    static String
    toHex(org.bukkit.Color color)
    Converts a Color object into a standard CSS-style hexadecimal string.
    static float[]
    toHSB(org.bukkit.Color color)
    Converts a Color into an array of HSB components.
    static int
    toInt(org.bukkit.Color color)
    Converts a Color into a single packed RGB integer.
    static double[]
    toLab(org.bukkit.Color c)
    Converts a Color to CIE Lab coordinates.
    static double[]
    toLch(org.bukkit.Color color)
    Converts a Color to Lch coordinates.
    static double[]
    toXYZ(org.bukkit.Color c)
    Converts a Color to CIE XYZ coordinates.
    static List<org.bukkit.Color>
    triadic(org.bukkit.Color color)
    Generates a triadic color scheme.
    static org.bukkit.Color
    xyz(double x, double y, double z)
    Creates a Color from CIE XYZ coordinates.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ColorUtils

      public ColorUtils()

  • Method Details

    • fromName

      public static org.bukkit.Color fromName(String name)
      Retrieves a color by its common English name.
      Parameters:
      name - The name of the color (case-insensitive).
      Returns:
      The matching Color, or null if the name is not recognized.

    • hex

      public static org.bukkit.Color hex(String hex)
      Parses a hexadecimal string into a Bukkit Color.

      Supports standard 6-digit hex (e.g., "#FF0000") and shorthand 3-digit hex (e.g., "#F00").

      Parameters:
      hex - The hexadecimal string, with or without a leading '#' character.
      Returns:
      The resulting Color object.
      Throws:
      NumberFormatException - if the string is not a valid hexadecimal value.

    • toHex

      public static String toHex(org.bukkit.Color color)
      Converts a Color object into a standard CSS-style hexadecimal string.
      Parameters:
      color - The Color to convert.
      Returns:
      A string formatted as "#RRGGBB" in lowercase.

    • toInt

      public static int toInt(org.bukkit.Color color)
      Converts a Color into a single packed RGB integer.
      Parameters:
      color - The Color to convert.
      Returns:
      An integer representing the RGB value (0xRRGGBB).

    • fromInt

      public static org.bukkit.Color fromInt(int rgb)
      Creates a Color object from a packed RGB integer.
      Parameters:
      rgb - The integer value (0xRRGGBB). Bitmask 0xFFFFFF is applied.
      Returns:
      The resulting Color.

    • hsb

      public static org.bukkit.Color hsb(float hue, float saturation, float brightness)
      Creates a Color using the HSB (Hue, Saturation, Brightness) color model.
      Parameters:
      hue - The hue component (0.0 to 1.0).
      saturation - The saturation component (0.0 to 1.0).
      brightness - The brightness/value component (0.0 to 1.0).
      Returns:
      The resulting Color.

    • toHSB

      public static float[] toHSB(org.bukkit.Color color)
      Converts a Color into an array of HSB components.
      Parameters:
      color - The Color to convert.
      Returns:
      A float array where [0] is Hue, [1] is Saturation, and [2] is Brightness.

    • cmyk

      public static org.bukkit.Color cmyk(float c, float m, float y, float k)
      Creates a Color using the CMYK color model.
      Parameters:
      c - Cyan component (0.0 to 1.0).
      m - Magenta component (0.0 to 1.0).
      y - Yellow component (0.0 to 1.0).
      k - Black/Key component (0.0 to 1.0).
      Returns:
      The resulting Color.

    • toCMYK

      public static float[] toCMYK(org.bukkit.Color color)
      Converts a Color to CMYK components.
      Parameters:
      color - The Color to convert.
      Returns:
      A float array containing C, M, Y, K in order.

    • xyz

      public static org.bukkit.Color xyz(double x, double y, double z)
      Creates a Color from CIE XYZ coordinates.
      Parameters:
      x - The X coordinate.
      y - The Y coordinate.
      z - The Z coordinate.
      Returns:
      The resulting Color.

    • toXYZ

      public static double[] toXYZ(org.bukkit.Color c)
      Converts a Color to CIE XYZ coordinates.
      Parameters:
      c - The Color to convert.
      Returns:
      A double array containing X, Y, Z.

    • lab

      public static org.bukkit.Color lab(double l, double a, double b)
      Creates a Color from CIE Lab coordinates.
      Parameters:
      l - Lightness.
      a - The A axis (green to red).
      b - The B axis (blue to yellow).
      Returns:
      The resulting Color.

    • toLab

      public static double[] toLab(org.bukkit.Color c)
      Converts a Color to CIE Lab coordinates.
      Parameters:
      c - The Color to convert.
      Returns:
      A double array containing L, a, b.

    • lch

      public static org.bukkit.Color lch(double l, double c, double h)
      Creates a Color from Lch (Lightness, Chroma, Hue) coordinates.
      Parameters:
      l - Lightness.
      c - Chroma.
      h - Hue (in degrees).
      Returns:
      The resulting Color.

    • toLch

      public static double[] toLch(org.bukkit.Color color)
      Converts a Color to Lch coordinates.
      Parameters:
      color - The Color to convert.
      Returns:
      A double array containing L, c, h.

    • mix

      public static org.bukkit.Color mix(org.bukkit.Color c1, org.bukkit.Color c2, double ratio)
      Performs a linear RGB interpolation (Lerp) between two colors.
      Parameters:
      c1 - The starting color.
      c2 - The target color.
      ratio - The interpolation factor (0.0 to 1.0).
      Returns:
      The mixed Color.

    • mixOkLab

      public static org.bukkit.Color mixOkLab(org.bukkit.Color c1, org.bukkit.Color c2, double ratio)
      Interpolates two colors within the OkLab color space.

      This provides perceptually linear transitions that avoid the desaturation common in standard RGB mixing.

      Parameters:
      c1 - The starting color.
      c2 - The target color.
      ratio - The interpolation factor (0.0 to 1.0).
      Returns:
      The mixed Color.

    • mixLch

      public static org.bukkit.Color mixLch(org.bukkit.Color c1, org.bukkit.Color c2, double ratio)
      Interpolates two colors within the Lch color space.

      This is ideal for gradients that need to maintain consistent lightness and chroma while shifting hue, particularly across the shortest path of the hue circle.

      Parameters:
      c1 - The starting color.
      c2 - The target color.
      ratio - The interpolation factor (0.0 to 1.0).
      Returns:
      The mixed Color.

    • blend

      public static org.bukkit.Color blend(org.bukkit.Color c1, org.bukkit.Color c2, BlendMode mode)
      Blends two colors using a specific BlendMode.
      Parameters:
      c1 - The base color.
      c2 - The overlay color.
      mode - The logic used to combine the colors.
      Returns:
      The resulting Color.

    • average

      public static org.bukkit.Color average(Collection<org.bukkit.Color> colors)
      Calculates the mathematical average of a collection of colors.
      Parameters:
      colors - The collection of Color objects.
      Returns:
      The average Color, or Color.WHITE if the collection is empty.

    • distanceSq

      public static double distanceSq(org.bukkit.Color c1, org.bukkit.Color c2)
      Computes the squared Euclidean distance between two colors in RGB space.
      Parameters:
      c1 - The first color.
      c2 - The second color.
      Returns:
      The squared distance value.

    • distanceLab

      public static double distanceLab(org.bukkit.Color c1, org.bukkit.Color c2)
      Computes the perceptual Delta-E distance between two colors in Lab space.
      Parameters:
      c1 - The first color.
      c2 - The second color.
      Returns:
      The Delta-E distance.

    • closest

      public static org.bukkit.Color closest(org.bukkit.Color target, Collection<org.bukkit.Color> palette)
      Finds the color in a palette that is closest to the target color.
      Parameters:
      target - The color to match.
      palette - The pool of available colors.
      Returns:
      The closest Color found, or Color.WHITE if palette is empty.

    • random

      public static org.bukkit.Color random()
      Generates a random RGB color.
      Returns:
      A randomly generated Color.

    • saturate

      public static org.bukkit.Color saturate(org.bukkit.Color color, float factor)
      Adjusts the saturation of a color.
      Parameters:
      color - The input color.
      factor - The multiplier (e.g., 2.0 for double saturation, 0.5 for half).
      Returns:
      The saturated Color.

    • desaturate

      public static org.bukkit.Color desaturate(org.bukkit.Color color, float factor)
      Reduces the saturation of a color.
      Parameters:
      color - The input color.
      factor - The reduction amount (0.0 to 1.0).
      Returns:
      The desaturated Color.

    • brighten

      public static org.bukkit.Color brighten(org.bukkit.Color color, float factor)
      Adjusts the brightness of a color.
      Parameters:
      color - The input color.
      factor - The multiplier for the brightness component.
      Returns:
      The brightened Color.

    • darken

      public static org.bukkit.Color darken(org.bukkit.Color color, float factor)
      Reduces the brightness of a color.
      Parameters:
      color - The input color.
      factor - The reduction amount (0.0 to 1.0).
      Returns:
      The darkened Color.

    • hueShift

      public static org.bukkit.Color hueShift(org.bukkit.Color color, float degrees)
      Shifts the hue of a color by a specific degree on the hue circle.
      Parameters:
      color - The input color.
      degrees - The amount to shift (e.g., 360 is a full rotation).
      Returns:
      The hue-shifted Color.

    • invert

      public static org.bukkit.Color invert(org.bukkit.Color color)
      Inverts the RGB components of a color.
      Parameters:
      color - The Color to invert.
      Returns:
      The inverted Color.

    • grayscale

      public static org.bukkit.Color grayscale(org.bukkit.Color color)
      Converts a color to its grayscale equivalent using a simple average.
      Parameters:
      color - The Color to convert.
      Returns:
      The grayscale Color.

    • contrast

      public static org.bukkit.Color contrast(org.bukkit.Color bg)
      Determines whether black or white provides better contrast against a background.

      Uses standard relative luminance coefficients: 0.299R, 0.587G, 0.114B.

      Parameters:
      bg - The background Color.
      Returns:
      Color.BLACK for light backgrounds, Color.WHITE for dark.

    • complementary

      public static org.bukkit.Color complementary(org.bukkit.Color color)
      Finds the complementary color (180-degree hue shift).
      Parameters:
      color - The input color.
      Returns:
      The complementary Color.

    • splitComplementary

      public static List<org.bukkit.Color> splitComplementary(org.bukkit.Color color)
      Generates a split-complementary color scheme.
      Parameters:
      color - The base color.
      Returns:
      A list containing the base, and two colors 150 and 210 degrees away.

    • triadic

      public static List<org.bukkit.Color> triadic(org.bukkit.Color color)
      Generates a triadic color scheme.
      Parameters:
      color - The base color.
      Returns:
      A list containing three colors spaced 120 degrees apart.

    • tetradic

      public static List<org.bukkit.Color> tetradic(org.bukkit.Color color)
      Generates a tetradic (double-complementary) color scheme.
      Parameters:
      color - The base color.
      Returns:
      A list containing four colors spaced 90 degrees apart.

    • analogous

      public static List<org.bukkit.Color> analogous(org.bukkit.Color color)
      Generates an analogous color scheme.
      Parameters:
      color - The base color.
      Returns:
      A list containing the base and its two immediate neighbors (±30 degrees).

    • monochromatic

      public static List<org.bukkit.Color> monochromatic(org.bukkit.Color color)
      Generates a monochromatic color scheme by varying brightness and saturation.
      Parameters:
      color - The base color.
      Returns:
      A list of five colors derived from the base.

    • gradient

      public static List<org.bukkit.Color> gradient(org.bukkit.Color start, org.bukkit.Color end, int steps)
      Generates a list of colors representing a gradient between two colors.
      Parameters:
      start - The starting color.
      end - The ending color.
      steps - The number of colors to generate.
      Returns:
      A list of colors in the gradient.

    • palette

      public static List<org.bukkit.Color> palette(BufferedImage image, int maxColors)
      Extracts a color palette from an image using a sparse sampling method.
      Parameters:
      image - The BufferedImage to sample.
      maxColors - The maximum number of unique colors to return.
      Returns:
      A list of colors extracted from the image.