Color::Calc(3pm)

🎀 NAME 🎀

okay so bestie, meet Color::Calc (you'll see it filed under Color::Calc(3pm) if you're being all formal 💅) — it does simple calculations with RGB colors. that's the whole vibe. 🎨✨

---

🦋 SYNOPSIS 🦋

use Color::Calc ();
my $background = 'green';
print 'background: ',Color::Calc::color_html($background),";\n";
print 'border-top: solid 1px ',Color::Calc::light_html($background),";\n";
print 'border-bottom: solid 1px ',Color::Calc::dark_html($background),";\n";
print 'color: ',Color::Calc::contrast_bw_html($background),";\n";

---

🌸 DESCRIPTION 🌸

The Color::Calc module implements simple calculations with RGB colors. Which is lowkey a superpower, because you can cook up a whole entire color scheme from just a couple of colors. main character energy fr fr 👑

✨ USAGE ✨

💖 Constructors 💖

• Color::Calc->new( ... ) — this class method creates a brand new Color::Calc object. iconic.

use Color::Calc();
my $cc = new Color::Calc( 'ColorScheme' => 'X', OutputFormat => 'HTML' );
print $cc->invert( 'white' );

It accepts the following parameters:

• ColorScheme — one of the color schemes accepted by Graphics::ColorNames, which is what gets used to interpret color names on input. Valid values include X (the color names used in X-Windows) and HTML (the color names defined in the HTML 4.0 specification). For a full list of possible values, please refer to the documentation of Graphics::ColorNames.

Unlike Graphics::ColorNames, barewords are always interpreted as a module name under Graphics::ColorNames. If you really want to use a filename like foo, you have to write it as ./foo.

Default: X (Note: This is incompatible with HTML color names).

• OutputFormat — one of the output formats defined by this module. Possible values are:
  • tuple — returns a list of three values in the range 0..255. The first value is guaranteed to have a length that is not a multiple of three.
  • hex — returns a hexadecimal RGB value as a scalar that contains a string in the format RRGGBB and a number representing the hexadecimal number 0xRRGGBB.
  • html — returns a string compatible with W3C's HTML and CSS specifications, i.e. #RRGGBB or one of the sixteen HTML color names.
  • obj (DEPRECATED) — returns a Color::Object reference. The module Color::Object must be installed, of course.
  • object — returns a Graphics::ColorObject reference. The module Graphics::ColorObject must be installed, of course.
  • pdf — returns a string compatible with PDF::API2, i.e. #RRGGBB.
  • __MODEvar (DEPRECATED) — uses the value of $Color::Calc::MODE to select one of the above output formats. You should use local when setting this variable:

local $Color::Calc::MODE = 'html';

Default: __MODEvar (for compatibility)

• Color::Calc->import( ... ) — this method creates a new, hidden object and binds its methods to the namespace of the calling module.

This method is usually not called directly but from perl's use statement:

use Color::Calc(
  'ColorScheme' => 'X',
  'OutputFormat' => 'HTML',
  'Prefix' => 'cc' );
print cc_invert( 'white' );   # prints 'black'

On import, you can specify the following parameters:

