{"id":"csqrl/colour-utils","name":"colour-utils","scope":"csqrl","platform":"roblox","description":"Colour manipulation utility for Roblox","version":"1.3.1","latest":"1.3.1","versions":["1.0.3","1.1.0","1.1.1","1.2.0","1.3.0","1.3.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":["The package archive does not include its license text; the license is declared in its manifest metadata."],"licenseVerified":false,"dependencies":{},"integrity":"51eacc69564b9e2444d08b3d3fb2a6189305418fade9785321a2d8e875f1cd42","likes":0,"downloads":0,"install":"forest install csqrl/colour-utils","url":"https://forest.dev/p/roblox/csqrl/colour-utils","files":"https://api.forest.dev/ai/package/roblox/csqrl/colour-utils/files","readme":"\n\n[ci status]: https://github.com/csqrl/colour-utils/actions\n[latest release]: https://github.com/csqrl/colour-utils/releases/latest\n[library url]: https://www.roblox.com/library/6573728888\n[npm package]: https://npmjs.com/package/@rbxts/colour-utils\n[rojo]: https://rojo.space\n[roblox-ts]: https://roblox-ts.com\n[wally]: https://github.com/upliftgames/wally\n\n\n\n[w3c contrast]: https://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast-contrast\n[wcag contrast ratio]: https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests\n[colorblendy]: https://github.com/shazow/colorblendy\n[w3c perceived brightness]: https://www.w3.org/TR/AERT/#color-contrast\n\n\n\n[shield ci]: https://github.com/csqrl/colour-utils/actions/workflows/unit-tests.yml/badge.svg\n[shield gh release]: https://img.shields.io/github/v/release/csqrl/colour-utils?label=latest+release&style=flat\n[shield npm release]: https://img.shields.io/npm/v/@rbxts/colour-utils?style=flat\n[shield wally release]: https://img.shields.io/endpoint?url=https://runkit.io/clockworksquirrel/wally-version-shield/branches/master/csqrl/colour-utils&color=blue&label=wally&style=flat\n\n# ColourUtils\n\n[![CI][shield ci]][ci status]\n[![GitHub release (latest by date)][shield gh release]][latest release]\n[![NPM release (latest)][shield npm release]][npm package]\n[![Wally release (latest)][shield wally release]][latest release]\n\nColourUtils provides handy methods for manipulating colours for your UI in Roblox.\n\n## Installation\n\n### Rojo\n\nYou can use git submodules to clone this repo into your project's packages directory:\n\n```sh\n$ git submodule add https://github.com/csqrl/colour-utils packages/colour-utils\n```\n\nOnce added, simply sync into Studio using the [Rojo][rojo] plugin.\n\n#### 0.5.x\n\nDownload/clone this repo on to your device, and copy the `/src` directory into your packages directory.\n\n### [Roblox-TS][roblox-ts]\n\nInstall the [`@rbxts/colour-utils`][npm package] package using npm or yarn.\n\n```sh\n$ npm i @rbxts/colour-utils\n$ yarn add @rbxts/colour-utils\n$ pnpm i @rbxts/colour-utils\n```\n\n### [Wally][wally]\n\nAdd `colour-utils` to your `wally.toml` and run `wally install`\n\n```toml\n[package]\nname = \"user/repo\"\ndescription = \"My awesome Roblox project\"\nversion = \"1.0.0\"\nlicense = \"MIT\"\nauthors = [\"You (https://github.com/you)\"]\nregistry = \"https://github.com/UpliftGames/wally-index\"\nrealm = \"shared\"\n\n[dependencies]\nColourUtils = \"csqrl/colour-utils@^1.1.0\"\n```\n\n```sh\n$ wally install\n```\n\n### Manual Installation\n\nGrab a copy [from the Roblox Library (Toolbox)][library url], or download the latest `.rbxm/.rbxmx` file from [the releases page][latest release] and drop it into Studio.\n\n## Usage\n\nHere's a quick example of how ColourUtils can be used:\n\n```lua\nlocal ColourUtils = require(path.to.ColourUtils)\nlocal TextLabel = path.to.awesome.TextLabel\n\nlocal Background = ColourUtils.Hex.fromHex(\"#00A2FF\")\nlocal Foreground = ColourUtils.Emphasise(Background, 0.9)\n\nTextLabel.BackgroundColor3 = Background\nTextLabel.TextColor3 = Foreground\n```\n\nHere's how you might use ColourUtils to generate an \"accessible\" text colour, [as recommended by the W3C accessibility guidelines][w3c contrast]:\n\n```lua\nlocal ColourUtils = require(game.ServerScriptService.ColourUtils)\nlocal TextLabel = game.StarterGui.ScreenGui.TextLabel\n\nlocal function GetAccessibleTextColour(background: Color3): Color3\n    local darkThemeText = Color3.new(1, 1, 1)\n    local lightThemeText = ColourUtils.Lighten(Color3.new(), .13)\n\n    local contrastRatio = ColourUtils.GetContrastRatio(background, darkThemeText)\n\n    return contrastRatio >= 3 and darkThemeText or lightThemeText\nend\n\nTextLabel.BackgroundColor3 = ColourUtils.Hex.fromHex(\"#00a2ff\")\nTextLabel.TextColor3 = GetAccessibleTextColour(TextLabel.BackgroundColor3)\n```\n\n# Documentation\n\n## API Overview\n\n- `ColourUtils.Darken(colour: Color3, coefficient: number): Color3`\n- `ColourUtils.Emphasise(colour: Color3, coefficient: number, threshold: number?): Color3`\n- `ColourUtils.GetContrastRatio(foreground: Color3, background: Color3): number`\n- `ColourUtils.GetLuminance(colour: Color3): number`\n- `ColourUtils.GetPerceivedBrightness(colour: Color3): number`\n- `ColourUtils.Invert(colour: Color3): Color3`\n- `ColourUtils.isDark(colour: Color3): boolean`\n- `ColourUtils.isLight(colour: Color3): boolean`\n- `ColourUtils.Lighten(colour: Color3, coefficient: number): Color3`\n- `ColourUtils.Rotate(colour: Color3, angle: number): Color3`\n\n**Hex**\n\n- `ColourUtils.Hex.fromHex(hex: string): Color3`\n- `ColourUtils.Hex.toHex(colour: Color3): string`\n\n**Int**\n\n- `ColourUtils.Int.fromInt(int: number): Color3`\n- `ColourUtils.Int.toInt(colour: Color3): number`\n\n**Blend**\n\n- `ColourUtils.Blend.Burn(background: Color3, foreground: Color3): Color3`\n- `ColourUtils.Blend.Dodge(background: Color3, foreground: Color3): Color3`\n- `ColourUtils.Blend.Multiply(background: Color3, foreground: Color3): Color3`\n- `ColourUtils.Blend.Overlay(background: Color3, foreground: Color3): Color3`\n- `ColourUtils.Blend.Screen(background: Color3, foreground: Color3): Color3`\n\n**Palette**\n\n- `ColourUtils.Palette.Analogous(base: Color3): Array<Color3>`\n- `ColourUtils.Palette.Complementary(base: Color3): Array<Color3>`\n- `ColourUtils.Palette.Monochromatic(base: Color3): Array<Color3>`\n- `ColourUtils.Palette.SplitComplementary(base: Color3): Array<Color3>`\n- `ColourUtils.Palette.Tetradic(base: Color3): Array<Color3>`\n- `ColourUtils.Palette.Triadic(base: Color3): Array<Color3>`\n- `ColourUtils.Palette.Vibrant(swatches: Array<Color3>, options: VibrantOptions?): Color3`\n\n## API Methods\n\n### Darken\n\n> Darkens a colour.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to darken\\\n> coefficient (`number`) - A multiplier in the range of 0-1\n>\n> #### Returns\n>\n> colour `Color3` - The darkened `Color3`\n\n### Lighten\n\n> Lightens a colour.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to lighten\\\n> coefficient (`number`) - A multiplier in the range of 0-1\n>\n> #### Returns\n>\n> colour `Color3` - The lightened `Color3`\n\n### Emphasise\n\n> Automatically darken a light colour or lighten a dark colour, depending on its luminance.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to affect\\\n> coefficient (`number`) - A multiplier in the range of 0-1\\\n> threshold (`number`) - The threshold for luminance (default: `0.5`)\n>\n> #### Returns\n>\n> colour `Color3` - The lightened or darkened `Color3`\n\n### GetLuminance\n\n> Get the relative brightness of a given `Color3`, using the [formula provided by WCAG][wcag contrast ratio].\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to get luminance of\n>\n> #### Returns\n>\n> luminance (`number`) - The relative luminance of the given `Color3`, in the range of 0-1\n\n### GetPerceivedBrightness\n\n> Calculates the perceived brightness of a given Color3, using the [formula provided by W3C][w3c perceived brightness].\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to calculate the perceived brightness of\n>\n> #### Returns\n>\n> brightness (`number`) - The perceived brightness of the given `Color3`, in the range of 0-1\n\n### GetContrastRatio\n\n> Calculates the contrast ratio between two colours, using the [formula provided by WCAG][wcag contrast ratio].\n>\n> #### Arguments\n>\n> background (`Color3`) - A `Color3` value representing the background\\\n> foreground (`Color3`) - A `Color3` value representing the foreground\n>\n> #### Returns\n>\n> ratio (`number`) - The contrast ratio of two two given > colours, in the range of 0-21.\n\n### Invert\n\n> Inverts a colour - White becomes black, black becomes white, etc.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to invert\n>\n> #### Returns\n>\n> colour (`Color3`) - The inverted `Color3`\n\n### Rotate\n\n> Rotates the hue of a colour by the specified number of degrees - Rotating a colour 180° would be the same as inverting a colour.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to rotate\\\n> angle (`number`) - The angle (in degrees) to rotate the hue by (usually a number between 0-360°)\n>\n> #### Returns\n>\n> colour (`Color3`) - A `Color3` with its hue rotated\n\n### isDark\n\n> Determines if a colour is a dark colour.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to analyse\n>\n> #### Returns\n>\n> isDark (`boolean`) - A boolean representing if the tested `Color3` is a dark colour\n\n### isLight\n\n> Determines if a colour is a light colour.\n>\n> #### Arguments\n>\n> colour (`Color3`) - The `Color3` to analyse\n>\n> #### Returns\n>\n> isLight (`boolean`) - A boolean representing if the tested `Color3` is a light colour\n\n## Hex\n\nHex is a submodule which enables conversion between Hex colour strings (e.g. `#8697F6`) and `Color3` values.\n\n### fromHex\n\n> Converts a hex string into a `Color3`. This method accepts hex strings of any length (but will only respect the first 6 characters); with or without a preceding hash (`#`).\n>\n> #### Arguments\n>\n> hex (`string`) - A hex colour string\n>\n> #### Returns\n>\n> colour (`Color3`) - The `Color3` representation of the given hex colour\n\n### toHex\n\n> Converts a `Color3` into a hex value. Note that this method does not prepend a hash (`#`) to the beginning of the string.\n>\n> #### Arguments\n>\n> colour (`Color3`) - A `Color3` to convert to hex\n>\n> #### Returns\n>\n> hex (`string`) - The resulting hex code of the given `Color3`\n\n## Int\n\nLike the Hex submodule, Int allows for conversion between integers (e.g. `8820726` or `0x8697F6`) and `Color3` values.\n\n### fromInt\n\n> Converts an integer into a `Color3`.\n>\n> #### Arguments\n>\n> integer (`number`) - An integer representing a colour\n>\n> #### Returns\n>\n> colour (`Color3`) - The `Color3` representation of the given hex colour\n\n### toInt\n\n> Converts a `Color3` into an integer value.\n>\n> #### Arguments\n>\n> colour (`Color3`) - A `Color3` to convert to an integer\n>\n> #### Returns\n>\n> int (`number`) - The resulting integer of the given `Color3`\n\n## Blend\n\nThe blend submodule provides a way of applying blending operations (as you'd expect to be able to use in applications such as Photoshop) to two `Color3`s.\n\n**Big shoutout to @shazow** is required, as the maths for these blending modes are borrowed from their [@shazow/colorblendy][colorblendy] project.\n\n### Burn\n\n> Applies a burn filter to two `Color3`s.\n>\n> #### Arguments\n>\n> background (`Color3`) - The \"bottom\" `Color3` to blend\\\n> foreground (`Color3`) - The \"top\" `Color3` to blend\n>\n> #### Returns\n>\n> result (`Color3`) - A `Color3` resulting from blending `background` with `foreground`\n\n### Dodge\n\n> Applies a dodge filter to two `Color3`s.\n>\n> #### Arguments\n>\n> background (`Color3`) - The \"bottom\" `Color3` to blend\\\n> foreground (`Color3`) - The \"top\" `Color3` to blend\n>\n> #### Returns\n>\n> result (`Color3`) - A `Color3` resulting from blending `background` with `foreground`\n\n### Multiply\n\n> Applies a multiply filter to two `Color3`s.\n>\n> #### Arguments\n>\n> background (`Color3`) - The \"bottom\" `Color3` to blend\\\n> foreground (`Color3`) - The \"top\" `Color3` to blend\n>\n> #### Returns\n>\n> result (`Color3`) - A `Color3` resulting from blending `background` with `foreground`\n\n### Overlay\n\n> Applies a overlay filter to two `Color3`s.\n>\n> #### Arguments\n>\n> background (`Color3`) - The \"bottom\" `Color3` to blend\\\n> foreground (`Color3`) - The \"top\" `Color3` to blend\n>\n> #### Returns\n>\n> result (`Color3`) - A `Color3` resulting from blending `background` with `foreground`\n\n### Screen\n\n> Applies a screen filter to two `Color3`s.\n>\n> #### Arguments\n>\n> background (`Color3`) - The \"bottom\" `Color3` to blend\\\n> foreground (`Color3`) - The \"top\" `Color3` to blend\n>\n> #### Returns\n>\n> result (`Color3`) - A `Color3` resulting from blending `background` with `foreground`\n\n## Palette\n\nThe palette submodule provides methods for generating colour palettes and operations relating to theming.\n\n### Analogous\n\n> Returns two nearby colours on the colour wheel, when given a base Color3.\n>\n> #### Arguments\n>\n> base (`Color3`) - The Color3 used as a \"starting point\" for determining the nearby colours\n>\n> #### Returns\n>\n> results (`Array<Color3>`) - Two Color3s located near the base Color3\n\n### Complementary\n\n> Returns the complementing colour to the given Color3. This should yield the same results as `Invert()` or `Rotate(..., 180)`.\n>\n> #### Arguments\n>\n> base (`Color3`) - The Color3 to find the complement of\n>\n> #### Returns\n>\n> results (`Array<Color3>`) - An array containing a single Color3 representing the complement of the base Color3. It is returned as an array for consistency with the other \"harmony\" methods\n\n### Monochromatic\n\n> Returns a lighter and darker shade of the passed Color3. This should yield the same results as `Lighten(..., .5)` and `Darken(..., .5)`.\n>\n> #### Arguments\n>\n> base (`Color3`) - The Color3 used as a base for the resulting palette\n>\n> #### Returns\n>\n> results (`Array<Color3>`) - Two Color3s; one lighter, one darker than the passed base Color3\n\n### SplitComplementary\n\n> Similarly to the Analogous and Complementary methods, SplitComplementary finds the complement of the base Color3, and returns two Color3s near to the complement.\n>\n> #### Arguments\n>\n> base (`Color3`) - The Color3 used as a base for the resulting palette\n>\n> #### Returns\n>\n> results (`Array<Color3>`) - Two Color3s which are nearby to the complement of the base Color3\n\n### Tetradic\n\n> Given a base Color3, the Tetradic harmony method will return three complementing colours which form a \"rectangle\" on the colour wheel.\n>\n> #### Arguments\n>\n> base (`Color3`) - The Color3 used as a base for the resulting palette\n>\n> #### Returns\n>\n> results (`Array<Color3>`) - Three complementary colours, resulting from the tetradic forumla\n\n### Triadic\n\n> Given a base Color3, the Triadic harmony method will return two Color3s which are equal distance from the base Color3 on the colour wheel. This forms an \"equilateral triangle\" on the colour wheel.\n>\n> #### Arguments\n>\n> base (`Color3`) - The Color3 used as a base for the resulting palette\n>\n> #### Returns\n>\n> results (`Array<Color3>`) - Two Color3s which are equal distance from the base Color3\n\n### Vibrant\n\n> Returns the \"most vibrant\" colour, given an array of Color3s.\n>\n> #### Arguments\n>\n> swatches (`Array<Color3>`) - An array of Color3s to analyse\\\n> options (`VibrantOptions?`) - Optional configuration for adjusting target values (see below for defaults)\n>\n> #### Types\n>\n> ```lua\n> type VibrantOptions = {\n>     TargetLuminance: number? = .49,\n>     TargetSaturation: number? = 1,\n>     TargetValue: number? = .8,\n> }\n> ```\n>\n> #### Returns\n>\n> result (`Color3`) - The \"most vibrant\" Color3 from the given array of Color3s\n","readmeBorrowedFrom":{"version":"1.1.0","source":"wally"},"readmeTruncated":false}