Download the PHP package talesoft/phim without Composer

Phim

PHP Image Manipulation

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 [email protected].

Installation

Install via Composer.

What is finished, what needs to be done?

• [x] Color Manipulation
  • [x] RGB
  • [x] RGBA
  • [x] HSL
  • [x] HSLA
  • [x] HSV
  • [x] HSVA
  • [x] CIE XYZ
  • [x] CIE L*a*b*
  • [x] CIEDE2000 Color Comparison
• [ ] Geometry
  • [x] Basic Geometrical Shapes
  • [ ] Geometrical Math utilities per Shape
• [ ] Image Manipulation
  • [ ] Abstract Image Representation
    • [x] Lines/Straight Paths
    • [x] Polygons/Shapes
    • [ ] Curves/Circles/Ellipses/Arcs
  • [ ] Creating Images
    • [x] Image and Shape Factory
    • [ ] Transformations
    • [ ] Color-Filters (Act on ColorInterface)
    • [ ] Point-Filters (Act on PointInterface)
  • [ ] Rendering Adapters
    • [ ] GD
      • [x] 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?

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

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.

Color conversion

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

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.

We will now look at the possibilities in detail.

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.

Color information

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

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

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

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

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.

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

Merging palettes

Filtering palettes

Pre-defined filters

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

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

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. 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

Complementary Scheme

Analogous Scheme

Triadic Scheme

Split-Complementary Scheme

Tetradic Scheme

Square 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.

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

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.

Tint Scheme

Generates lighter tints of the color.

Shade Scheme

Generates darker shades of the color.

Tone Scheme

Generates less saturated tones of the 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

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

Putting it all together

Notice that you can combine and filter the result of a scheme, since they are also palettes. The result will always be a Palette instance (Even in the NameMonochromaticScheme, so beware, you'll use your naming functionality completely)

You can combine all that stuff above into some awesome color operations.

This will yield the colors blue and navy. Reducing the required range on filterSimilarColors will yield more and different blue-ish colors.

Using a color in HTML

The colors mostly convert to their best CSS representation automatically when casted to a string.

Given that some browsers don't support hsl() CSS colors, it's best to always convert to RGB or RGBA before casting to a string.

It's not automatically done to give you the ability to also use the hsl() writing style. We also don't know, if CSS will implement further color constructors in the future.

Notice that most literals you pass to Color::get return an RgbaColor-instance, as most systems (hex, int, names) are designed based on RGB values.

Geometry, Image manipulation etc.

As you can see, this README will get pretty big if I keep it up now, so I'll stop here and slowly work on better structured documentation.

You can see a quick example of how image manipulation will work in tests/how-to.php

Examples, Code, Contribution, Support

If you have questions, problems with the code or you want to contribue, either consult the examples, the code, write an issue or send me an E-Mail. You can also contribute via pull requests, just send them in.

For a list of all available color names click here.

If you like my work, it helped you in some way, eased up work for you or anything like that, think about supporting me by spending me a coffee.

Credits

• http://wikipedia.com
• http://www.easyrgb.com
• http://www.tigercolor.com/color-lab/color-theory/color-theory-intro.htm
• https://gist.github.com/mjackson/5311256
• https://raw.githubusercontent.com/RnbwNoise/ImageAffineMatrix/master/ImageAffineMatrix.php
• https://github.com/Qix-/color-convert/blob/master/conversions.js