irydacea / wespal

Wespal, visual sprite team-coloring/recoloring tool for the Battle for Wesnoth.

Wespal

This is a small app which allows Wesnoth artists and content authors to easily preview graphics as they would be recolored by the game’s unit team coloring system, without needing to run or modify the game itself.

It provides a simple image preview functionality, as well as the option to save the results to disk for other purposes. A built-in visual palette and color range editor allows artists and coders to play around with the various possibilities offered by Wesnoth’s team coloring and generate WML code for use in add-ons.

License

Wespal as a whole is licensed under the GNU General Public License version 2, or (at your option) any later version — a copy of the GNU GPL version 2 is included in COPYING.

QuaZip is licensed under the GNU Lesser General Public License version 2.1 with a static linking exception. See src/3rdparty/quazip/COPYING for details.

KImageFormats includes code provided under a number of compatible licenses. See src/3rdparty/kimageformats/licenses/ for the individual licenses.

Installing

Windows and macOS users should use the binary packages provided on the Wespal web page — these support Windows 10 and later, and macOS 11 Big Sur and later. Users on Linux and other platforms should see the INSTALL.md file for instructions on building from source.

Windows

For Windows users, after extracting the downloaded .zip file you can move and run the contained Wespal.exe file anywhere.

The first time you launch a new version of Wespal you may see a warning like this:

Windows protected your PC

Windows Defender SmartScreen prevented an unrecognized app from starting.

To add an exception for the app, click on the More Info link, and then click on the newly-revealed Run Anyway button at the bottom.

macOS

For macOS users, after double-clicking the downloaded .dmg file, you can drag Wespal to your Applications folder.

The first time you launch a new version of Wespal you may see a warning like this:

“Wespal” can’t be opened because Apple cannot check it for malicious software.

This software needs to be updated. Contact the developer for more information.

To add an exception for the app, you need to use Finder to browse to the folder where Wespal is installed, and attempt to open it twice using right-click + Open. The second time you do this, there will be an Open button underneath the warning, which you can then click on to allow Wespal to launch.

Usage

To start Wespal, just double click the wespal executable.

You’ll be presented with an empty main window where you can choose to open an image file. Once you have opened a file, you can preview the effects of various Wesnoth recoloring systems on it. You can also generate pre-recolored copies of the original image file.

Configuration

The Tools menu allows access to the color range and palette editors, which allow you to define your own color ranges and palette editors for use in Wespal. You can also choose to generate WML code for your custom palettes and ranges, and copy it to clipboard, or simply save it to a file.

Wespal’s configuration, including any created custom palettes and ranges, is stored in a platform-dependent location:

Platform	Location
Windows	HKEY_CURRENT_USER\Software\Irydacea\Wespal (in the Registry)
macOS	$HOME/Library/Preferences/me.irydacea.Wespal.plist
Linux	$HOME/.config/Irydacea/Wespal.conf

Reporting bugs

There is an issue tracker on GitHub. Alternatively, you may post in the Wesnoth.org forum topic.

When reporting a bug, make sure to provide as much relevant information as possible, including your operating system version (e.g. Windows 10 1903) and Wespal version. If you experience issues with a specific image or palette/color range, be sure to provide those as well.

wespal's Issues

Support for multiple transforms

It may be desirable to recolour an image file by applying multiple transforms to it. For example, an image could have portions using a blue palette and others using a green palette, and both could be recoloured independently.

This may not be particularly useful at the moment since Wesnoth does not use techniques like this in mainline content, so it should be a pretty low-priority idea.

Basic support for animation frames

It would be nice to be able to open image files belonging to a single unit animation together, in order to preview the effects of colour transforms on each frame while still grouping them up in a logical and intuitive fashion.

This is somewhat connected to issue #6, which deals with switching to a MDI architecture in general, but separate. The goal would be to be able to open multiple image files either as independent units, or grouped up neatly into animations, with sliders or comboboxes to switch between frames in the same document tab.

(A crazier long term goal would be to replicate Wesnoth's animation engine but it doesn't seem particularly feasible at the moment, especially since it would 100% require us to gain the ability to consume WML.)

Use a custom widget instead of QScrollArea/ImageLabel/CompositeImageLabel combos

The current approach of using QScrollArea + specialised child widgets to display the image preview is spectacularly clunky and requires MainWindow to handle more special information about the original image and its transformed version than it really should, as well as manually resize the xImageLabel widgets according to the current zoom level. These will become major hindrances when we eventually move to an MDI model. It also makes it impossible to implement any kind of visual indication for Swipe views that spans beyond the actual image's vertical extents and into the empty vertical space around it in its view container.

