Clone wiki

agtools / CryptoChrome

This guide is based on PCS v6.30, available in the repo bin/ dir and separately in the downloads section.

CryptoChrome is a sub-tool within PhotoChrome v6 onwards which provides special functions for colour-reducing images, backgrounds, sprites, texturesets and for generating 16-colour shared palettes.

While the primary PhotoChrome functions are for generating CPU-hungry multipalette images, the CryptoChrome functions generate 16-colour interlaced images and optimised palettes which can increase colour availability without consuming CPU time on the Atari.

The tool is designed for game graphics preparation but can be used for other things (e.g. demos, slideshows etc.).

Using CryptoChrome to generate single-field 16-colour superpalettes

You can use CryptoChrome to generate normal 16-colour palettes from one or multiple source images at once. Palettes generated from multiple images are sometimes called 'superpalettes' since they are shared between graphics assets. Passing a single source image works just fine also.

Q: Why use CryptoChrome to generate palettes instead of some other popular colour quantiser tool?

A: Because it nearly always produces better results. Sometimes a lot better. The price is that it is slow - it can take anything from a few seconds to many minutes depending on the task. But what's the rush?

A: Because it emits some handy tables that let you convert truecolour images to use the new palette very quickly and easily at runtime without using any other tools.

A: Because you have full control over which palette colours are usable and which are reserved - and you can force specific colours to specific values while still allowing them to be used in converted images (or not - as you wish).

Here's a comparison between CryptoChrome's custom quantiser and two other popular colour quantisers: the median cut and octree algorithms. The sample image is a small slice from a larger background which has been reduced to 16 colours.

Reference image:

quant16_ref.png quant16b_ref.png bern320.png

Median-Cut quantiser:

quant16_median.png quant16b_median.png bern320med.png

Octree quantiser:

quant16_oct.png quant16b_oct.png bern320oct.png

CryptoChrome quantiser:

quant16_cc.png quant16b_cc.png composite00.png

Zoom and inspect the shading. You can try with Gimp, Imagemagick and other colour reduction tools for extra fun.

Example command:

pcs -cd ste -ccmode 3 -ccfields 1 -ccl 0=0:0:0 -ccignore ff:00:ff -ccpopctrl 0.5 -ccrounds 10 -ccthreads 2 tutor2.png


-cd ste

Generate palette using STE colour depth / native palette of 4096 shades

-ccmode 3

Superpalette mode. Generate palette & reduction tables for one or more source images.

-ccfields 1

Generate single-field palette. Normal 16 colour mode (no interlacing or dithering).

-ccl 0=0:0:0

Lock colour 0 to black.

-ccignore ff:00:ff

Ignore any magenta pixels in source image(s) e.g. mask areas on spritesheets.

-ccpopctrl 0.5

This is an important tuning field for palette generation. It sets the population significance control curve, which is just a way of managing how the popularity of a colour affects its importance in the palette. It is configured much like a typical colour gamma curve, with 1.0 being the 'middle' - values near or beyond 1.0 give popular colours extra importance, small values like 0.1 will dampen the importance of popular colours. 0.5 is usually a good starting point for tuning.

Note: Most common quantisers behave as if this value is set to 1.0, but highlights and shading can suffer at the expense of large fill areas. But from a perception point of view, highlights and shading are usually more important than large areas of perfectly accurate hue. This value lets you trade one against the other

-ccrounds 10 -ccthreads 2

Run 10 refinement rounds across 2 processor threads. Adjust to suit host machine. More can be better, up to a point. Don't run more threads than you have processors though or it will just crawl.

See CryptoChrome palettes for info on the very simple file formats produced by this step.

Using CryptoChrome to generate dual-field (interlaced) 16-colour superpalettes

The procedure for generating dual-field palettes is nearly exactly the same as for single-field, but there are some important differences to be aware of when using this feature.

'dual-field' palettes are just plain 16-colour palettes which are used with either A) a dither pattern or B) a pair of images which are strobed to simulate hybrid colours. There is nothing special about the palette data - it's just 16 standard colours. What is special is the values of those colours contained and how they dither/mix to produce the intended hybrids.

