illuminateilluminateIlluminateIlluminate (Operator)

Name

illuminateilluminateIlluminateIlluminate — Illuminate image.

Signature

illuminate(Image : ImageIlluminate : MaskWidth, MaskHeight, Factor : )

Herror illuminate(const Hobject Image, Hobject* ImageIlluminate, const Hlong MaskWidth, const Hlong MaskHeight, double Factor)

Herror T_illuminate(const Hobject Image, Hobject* ImageIlluminate, const Htuple MaskWidth, const Htuple MaskHeight, const Htuple Factor)

void Illuminate(const HObject& Image, HObject* ImageIlluminate, const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& Factor)

HImage HImage::Illuminate(Hlong MaskWidth, Hlong MaskHeight, double Factor) const

static void HOperatorSet.Illuminate(HObject image, out HObject imageIlluminate, HTuple maskWidth, HTuple maskHeight, HTuple factor)

HImage HImage.Illuminate(int maskWidth, int maskHeight, double factor)

Description

The operator illuminateilluminateIlluminateIlluminateIlluminate enhances contrast. Very dark parts of the image are “illuminated” more strongly, very light ones are “darkened”. If orig is the original gray value and mean is the corresponding gray value of the low pass filtered image detected via the operators mean_imagemean_imageMeanImageMeanImageMeanImage and filter size MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight x MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth. For byte-images val equals 127, for int2-images and uint2-images val equals the median value. The resulting gray value is new: new = round ( (val - mean) * Factor + orig ). The low pass should have rather large dimensions (30 x 30 to 200 x 200). Reasonable parameter combinations might be: Height Width Factor --------------------- 40 40 0.55 100 100 0.7 150 150 0.8 i.e. the larger the low pass mask is chosen, the larger FactorFactorFactorFactorfactor should be as well.

The following “spotlight effect” should be noted: If, for example, a dark object is in front of a light wall the object as well as the wall, which is already light in the immediate proximity of the object contours, are lightened by the operator illuminateilluminateIlluminateIlluminateIlluminate. This corresponds roughly to the effect that is produced when the object is illuminated by a strong spotlight. The same applies to light objects in front of a darker background. In this case, however, the fictitious “spotlight” darkens objects.

Attention

Note that filter operators may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.

Execution Information

Parameters

ImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHobject (byte / int2 / uint2)

Image to be enhanced.

ImageIlluminateImageIlluminateImageIlluminateImageIlluminateimageIlluminate (output_object)  (multichannel-)image(-array) objectHImageHImageHobject * (byte / int2 / uint2)

“Illuminated” image.

MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth (input_control)  extent.x HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Width of low pass mask.

Default value: 101

Suggested values: 31, 41, 51, 71, 101, 121, 151, 201

Typical range of values: 3 ≤ MaskWidth MaskWidth MaskWidth MaskWidth maskWidth ≤ 299

Minimum increment: 2

Recommended increment: 10

Restriction: MaskWidth < width(Image) * 2

MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight (input_control)  extent.y HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Height of low pass mask.

Default value: 101

Suggested values: 31, 41, 51, 71, 101, 121, 151, 201

Typical range of values: 3 ≤ MaskHeight MaskHeight MaskHeight MaskHeight maskHeight ≤ 299

Minimum increment: 2

Recommended increment: 10

Restriction: MaskHeight < height(Image) * 2

FactorFactorFactorFactorfactor (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Scales the “correction gray value” added to the original gray values.

Default value: 0.7

Suggested values: 0.3, 0.5, 0.7, 1.0, 1.5, 2.0, 3.0, 5.0

Typical range of values: 0.0 ≤ Factor Factor Factor Factor factor ≤ 5.0

Minimum increment: 0.01

Recommended increment: 0.2

Restriction: 0 < Factor && Factor < 5

Example (HDevelop)

read_image(Image,'fabrik')
dev_display (Image)
illuminate(Image,Better,40,40,0.55)
dev_display (Better)

Example (C)

read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
illuminate(Image,&Better,40,40,0.55);
disp_image(Better,WindowHandle); 

Example (HDevelop)

read_image(Image,'fabrik')
dev_display (Image)
illuminate(Image,Better,40,40,0.55)
dev_display (Better)

Example (HDevelop)

read_image(Image,'fabrik')
dev_display (Image)
illuminate(Image,Better,40,40,0.55)
dev_display (Better)

Example (HDevelop)

read_image(Image,'fabrik')
dev_display (Image)
illuminate(Image,Better,40,40,0.55)
dev_display (Better)

Result

If the parameter values are correct the operator illuminateilluminateIlluminateIlluminateIlluminate returns the value 2 (H_MSG_TRUE) The behavior in case of empty input (no input images available) is set via the operator set_system(::'no_object_result',<Result>:)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>). If necessary an exception is raised.

Possible Successors

disp_imagedisp_imageDispImageDispImageDispImage

Alternatives

scale_image_maxscale_image_maxScaleImageMaxScaleImageMaxScaleImageMax, equ_histo_imageequ_histo_imageEquHistoImageEquHistoImageEquHistoImage, mean_imagemean_imageMeanImageMeanImageMeanImage, sub_imagesub_imageSubImageSubImageSubImage

See also

emphasizeemphasizeEmphasizeEmphasizeEmphasize, gray_histogray_histoGrayHistoGrayHistoGrayHisto

Module

Foundation