The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Games-Simutrans-Pakset-0.02
River stage zero No dependents
++
/ Games::Simutrans::Image

NAME

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

VERSION

version 0.01

SYNOPSIS

    use Games::Simutrans::Image;

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

DESCRIPTION

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.

FUNCTIONS

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 https://simutrans-germany.com/wiki/wiki/en_SpecialColors.

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 https://simutrans-germany.com/wiki/wiki/en_GoodsDef#MapColor_Parameter.

ATTRIBUTES

file

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

image

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

modified

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

width

The width of the image, in pixels.

height

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.

tilesize

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.

is_transparent

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.

METHODS

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:

save

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

file

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.

flush

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

make_transparent

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 Image.pm source code which may shed additional light on the situation.

guess_tilesize

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:

from_color

An object of type Imager::Color

to_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:

from_hue

The hue of existing pixels to match

from_hue_thresh

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

new_hue

The new hue to use.

replace_hue_sat ($constants)

As replace_hue but with the additional constants parameter:

new_sat

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.

to_color

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.

levels

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

offset

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

level_offset

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

hue

The single hue of the new colors to be created

sat

The saturation of the new colors to be created

map

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.

AUTHOR

William Lindley <wlindley@wlindley.com>

COPYRIGHT

Copyright 2021, William Lindley

LICENSE

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

SEE ALSO

Games::Simutrans::Pak