PaletteTool User Documentation

Copyright 2018

Table of Contents

1. Introduction

2. Color palettes and PaletteTool

3. PaletteTool's Graphical User Interface

3.1. Overview

3.2. Image Viewer

3.3. Menu Bar

3.4. Tool Bar

A. Supported Palette Types

B. Formatted String Variables

1.Introduction

PaletteTool is a software application for MS Windows for generating, importing, and conversion of color palettes. Conversion can be performed “in batch” for multiple files. Palettes can be also saved as .gif-files. In addition, PaletteTool can load or generate images, apply a new color map to them, and if wanted, export them as a color cycling .gif-file. The following palette formats are supported for im- and export

• GIMP palette (*.gpl);

• Adobe Photoshop palette (*.aco);

• Fractint palette (*.map);

• Microsoft palette (*.pal);

• A hexadecimal color list (*.hextxt).

The following formats can be exported only, but not read:

• HTML (as a table) (*.html);

• CSS color list (*.css);

• JavaScript list (*.js).

The following methods for generating palettes are implemented:

• A cosinus-based approach as described in Inigo Quilez' article about palettes.

The following methods for generating images are implemented:

• Mandelbrot fractals;

• Julia fractals.

This document is the user manual for PaletteTool, version 1.0. It contains information that explains what PaletteTool was designed for and how to use it.

PaletteTool was tried to be designed to please its users. We hope for a feedback on this. Please give us a notice about your experience with PaletteTool using the contact possibilities located at http://www.krajzewicz.de/palettetool/. We would also be very lucky to be informed about errors within the application or mistakes in the documentation.

This user documentation is structured as following: Chapter 2 gives an introduction into color palettes and what PaletteTool is for. Chapter 3 describes the interaction possibilities using PaletteTool's graphical user interface. The document closes with appendices that lists the supported palette types and the available formatting options.

2.Color palettes and PaletteTool

Initially, computer images (“bitmaps”) had a limited number of colors. Each pixel was not holding a value for red, green, and blue (RGB) as nowadays, but was rather pointing to a colour in a colour table. Such image formats, where each pixel points to an entry in a colour palette are called indexed images. The colour table itself is called “palette”, “colour map” or “colour palette”.

As usual, different formats for storing colour palettes were developed. PaletteTool's main application is to convert between different formats.

Nowadays, colour palettes can be found in .gif-images, which store indexed colour images. As known, .gif-images are capable to store animations as well. Generating images by colourcycling — rotating the colour map — is the second main application for PaletteTool.

In addition, PaletteTool can generate palettes and can generate as well example images, mainly for testing colour cycling.

3.PaletteTool's Graphical User Interface

3.1.Overview

The main window is divided into two sections, an image viewer part and a colour map viewer part. Additionally, a menu bar and a tool bar exist that allow further interaction. The following image shows this graphical interface, its usage is described in the following.

Figure3.1.Main PaletteTool window

3.2.Image Viewer

After starting the application or if an image was closed (see “Close Image”), the viewer stays empty. As soon as an image was loaded (see “Open Image”) or the user has generated an image (see “Image Generation”), the image is displayed within the viewer.

The user can zoom into (see “Zoom In (25%)”) the image and out (see “Zoom Out (25%)”) of image. The view can be restored to its original size (see “Normal Size”) .

3.3.Menu Bar

3.3.1.The “File” Menu

The File menu allows you to load and save images and colour palettes from/to different formats. Additionally, a loaded palette can be exported as a gif-image. The File menu contains the following entries:

• Open Palette…: a window opens which allows you to choose a palette-file to load. After selecting the file and clicking “OK” or double-clicking the file within the window, the palette will be loaded and shown in the palette viewer.

• Save Palette: If a palette was loaded and modified you can save the changed palette by choosing this item. If the palette was not saved before, a window will be shown where you can select the folder to save the palette into and define the palette's file name. As well, this dialog enables you to select the format under which you want the palette to be saved under.

• Save Palette As…: Choosing this item will show a window where you can select the folder to save the palette into and its name. As well, this dialog enables you to select the format under which you want the palette to be saved under.

