Previous section To contents Next section

12.2 Image.Colortable

CLASS
Image.Colortable

DESCRIPTION
This object keeps colortable information, mostly for image re-coloring (quantization).

The object has color reduction, quantisation, mapping and dithering capabilities.

SEE ALSO
Image, Image.Image, Image.Font and Image.GIF

METHOD
Image.Colortable.create,
Image.Colortable.add

SYNTAX
void create()
void create(array(array(int)) colors)
void create(object(Image.Image) image, int number)
void create(object(Image.Image) image, int number, array(array(int)) needed)
void create(int r, int g, int b)
void create(int r, int g, int b,  array(int) from1, array(int) to1, int steps1,  ...,  array(int) fromn, array(int) ton, int stepsn)
object add(array(array(int)) colors)
object add(object(Image.Image) image, int number)
object add(object(Image.Image) image, int number, array(array(int)) needed)
object add(int r, int g, int b)
object add(int r, int g, int b,  array(int) from1, array(int) to1, int steps1,  ...,  array(int) fromn, array(int) ton, int stepsn)

DESCRIPTION
create initiates a colortable object. Default is that no colors are in the colortable.

add takes the same argument(s) as create, thus adding colors to the colortable.

The colortable is mostly a list of colors, or more advanced, colors and weight.

The colortable could also be a colorcube, with or without additional scales. A colorcube is the by-far fastest way to find colors.

Example: 

ct=colortable(my_image,256); // the best 256 colors
ct=colortable(my_image,256,({0,0,0})); // black and the best other 255


ct=colortable(({({0,0,0}),({255,255,255})})); // black and white


ct=colortable(6,7,6); // a colortable of 252 colors
ct=colortable(7,7,5, ({0,0,0}),({255,255,255}),11);
// a colorcube of 245 colors, and a greyscale of the rest -> 256

ARGUMENTS
argument(s)description
array(array(int)) colors
list of colors
object(Image.Image) image
source image
int number
number of colors to get from the image

0 (zero) gives all colors in the image.

Default value is 256.

array(array(int)) needed
needed colors (to optimize selection of others to these given)

this will add to the total number of colors (see argument 'number')

int r
int g
int b
size of sides in the colorcube, must (of course) be equal or larger than 2 - if smaller, the cube is ignored (no colors). This could be used to have only scales (like a greyscale) in the output.
array(int) fromi
array(int) toi
int stepi
This is to add the possibility of adding a scale of colors to the colorcube; for instance a grayscale using the arguments ({0,0,0}),({255,255,255}),17, adding a scale from black to white in 17 or more steps.

Colors already in the cube is used again to add the number of steps, if possible.

The total number of colors in the table is therefore r*b*g+step1+...+stepn.