Furthermore, KDE Plasma 6's Breeze style has major issues with this approach because we do not handle mouse events in the widgets themselves as we are expected to do, so in order to prevent Breeze from stealing our events, we are forced to disable the style's window dragging for the entire main window rather than just those widgets, unlike with KDE Plasma 5's Breeze — even the way we do this is by setting an undocumented internal attribute.

setProperty("_kde_no_window_grab", true);

Just yucky code all around.

It generally makes more sense to use a custom widget, or potentially QGraphicsView, to avoid issues. I already do have a prototype using a subclass of the latter in a private branch, which I want to resume work on after v0.5.0 is out.

Support for opening multiple image files (MDI)

Support for textured background previews

In practice, Wesnoth sprites are rendered on detailed digitally-painted art backgrounds composited by the game via the terrain graphics system. While striving for sprites to look good on solid colour backgrounds is generally the best idea, sometimes it's worth keeping their practical use into consideration so that they don't blend too much into terrains.

It would therefore be nice to have textured preview background options in addition to the solid colour ones. Wespal does not need to replicate Wesnoth's terrain system 1:1 for this, as the background textures can be either pre-baked (inefficient due to differing window/display sizes and resolutions) or procedurally composited just from Wesnoth's terrain base graphics, which are simple hexagon tiles.

If we went with the second approach, it would probably be best to provide a way to locate Wesnoth's data files so we don't need to ship image files with the Windows build. There could be two options in Settings > General: one to detect Wesnoth's data path from looking at currently-running processes + installed software, and another to let the user manually specify this path.

Command-line interface support

Wespal could use a batch/CLI mode for image manipulation.

There are some sub-issues to consider for this:

• Currently, custom colour ranges and palettes need to be defined in the UI as we use the QSettings interface instead of a visible configuration file. We could probably add a way to specify 'transient' (not saved) definitions in the CLI.
• Overriding output filenames/specifying output filenames on a per-task basis may be desirable. e.g.
  --input elynia.png --output RC(magenta>green)=elynia-green.png --output RC(magenta>blue)=elynia-blue.png
• It may be desirable to allow multiple transformations per image file, e.g. swap or recolour more than one palette in the image.
• WML read support would be nice, but it's definitely not worth the hassle — Wesnoth's own config class and WML parser/preprocessor suffer from super-tight coupling with the rest of the game and cannot be imported easily.
• WML write support for colour artefacts may be desirable (the Generate WML option but in CLI form).
• Responses from Wespal should be completely non-interactive so we can do with just a QCoreApplication in this mode instead of initialising the whole kitchen sink.

Krita and OpenRaster image support

Since version 0.4.0, Wespal has built-in support for XCF images using xcfplugin, borrowing code from KImageFormats. Because xcfplugin is part of the Wespal source tree, XCF support is available on all platforms without the need to rely on preinstalled Qt plugins, which in particular we cannot use on Windows anyway since: 1) Wespal is deployed as a statically-built binary; 2) hardly anybody would have Qt preinstalled.

As with previous versions, however, Wespal can also make use of other QImageIOPlugin plugins that may already be installed system-wide, which is especially convenient in KDE-based Linux or BSD operating environments. People who have KDE Plasma or KDE applications installed are likely to have KImageFormats already installed, which provides plugins for the Krita and OpenRaster image formats. These two are of particular interest for Wespal due to both being supported by Krita, which these days is probably more popular than the GIMP due to ease of use and its superior feature set for digital drawing and painting (as opposed to image manipulation).

The KImageFormats plugins for both of these formats require KArchive due to both formats actually being specially-structured zip files, with the payload being one particular file generated by the image writer, merging/flattening all layers as they would be rendered when exported to a flat format like PNG.

KArchive is a tier 1 KDE Frameworks component, which means it only depends upon Qt itself. It should be possible to integrate it into Wespal via CMake and Git submodules for platforms where it may not be already installed (Windows, macOS). If we adopt this approach, it would be tempting to do something similar with KImageFormats. We'd need a way to ensure that Windows and macOS builds don't build any KImageFormats plugins we won't ever need, though.

Wesnoth map marker colour support

Wesnoth colour ranges support a fourth colour parameter which is not used by the recolour transform but rather used by the game UI to display unit and village locations in the minimap. This parameter is not currently supported by Wespal, and if the From List option in Settings > Colour Ranges is used with four or more parameters, the extra colours are ignored. Additionally, the Generate WML option generates a colour range with the fourth parameter being a copy of the first (the mid shade).

It may make sense to add optional support for the map marker parameter, meaning that custom colour ranges shouldn't need to specify one (which also helps with old config migration) and if it is specified, it should be used instead of the mid shade in icons in the UI.

(Having the map marker parameter could also make it possible to implement other related features in the future such as displaying a preview of the unit's bars and ellipse on a textured background.)

Note: The new Settings dialog already has some elements for supporting the fourth colour range parameter, hidden by default in the dialog constructor, or commented out in the code with TODO notes attached.