• Export Palette…: A dialog is opened that allows you to name the file to save and to define the format to use. Afterwards, a further dialog, specific for the selected export format, is opened, see “Exporting Palettes”.

• Open Image…: A window opens which allows you to choose an image file to load. After selecting the file and clicking “OK” or double-clicking the file within the window, the image will be loaded and shown in the image viewer after being computed.

• Save Image: If an image was loaded and modified you can save the changes by choosing this item. If the image was not saved before, a window will be shown where you can select the folder to save the image into and define the image's file name.

• Save Image As…: Choosing this item will show a window where you can select the folder to save the image into and define the image's file name.

• Close Image…: Choosing this item will remove the image from the image viewer. If the image was generated or modified, you will be asked whether you want to save the image before.

• Exit: Quits the application

3.3.1.1.Exporting Palettes

Most palette formats are fixed. Yet, when exporting palettes to .css or to .js-files, additional format options can be set. This is also true when generating .gif-images that show the palettes. The individual options are described in the following.

3.3.1.1.1.Exporting Palettes to JSON

When exporting palettes to .js/.json-files the following dialog will be shown.

Figure3.2.JSON export dialog

You can define the following:

• Variable name: the name of the variable under which the palette will be exported; you may either give the name of the variable, or use one of the format strings as shown in Format String Variables.

