PHPackages                             talesoft/phim - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. talesoft/phim

ActiveLibrary[Image & Media](/categories/media)

talesoft/phim
=============

An image and color manipulation and processing library for PHP

1.0.6(5y ago)2958.2k—0%8[1 issues](https://github.com/Talesoft/phim/issues)MITPHPPHP >=5.6

Since Jul 20Pushed 5y ago4 watchersCompare

[ Source](https://github.com/Talesoft/phim)[ Packagist](https://packagist.org/packages/talesoft/phim)[ Docs](http://phim.talesoft.codes)[ RSS](/packages/talesoft-phim/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (9)Dependencies (1)Versions (10)Used By (0)

Phim
====

[](#phim)

#### PHP Image Manipulation

[](#php-image-manipulation)

---

What is Phim?
-------------

[](#what-is-phim)

Phim is an image manipulation library for PHP. It includes a powerful color manipulation library and image processing abstraction for several adapters, including GD and Imagick.

This library is still in development. If you're interested in helping out, write an e-mail to .

---

Installation
------------

[](#installation)

Install via Composer.

```
$ composer require talesoft/phim
```

---

What is finished, what needs to be done?
----------------------------------------

[](#what-is-finished-what-needs-to-be-done)

- Color Manipulation
    - RGB
    - RGBA
    - HSL
    - HSLA
    - HSV
    - HSVA
    - CIE XYZ
    - CIE L\*a\*b\*
    - CIEDE2000 Color Comparison
- Geometry
    - Basic Geometrical Shapes
    - Geometrical Math utilities per Shape
- Image Manipulation
    - Abstract Image Representation
        - Lines/Straight Paths
        - Polygons/Shapes
        - Curves/Circles/Ellipses/Arcs
    - Creating Images
        - Image and Shape Factory
        - Transformations
        - Color-Filters (Act on `ColorInterface`)
        - Point-Filters (Act on `PointInterface`)
    - Rendering Adapters
        - GD
            - Basic rendering
            - Fully compatible rendering
        - Imagick
            - Basic rendering
            - Fully compatible rendering
        - Phim (library-intern, own rendering)
            - Basic rendering
            - Fully compatible rendering
    - Image File Parsing
        - Parse PNG
        - Parse JPG
        - Parse GIF
        - Parse BMP
        - Parse WebP
        - Parse animated GIF
        - Parse ICO
        - Parse SVG
        - Parse PDF
        - Parse PSD
        - Parse AI (Possible?)
        - Parse EPS
        - Parse GhostScript

---

Can I use this in production?
-----------------------------

[](#can-i-use-this-in-production)

You can use the color manipulation in production already, it's tested and stable. Everything else is very experimental and shouldn't be used in production anywhere right now.

---

API
===

[](#api)

Color parsing
-------------

[](#color-parsing)

Phim can handle many different color formats and modify them on a very detailed level.

Any color Phim provides will be of type `Phim\ColorInterface`. They usually have a higher-level class which defines what color space the color is in.

Phim is designed so that you don't need to care about what color space your color is in. If you need a different one to modify the color, just use one of the `to{Space}`-functions.

It all starts with the `Color::get()` function, which will take a mixed argument and provide a valid color of type `ColorInterface` for you.

You can pass color names, integer values, hex-strings and function-literals freely.

```
use Phim\Color;

//By name
Color::get('red'); //RgbColor(255,0,0)
Color::get(Color::MAROON); //RgbColor(128, 0, 0)

//By hex string
Color::get('#00ff00'); //RgbColor(0, 255, 0)
Color::get('#00f'); //RgbColor(0, 0, 255)
Color::get('#000a'); //RgbaColor(0, 0, 0, 0.1)

//By integer
Color::get(0x00ff00); //RgbColor(0, 255, 0)
Color::get(0x00ff00ff); //RgbaColor(0, 255, 0, 1.0)

//By function literals
Color::get('rgb(14, 24, 100)'); //RgbColor(14, 24, 100)
Color::get('hsl(120, .5, 1.0)'); //HslColor(120, 0.5, 1.0)
Color::get('lab(50, 40, 22)'); //LabColor(50, 40, 22)

//Percent-values are allowed and will scale automatically
Color::get('rgba(50%, 100, 20%, 50%)'); //RgbaColor(127.5, 100, 51, 0.5)
Color::get('hsl(50%, 50%, 1.0)'); //HslColor(180, 0.5, 1.0)

//You can also just create them manually (better performance)

use Phim\Color\RgbColor;
use Phim\Color\HslaColor;

$myRgbColor = new RgbColor(0, 100, 0);
$myHslaColor = new HslaColor(120, .5, .1, 1.0);
```

---

Color conversion
----------------

[](#color-conversion)

Every color in Phim can be converted to any other color space instantly.

```
$color->toHsl()->getLightness();

$color->toRgb()->getGreen();

$color->toLab()->getL();
```

Here's a list of the supported color spaces with their respective getters/setters for their values

- RgbColor (`toRgb()`)
    - `getRed() | setRed($red)`
    - `getGreen() | setGreen($green)`
    - `getBlue() | setBlue($blue)`
    - `toAlpha() -> RgbaColor`
- RgbaColor (`toRgba()`)
    - `getRed() | setRed($red)`
    - `getGreen() | setGreen($green)`
    - `getBlue() | setBlue($blue)`
    - `getAlpha() | setAlpha($alpha)`
    - `toOpaque() -> RgbColor`
- HslColor (`toHsl()`)
    - `getHue() | setHue($hue)`
    - `getSaturation() | setSaturation($saturation)`
    - `getLightness() | setLightness($lightness)`
    - `toAlpha() -> HslaColor`
- HslaColor (`getHsla()`)
    - `getHue() | setHue($hue)`
    - `getSaturation() | setSaturation($saturation)`
    - `getLightness() | setLightness($lightness)`
    - `getAlpha() | setAlpha($alpha)`
    - `toOpaque() -> HslColor`
- HsvColor (`toHsv()`)
    - `getHue() | setHue($hue)`
    - `getSaturation() | setSaturation($saturation)`
    - `getValue() | setValue($value)`
    - `toAlpha() -> HsvaColor`
- HsvaColor (`toHsva()`)
    - `getHue() | setHue($hue)`
    - `getSaturation() | setSaturation($saturation)`
    - `getLightness() | setLightness($lightness)`
    - `getAlpha() | setAlpha($alpha)`
    - `toOpaque() -> HsvColor`
- XyzColor (`toXyz()`)
    - `getX() | setX($x)`
    - `getY() | setY($y)`
    - `getZ() | setZ($z)`
    - `toAlpha() -> RgbaColor`
- CIE L\*a\*b\* (`toLab()`)
    - `getL() | setL($l)`
    - `getA() | setA($a)`
    - `getB() | setB($b)`
    - `toAlpha() -> RgbaColor`

With this system, you can easily manipulate colors through a really expressive API. Let's have a quick look.

```
$lightTurquoise = Color::get('blue')
    ->toRgb()
        ->setGreen(50) //Mix some green in
    ->toHsl()
        ->setLightness(.6) //Make it lighter
    ->toAlpha()
        ->setAlpha(.4) //Add 40% transparency
    ->toRgba(); //Make sure it's an RGBA color in the end

echo $lightTurquoise; //Will print `rgba(50,90,255,0.4)`
```

We will now look at the possibilities in detail.

---

Color modification
------------------

[](#color-modification)

Color modification is done by converting to specific color spaces and modifying their values. e.g. the HSL color space is very handy for reducing lightness or increasing saturation of a color.

The `Phim\Color`-class will shorten most operations for you. You don't need to convert the color to any space when using the `Color`-class static methods, it automatically converts them to the space it needs for the operation.

Notice that these will almost always change the return type of your color. Convert back and forth to the format you require in your application, double-conversions have a really low memory profile.

```
use Phim\Color;

//Lightening and darkening (Added, not multiplied)
Color::lighten($color, .4);
Color::darken($color, .2);

//Get the complementary color (180° rotated hue)
Color::complement($color);

//Convert to grayscale
Color::grayscale($color);

//Fade in or out (Added, not multiplied)
Color::fade($color, .1);
Color::fade($color, -.1);

//Mix two colors
Color::mix($color, $mixColor);

//Inverse a color
Color::inverse($color);

//Saturate/Desaturate
Color::saturate($color, .4);
Color::desaturate($color, .2);
```

---

Color information
-----------------

[](#color-information)

The `Color` static class also contains useful utilities that help receiving information of the color you pass to them.

```
//Get the hue range the color resides in (basically, "what base color is this color"?)
//Supported hue ranges are: RED, YELLOW, GREEN, CYAN, BLUE and MAGENTA.
Color::getColorHueRange(Color::get('rgba(80, 0, 0)')); //Color::HUE_RANGE_RED

//Gets the hexadecimal representation of a color.
//Notice that it will turn an Alpha-color into a 4-channel hexadecimal string, because it can also parse them.
//If you want to use the hex value in CSS or HTML, use `toRgb()` on the color before to strip the alpha channel
Color::toHexString($color);

//Gets the integer representation of a color (including support for alpha channel)
Color::toInt($color);

//Get the name of a color. Many colors don't have names, it will return a hex-representation in this case
Color::toName($color);
```

---

Color comparison
----------------

[](#color-comparison)

Through the implementation of CIE XYZ, CIE L\*a\*b\* and the CIEDE2000 standard for color comparison, you can compare colors visually easily

```
$red = Color::get('red'); //rgb(255, 0, 0)

Color::getDifference($red, Color::get('blue')); //52.878674140461

Color::getDifference($red, Color::get('maroon')); //25.857031489394

Color::getDifference($red, Color::get('rgb(250, 0, 0)')); //1.0466353226581
```

To compare colors with a tolerance, you can use the `equals`-method

```
$red = Color::get('red');

foreach ($otherColors as $otherColor) {

    //Using a tolerance of 2, so the maximum difference between the colors is 2
    if (Color::equals($red, $otherColor, 2))
        echo "Well, this is almost the same color!";
}
```

If that's not already enough, lets go on! Phim got more cool stuff.

---

Color palettes
--------------

[](#color-palettes)

Basically a small helper class to keep colors together, acts like a normal array. Passed colors get converted automatically.

The maximum size can be limited with the second parameter to `Palette`.

```
use Phim\Color\Palette;

$palette = new Palette([
    'red',
    'green',
    'blue',
    'yellow',
    'white',
    'black'
]);

$palette[] = 'rgb(120, 35, 56)';

$palette[0]; //RgbColor(255, 0, 0)
$palette[6]; //RgbColor(120, 35, 56)
```

You can manipulate palettes with the static methods of the `Palette`-class

### Merging palettes

[](#merging-palettes)

```
use Phim\Color\Palette;

$palette = Palette::merge($somePalette, $someOtherPalette);
```

### Filtering palettes

[](#filtering-palettes)

```
use Phim\Color\Palette;
use Phim\ColorInterface;

//Filter all colors that have a lightness below .4
$palette = Palette::filter(function(ColorInterface $color) {

    return $color->getHsl()->getLightness() >= .4;
});
```

### Pre-defined filters

[](#pre-defined-filters)

Filter all colors based on a hue range. You'll only get colors in the given hue range.

```
use Phim\Color\Palette;

//Would only yield colors that have a red-ish hue
$palette = Palette::filterByHueRange($palette, Color::HUE_RANGE_RED);
```

Filter out colors that *look* similar (Uses CIEDE2000 for color comparison)

```
use Phim\Color\Palette;

//Colors would need to have a difference of at least 4 to all other colors
//in the palette in order to be put in the result collection.
$palette = Palette::filterSimilarColors($palette, 4);
```

---

Color Schemes
-------------

[](#color-schemes)

Schemes are pre-defined, generated palettes. They take a base color and generate a bunch of related colors out of them. For more information, you may read [this](http://www.tigercolor.com/color-lab/color-theory/color-theory-intro.htm). This is also where I ripped the following images from.

Notice that any scheme is always a palette like above, too.

Phim can generate the following schemes for you:

### Schemes with fixed size

[](#schemes-with-fixed-size)

#### Complementary Scheme

[](#complementary-scheme)

[![Complementary Scheme](https://camo.githubusercontent.com/1aeae991094adce14a54cd34f9574dcb9eb364e194328b124a139ccacfa2ad58/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f436f6d706c656d656e746172792e676966)](https://camo.githubusercontent.com/1aeae991094adce14a54cd34f9574dcb9eb364e194328b124a139ccacfa2ad58/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f436f6d706c656d656e746172792e676966)

```
use Phim\Color\Scheme\ComplementaryScheme;

$colors = new ComplementaryScheme($baseColor); //2 colors
```

#### Analogous Scheme

[](#analogous-scheme)

[![Analogous Scheme](https://camo.githubusercontent.com/785791e2aab3f20e4d27e4f551b9d5e15baca595f5b5fb0ccb1743b6d99f1952/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f416e616c6f676f75732e676966)](https://camo.githubusercontent.com/785791e2aab3f20e4d27e4f551b9d5e15baca595f5b5fb0ccb1743b6d99f1952/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f416e616c6f676f75732e676966)

```
use Phim\Color\Scheme\AnalogousScheme;

$colors = new AnalogousScheme($baseColor); //3 colors
```

#### Triadic Scheme

[](#triadic-scheme)

[![Triadic Scheme](https://camo.githubusercontent.com/404213c1e7e4884e7fb6c91d2a439b40c21d8b862854c496f722da61e182573d/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f54726961642e676966)](https://camo.githubusercontent.com/404213c1e7e4884e7fb6c91d2a439b40c21d8b862854c496f722da61e182573d/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f54726961642e676966)

```
use Phim\Color\Scheme\TriadicScheme;

$colors = new TriadicScheme($baseColor); //3 colors
```

#### Split-Complementary Scheme

[](#split-complementary-scheme)

[![Split-Complementary Scheme](https://camo.githubusercontent.com/295216c6de7d4531ac39f81ed03bf55202d0ce20a8ce9cb96ffd9c4d921b6112/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f53706c6974436f6d706c656d656e746172792e676966)](https://camo.githubusercontent.com/295216c6de7d4531ac39f81ed03bf55202d0ce20a8ce9cb96ffd9c4d921b6112/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f53706c6974436f6d706c656d656e746172792e676966)

```
use Phim\Color\Scheme\SplitComplementaryScheme;

$colors = new SplitComplementaryScheme($baseColor); //3 colors
```

#### Tetradic Scheme

[](#tetradic-scheme)

[![Tetradic Scheme](https://camo.githubusercontent.com/ca24a6b9e9f25c6ac4bc194f99b615fe70a60db3727dd95f86f1f170b74c311e/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f5465747261642e676966)](https://camo.githubusercontent.com/ca24a6b9e9f25c6ac4bc194f99b615fe70a60db3727dd95f86f1f170b74c311e/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f5465747261642e676966)

```
use Phim\Color\Scheme\TetradicScheme;

$colors = new TetradicScheme($baseColor); //4 colors
```

#### Square Scheme

[](#square-scheme)

[![Square Scheme](https://camo.githubusercontent.com/d5bb75b64327de54e372be351ac6e4d7f8d6f1886e6589dceacfdc51024ef425/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f5371756172652e676966)](https://camo.githubusercontent.com/d5bb75b64327de54e372be351ac6e4d7f8d6f1886e6589dceacfdc51024ef425/687474703a2f2f7777772e7469676572636f6c6f722e636f6d2f496d616765732f5371756172652e676966)

```
use Phim\Color\Scheme\SquareScheme;

$colors = new SquareScheme($baseColor); //4 colors
```

#### Named Monochromatic Scheme

[](#named-monochromatic-scheme)

Generates 3 shades and 3 tints of a color that you can access via a method. The second parameter is `step` which defines the amount of darkening/lightening between each color.

```
use Phim\Color\Scheme\NamedMonochromaticScheme;

$colors = new NamedMonochromaticScheme($baseColor, .3); //7 colors

$colors->getDarkestShade();
$colors->getDarkerShader();
$colors->getDarkShade();
$colors->getBaseColor();
$colors->getLightTint();
$colors->getLighterTint();
$colors->getLightestTint();
```

### Generated schemes (dynamic size)

[](#generated-schemes-dynamic-size)

These take an `amount` and `step`. `amount` specifies the total amount of colors to generate. Specifying `5` will yield a palette with 5 colors (Including the base-color, mostly)

#### Hue Rotation Scheme

[](#hue-rotation-scheme)

Adds adjacent colors in the hue circle.

The code below would generate 5 colors, the base color and 4 further colors each rotated by +5° in hue.

```
use Phim\Color\Scheme\HueRotationScheme;

$colors = new HueRotationScheme($baseColor, 5, 5); //5 colors, +5° hue per color
```

#### Tint Scheme

[](#tint-scheme)

Generates lighter tints of the color.

```
use Phim\Color\Scheme\TintScheme;

$colors = new TintScheme($baseColor, 6, .3); //6 colors, +.3 lightness per color
```

#### Shade Scheme

[](#shade-scheme)

Generates darker shades of the color.

```
use Phim\Color\Scheme\ShadeScheme;

$colors = new ShadeScheme($baseColor, 6, .3); //6 colors, -.3 lightness per color
```

#### Tone Scheme

[](#tone-scheme)

Generates less saturated tones of the color.

```
use Phim\Color\Scheme\ToneScheme;

$colors = new ToneScheme($baseColor, 6, .3); //6 colors, -.3 saturation per color
```

If you are not sure what a scheme will end up, you can always dump a visual representation of the whole palette by using

```
Palette::toHtml($myPalette);
```

This will print a little table containing all colors in the palette including basic information about the colors.

To roll your own scheme, you have many possibilities, the most simple one is extending `Phim\Color\SchemeBase` or `Phim\Color\Scheme\ContinousSchemeBase`

```