selection() - Media Method

The selection() method creates a selection from the specified Media object.

The selected area can be thought of as a grayscale image or alpha channel that determines the way in which a given transform is applied to an image. Where the selection is 255, the transform or function is applied to the image pixel; where the selection is 0, the transform is not applied. In cases where the selection is between 1 and 254, the transform is applied to the source pixel, and the result is then blended with the original pixel based on the selection value. This function also fully supports the CMYK colorspace.

This function can be used in conjunction with the following functions: adjustHsb() - Media Method, adjustRgb() - Media Method, blur() - Media Method, blurBlur() - Media Method, blurGaussianBlur() - Media Method, blurMoreBlur() - Media Method, blurMotionBlur() - Media Method, colorize() - Media Method, composite() - Media Method, equalize() - Media Method, noiseAddNoise() - Media Method, otherHighPass() - Media Method, otherMaximum() - Media Method, otherMinimum() - Media Method, pixellateMosaic() - Media Method, pixellateFragment() - Media Method, sharpenSharpen() - Media Method, sharpenSharpenMore() - Media Method, sharpenUnsharpMask() - Media Method, stylizeDiffuse() - Media Method, stylizeEmboss() - Media Method, stylizeFindEdges() - Media Method, and stylizeTraceContour() - Media Method.

Syntax

selection(

[Source @ <user-defined Media object name>]

[Fill @ <value 0..255)]

[X @ <pixel>]

[Y @ <pixel]

[BackColor @ <true, false>]

[Color @ <color in hexadecimal or rgb>]

[Index @ <value 0..16777215>]

[ColorType @ <"Cyans", "Magentas", "Yellows", "Reds", "Greens", "Blues", "Hilites", "Midtones", "Shadows">]

[Invert @ <true, false>]

[Remove @ <true, false>]

[Opacity @ <value 0..255>]

[Radius @ <value 1..600>]

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

);

Parameters

Source - When you use Source, the system interprets the image as a grayscale (if it is not one). Loading a selection replaces one that is already active.

• Before creating a new selection, you must load() the image. Then, use the Source parameter to refer to that image by its user-defined Media object name.

• If the source and target images are of different size, use the Fill parameter to specify what value pixels have in the selection mask that fall outside the size of the selection image. The default is 0.

• The X parameter determines at what horizontal position the top left corner of the source image is placed on the target image. If the X parameter is not specified, the selection image will be centered over the target image horizontally.

• The Y parameter determines at what vertical position the top left corner of the source image is placed on the target image. If the Y parameter is not specified, the selection image will be centered over the target image vertically.

• Using Backcolor, Color, Index, or ColorType. Use one of these parameters to create a selection from an image that includes all pixels that match the specified color or color type.

The color can be specified as the background color, or as all pixels of a specified color, index value, or color type. In the event that a selection containing everything except a particular color is required, the invert parameter can be added to the command.

Invert - reverses the opacity values of the current selection (for example, 0->255 and 255‑>0).

Remove - de-activates any current selection.

Opacity - alters the current level of transparency for the selection. Applying an opacity level of 128 will increase the transparency level of the selection by 50%. If reduced, the level of the selection cannot be increased again.

Radius - when the backcolor, color, index, or color type parameter is also specified, this parameter selects all pixels of colors most similar to the specified color (using the specified color as the starting point) and increases the range of similar colors included in the selection as the value for Radius increases. The value for this parameter must be higher than zero. For example:

image.selection(Color @ 0x008000, Radius @ 20);

This example will create a selection consisting of all the colors in the image that are most similar to this color green within a radius of 20.

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

Example

var Target = new Media();

var Source = new Media();

Target.load(name @ "peppers.tga");

Source.load(name @ "Bears.tga");

Target.selection(source @ Source, opacity @ 240);

Target.adjustHsb(hue @ 75, saturation @ 75);

Target.save(type @ "jpeg");