Games::Simutrans::Image - An abstraction of a PNG file for Simutrans


version 0.01


    use Games::Simutrans::Image;

    my $image = Games::Simutrans::Image->new(file => '/tmp/example.png');
    $image->read( { save => 1 } );


This module uses colors as described in the Imager::Color documentation. The values for hue, saturation, value, and alpha likewise. If you are copying values from your favorite graphic editing program, be sure you are using the correct range values or you will notice confusing behavior.


player_color ($type, $index)

Returns either a primary (standard) player color (when type is 'std') or an alternate player color (when type is 'alt'). The index value should be 0..7. The return value is an object of type Imager::Color. For a complete description of player colors, see

Additionally, the type 'menu' with index 0..4 is for menu grays; the types 'day' and 'night' with index 0..9 are the special day/night bright colors.

mapcolor ($index)

Returns a Simutrans map color, with index 0..223. The return value is an object of type Imager::Color.The special map colors are defined at



Sets or returns the full pathname of the associated .PNG image file. Ordinarily set at or shortly after creating the object.


The Imager object which represents the image itself. This may be undef or may not exist if the 'read' method has not been used.


The modification date/time of the .PNG image file, as retrieved Perl's -M file test operator.


The width of the image, in pixels.


The height of the image, in pixels.

xmax, ymax

The maximum subimage grid indices in the x and y dimensions, as accumulated by the 'record_grid_coordinate' method.


The imputed tilesize dimension (e.g., 32, 64, 128, 192, 256) for this .PNG file; see 'record_grid_coordinate' below. This is a cached value, and is set by the guess_tilesize method, which in turn is automatically invoked by the read method. The flush method will force a recomputation when read is called again.


Nonzero if the .PNG image has been modified to have actual transparency or is believed to (by virtue of its lower-left pixel being transparent; because of Simutrans's graphic design, the far lower-left and lower-right triangular areas of any given subimage cell should be blank). Legacy .PNG files for Simutrans used a special light-blue color (#e7ffff) in lieu of actual transparency.


new ( file => '/path/to/file' )

Creates a new Image object. Ordinarily, and optionally, only the file attribute will be set. The file itself is not read until the read method is invoked.

read ( $params )

Actually reads the .PNG file. The optional hash of parameters may include:


set to zero to discard the Imager object for the image data; otherwise it will be saved in the image attribute.


sets or overrides the file attribute of the object

Note that the file will not be re-read unless it has been modified on disk (see the modified attribute) or unless the save parameter is set.


Frees the memory associated with the image attribute by undefining any Imager object. Also undef's the 'modified' attribute.


Changes the image's legacy pseudo-transparent light-blue color into actual transparency.

record_grid_coordinate ($x, $y)

Makes a note that grid coordinate (x,y) was invoked by a .dat file in the current pakset. Because the .dat files which refer to .png files in Simutrans definitions do not explicitly state the grid size (e.g., 32x32 or 128x128), it must be inferred by examining the entire pakset and making an educated guess based on the maximum grid coordinate requested after reading the entire pakset.

The only other way to impute this information would be to attempt to interpret the pakset's make-files, a task which is beyond the scope of this Perl module. Further comments exist in the source code which may shed additional light on the situation.


Once the width and height (in pixels) of the image are known (usually by calling the read method), and once at least one grid coordinate has been recorded by record_grid_coordinate, this method takes a best-guess at the tile size used in the file.

subimage ($x, $y)

Returns an Imager object which is only the extracted cell (subimage) of the .PNG file, based on the 'tilesize' attribute.

replace_rgb ($constants)

This replaces each pixel of the given 'from' color to the 'to' color. NOTE: The replace_ methods modify the object's image attribute.

The constants parameter is a hash reference with these keys:


An object of type Imager::Color


An object of type Imager::Color

replace_hue ($constants)

This replaces pixels which match the given hue. The constants parameter is a hash reference with these keys:


The hue of existing pixels to match


A threshold, or range, plus or minus from from_hue, to match. Use 0 for only an exact hue match.


The new hue to use.

replace_hue_sat ($constants)

As replace_hue but with the additional constants parameter:


The new saturation value to set

replace_color_range ($constants)

Replaces a range of colors, based on ranges of their hue and value, with constants being:

from_hue, from_hue_thresh
from_value, from_value_thresh

The hue and value to match, with a threshold (range) for each.


The color with which the matched colors will be replaced.

change_to_player_colors ($opts)

Change a range of colors to player, or alternate player, colors. Options include the following (with alternate spellings for the options in parentheses):

colortype (type)

'std' for standard player colors, 'alt' for alternate. The special color ranges 'menu' for Simutrans menu colors, 'day' and 'night' for the day/night colors may also be used.

hue, hue_thresh

The hue of the new colors to match, and the threshold (plus/minus) for matching.


The number of different color levels to be created. If not specified, defaults to 8 for standard player and alternate color sets.


The first level of the color set to be created. Defaults to 0.


An offset (as a fraction from -1..1) which will be added to the Value component for each level of the output colors

change_to_player_colors ($opts)

Change player, or alternate player, colors, to a range of new colors. Options include the following (with alternate spellings for the options in parentheses):

colortype (type)

As with change_from_player_colors

levels, offset, level_offset

Affects the number of output colors, and their Value components, similar to change_from_player_colors


The single hue of the new colors to be created


The saturation of the new colors to be created


Instead of specifying hue and sat, you may specify a Simutrans mini-map color (0..223).

write ($filename)

Writes the Imager object to a file at a given path, returning the value from its write() method.


William Lindley <>


Copyright 2021, William Lindley


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.