mike42 / gfx-php

The pure PHP graphics library

gfx-php - The pure PHP graphics library

This library implements input, output and processing of raster images in pure PHP, so that image processing extensions (Gd, Imagick) are not required.

This allows developers to eliminate some portability issues from their applications.

Features

• Format support includes PNG, GIF, BMP and the Netpbm formats (See docs: File formats).
• Support for scaling, cropping, format conversion and colorspace transformations (See docs: Image operations).
• Pure PHP: This library does not require Gd, ImageMagick or GraphicsMagick extensions.

Quick start

Requirements

• PHP 7.0 or newer.
• zlib extension, for reading PNG files.

Installation

Install gfx-php with composer:

composer install mike42/gfx-php

Basic usage

The basic usage is like this:

<?php
use Mike42\GfxPhp\Image;
$img = Image::fromFile("colorwheel256.png");
$img -> write("test.gif");

Further reading

• Read of the documentation at gfx-php.readthedocs.io
• See the examples/ sub-folder for snippets.

Contributing

This project is open to all kinds of contributions, including suggestions, documentation fixes, examples, formats and image processing algorithms.

Some ideas for improvement listed in the issue tracker. Code contributions must be releasable under the LGPLv3 or later.

Scope

As a small project, we can't do everything. In particular, gfx-php is not likely to ever perform non-raster operations:

• vector image formats (PDF, SVG, EPS, etc).
• anything involving vector fonts

Acknowledgements

This repository uses test files from other projects:

• BMP Suite by Jason Summers.
• PyGIF test suite by Robert Ancell.
• pngsuite by Willem van Schaik.

Similar projects

• Imagine, which wraps available libraries.

gfx-php's Issues

my hosting says you have a virus

test/resources/pygif/max-width.gif: BC.Gif.Exploit.Agent-1425366.Agent

Add HHVM to CI

I noticed a regression in 0.4.1 where HHVM no longer worked (hhvm-3.21 there).

Both hhvm-3.21 and hhvm-3.27 are likely to work with minor changes to error handling. Later versions drop PHP support, so this is expected to be a fairly temporary part of the project.

Hosted documentation

Find a way to automatically generate and host documentation with each release.

BMP decoder

Currently, we can write BMP files, but cannot read them.

Implement a BMP decoder. This will also require RLE decoding, and some logic to map the variety of colour modes to simple RGB.

Best test suite available is bmpsuite, which appears to be under a suitable license (see README here).

Image files generated by this program are not covered by this license, and are
in the public domain (except for the embedded ICC profiles).

Conversion between PBM, PGM, PPM images

We have the ability to read and write all three of these formats.

• Use the file extension of the output filename to detect the best output format
• Convert color space before writing output

ANSI output

It's currently possible to convert a black/white raster image to text.

Write an output codec for printing an image as ANSI (for command-line use).

• Expand current text output to convert any image to plaintext using unicode box characters.
• Create palettes for terminal colors
• Create output codec for converting an image to text with embedded terminal codes

Reading first image from GIF file

Read raster data and palette from a GIF file into an indexed raster image.

If multiple images are stored in the GIF, then retrieve the first one only.

Need indexed raster image implementation at #14

Test file collections:

• imagetestsuite
• jburkardt's test files

BMP image output length and filesize do not match

The BMP output is not understood by some readers, which report that the file is invalid.

For example, taking this sample image:

<?php
require_once(__DIR__ . "/../vendor/autoload.php");

use Mike42\GfxPhp\Image;

// Write abc.png out as BMP
$img = Image::fromFile(dirname(__FILE__). "/resources/abc.png");
$img -> write("abc.bmp");

The resulting BMP is understood by some readers, but gimp and ImageMagick convert it back to PNG like this:

