chillerlan/php-imagetiler

An image tile generator. PHP 7.4+


Keywords
generator, image, maps, tile, leaflet, game-maps, google-maps, imagemagick, php-library, php7, php8, tile-generator
License
MIT

Documentation

php-imagetiler

A script for PHP 7.4+ to cut images (maps) into pieces (tiles). Based on the map tiler script by Fedik. This script will keep the proportions of the input image and generate only necessary tiles - no need for square input files!

PHP Version Support Packagist version License Continuous Integration CodeCov Packagist downloads

Documentation

Requirements

Installation

requires composer

composer.json (note: replace dev-main with a version boundary)

{
	"require": {
		"php": "^7.4 || ^8.0",
		"ext-imagick": "*",
		"chillerlan/php-imagetiler": "dev-main"
	}
}

Profit!

Usage

Use the example for live testing.

// invoke an options instance
$options = new ImagetilerOptions([
	'zoom_min'             => 0,
	'zoom_max'             => 8,
	'zoom_normalize'       => 6,
	'fill_color'           => 'transparent',
	'fast_resize'          => true,
	'optimize_output'      => true,
	// ... whatever you need
]);

// see https://github.com/psliwa/image-optimizer#configuration
$optimizer = (new OptimizerFactory([]))->get();

// invoke and run the tiler
$tiler  = new Imagetiler($options, $optimizer);
$tiler->process('/path/to/image.png', '/path/to/output/');

That's it!

Memory trouble

If you're running into issues with ImageMagick complaining about not enough space on the cache path, you might want to check the policy.xml in the ImageMagick installation path (on Windows). For your consideration: an image of 49152x49152 will generate a cache file of ~28.5GB,

Image optimizers

API

Imagetiler public methods

method return description
__construct(ContainerInterface $options = null, LoggerInterface $logger = null) - see SettingsContainerInterface and LoggerInterface. Invokes an empty ImagetilerOptions object and a Psr\NullLogger if the respective parameters aren't set.
setOptions(ContainerInterface $options) Imagetiler set options on-the-fly, called internally by the constructor
setOptimizer(Optimizer $optimizer) Imagetiler set an optimizer instance on-the-fly, called internally by the constructor
process(string $image_path, string $out_path) Imagetiler processes the given image from $image_path and dumps the output to $out_path

ImagetilerOptions properties

property type default allowed description
$tile_size int 256 positive int width/height of a single tile
$zoom_min int 0 positive int minimum zoom level
$zoom_max int 8 positive int maximum zoom level
$zoom_normalize int null positive int this zoom level represents the size of the original image. zoom levels higher than this will be upscaled, which may take some time and resources depending on the size of the input image.
$tms bool false * if set to true - the origin will be set to bottom left, +y upwards, according to Tile Map Service Specification, otherwise the origin is on the top left, +y downwards, like described by the Google Maps specification
$fill_color string '#000000' * the fill color for leftover space, can be transparent for png
$memory_limit string '-1' * see php.ini settings
$store_structure string '%1$d/%2$d/%3$d' * storage structure - can be anything. %1$d = zoom, %2$d = x, %3$d = y. see sprintf()
$fast_resize_upsample bool false * determines whether to use fast Imagick::scaleImage() (true) or slow Imagick::resizeImage() (false)
$resize_filter_upsample int Imagick::FILTER_ROBIDOUXSHARP Imagick::FILTER_* see Imagick::resizeImage() and Imagick filter constants
$resize_blur_upsample float 1.0 positive float see Imagick::resizeImage()
$fast_resize_downsample bool false * see $fast_resize_upsample
$resize_filter_downsample int Imagick::FILTER_LANCZOSRADIUS Imagick::FILTER_* see $resize_filter_upsample
$resize_blur_downsample float 1.0 positive float see $resize_blur_upsample
$tile_format string 'png' png, jpg see Imagick formats
$tile_ext string null * tile image extension - autodetected from format if none given.
$quality_jpeg int 80 0-100 quality of the saved image in jpeg format
$imagick_tmp string null * ImageMagick tmp folder
$overwrite_base_image bool false *
$overwrite_tile_image bool false *
$clean_up bool true * whether or not to delete temp images
$optimize_output bool false * enable image optimization (requires Optimizer instance)
$no_temp_baseimages bool false * whether or not to create and save temporary base images (may save resources)