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!

Documentation

Requirements

• PHP 7.4+
• the ImageMagick extension
• a crapload of RAM, CPU power and free disk space
• image optimization utilities (optional), see psliwa/image-optimizer

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

• PNG
  • advpng
  • optipng
  • pngcrush
  • pngquant
• JPG
  • jpegoptim
  • jpegtran

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)