ImageGear for C and C++ on Windows v19.3 - Updated
IG_FX_noise
API Reference Guide > Core Component API Reference > Core Component Functions Reference > FX Functions > IG_FX_noise

This function is used to create noise in an image.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_FX_noise (
        HIGEAR hIGear, 
        const LPAT_RECT lpRect, 
        const WORD nType, 
        const DOUBLE dblStrength, 
        const INT nHitRate, 
        const DOUBLE dblSigma, 
        const AT_MODE nColorChannel 
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image.
lpRect const LPAT_RECT Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nType const WORD An IG_NOISE constant such as IG_NOISE_LINEAR, IG_NOISE_GAUSSIAN.
dblStrength const DOUBLE From 0.0 to 127.0, specifying the degree of noise alteration to introduce into affected pixels.
nHitRate const INT Set = 1 to add noise to all pixels, > 1 to skip pixels, only adding noise to some. Larger values cause fewer pixels to be affected. Valid range: 1 to 500.
dblSigma const DOUBLE Used with IG_NOISE_GAUSSIAN, range: 0.1-25.0.
nColorChannel const AT_MODE An IG_COLOR_COMP_ constant. See file accucnst.h for the full list of these constants.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear for C and C++.

Sample:

FlashPix

Example:

 
Copy Code
HIGEAR    hIGear;  /* HIGEAR handle of image   */
/* Add moderate noise to about 5 percent of the pixels: */
IG_FX_noise ( hIGear, NULL, IG_NOISE_LINEAR, 30.0, 20, 1.0, IG_COLOR_COMP_RGB );

Remarks:

This effect can make an image look older. nHitRate selects how many pixels may have noise introduced into them. dblStrength determines how strongly a pixel's value is to be altered when it is selected to be altered. nType determines the algorithm used to determine the noise alteration.

nHitRate = 1 indicates that almost every pixel should be affected. A value of 100 would indicate that every 100th pixel should be affected. dblStrength = 1.0 indicates that a value of about +1 to -1 should be added to those pixels selected while dblStrength = 50.0 would increase the noise result by adding values in the range of -50 to +50.

Which pixels are altered and the amount of noise to apply are selected randomly.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular sub-region of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.