Generating dual-field palettes is a slow, expensive job. It takes a lot longer than single-field mode. The actual time taken is a function of the number of colours being matched in the input image(s), not the size or number of input images. This means you can considerably speed up the process by pre-limiting the input colour count. e.g. you can get good previews within a minute or so by reducing source images to 256 colours first. The original material might yield slightly better results, but for a few thousand source colours the crunching time can be long.

Once the palette is generated, three files are emitted containing tables which map every possible RGB colour (18bit resolution) to a 'solution pair', which is a byte made up of two complementary ST/e colours (0-15 each) from the generated palette. These two colours can either be dithered or interlaced to approximate a 'missing' colour.

The rest is down to configuration, which is a bit more complex than for single-field palettes. Since interlacing (or just dithering) is involved, there are several controls to balance and trade-off colour accuracy against contrast and flicker. This tuning is optional but usually important for good results.

Q: Why does it take so long to make a 16 colour palette?

A: Because the permutation space being searched is huge and the 'fitness' function which continuously evaluates the potential palette against the input images is expensive - lots of settings & adjustments involved.

Q: Does it try every palette possible?

A: No - that takes too long for a complex fitness function like this. It seeks towards a best fit and so doesn't guarantee the best answer will be found. However it always gets close.

See CryptoChrome palettes for info on the very simple file formats produced by this step.

Using CryptoChrome to generate bitplane-locked or colour-constrained graphics

In combination with any other -ccmode, you can specify which colour indices are available to use or placed out of bounds, using the bitplane dodge -ccdodge command or the colour protect -ccprotect command.

Normally CryptoChrome will use all available palette colours when generating palettes & remapping images to use them. You can make more specific choices using these switches.

Example commands:

pcs -cd ste -ccmode 5 -ccfields 1 -ccprotect 15 -ccpopctrl 0.5 mytest.png

pcs -cd ste -ccmode 5 -ccfields 2 -ccdodge 1011 -ccpopctrl 0.5 mytest.png


-cd ste

Generate palette using STE colour depth / native palette of 4096 shades

-ccmode 5

Raw image mode. Convert image of any size, without resizing, emitting raw bitplanes. Also emits palette & reduction tables as with most of the other modes.

-ccfields 1

Generate single-field palette. Normal 16 colour mode (no interlacing or dithering).

-ccprotect 15

Prevent colour 15 from being generated, or being used in the remapped image. Multiple -ccprotect switches can be passed at once.

Detail: Reserves a colour from taking part in colour reduction. Remaining palette colours are used to make up the required palette for the target image(s). The reserved colour(s) are then free to be changed at will. Useful for keeping colours aside for a mouse cursor or 'special player colour' for games with multiple players.

-ccfields 2

Generate dual-field palette, either for dithered graphics or for interlacing.

-ccdodge 1011

Generate only colours on bitplanes 0,1 and 3. Dodge colours needing bitplane 2.

Can be combined with -ccprotect so long as -ccprotect switches follow -ccdodge switch.

Here is an example of -ccdodge used to generate a bitplane-locked image with interlacing, resulting in 32 simulated colours with one bitplane left 'free' using -ccdodge 1110.

A single dithered 16c field: ilfield0.png

Full composite 32c image: composite00.png

It is also possible to force (lock) colours to specific values. If these colours are left unprotected with --ccprotect or -ccdodge they can still be used by the remapped image. If they are protected or require dodged bitplanes, the colour values will be inserted into the palette but left unused by the remapped image.


-ccl 0=0:0:0 -ccl 15=f:f:f

Lock colour 0 to black, lock colour 15 to white.

Using CryptoChrome to generate dual-field (interlaced) 16-colour 320x200 .PI1 images

Using CryptoChrome to generate dual-field (interlaced) 16-colour raw images of any size

Using CryptoChrome to generate dual-field (interlaced) 16-colour game playfields

Using CryptoChrome to generate dual-field (interlaced) 16-colour C2P texture sets