File formats¶

Input formats
- PNG
- GIF
- Netpbm Formats
Output formats
- PNG
- GIF
- BMP
- Netpbm Formats

Input formats ¶

Files are read from a file or URL by using the Image::fromFile() function:

use Mike42\GfxPhp\Image;
$tux = Image::fromFile("tux.png")

If the your image is not being read from a file, then Image::fromBlob() can load it from a binary string:

use Mike42\GfxPhp\Image;
$tuxStr = "...";
$tux = Image::fromBlob($tuxStr, "tux.png");

In either case, the input format is determined using the file’s magic number.

PNG ¶

The PNG codec is used where the input has the png file extension.

All valid PNG files can be read, including:

RGB or RGBA images
Indexed images
Monochrome images, from 1 to 16 bits per pixel
Interlaced images

This library currently has limited support for transparency, and will discard any alpha channel from a PNG file when it is loaded.

GIF ¶

The GIF codec is used where the input has the gif file extension. Any well-formed GIF file can be read, but there are some limitations:

If a GIF file contains multiple images, then only the first one will be loaded
If a transparent color is present, then this will be mixed to white

A GIF image will always be loaded into an omstamce of IndexedRasterImage, which makes palette information available.

Netpbm Formats ¶

The Netpbm formats are a series of uncompressed bitmap formats, which can represent most types of image. These formats can be read by gfx-php:

PNM:	This is a file extension only. Files carrying `.pnm` extension can carry any of the below formats.
PPM:	This is a color raster format. A PPM file is identified by the P6 magic number, and will be loaded into an instance of `RgbRasterImage`.
PGM:	This is a monochrome raster format. A PGM file is identified by the P5 magic number, and will be loaded instance of `GrayscaleRasterImage`.
PBM:	This is a 1-bit bitmap format. A PBM file is identified by the P4 header, and loaded into an instance of `BlackAndWhiteRasterImage`.

Each of these formats has both a binary and text encoding. gfx-php only supports the binary encodings at this stage.

Output formats ¶

When you write a RasterImage to a file, you need to specify a filename. The extension on this file is used to determine the desired output format.

There is currently no mechanism to write a file directly to a string.

PNG ¶

The PNG format is selected by using the png file extension when you call RasterImage::write().

$tux -> write("tux.png");

This library will currently output PNG files as RGB data. If you write to PNG from an instance of RgbRasterImage, then no conversion has to be done, so the output is significantly faster.

GIF ¶

The GIF format is selected by using the gif file extension.

$tux -> write("tux.gif");

This format is limited to using a 256-color palette.

If your image is not an IndexedRasterImage, then it is indexed when you write.
If the image uses more than 256 colors, then it will be converted to an 8-bit RGB representation (3 bits red, 3 bits green, 2 bits blue), which introduces some distortions.

When you are creating GIF images, then you can avoid these conversions by using a IndexedRasterImage with a palette of fewer than 256 colors.

There is no encoder for multi-image GIF files at this stage.

BMP ¶

The BMP format is selected by using the bmp file extension.

$tux -> write("tux.bmp");

This library will currently output BMP files using an uncompressed 24-bit RGB representation of the image.

Netpbm Formats ¶

The Netpbm formats can be used for output. Each format is identified by their respective file extension:

$tux -> write("tux.ppm");
$tux -> write("tux.pgm";
$tux -> write("tux.pbm");

Since each of these formats has a different raster data representation, you should be aware that

PPM:	For this output format, the file is converted to a `RgbRasterImage` and typically written with a 24 bit color depth. In some cases, a 48 bit color depth will be used.
PGM:	The file is converted to a `GrayscaleRasterImage` and written with a depth of 8 or 16 bits per pixel.
PPM:	The file is converted to a `BlackAndWhiteRasterImage` and written with 1 bit per pixel.

If you want to avoid these conversions, then you should use the pnm extension to write your files. Since files with this extension can hold any of the above formats, the output encoder will avoid converting the raster data where possible.

$tux -> write("tux.pnm");