reduce() - Media Method

The reduce() method applies a specified or generated color palette to the image. By default, this function generates an optimal palette of 256 colors. It accepts a boolean parameter, UseAlpha. It defaults to false to maintain compatibility with the old behavior. If set to true, alpha channel values below the cutoff will cause the pixels in the paletted image to be transparent.

Also an additional integer parameter, AlphaCutoff, can be specified. It defaults to 127. Valid values range from 0 to 255. It controls the decision as to whether to make a pixel transparent or opaque in the resulting paletted image.

If the source Media object does not have an alpha channel, the UseAlpha and AlphaCutoff parameters will be ignored.

Syntax

reduce(

[Netscape @ <true, false>]

[BW @ <true, false>]

[Pad @ <true, false>]

[PreserveBackground @ <true, false>]

[NoWarp @ <true, false>]

[Name @ <"Palettes/filename.pal", "virtualfilesystem:/filename.pal">]

[Colors @ <1 to 256>]

[Dither @ <value 0..10>]

[DitherTop @ <value 0..10>]

[UseAlpha @ <true, false>]

[AlphaCutoff @ <0 to 255>]

[layers @ <"layer list">] // (PSD files only)

);

Parameters

Netscape - if set to true, applies the Netscape default palette as an alternative to applying the default custom palette.

BW - if set to true, applies the two-color, black and white palette.

Pad - ensures that the palette always contains the required number of colors. In a situation where there are fewer unique colors in the image than required for the palette, the extra colors are padded with black. If pad is not specified, the palette will shrink down to the number of unique colors available.

PreserveBackground - when dithering is used, eliminates any pixels in the source image that match the background color from the dithering process in the destination image. This can be used to eliminate fuzzy edges for an object against a solid color background.

Nowarp - if set to true, turns off the normal colorspace warping that occurs when searching for a closest color to take into account the bias in the human eye. This is useful when reducing an image to an existing palette with a small number of colors, such as the Windows 16-color palette.

Name - specifies a palette file as the palette to be applied to the image. The following color palette files are installed on MediaRich:

» 128_Grays.pal

» 16_Grays.pal

» 256_Grays.pal

» 32_Grays.pal

» 4_Grays.pal

» 64_Grays.pal

» 8_Grays.pal

» Macintosh_16.pal

» Macintosh_256.pal

» Netscape.pal

» Windows_16.pal

» Windows_256.pal

The default location for palette files is the following:

MediaRichCore/Shared/Originals/Media/Palettes

You can store additional palette files in this directory and use the Name parameter to specify the palette to be applied to the image.

MediaRich also allows you to set up virtual file systems and then use the Name parameter to load palettes from a virtual file system. Virtual file systems are defined in the MediaRich server’s local.properties file. For example, if you define MyPalettes: to represent the path C:/PALS/MyPalettes/ in the local.properties file, you can use files from the MyPalettes directory with the reduce() function :

image.reduce(name @ "MyPalettes:/custom.pal");

image.reduce(Name @ "Palettes/Windows_256.pal");

Colors - specifies the number of palette colors to be generated and applied. In the case of a Media with multiple frames, all the frames are reduced to one palette based on the contents of all the frames.

Dither - determines the level of dithering to use for remapping image pixels to the palette. The default is 0, which is no dithering. While the dither value ranges from 0 to 10, the actual effects of different values vary according to the number of colors in the palette and their spread relative to each other.

Dithertop - if set to true when dithering is used, sets an upper threshold of how far the dithering algorithm will go to pick a color in order to correct color balance. The default value is 10. When an optimal (custom) palette is used, lowering the value of dithertop tends to reduce the pixelization of the image, making the dithering effect softer.

UseAlpha - if set to true, alpha channel values below the cutoff will cause the pixels in the paletted image to be transparent. It defaults to false to maintain compatibility with the old behavior.

AlphaCutoff - when UseAlpha is true, this can be specified to control the decision as to whether to make a pixel transparent or opaque in the resulting paletted image. Valid values are 0 to 255, with a default of 127.

If the source Media object does not have an alpha channel, the UseAlpha and AlphaCutoff parameters will be ignored.

layers - for PSD files, specifies the layers to be affected. The layer numbers begin at 0 (background) and go up. For more information see load() - Media Method.

Example

var image = new Media();

image.load(name @ "car.tga");

image.reduce(colors @ 256, dither @ 3, pad @ true);

image.save(type @ "jpeg");