gimpdrawablecolor: GIMP Library Reference Manual

## gimpdrawablecolor gimpdrawablecolor — Functions for manipulating a drawable's color. |

## Functions

gboolean | gimp_drawable_brightness_contrast ()
gboolean | gimp_drawable_color_balance ()
gboolean | gimp_drawable_colorize_hsl ()
gboolean | gimp_drawable_curves_explicit ()
gboolean | gimp_drawable_curves_spline ()
gboolean | gimp_drawable_desaturate ()
gboolean | gimp_drawable_equalize ()
gboolean | gimp_drawable_histogram ()
gboolean | gimp_drawable_hue_saturation ()
gboolean | gimp_drawable_invert ()
gboolean | gimp_drawable_levels ()
gboolean | gimp_drawable_levels_stretch ()
gboolean | gimp_drawable_posterize ()
gboolean | gimp_drawable_threshold ()

## Description

Functions for manipulating a drawable's color, including curves and histograms.

## Functions

### gimp_drawable_brightness_contrast ()

    gboolean
    gimp_drawable_brightness_contrast (gint32 drawable_ID,
                                       gdouble brightness,
                                       gdouble contrast);

Modify brightness/contrast in the specified drawable.

This procedures allows the brightness and contrast of the specified drawable to be modified. Both 'brightness' and 'contrast' parameters are defined between -1.0 and 1.0.

#### Parameters

drawable_ID | The drawable. |
brightness | Brightness adjustment. |
contrast | Contrast adjustment. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_color_balance ()

    gboolean
    gimp_drawable_color_balance (gint32 drawable_ID,
                                 GimpTransferMode transfer_mode,
                                 gboolean preserve_lum,
                                 gdouble cyan_red,
                                 gdouble magenta_green,
                                 gdouble yellow_blue);

Modify the color balance of the specified drawable.

Modify the color balance of the specified drawable. There are three axis which can be modified: cyan-red, magenta-green, and yellow-blue. Negative values increase the amount of the former, positive values increase the amount of the latter. Color balance can be controlled with the 'transfer_mode' setting, which allows shadows, mid-tones, and highlights in an image to be affected differently. The 'preserve-lum' parameter, if TRUE, ensures that the luminosity of each pixel remains fixed.

#### Parameters

drawable_ID | The drawable. |
transfer_mode | Transfer mode. |
preserve_lum | Preserve luminosity values at each pixel. |
cyan_red | Cyan-Red color balance. |
magenta_green | Magenta-Green color balance. |
yellow_blue | Yellow-Blue color balance. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_colorize_hsl ()

    gboolean
    gimp_drawable_colorize_hsl (gint32 drawable_ID,
                                gdouble hue,
                                gdouble saturation,
                                gdouble lightness);

Render the drawable as a grayscale image seen through a colored glass.

Desaturates the drawable, then tints it with the specified color. This tool is only valid on RGB color images. It will not operate on grayscale drawables.

#### Parameters

drawable_ID | The drawable. |
hue | Hue in degrees. |
saturation | Saturation in percent. |
lightness | Lightness in percent. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_curves_explicit ()

    gboolean
    gimp_drawable_curves_explicit (gint32 drawable_ID,
                                   GimpHistogramChannel channel,
                                   gint num_values,
                                   const gdouble *values);

Modifies the intensity curve(s) for specified drawable.

Modifies the intensity mapping for one channel in the specified drawable. The channel can be either an intensity component, or the value. The 'values' parameter is an array of doubles which explicitly defines how each pixel value in the drawable will be modified. Use the `gimp_curves_spline()` function to modify intensity levels with Catmull Rom splines.

#### Parameters

drawable_ID | The drawable. |
channel | The channel to modify. |
num_values | The number of values in the new curve. |
values | The explicit curve. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_curves_spline ()

    gboolean
    gimp_drawable_curves_spline (gint32 drawable_ID,
                                 GimpHistogramChannel channel,
                                 gint num_points,
                                 const gdouble *points);

Modifies the intensity curve(s) for specified drawable.

Modifies the intensity mapping for one channel in the specified drawable. The channel can be either an intensity component, or the value. The 'points' parameter is an array of doubles which define a set of control points which describe a Catmull Rom spline which yields the final intensity curve. Use the `gimp_curves_explicit()` function to explicitly modify intensity levels.

#### Parameters

drawable_ID | The drawable. |
channel | The channel to modify. |
num_points | The number of values in the control point array. |
points | The spline control points: { cp1.x, cp1.y, cp2.x, cp2.y, ... }. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_desaturate ()

    gboolean
    gimp_drawable_desaturate (gint32 drawable_ID,
                              GimpDesaturateMode desaturate_mode);

Desaturate the contents of the specified drawable, with the specified formula.

This procedure desaturates the contents of the specified drawable, with the specified formula. This procedure only works on drawables of type RGB color.

#### Parameters

drawable_ID | The drawable. |
desaturate_mode | The formula to use to desaturate. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_equalize ()

    gboolean
    gimp_drawable_equalize (gint32 drawable_ID,
                            gboolean mask_only);

Equalize the contents of the specified drawable.

This procedure equalizes the contents of the specified drawable. Each intensity channel is equalized independently. The equalized intensity is given as inten' = (255 - inten). The 'mask_only' option specifies whether to adjust only the area of the image within the selection bounds, or the entire image based on the histogram of the selected area. If there is no selection, the entire image is adjusted based on the histogram for the entire image.

#### Parameters