NOTE
max hash size is (probably, set by a #define) 32768 entries, giving maybe half that number of colors as maximum.

METHOD
Image.Colortable.cast

SYNTAX
object cast(string to)

DESCRIPTION
cast the colortable to an array or mapping, the array consists of Image.Color objects and are not in index order. The mapping consists of index:Image.Color pairs, where index is the index (int) of that color.

example: (mapping)Image.Colortable(img)

ARGUMENTS
argument(s)description
string to
must be "string", "array" or "mapping".

METHOD
Image.Colortable.corners

SYNTAX
array(object) corners()

DESCRIPTION
Gives the eight corners in rgb colorspace as an array. The "black" and "white" corners are the first two.

METHOD
Image.Colortable.cubicles

SYNTAX
object cubicles()
object cubicles(int r, int g, int b)
object cubicles(int r, int g, int b, int accuracy)

DESCRIPTION
Set the colortable to use the cubicles algorithm to lookup the closest color. This is a mostly very fast and very accurate way to find the correct color, and the default algorithm.

The colorspace is divided in small cubes, each cube containing the colors in that cube. Each cube then gets a list of the colors in the cube, and the closest from the corners and midpoints between corners.

When a color is needed, the algorithm first finds the correct cube and then compares with all the colors in the list for that cube.

example: colors=Image.Colortable(img)->cubicles();

algorithm time: between O[m] and O[m * n], where n is numbers of colors and m is number of pixels

The arguments can be heavy trimmed for the usage of your colortable; a large number (10×10×10 or bigger) of cubicles is recommended when you use the colortable repeatedly, since the calculation takes much more time than usage.

recommended values: 

image size  setup
100×100     cubicles(4,5,4) (default)
1000×1000   cubicles(12,12,12) (factor 2 faster than default)

In some cases, the full method is faster.

original default cubicles,
16 colors		 accuracy=200

ARGUMENTS
argument(s)description
int r
int g
int b
Size, ie how much the colorspace is divided. Note that the size of each cubicle is at least about 8b, and that it takes time to calculate them. The number of cubicles are r*g*b, and default is 4,5,4, ie 80 cubicles. This works good for 200±100 colors.
int accuracy
Accuracy when checking sides of cubicles. Default is 16. A value of 1 gives complete accuracy, ie cubicle() method gives exactly the same result as full(), but takes (in worst case) 16× the time to calculate.

RETURNS
the called object

NOTE
this method doesn't figure out the cubicles, this is done on the first use of the colortable.

Not applicable to colorcube types of colortable.

METHOD
Image.Colortable.floyd_steinberg

SYNTAX
object floyd_steinberg()
object floyd_steinberg(int bidir, int|float forward, int|float downforward, int|float down, int|float downback, int|float factor)

DESCRIPTION
Set dithering method to floyd_steinberg.

The arguments to this method is for fine-tuning of the algorithm (for computer graphics wizards).

original floyd_steinberg to a 4×4×4 colorcube floyd_steinberg to 16 chosen colors

ARGUMENTS
argument(s)description
int bidir
Set algorithm direction of forward. -1 is backward, 1 is forward, 0 for toggle of direction each line (default).
int|float forward
int|float downforward
int|float down
int|float downback
Set error correction directions. Default is forward=7, downforward=1, down=5, downback=3.
int|float factor
Error keeping factor. Error will increase if more than 1.0 and decrease if less than 1.0. A value of 0.0 will cancel any dither effects. Default is 0.95.

RETURNS
the called object

METHOD
Image.Colortable.full

SYNTAX
object full()

DESCRIPTION
Set the colortable to use full scan to lookup the closest color.

example: colors=Image.Colortable(img)->full();

algorithm time: O[n*m], where n is numbers of colors and m is number of pixels

RETURNS
the called object

NOTE
Not applicable to colorcube types of colortable.

SEE ALSO
cubicles and map

METHOD
Image.Colortable.image

SYNTAX
object image()

DESCRIPTION
cast the colortable to an image object

each pixel in the image object is an entry in the colortable

RETURNS
the resulting image object

METHOD
Image.Colortable.`*,
Image.Colortable.``*,
Image.Colortable.map

SYNTAX
object map(object image)
object `*(object image)
object ``*(object image)
object map(string data, int xsize, int ysize)
object `*(string data, int xsize, int ysize)
object ``*(string data, int xsize, int ysize)

DESCRIPTION
Map colors in an image object to the colors in the colortable, and creates a new image with the closest colors.

no dither
floyd_steinberg dither
ordered dither
randomcube dither
original 2 4 8 16 32 colors

RETURNS
a new image object

NOTE
Flat (not cube) colortable and not 'full' method: this method does figure out the data needed for the lookup method, which may take time the first use of the colortable - the second use is quicker.

SEE ALSO
cubicles and full

METHOD
Image.Colortable.nodither

SYNTAX
object nodither()

DESCRIPTION
Set no dithering (default).

RETURNS
the called object

METHOD
Image.Colortable.ordered

SYNTAX
object ordered()
object ordered(int r, int g, int b)
object ordered(int r, int g, int b, int xsize, int ysize)
object ordered(int r, int g, int b, int xsize, int ysize, int x, int y)
object ordered(int r, int g, int b, int xsize, int ysize, int rx, int ry, int gx, int gy, int bx, int by)

DESCRIPTION
Set ordered dithering, which gives a position-dependent error added to the pixel values.

original mapped to
Image.Colortable(6,6,6)->
ordered
(42,42,42,2,2)		 ordered() ordered
(42,42,42, 8,8,
0,0, 0,1, 1,0)

ARGUMENTS
argument(s)description
int r
int g
int b
The maximum error. Default is 32, or colorcube steps (256/size).
int xsize
int ysize
Size of error matrix. Default is 8×8. Only values which factors to multiples of 2 and 3 are possible to choose (2,3,4,6,8,12,...).
int x
int y
int rx
int ry
int gx
int gy
int bx
int by
Offset for the error matrix. x and y is for both red, green and blue values, the other is individual.

RETURNS
the called object

SEE ALSO
randomcube, nodither, floyd_steinberg and create

METHOD
Image.Colortable.randomcube,
Image.Colortable.randomgrey

SYNTAX
object randomcube()
object randomcube(int r, int g, int b)
object randomgrey()
object randomgrey(int err)

DESCRIPTION
Set random cube dithering. Color choosen is the closest one to color in picture plus (flat) random error; color±random(error).

The randomgrey method uses the same random error on red, green and blue and the randomcube method has three random errors.

original mapped to
Image.Colortable(4,4,4)->
randomcube() randomgrey()

ARGUMENTS
argument(s)description
int r
int g
int b
int err
The maximum error. Default is 32, or colorcube step.

RETURNS
the called object

NOTE
randomgrey method needs colorcube size to be the same on red, green and blue sides to work properly. It uses the red colorcube value as default.

SEE ALSO
ordered, nodither, floyd_steinberg and create

METHOD
Image.Colortable.reduce,
Image.Colortable.reduce_fs

SYNTAX
object reduce(int colors)
object reduce_fs(int colors)

DESCRIPTION
reduces the number of colors

All needed (see create) colors are kept.

reduce_fs creates and keeps the outmost corners of the color space, to improve floyd-steinberg dithering result. (It doesn't work very well, though.)

ARGUMENTS
argument(s)description
int colors
target number of colors

RETURNS
the new Colortable object

NOTE
this algorithm assumes all colors are different to begin with (!)

reduce_fs keeps the "corners" as "needed colors".

SEE ALSO
corners

METHOD
Image.Colortable.rigid

SYNTAX
object rigid()
object rigid(int r, int g, int b)

DESCRIPTION
Set the colortable to use the "rigid" method of looking up colors.

This is a very simple way of finding the correct color. The algorithm initializes a cube with r x g x b colors, where every color is chosen by closest match to the corresponding coordinate.

This format is not recommended for exact match, but may be usable when it comes to quickly view pictures on-screen.

It has a high init-cost and low use-cost. The structure is initiated at first usage.

RETURNS
the called object

NOTE
Not applicable to colorcube types of colortable.

SEE ALSO
cubicles, map and full

METHOD
Image.Colortable.spacefactors

SYNTAX
object spacefactors(int r, int g, int b)

DESCRIPTION
Colortable tuning option, this sets the color space distance factors. This is used when comparing distances in the colorspace and comparing grey levels.

Default factors are 3, 4 and 1; blue is much darker than green. Compare with Image.Image->grey().

RETURNS
the called object

NOTE
This has no sanity check. Some functions may bug if the factors are to high - color reduction functions sums grey levels in the image, this could exceed maxint in the case of high factors. Negative values may also cause strange effects. *grin*

METHOD
Image.Colortable.`+

SYNTAX
object `+(object with, ...)

DESCRIPTION
sums colortables

ARGUMENTS
argument(s)description
object(Colortable) with
Colortable object with colors to add

RETURNS
the resulting new Colortable object

METHOD
Image.Colortable.`-

SYNTAX
object `-(object with, ...)

DESCRIPTION
subtracts colortables

ARGUMENTS
argument(s)description
object(Colortable) with
Colortable object with colors to subtract

RETURNS
the resulting new Colortable object
Previous section To contents Next section