$ convert abc.bmp abc.png
convert-im6.q16: length and filesize do not match `abc.bmp' @ warning/bmp.c/ReadBMPImage/842.

$ file abc.bmp 
abc.bmp: PC bitmap, Windows 3.x format, 40 x 40 x 24
$ hexdump -C abc.bmp 
00000000  42 4d 00 00 00 00 00 00  00 00 00 00 00 00 28 00  |BM............(.|
00000010  00 00 28 00 00 00 28 00  00 00 01 00 18 00 00 00  |..(...(.........|
00000020  00 00 00 00 00 00 01 00  00 00 01 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 ff ff  ff ff ff ff ff ff ff ff  |................|
00000040  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
*
00000120  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ec  |................|
00000130  c3 df b0 00 7a b0 00 7a  b0 00 7a b0 02 7b b4 0e  |....z..z..z..{..|
00000140  81 bc 28 8e cc 5c a9 e7  b2 d6 fe fe fe ff ff ff  |..(..\..........|
00000150  ff ff ff ff ff ff ff ff  ff c3 ea ec 00 a7 b0 00  |................|
00000160  a7 b0 00 a7 b0 00 a7 b0  00 a7 b0 00 a7 b0 00 a7  |................|
00000170  b0 00 a7 b0 c7 eb ed ff  ff ff ed ed c3 b6 b6 00  |................|
00000180  d6 d6 73 ff ff ff ff ff  ff ff ff ff ff ff ff ff  |..s.............|
...

Writer for monochrome GIF images

Write GIF output.

Because we don't have support for indexed raster images, save as monocrome, since it will align with a hard-coded palette of 256 entries (0, 0, 0) to (255, 255, 255).

PHP 8.2 compatibility errors

Two known issues from using this library on newer PHP versions.

• "Creation of dynamic property Mike42\GfxPhp\Codec\Common\DataBlobInputStream::$data is deprecated" in DataBlobInputStream.
• "Use of "self" in callables is deprecated" in eg. BlackAndWhiteRasterImage.php, line 20.

LZW decoder rejects valid file with large dictionary

The test file 4095-codes.gif is valid, but will cause the LZW decoder in gfx-php to throw an Exception.

There is a skipped test called test_4095_codes. Fix the LZW decoder and enable this test.

Image quantization

• Implement median-cut quantization to generate palettes from a higher color-depth image.
• Update GIF output to use this when you attempt to save an image with > 256 colors.

Blocked by #14.

Read image from PNG (ignore transparency)

Read raster data a from a PNG file into the most appropriate raster image format.

For the initial implementation, flatten RGBA data to RGB by mixing with white.

Test file collections:

• pngsuite
• imagetestsuite

Build system, dependency changes

Changes necessary to get build/test rolling again for next release.

• Upgrade development dependencies, possibly find modern alternative to php_codesniffer

        "phpunit/phpunit": "^6.5",
        "squizlabs/php_codesniffer": "^3.3.1",
        "phpbench/phpbench": "@dev"

• Raise minimum PHP version for next release
• Write GitHub actions build to replace Travis build
• Replace build status badge in repo

Basic palette management

• Method to flatten the alpha channel of a palette by mixing with a background color N/A, removed support for alpha in palette values.
• Method to invert colors
• Method to eliminate un-used values from palette
• Update GIF output to remove un-used values from palette before writing
• Method to find the closest palette entry to an RGBA value

Project rename

Project is currently image-php, which is confusingly similar to the existing php-image package.

Rename to gfx-php and fix breakages (easier while it's new).

Implement indexed raster image

Add a new RasterImage implementation to access an indexed raster image.

It needs to have colors stored via a numeric index. The index will be re-sizable up to some per-instance limit, or 256 colors by default. The palette color space should be 4 byte RGBA.

Logical order to implement this:

• Implementation for raster data storage
• Methods to allocate, query palette. Throw an exception if it becomes full.
• New method toIndexed() returning a new indexed raster image from existing implementations
• Update GIF output to convert to indexed image and write using the given palette if it has < 256 colors (otherwise still convert to greyscale)
• Add generators for web-safe, monochrome, pure black and white palettes
• Method to map image from one palette to another, eg, convert from true color to the web-safe palette
• Update GIF output to map to web colors if there is > 256.

Writer for 24bpp BMP files

When an image is saved with a 'bmp' extension, encode it as a 24 bit per pixel BMP image.

The file should be readable by ImageMagick, GIMP, and bmptoppm.

Writer for 24bpp PNG files

Write an encoder which can create PNG files (RGB format, compress with zlib).

PPM Binary (Portable Pixel-Map) image format implementation

This is a color bitmap format.

• Format spec: http://netpbm.sourceforge.net/doc/ppm.html
• External test files: http://people.sc.fsu.edu/~jburkardt/data/ppmb/ppmb.html
• Should generate a small HSL colorwheel to include in the repository: http://www.imagemagick.org/Usage/color_basics/#colorwheel

WBMP encoder and decoder

This is a monochrome format which was designed by the web but is not widely used. It is mentioned in the PHP GD docs, works with the ImageMagick command-line.

The format is a header around uncompressed 1-bit raster data, which is apparently understood directly by some printers.

• Spec: www.wapforum.org/what/technical/SPEC-WAESpec-19990524.pdf
• Test files: No known test suite. Convert any file with convert foo.png foo.wbmp

Add benchmarks

Add a sample of benchmarks to the code via phpbench.

This should enable us to evaluate the performance impact of changes over time.