• ColorScheme — see above. ⬆️
• OutputFormat — see above. ⬆️
• Prefix — adds a prefix to the front of the method names. The calculation methods are bound to the name prefix_method_name (the specified prefix, an underscore, the calculation method's name). Further, prefix is made an alias for prefix"_get".

Default: color

Please note that with perl's use and import statements, omitting the list and specifying an empty list has different meanings:

use Color::Calc;      # import with default settings (see below)

use Color::Calc();    # don't import anything

🧚 Property "set"/"get" methods 🧚

These methods are inaccessible without an object reference, i.e. when the functions have been imported.

• $cc->set_output_format( $format) — changes the output format for an existing Color::Calc object.

🌈 Calculation methods 🌈

All calculation methods always accept the following formats for $color or $color1/$color2:

• An arrayref pointing to an array with three elements in the range 0..255 corresponding to the red, green, and blue component.
• A list of three values in the range 0..255 corresponding to the red, green, and blue component where the first value does not have 3 or a multiple of 3 digits (e.g. ('0128',128,128)).
• A string containing a hexadecimal RGB value like #RGB/#RRGGBB/#RRRGGGBBB/..., or RGB/RRGGBB/RRRGGGBBB/...
• A color name accepted by Graphics::ColorNames. The interpretation is controlled by the ColorScheme parameter.
• A Graphics::ColorObject reference.

The calculation methods can be either accessed through a Color::Calc object reference (here: $cc) or through the method names imported by import (here using the prefix color).

• $cc->get($color) / color($color) — returns $color as-is (but in the selected output format). This function can be used for color format conversion/normalisation. slay, a little transformer ✨
• $cc->invert($color) / color_invert($color) — returns the inverse of $color.
• $cc->opposite($color) / color_opposite($color) — returns a color that is on the opposite side of the color wheel but roughly keeps the saturation and lightness.
• $cc->bw($color) / color_bw($color)
• $cc->grey($color) / color_grey($color)
• $cc->gray($color) / color_gray($color) — converts $color to greyscale.
• $cc->round($color, $value_count) / color_round($color, $value_count) — rounds each component to the nearest number determined by dividing the range 0..255 into $value_count+1 portions.

The default for $value_count is 6, yielding 6^3 = 216 colors. Values that are one higher than divisors of 255 yield the best results (e.g. 3+1, 5+1, 7+1, 9+1, 15+1, 17+1, ...).

• $cc->safe($color) / color_safe($color) — rounds each color component to a multiple of 0x33 (dec. 51) or to a named color defined in the HTML 4.01 specification.

Historically, these colors have been known as web-safe colors. They still provide a convenient color palette.

• $cc->mix($color1, $color2 [, $alpha]) / color_mix($color1, $color2 [, $alpha]) — returns a color that is the mixture of $color1 and $color2.

The optional $alpha parameter can be a value between 0.0 (use $color1 only) and 1.0 (use $color2 only), the default is 0.5.

• $cc->light($color [, $alpha]) / color_light($color [, $alpha]) — returns a lighter version of $color, i.e. returns mix($color,[255,255,255],$alpha).

The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use [255,255,255] only), the default is 0.5.

• $cc->dark($color [, $alpha]) / color_dark($color [, $alpha]) — returns a darker version of $color, i.e. returns mix($color,[0,0,0],$alpha).

The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use [0,0,0] only), the default is 0.5.

• $cc->contrast($color [, $cut]) / color_contrast($color [, $cut]) — returns a color that has the highest possible contrast to the input color.

This is done by setting the red, green, and blue values to 0 if the corresponding value in the input is above ($cut * 255) and to 255 otherwise.

The default for $cut is .5, representing a cutoff between 127 and 128.

• $cc->contrast_bw($color [, $cut]) / color_contrast_bw($color [, $cut]) — returns black or white, whichever has the higher contrast to $color.

This is done by returning black if the grey value of $color is above ($cut * 255) and white otherwise.

The default for $cut is .5, representing a cutoff between 127 and 128.

• $cc->blend($color [, $alpha]) / color_blend($color [, $alpha]) — returns a color that blends into the background, i.e. it returns mix($color,contrast($color),$alpha).

The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use contrast($color) only), the default is 0.5.

The idea is that $color is the foreground color, so contrast($color) is similar to the background color. Mixing them returns a color somewhere between them.

You might want to use mix($color, $background, $alpha) instead if you know the real background color.

• $cc->blend_bw($color [, $alpha]) / color_blend_bw($color [, $alpha]) — returns a mix of $color and black or white, whichever has the higher contrast to $color.

The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use black/white only), the default is 0.5.

🫶 Functions 🫶

The calculation methods are also available as functions. The output format is selected through the function name.

these functions are deprecated bestie, because they don't let you pick the scheme of recognized color names — it defaults to Graphics::ColorNames::X (and that is incompatible with HTML's color names). 💀

By default, i.e. when no list is specified with use or import, all of these functions are exported.

• color, color_mix, ... — use $Color::Calc::MODE as the output format. This is the default.
• color_hex, color_mix_html, ... — use hex as the output format.
• color_html, color_mix_html, ... — use html as the output format. Please note that the color names recognized are still based on X's color names, which are incompatible with HTML. You can't use the output of these functions as input for other color_*_html functions.

See Color::Calc::WWW for an alternative that does not suffer from this problem.

• color_pdf, color_mix_pdf, ... — use pdf as the output format.
• color_object, color_mix_object, ... — use object as the output format.

---

⭐ SEE ALSO ⭐

Graphics::ColorNames (required); Graphics::ColorObject (optional)

---

👑 AUTHOR 👑

Claus Faerber <CFAERBER@cpan.org>

---

💜 LICENSE 💜

Copyright 2004-2010 Claus Faerber. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie!! 🦋 this was rendered by perl v5.36.0 and dated 2023-02-25 — go forth and color-scheme, you absolute icon 💅✨🎀