• Entry format: sets the format used to store the palette; when choosing “hex”, the palette entries will be saved as hex-triplets (with a ‘#’ appendix), e.g. “#ffff00” for yellow; when choosing “triplet”, each palette entry will be stored as an array of the R, G, B value, e.g. [255, 255, 0] for yellow.

3.3.1.1.2.Exporting Palettes to CSS

When exporting palettes to .css-files the following dialog will be shown.

Figure3.3.CSS export dialog

You can define the following:

• Entry name: defines the CSS-selectors under which the colors will be stored; you may use the format strings as shown in Format String Variables; please note that the name should include the ‘%i’ field for setting the index of each palette entry;

• Attribute: defines the CSS-attribute to set.

3.3.1.1.3.Exporting Palettes to GIF

When exporting palettes as .gif-images the following dialog will be shown.

Figure3.4.GIF export dialog

You can define the following:

• Cell Width: defines the width of a cell (area showing a single colour) in pixels;

• Cell Height: defines the height of a cell in pixels;

• Column Number: defines the number of columns.

3.3.2.The “Image” Menu

Here, you can find items for generating images, converting images to indexed images and for exporting a colorcycling animation

• Generate: Opens a sub-menu where the method to use for image generation can be chosen; see Image Generation.

• Convert: Opens a sub-menu that contains actions for converting the image to indexed colors or to a grayscale image, see Image Conversion.

• Export Animation: Opens a menu that controls how the image shall be exported to a colourcycling gif-image, see Export Animation.

3.3.2..Image Generation

Currently, PaletteTool offers two ways to generate an image. They will be described in the following.

3.3.2..1.Mandelbrot

When choosing the option “Image -> Generate -> Mandelbrot” the following dialog will be shown.

Figure3.5.Mandelbrot generation dialog

When selecting the view of the Mandelbrot fractal, you can use the mouse to move the area to generate when keeping the left mouse button pressed, similar to setting the X- and Y-coordinate of the center (see below). You can as well use the cursor keys (left/right/up/down). Additionally, you can zoom into / out of the area by moving the mouse wheel or using the keys ‘+’ and ‘-’. This can be as well controlled using the scale-field (see below).

The dialog offers additional controls for changing the selected area and setting the size of the image to generate:

• Center X: sets the X-coordinate of the Mandelbrot area to generate;

• Center Y: sets the Y-coordinate of the Mandelbrot area to generate;

• Scale: sets the zoom of the Mandelbrot area to generate;

• Width: sets the width of the image to generate;

• Height: sets the height of the image to generate.

For further information about Julia sets, see the Wikipedia article about Mandelbrot sets.

3.3.2..2.Julia

When choosing the option “Image -> Generate -> Julia” the following dialog will be shown.

Figure3.6.Julia generation dialog

When selecting the view of the Julia fractal, you can use the cursor keys (left/right/up/down) to change the real/imaginary (X(Y) part of the center pixel.

The dialog offers additional controls for changing the selected area and setting the size of the image to generate:

• Center X: sets the X-coordinate of the Julia area to generate;

• Center Y: sets the Y-coordinate of the Julia area to generate;

• Width: sets the width of the image to generate;

• Height: sets the height of the image to generate.

For further information about Julia sets, see the Wikipedia article about Julia sets.

3.3.2.2.Image Conversion

PaletteTool can convert not indexed RGB-images into indexed images for applying colour palettes to them.

3.3.2.2.1.Greyscale

The loaded image will be converted into a greyscale image. The brightness of each pixel is set to the average of the pixel's original RGB components. The palette will be set to a greyscale palette.

3.3.2.2.2.Indexed

The loaded image will be quantized and converted into an indexed 8bit-image. The palette will be obtained from the quantized colors of the image.

3.3.2.3.Export Animation

This option allows to generate gifs animated by colorcycling. It can only be chosen, if an indexed image has been loaded or if a loaded image was converted to an indexed one.

When selected, a window that allows to select a filename to save the animation to is shown. After entering or selecting a valid filename, the following dialog is shown:

Figure3.7.Animation export dialog

Here, you can define the start and the end indices between which the palette shall be rotated. Additionally, the animation speed stored in the .gif file can be changed.

3.3.3.The “Palette” Menu

The “Palette” menu contains entries for generating palettes and for converting palettes in batch.

• Generate: Opens a sub-menu where the method to use for palette generation can be chosen; see Palette Generation.

• Batch Convert…: Opens a dialog which allow to select palettes for batch conversion and controls how that should be done, see Batch Convert.

3.3.3.1.Palette Generation

Currently, PaletteTool included the possibility to generate palettes using a cosinus-based approach. It is described in the following.

3.3.3.1.1.Using Cosini

When choosing the option “Palette -> Generate… -> using Cosini” the following dialog will be shown.

Figure3.8.Dialog for generating a palette using Cosini

You can select a pre-given default. In addition, you can change the parameters of the cosinus functions for the R, G, and B components.

For further information about generating palettes this way, see Inigo Quilez' article about palettes.

3.3.3.2.Batch Convert

This option allows you to convert multiple palettes in batch. When selecting “Palette -> Batch Convert…”, the following dialog is shown:

Figure3.9.Dialog for batch conversion

This dialog allows you to select the individual files as well as folders. When selecting folders, all found palette files stored within them will be converted. Whether a file is a palette file or not is determined by the file's extension. Using the “Assume file format:” option, you can force PaletteTool to convert only certain types of palettes. The “Convert to:” option allows you to set the format to convert the palettes to. The extension used by this file format will be automatically set. When exporting, some palette formats can have additional options, see Exporting Palettes. They can be set using the “Extended Settings” option.

3.3.4.The “View” Menu

Here, the zoom at a loaded/generated image can be changed:

• Zoom In (25%): Increases the zoom factor by 25%.

• Zoom Out (25%): Decreases the zoom factor by 25%.

• Normal Size: Resets the zoom factor to normal size.

3.3.5.The “Help” Menu

Contains basic information about the application.

• About: Shows some information about the application.

3.4.Tool Bar

The tool bar contains shortcuts to the following menu entries which also can be found within the menu bar and were described previously:

• Open Palette…

• Save Palette

• Save Palette As…

• Open Image…

• Save Image

• Save Image As…

• Export Animation…

• Batch Convert…

AppendixA.Supported Palette Types

The following table shows which palette formats are known by PaletteTool.

TableA.1.Palette formats that can be imported and exported

AppendixB.Formatted String Variables

At some places, a FORMAT_STRING is used. The string may contain placeholders for current values, e.g. the color table entry's index. The following placeholders are supported:

TableB.1.FORMAT_STRING variables

Supporting an e-mail address allows us to answer.

Your message has been sent. Thank you.