drawable_ID | The drawable. |
mask_only | Equalization option. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_histogram ()

    gboolean
    gimp_drawable_histogram (gint32 drawable_ID,
                             GimpHistogramChannel channel,
                             gdouble start_range,
                             gdouble end_range,
                             gdouble *mean,
                             gdouble *std_dev,
                             gdouble *median,
                             gdouble *pixels,
                             gdouble *count,
                             gdouble *percentile);

Returns information on the intensity histogram for the specified drawable.

This tool makes it possible to gather information about the intensity histogram of a drawable. A channel to examine is first specified. This can be either value, red, green, or blue, depending on whether the drawable is of type color or grayscale. Second, a range of intensities are specified. The `gimp_drawable_histogram()` function returns statistics based on the pixels in the drawable that fall under this range of values. Mean, standard deviation, median, number of pixels, and percentile are all returned. Additionally, the total count of pixels in the image is returned. Counts of pixels are weighted by any associated alpha values and by the current selection mask. That is, pixels that lie outside an active selection mask will not be counted. Similarly, pixels with transparent alpha values will not be counted. The returned mean, std_dev and median are in the range (0..255) for 8-bit images or if the plug-in is not precision-aware, and in the range (0.0..1.0) otherwise.

#### Parameters

drawable_ID | The drawable. |
channel | The channel to query. |
start_range | Start of the intensity measurement range. |
end_range | End of the intensity measurement range. |
mean | Mean intensity value. |
std_dev | Standard deviation of intensity values. |
median | Median intensity value. |
pixels | Alpha-weighted pixel count for entire image. |
count | Alpha-weighted pixel count for range. |
percentile | Percentile that range falls under. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_hue_saturation ()

    gboolean
    gimp_drawable_hue_saturation (gint32 drawable_ID,
                                  GimpHueRange hue_range,
                                  gdouble hue_offset,
                                  gdouble lightness,
                                  gdouble saturation,
                                  gdouble overlap);

Modify hue, lightness, and saturation in the specified drawable.

This procedure allows the hue, lightness, and saturation in the specified drawable to be modified. The 'hue-range' parameter provides the capability to limit range of affected hues. The 'overlap' parameter provides blending into neighboring hue channels when rendering.

#### Parameters

drawable_ID | The drawable. |
hue_range | Range of affected hues. |
hue_offset | Hue offset in degrees. |
lightness | Lightness modification. |
saturation | Saturation modification. |
overlap | Overlap other hue channels. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_invert ()

    gboolean
    gimp_drawable_invert (gint32 drawable_ID,
                          gboolean linear);

Invert the contents of the specified drawable.

This procedure inverts the contents of the specified drawable. Each intensity channel is inverted independently. The inverted intensity is given as inten' = (255 - inten). If 'linear' is TRUE, the drawable is inverted in linear space.

#### Parameters

drawable_ID | The drawable. |
linear | Whether to invert in linear space. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_levels ()

    gboolean
    gimp_drawable_levels (gint32 drawable_ID,
                          GimpHistogramChannel channel,
                          gdouble low_input,
                          gdouble high_input,
                          gboolean clamp_input,
                          gdouble gamma,
                          gdouble low_output,
                          gdouble high_output,
                          gboolean clamp_output);

Modifies intensity levels in the specified drawable.

This tool allows intensity levels in the specified drawable to be remapped according to a set of parameters. The low/high input levels specify an initial mapping from the source intensities. The gamma value determines how intensities between the low and high input intensities are interpolated. A gamma value of 1.0 results in a linear interpolation. Higher gamma values result in more high-level intensities. Lower gamma values result in more low-level intensities. The low/high output levels constrain the final intensity mapping--that is, no final intensity will be lower than the low output level and no final intensity will be higher than the high output level. This tool is only valid on RGB color and grayscale images.

#### Parameters

drawable_ID | The drawable. |
channel | The channel to modify. |
low_input | Intensity of lowest input. |
high_input | Intensity of highest input. |
clamp_input | Clamp input values before applying output levels. |
gamma | Gamma adjustment factor. |
low_output | Intensity of lowest output. |
high_output | Intensity of highest output. |
clamp_output | Clamp final output values. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_levels_stretch ()

    gboolean
    gimp_drawable_levels_stretch (gint32 drawable_ID);

Automatically modifies intensity levels in the specified drawable.

This procedure allows intensity levels in the specified drawable to be remapped according to a set of guessed parameters. It is equivalent to clicking the \"Auto\" button in the Levels tool.

#### Parameters

drawable_ID | The drawable. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_posterize ()

    gboolean
    gimp_drawable_posterize (gint32 drawable_ID,
                             gint levels);

Posterize the specified drawable.

This procedures reduces the number of shades allows in each intensity channel to the specified 'levels' parameter.

#### Parameters

drawable_ID | The drawable. |
levels | Levels of posterization. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_drawable_threshold ()

    gboolean
    gimp_drawable_threshold (gint32 drawable_ID,
                             GimpHistogramChannel channel,
                             gdouble low_threshold,
                             gdouble high_threshold);

Threshold the specified drawable.

This procedures generates a threshold map of the specified drawable. All pixels between the values of 'low_threshold' and 'high_threshold', on the scale of 'channel' are replaced with white, and all other pixels with black.

#### Parameters

drawable_ID | The drawable. |
channel | The channel to base the threshold on. |
low_threshold | The low threshold value. |
high_threshold | The high threshold value. |

#### Returns

TRUE on success.

Since: 2.10