Gimp.Image¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`convert_set_dither_matrix` (width, height, matrix)
class	`get_by_id` (image_id)
class	`id_is_valid` (image_id)
class	`metadata_load_thumbnail` (file)
class	`new` (width, height, type)
class	`new_with_precision` (width, height, type, precision)
	`add_hguide` (yposition)
	`add_sample_point` (position_x, position_y)
	`add_vguide` (xposition)
	`attach_parasite` (parasite)
	`autocrop` (drawable)
	`autocrop_selected_layers` (drawable)
	`clean_all` ()
	`convert_color_profile` (profile, intent, bpc)
	`convert_color_profile_from_file` (file, intent, bpc)
	`convert_grayscale` ()
	`convert_indexed` (dither_type, palette_type, num_cols, alpha_dither, remove_unused, palette)
	`convert_precision` (precision)
	`convert_rgb` ()
	`crop` (new_width, new_height, offx, offy)
	`delete` ()
	`delete_guide` (guide)
	`delete_sample_point` (sample_point)
	`detach_parasite` (name)
	`duplicate` ()
	`export_path_to_file` (file, path)
	`export_path_to_string` (path)
	`find_next_guide` (guide)
	`find_next_sample_point` (sample_point)
	`flatten` ()
	`flip` (flip_type)
	`floating_sel_attached_to` ()
	`freeze_channels` ()
	`freeze_layers` ()
	`freeze_paths` ()
	`get_base_type` ()
	`get_channel_by_name` (name)
	`get_channel_by_tattoo` (tattoo)
	`get_channels` ()
	`get_color_profile` ()
	`get_component_active` (component)
	`get_component_visible` (component)
	`get_default_new_layer_mode` ()
	`get_effective_color_profile` ()
	`get_exported_file` ()
	`get_file` ()
	`get_floating_sel` ()
	`get_guide_orientation` (guide)
	`get_guide_position` (guide)
	`get_height` ()
	`get_id` ()
	`get_imported_file` ()
	`get_item_position` (item)
	`get_layer_by_name` (name)
	`get_layer_by_tattoo` (tattoo)
	`get_layers` ()
	`get_metadata` ()
	`get_name` ()
	`get_palette` ()
	`get_parasite` (name)
	`get_parasite_list` ()
	`get_path_by_name` (name)
	`get_path_by_tattoo` (tattoo)
	`get_paths` ()
	`get_precision` ()
	`get_resolution` ()
	`get_sample_point_position` (sample_point)
	`get_selected_channels` ()
	`get_selected_drawables` ()
	`get_selected_layers` ()
	`get_selected_paths` ()
	`get_selection` ()
	`get_simulation_bpc` ()
	`get_simulation_intent` ()
	`get_simulation_profile` ()
	`get_tattoo_state` ()
	`get_thumbnail` (width, height, alpha)
	`get_thumbnail_data` (width, height)
	`get_unit` ()
	`get_width` ()
	`get_xcf_file` ()
	`grid_get_background_color` ()
	`grid_get_foreground_color` ()
	`grid_get_offset` ()
	`grid_get_spacing` ()
	`grid_get_style` ()
	`grid_set_background_color` (bgcolor)
	`grid_set_foreground_color` (fgcolor)
	`grid_set_offset` (xoffset, yoffset)
	`grid_set_spacing` (xspacing, yspacing)
	`grid_set_style` (style)
	`import_paths_from_file` (file, merge, scale)
	`import_paths_from_string` (string, length, merge, scale)
	`insert_channel` (channel, parent, position)
	`insert_layer` (layer, parent, position)
	`insert_path` (path, parent, position)
	`is_dirty` ()
	`is_valid` ()
	`lower_item` (item)
	`lower_item_to_bottom` (item)
	`merge_down` (merge_layer, merge_type)
	`merge_visible_layers` (merge_type)
	`metadata_save_filter` (mime_type, metadata, flags, file)
	`metadata_save_prepare` (mime_type, suggested_flags)
	`pick_color` (drawables, x, y, sample_merged, sample_average, average_radius)
	`pick_correlate_layer` (x, y)
	`policy_color_profile` (interactive)
	`policy_rotate` (interactive)
	`raise_item` (item)
	`raise_item_to_top` (item)
	`remove_channel` (channel)
	`remove_layer` (layer)
	`remove_path` (path)
	`reorder_item` (item, parent, position)
	`resize` (new_width, new_height, offx, offy)
	`resize_to_layers` ()
	`rotate` (rotate_type)
	`scale` (new_width, new_height)
	`select_color` (operation, drawable, color)
	`select_contiguous_color` (operation, drawable, x, y)
	`select_ellipse` (operation, x, y, width, height)
	`select_item` (operation, item)
	`select_polygon` (operation, segs)
	`select_rectangle` (operation, x, y, width, height)
	`select_round_rectangle` (operation, x, y, width, height, corner_radius_x, corner_radius_y)
	`set_color_profile` (profile)
	`set_color_profile_from_file` (file)
	`set_component_active` (component, active)
	`set_component_visible` (component, visible)
	`set_file` (file)
	`set_metadata` (metadata)
	`set_palette` (new_palette)
	`set_resolution` (xresolution, yresolution)
	`set_selected_channels` (channels)
	`set_selected_layers` (layers)
	`set_selected_paths` (paths)
	`set_simulation_bpc` (bpc)
	`set_simulation_intent` (intent)
	`set_simulation_profile` (profile)
	`set_simulation_profile_from_file` (file)
	`set_tattoo_state` (tattoo_state)
	`set_unit` (unit)
	`take_selected_channels` (channels)
	`take_selected_layers` (layers)
	`take_selected_paths` (paths)
	`thaw_channels` ()
	`thaw_layers` ()
	`thaw_paths` ()
	`undo_disable` ()
	`undo_enable` ()
	`undo_freeze` ()
	`undo_group_end` ()
	`undo_group_start` ()
	`undo_is_enabled` ()
	`undo_thaw` ()
	`unset_active_channel` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`id`	`int`	r/w/co	The image id for internal use

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Gimp.Image(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gimp.ImageClass

Operations on complete images: creation, resizing/rescaling, and operations involving multiple layers.

classmethod convert_set_dither_matrix(width, height, matrix)¶

Parameters:

width (int) – Width of the matrix (0 to reset to default matrix).
height (int) – Height of the matrix (0 to reset to default matrix).
matrix (GLib.Bytes) – The matrix – all values must be >= 1.

Returns:

True on success.

Return type:

bool

Set dither matrix for conversion to indexed

This procedure sets the dither matrix used when converting images to INDEXED mode with positional dithering.

New in version 2.4.

classmethod get_by_id(image_id)¶

Parameters:: image_id (int) – The image id.
Returns:: a Gimp.Image for image_id or None if image_id does not represent a valid image. The object belongs to libgimp and you must not modify or unref it.
Return type:: Gimp.Image or None

New in version 3.0.

classmethod id_is_valid(image_id)¶

Parameters:: image_id (int) – The image ID to check.
Returns:: Whether the image ID is valid.
Return type:: bool

Returns True if the image ID is valid.

This procedure checks if the given image ID is valid and refers to an existing image.

New in version 3.0.

classmethod metadata_load_thumbnail(file)¶

Parameters:: file (Gio.File) – A Gio.File image
Raises:: GLib.Error
Returns:: a Gimp.Image of the file thumbnail.
Return type:: Gimp.Image or None

Retrieves a thumbnail from metadata if present.

New in version 2.10.

classmethod new(width, height, type)¶

Parameters:

width (int) – The width of the image.
height (int) – The height of the image.
type (Gimp.ImageBaseType) – The type of image.

Returns:

The newly created image.

Return type:

Gimp.Image

Creates a new image with the specified width, height, and type.

Creates a new image, undisplayed, with the specified extents and type. A layer should be created and added before this image is displayed, or subsequent calls to Gimp.Display.new() with this image as an argument will fail. Layers can be created using the Gimp.Layer.new() commands. They can be added to an image using the Gimp.Image.insert_layer() command.

If your image’s type if INDEXED, a palette must also be set with [method`Gimp`.Image.set_palette]. An indexed image without a palette will output unexpected colors.

classmethod new_with_precision(width, height, type, precision)¶

Parameters:

width (int) – The width of the image.
height (int) – The height of the image.
type (Gimp.ImageBaseType) – The type of image.
precision (Gimp.Precision) – The precision.

Returns:

The newly created image.

Return type:

Gimp.Image

Creates a new image with the specified width, height, type and precision.

Creates a new image, undisplayed with the specified extents, type and precision. Indexed images can only be created at Gimp.Precision.U8_NON_LINEAR precision. See Gimp.Image.new() for further details.

New in version 2.10.

add_hguide(yposition)¶

Parameters:: yposition (int) – The guide’s y-offset from top of image.
Returns:: The new guide.
Return type:: int

Add a horizontal guide to an image.

This procedure adds a horizontal guide to an image. It takes the input image and the y-position of the new guide as parameters. It returns the guide ID of the new guide.

add_sample_point(position_x, position_y)¶

Parameters:

position_x (int) – The sample point’s x-offset from left of image.
position_y (int) – The sample point’s y-offset from top of image.

Returns:

The new sample point.

Return type:

int

Add a sample point to an image.

This procedure adds a sample point to an image. It takes the input image and the position of the new sample points as parameters. It returns the sample point ID of the new sample point.

New in version 2.10.

add_vguide(xposition)¶

Parameters:: xposition (int) – The guide’s x-offset from left of image.
Returns:: The new guide.
Return type:: int

Add a vertical guide to an image.

This procedure adds a vertical guide to an image. It takes the input image and the x-position of the new guide as parameters. It returns the guide ID of the new guide.

attach_parasite(parasite)¶

Parameters:: parasite (Gimp.Parasite) – The parasite to attach to an image.
Returns:: True on success.
Return type:: bool

Add a parasite to an image.

This procedure attaches a parasite to an image. It has no return values.

New in version 2.8.

autocrop(drawable)¶

Parameters:: drawable (Gimp.Drawable or None) – Input drawable.
Returns:: True on success.
Return type:: bool

Remove empty borders from the image

Remove empty borders from the self based on empty borders of the input drawable.

The input drawable serves as a base for detecting cropping extents (transparency or background color). With a None input drawable, the image itself will serve as a base for detecting cropping extents.

autocrop_selected_layers(drawable)¶

Parameters:: drawable (Gimp.Drawable or None) – Input drawable.
Returns:: True on success.
Return type:: bool

Crop the selected layers based on empty borders of the input drawable

Crop the selected layers of the input self based on empty borders of the input drawable. The input drawable serves as a base for detecting cropping extents (transparency or background color), and is not necessarily among the cropped layers (the current selected layers). With a None input drawable, the image itself will serve as a base for detecting cropping extents.

clean_all()¶

Returns:: True on success.
Return type:: bool

Set the image dirty count to 0.

This procedure sets the specified image’s dirty count to 0, allowing operations to occur without having a ‘dirtied’ image. This is especially useful for creating and loading images which should not initially be considered dirty, even though layers must be created, filled, and installed in the image. Note that save plug-ins must NOT call this function themselves after saving the image.

convert_color_profile(profile, intent, bpc)¶

Parameters:

profile (Gimp.ColorProfile) – The color profile to convert to.
intent (Gimp.ColorRenderingIntent) – Rendering intent.
bpc (bool) – Black point compensation.

Returns:

True on success.

Return type:

bool

Convert the image’s layers to a color profile

This procedure converts from the image’s color profile (or the default profile if none is set) to the given color profile.

Only RGB and grayscale color profiles are accepted, according to the image’s type.

New in version 2.10.

convert_color_profile_from_file(file, intent, bpc)¶

Parameters:

file (Gio.File) – The file containing the new color profile.
intent (Gimp.ColorRenderingIntent) – Rendering intent.
bpc (bool) – Black point compensation.

Returns:

True on success.

Return type:

bool

Convert the image’s layers to a color profile

This procedure converts from the image’s color profile (or the default RGB or grayscale profile if none is set) to an ICC profile specified by ‘file’. Only RGB and grayscale color profiles are accepted, according to the image’s type.

New in version 2.10.

convert_grayscale()¶

Returns:: True on success.
Return type:: bool

Convert specified image to grayscale

This procedure converts the specified image to grayscale. This process requires an image in RGB or Indexed color mode.

convert_indexed(dither_type, palette_type, num_cols, alpha_dither, remove_unused, palette)¶

Parameters:

dither_type (Gimp.ConvertDitherType) – The dither type to use.
palette_type (Gimp.ConvertPaletteType) – The type of palette to use.
num_cols (int) – The number of colors to quantize to, ignored unless (palette_type == Gimp.ConvertPaletteType.GENERATE).
alpha_dither (bool) – Dither transparency to fake partial opacity.
remove_unused (bool) – Remove unused or duplicate color entries from final palette, ignored if (palette_type == Gimp.ConvertPaletteType.GENERATE).
palette (str) – The name of the custom palette to use, ignored unless (palette_type == Gimp.ConvertPaletteType.CUSTOM).

Returns:

True on success.

Return type:

bool

Convert specified image to and Indexed image

This procedure converts the specified image to ‘indexed’ color. This process requires an image in RGB or Grayscale mode. The ‘palette_type’ specifies what kind of palette to use, A type of ‘0’ means to use an optimal palette of ‘num_cols’ generated from the colors in the image. A type of ‘1’ means to re-use the previous palette (not currently implemented). A type of ‘2’ means to use the so-called WWW-optimized palette. Type ‘3’ means to use only black and white colors. A type of ‘4’ means to use a palette from the gimp palettes directories. The ‘dither type’ specifies what kind of dithering to use. ‘0’ means no dithering, ‘1’ means standard Floyd-Steinberg error diffusion, ‘2’ means Floyd-Steinberg error diffusion with reduced bleeding, ‘3’ means dithering based on pixel location (‘Fixed’ dithering).

convert_precision(precision)¶

Parameters:: precision (Gimp.Precision) – The new precision.
Returns:: True on success.
Return type:: bool

Convert the image to the specified precision

This procedure converts the image to the specified precision. Note that indexed images cannot be converted and are always in GIMP_PRECISION_U8.

New in version 2.10.

convert_rgb()¶

Returns:: True on success.
Return type:: bool

Convert specified image to RGB color

This procedure converts the specified image to RGB color. This process requires an image in Grayscale or Indexed color mode. No image content is lost in this process aside from the colormap for an indexed image.

crop(new_width, new_height, offx, offy)¶

Parameters:

new_width (int) – New image width: (0 < new_width <= width).
new_height (int) – New image height: (0 < new_height <= height).
offx (int) – X offset: (0 <= offx <= (width - new_width)).
offy (int) – Y offset: (0 <= offy <= (height - new_height)).

Returns:

True on success.

Return type:

bool

Crop the image to the specified extents.

This procedure crops the image so that it’s new width and height are equal to the supplied parameters. Offsets are also provided which describe the position of the previous image’s content. All channels and layers within the image are cropped to the new image extents; this includes the image selection mask. If any parameters are out of range, an error is returned.

delete()¶

Returns:: True on success.
Return type:: bool

Delete the specified image.

If there are no displays associated with this image it will be deleted. This means that you can not delete an image through the PDB that was created by the user. If the associated display was however created through the PDB and you know the display ID, you may delete the display. Removal of the last associated display will then delete the image.

delete_guide(guide)¶

Parameters:: guide (int) – The ID of the guide to be removed.
Returns:: True on success.
Return type:: bool

Deletes a guide from an image.

This procedure takes an image and a guide ID as input and removes the specified guide from the specified image.

delete_sample_point(sample_point)¶

Parameters:: sample_point (int) – The ID of the sample point to be removed.
Returns:: True on success.
Return type:: bool

Deletes a sample point from an image.

This procedure takes an image and a sample point ID as input and removes the specified sample point from the specified image.

New in version 2.10.

detach_parasite(name)¶

Parameters:: name (str) – The name of the parasite to detach from an image.
Returns:: True on success.
Return type:: bool

Removes a parasite from an image.

This procedure detaches a parasite from an image. It has no return values.

New in version 2.8.

duplicate()¶

Returns:: The new, duplicated image.
Return type:: Gimp.Image

Duplicate the specified image

This procedure duplicates the specified image, copying all layers, channels, and image information.

export_path_to_file(file, path)¶

Parameters:

file (Gio.File) – The SVG file to create.
path (Gimp.Path or None) – The path object to export, or None for all in the image.

Returns:

True on success.

Return type:

bool

save a path as an SVG file.

This procedure creates an SVG file to save a Path object, that is, a path. The resulting file can be edited using a vector graphics application, or later reloaded into GIMP. Pass None as the ‘path’ argument to export all paths in the image.

New in version 2.6.

export_path_to_string(path)¶

Parameters:: path (Gimp.Path or None) – The path object to export, or None for all in the image.
Returns:: A string whose contents are a complete SVG document. The returned value must be freed with GLib.free().
Return type:: str

Save a path as an SVG string.

This procedure works like [method`Gimp`.Image.export_path_to_file] but creates a string rather than a file. The string is None-terminated and holds a complete XML document. Pass None as the ‘path’ argument to export all paths in the image.

New in version 2.6.

find_next_guide(guide)¶

Parameters:: guide (int) – The ID of the current guide (0 if first invocation).
Returns:: The next guide’s ID.
Return type:: int

Find next guide on an image.

This procedure takes an image and a guide ID as input and finds the guide ID of the successor of the given guide ID in the image’s guide list. If the supplied guide ID is 0, the procedure will return the first Guide. The procedure will return 0 if given the final guide ID as an argument or the image has no guides.

find_next_sample_point(sample_point)¶

Parameters:: sample_point (int) – The ID of the current sample point (0 if first invocation).
Returns:: The next sample point’s ID.
Return type:: int

Find next sample point on an image.

This procedure takes an image and a sample point ID as input and finds the sample point ID of the successor of the given sample point ID in the image’s sample point list. If the supplied sample point ID is 0, the procedure will return the first sample point. The procedure will return 0 if given the final sample point ID as an argument or the image has no sample points.

New in version 2.10.

flatten()¶

Returns:: The resulting layer.
Return type:: Gimp.Layer

Flatten all visible layers into a single layer. Discard all invisible layers.

This procedure combines the visible layers in a manner analogous to merging with the CLIP_TO_IMAGE merge type. Non-visible layers are discarded, and the resulting image is stripped of its alpha channel.

flip(flip_type)¶

Parameters:: flip_type (Gimp.OrientationType) – Type of flip.
Returns:: True on success.
Return type:: bool

Flips the image horizontally or vertically.

This procedure flips (mirrors) the image.

floating_sel_attached_to()¶

Returns:: The drawable the floating selection is attached to.
Return type:: Gimp.Drawable

Return the drawable the floating selection is attached to.

This procedure returns the drawable the image’s floating selection is attached to, if it exists. If it doesn’t exist, -1 is returned as the drawable ID.

freeze_channels()¶

Returns:: True on success.
Return type:: bool

Freeze the image’s channel list.

This procedure freezes the channel list of the image, suppressing any updates to the Channels dialog in response to changes to the image’s channels. This can significantly improve performance while applying changes affecting the channel list.

Each call to Gimp.Image.freeze_channels() should be matched by a corresponding call to Gimp.Image.thaw_channels(), undoing its effects.

New in version 2.10.2.

freeze_layers()¶

Returns:: True on success.
Return type:: bool

Freeze the image’s layer list.

This procedure freezes the layer list of the image, suppressing any updates to the Layers dialog in response to changes to the image’s layers. This can significantly improve performance while applying changes affecting the layer list.

Each call to Gimp.Image.freeze_layers() should be matched by a corresponding call to Gimp.Image.thaw_layers(), undoing its effects.

New in version 2.10.2.

freeze_paths()¶

Returns:: True on success.
Return type:: bool

Freeze the image’s path list.

This procedure freezes the path list of the image, suppressing any updates to the Paths dialog in response to changes to the image’s path. This can significantly improve performance while applying changes affecting the path list.

Each call to Gimp.Image.freeze_paths() should be matched by a corresponding call to Gimp.Image.thaw_paths (), undoing its effects.

New in version 2.10.2.

get_base_type()¶

Returns:: The image’s base type.
Return type:: Gimp.ImageBaseType

Get the base type of the image.

This procedure returns the image’s base type. Layers in the image must be of this subtype, but can have an optional alpha channel.

get_channel_by_name(name)¶

Parameters:: name (str) – The name of the channel to find.
Returns:: The channel with the specified name.
Return type:: Gimp.Channel

Find a channel with a given name in an image.

This procedure returns the channel with the given name in the specified image.

New in version 2.8.

get_channel_by_tattoo(tattoo)¶

Parameters:: tattoo (int) – The tattoo of the channel to find.
Returns:: The channel with the specified tattoo.
Return type:: Gimp.Channel

Find a channel with a given tattoo in an image.

This procedure returns the channel with the given tattoo in the specified image.

get_channels()¶

Returns:: The list of channels contained in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Channel]

Returns the list of channels contained in the specified image.

This procedure returns the list of channels contained in the specified image. This does not include the selection mask, or layer masks. The order is from topmost to bottommost. Note that \”channels\” are custom channels and do not include the image’s color components.

get_color_profile()¶

Returns:: The image’s color profile. The returned value must be freed with [method`GObject`.Object.unref].
Return type:: Gimp.ColorProfile

Returns the image’s color profile

This procedure returns the image’s color profile, or None if the image has no color profile assigned.

New in version 2.10.

get_component_active(component)¶

Parameters:: component (Gimp.ChannelType) – The image component.
Returns:: Component is active.
Return type:: bool

Returns if the specified image’s image component is active.

This procedure returns if the specified image’s image component (i.e. Red, Green, Blue intensity channels in an RGB image) is active or inactive – whether or not it can be modified. If the specified component is not valid for the image type, an error is returned.

get_component_visible(component)¶

Parameters:: component (Gimp.ChannelType) – The image component.
Returns:: Component is visible.
Return type:: bool

Returns if the specified image’s image component is visible.

This procedure returns if the specified image’s image component (i.e. Red, Green, Blue intensity channels in an RGB image) is visible or invisible – whether or not it can be seen. If the specified component is not valid for the image type, an error is returned.

get_default_new_layer_mode()¶

Returns:: The layer mode.
Return type:: Gimp.LayerMode

Get the default mode for newly created layers of this image.

Returns the default mode for newly created layers of this image.

New in version 2.10.

get_effective_color_profile()¶

Returns:: The color profile. The returned value must be freed with [method`GObject`.Object.unref].
Return type:: Gimp.ColorProfile

Returns the color profile that is used for the image.

This procedure returns the color profile that is actually used for this image, which is the profile returned by [method`Gimp`.Image.get_color_profile] if the image has a profile assigned, or the default profile from preferences, for the given color space, if no profile is assigned to the image. If there is no default profile configured in preferences either, a generated default profile is returned.

New in version 2.10.

get_exported_file()¶

Returns:: The exported file.
Return type:: Gio.File

Returns the exported file for the specified image.

This procedure returns the file associated with the specified image if the image was exported a non-native GIMP format. If the image was not exported, this procedure returns None.

New in version 2.8.

get_file()¶

Returns:: The file.
Return type:: Gio.File

Returns the file for the specified image.

This procedure returns the file associated with the specified image. The image has a file only if it was loaded or imported from a file or has since been saved or exported. Otherwise, this function returns None. See also gimp-image-get-imported-file to get the current file if it was imported from a non-GIMP file format and not yet saved, or gimp-image-get-exported-file if the image has been exported to a non-GIMP file format.

New in version 2.8.

get_floating_sel()¶

Returns:: The image’s floating selection.
Return type:: Gimp.Layer

Return the floating selection of the image.

This procedure returns the image’s floating selection, if it exists. If it doesn’t exist, -1 is returned as the layer ID.

get_guide_orientation(guide)¶

Parameters:: guide (int) – The guide.
Returns:: The guide’s orientation.
Return type:: Gimp.OrientationType

Get orientation of a guide on an image.

This procedure takes an image and a guide ID as input and returns the orientations of the guide.

get_guide_position(guide)¶

Parameters:: guide (int) – The guide.
Returns:: The guide’s position relative to top or left of image.
Return type:: int

Get position of a guide on an image.

This procedure takes an image and a guide ID as input and returns the position of the guide relative to the top or left of the image.

get_height()¶

Returns:: The image’s height.
Return type:: int

Return the height of the image

This procedure returns the image’s height. This value is independent of any of the layers in this image. This is the \”canvas\” height.

get_id()¶

Returns:: the image ID.
Return type:: int

New in version 3.0.

get_imported_file()¶

Returns:: The imported file.
Return type:: Gio.File

Returns the imported file for the specified image.

This procedure returns the file associated with the specified image if the image was imported from a non-native Gimp format. If the image was not imported, or has since been saved in the native Gimp format, this procedure returns None.

New in version 2.8.

get_item_position(item)¶

Parameters:: item (Gimp.Item) – The item.
Returns:: The position of the item in its level in the item tree.
Return type:: int

Returns the position of the item in its level of its item tree.

This procedure determines the position of the specified item in its level in its item tree in the image. If the item doesn’t exist in the image, or the item is not part of an item tree, an error is returned.

New in version 2.8.

get_layer_by_name(name)¶

Parameters:: name (str) – The name of the layer to find.
Returns:: The layer with the specified name.
Return type:: Gimp.Layer

Find a layer with a given name in an image.

This procedure returns the layer with the given name in the specified image.

New in version 2.8.

get_layer_by_tattoo(tattoo)¶

Parameters:: tattoo (int) – The tattoo of the layer to find.
Returns:: The layer with the specified tattoo.
Return type:: Gimp.Layer

Find a layer with a given tattoo in an image.

This procedure returns the layer with the given tattoo in the specified image.

get_layers()¶

Returns:: The list of layers contained in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Layer]

Returns the list of root layers contained in the specified image.

This procedure returns the list of root layers contained in the specified image. The order of layers is from topmost to bottommost. Note that this is not the full list of layers, but only the root layers, i.e. layers with no parents themselves. If you need all layers, it is up to you to verify that any of these layers is a group layer with Gimp.Item.is_group() and to obtain its children with Gimp.Item.get_children() (possibly recursively checking if these have children too).

get_metadata()¶

Returns:: The exif/ptc/xmp metadata, or None if there is none.
Return type:: Gimp.Metadata or None

Returns the image’s metadata.

Returns exif/iptc/xmp metadata from the image.

New in version 2.10.

get_name()¶

Returns:: The name. The returned value must be freed with GLib.free().
Return type:: str

Returns the specified image’s name.

This procedure returns the image’s name. If the image has a filename or an URI, then the returned name contains the filename’s or URI’s base name (the last component of the path). Otherwise it is the translated string \”Untitled\”. The returned name is formatted like the image name in the image window title, it may contain ‘[]’, ‘(imported)’ etc. and should only be used to label user interface elements. Never use it to construct filenames.

get_palette()¶

Returns:: The image’s colormap palette.
Return type:: Gimp.Palette

Returns the image’s colormap

This procedure returns the image’s colormap as a Gimp.Palette. If the image is not in Indexed color mode, None is returned.

New in version 3.0.

get_parasite(name)¶

Parameters:: name (str) – The name of the parasite to find.
Returns:: The found parasite.
Return type:: Gimp.Parasite

Look up a parasite in an image

Finds and returns the parasite that was previously attached to an image.

New in version 2.8.

get_parasite_list()¶

Returns:: The names of currently attached parasites. The returned value must be freed with GLib.strfreev().
Return type:: [str]

List all parasites.

Returns a list of the names of all currently attached parasites. These names can later be used to get the actual Gimp.Parasite with Gimp.Image.get_parasite() when needed.

New in version 2.8.

get_path_by_name(name)¶

Parameters:: name (str) – The name of the path to find.
Returns:: The path with the specified name.
Return type:: Gimp.Path

Find a path with a given name in an image.

This procedure returns the path with the given name in the specified image.

New in version 2.8.

get_path_by_tattoo(tattoo)¶

Parameters:: tattoo (int) – The tattoo of the path to find.
Returns:: The path with the specified tattoo.
Return type:: Gimp.Path

Find a path with a given tattoo in an image.

This procedure returns the path with the given tattoo in the specified image.

New in version 2.6.

get_paths()¶

Returns:: The list of paths contained in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Path]

Returns the list of paths contained in the specified image.

This procedure returns the list of paths contained in the specified image.

New in version 2.4.

get_precision()¶

Returns:: The image’s precision.
Return type:: Gimp.Precision

Get the precision of the image.

This procedure returns the image’s precision.

New in version 2.10.

get_resolution()¶

Returns:

True on success.

xresolution:: The resolution in the x-axis, in dots per inch.
yresolution:: The resolution in the y-axis, in dots per inch.

Return type:

(bool, xresolution: float, yresolution: float)

Returns the specified image’s resolution.

This procedure returns the specified image’s resolution in dots per inch. This value is independent of any of the layers in this image.

get_sample_point_position(sample_point)¶

Parameters:

sample_point (int) – The guide.

Returns:

The sample point’s x-offset relative to left of image.

position_y:: The sample point’s y-offset relative to top of image.

Return type:

(int, position_y: int)

Get position of a sample point on an image.

This procedure takes an image and a sample point ID as input and returns the position of the sample point relative to the top and left of the image.

New in version 2.10.

get_selected_channels()¶

Returns:: The list of selected channels in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Channel]

Returns the specified image’s selected channels.

This procedure returns the list of selected channels in the specified image.

New in version 3.0.0.

get_selected_drawables()¶

Returns:: The list of selected drawables in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Drawable]

Get the image’s selected drawables

This procedure returns the list of selected drawable in the specified image. This can be either layers, channels, or a layer mask. The active drawables are the active image channels. If there are none, these are the active image layers. If the active image layer has a layer mask and the layer mask is in edit mode, then the layer mask is the active drawable.

New in version 3.0.0.

get_selected_layers()¶

Returns:: The list of selected layers in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Layer]

Returns the specified image’s selected layers.

This procedure returns the list of selected layers in the specified image.

New in version 3.0.0.

get_selected_paths()¶

Returns:: The list of selected paths in the image. The returned value must be freed with GLib.free().
Return type:: [Gimp.Path]

Returns the specified image’s selected paths.

This procedure returns the list of selected paths in the specified image.

New in version 3.0.0.

get_selection()¶

Returns:: The selection channel.
Return type:: Gimp.Selection

Returns the specified image’s selection.

This will always return a valid ID for a selection – which is represented as a channel internally.

get_simulation_bpc()¶

Returns:: The Black Point Compensation status.
Return type:: bool

Returns whether the image has Black Point Compensation enabled for its simulation

This procedure returns whether the image has Black Point Compensation enabled for its simulation

New in version 3.0.

get_simulation_intent()¶

Returns:: The image’s simulation rendering intent.
Return type:: Gimp.ColorRenderingIntent

Returns the image’s simulation rendering intent

This procedure returns the image’s simulation rendering intent.

New in version 3.0.

get_simulation_profile()¶

Returns:: The image’s simulation color profile. The returned value must be freed with GObject.Object.unref().
Return type:: Gimp.ColorProfile

Returns the image’s simulation color profile

This procedure returns the image’s simulation color profile, or None if the image has no simulation color profile assigned.

New in version 3.0.

get_tattoo_state()¶

Returns:: The tattoo state.
Return type:: int

Returns the tattoo state associated with the image.

This procedure returns the tattoo state of the image. Use only by save/load plug-ins that wish to preserve an images tattoo state. Using this function at other times will produce unexpected results.

get_thumbnail(width, height, alpha)¶

Parameters:

width (int) – the requested thumbnail width (<= 1024 pixels)
height (int) – the requested thumbnail height (<= 1024 pixels)
alpha (Gimp.PixbufTransparency) – how to handle an alpha channel

Returns:

a new GdkPixbuf.Pixbuf

Return type:

GdkPixbuf.Pixbuf

Retrieves a thumbnail pixbuf for self. The thumbnail will be not larger than the requested size.

New in version 2.2.

get_thumbnail_data(width, height)¶

Parameters:

width (int) – The requested thumbnail width.
height (int) – The requested thumbnail height.

Returns:

the thumbnail data.

width:: The requested thumbnail width.
height:: The requested thumbnail height.
bpp:: The previews bpp.

Return type:

(GLib.Bytes, width: int, height: int, bpp: int)

Get a thumbnail of an image.

This function gets data from which a thumbnail of an image preview can be created. Maximum x or y dimension is 1024 pixels. The pixels are returned in RGB[A] or GRAY[A] format. The bpp return value gives the number of bytes per pixel in the image.

get_unit()¶

Returns:: The unit.
Return type:: Gimp.Unit

Returns the specified image’s unit.

This procedure returns the specified image’s unit. This value is independent of any of the layers in this image. See the gimp_unit_*() procedure definitions for the valid range of unit IDs and a description of the unit system.

get_width()¶

Returns:: The image’s width.
Return type:: int

Return the width of the image

This procedure returns the image’s width. This value is independent of any of the layers in this image. This is the \”canvas\” width.

get_xcf_file()¶

Returns:: The imported XCF file.
Return type:: Gio.File

Returns the XCF file for the specified image.

This procedure returns the XCF file associated with the image. If there is no such file, this procedure returns None.

New in version 2.8.

grid_get_background_color()¶

Returns:: The image’s grid background color.
Return type:: Gegl.Color

Sets the background color of an image’s grid.

This procedure gets the background color of an image’s grid.

New in version 2.4.

grid_get_foreground_color()¶

Returns:: The image’s grid foreground color.
Return type:: Gegl.Color

Sets the foreground color of an image’s grid.

This procedure gets the foreground color of an image’s grid.

New in version 2.4.

grid_get_offset()¶

Returns:

True on success.

xoffset:: The image’s grid horizontal offset.
yoffset:: The image’s grid vertical offset.

Return type:

(bool, xoffset: float, yoffset: float)

Gets the offset of an image’s grid.

This procedure retrieves the horizontal and vertical offset of an image’s grid. It takes the image as parameter.

New in version 2.4.

grid_get_spacing()¶

Returns:

True on success.

xspacing:: The image’s grid horizontal spacing.
yspacing:: The image’s grid vertical spacing.

Return type:

(bool, xspacing: float, yspacing: float)

Gets the spacing of an image’s grid.

This procedure retrieves the horizontal and vertical spacing of an image’s grid. It takes the image as parameter.

New in version 2.4.

grid_get_style()¶

Returns:: The image’s grid style.
Return type:: Gimp.GridStyle

Gets the style of an image’s grid.

This procedure retrieves the style of an image’s grid.

New in version 2.4.

grid_set_background_color(bgcolor)¶

Parameters:: bgcolor (Gegl.Color) – The new background color.
Returns:: True on success.
Return type:: bool

Gets the background color of an image’s grid.

This procedure sets the background color of an image’s grid.

New in version 2.4.

grid_set_foreground_color(fgcolor)¶

Parameters:: fgcolor (Gegl.Color) – The new foreground color.
Returns:: True on success.
Return type:: bool

Gets the foreground color of an image’s grid.

This procedure sets the foreground color of an image’s grid.

New in version 2.4.

grid_set_offset(xoffset, yoffset)¶

Parameters:

xoffset (float) – The image’s grid horizontal offset.
yoffset (float) – The image’s grid vertical offset.

Returns:

True on success.

Return type:

bool

Sets the offset of an image’s grid.

This procedure sets the horizontal and vertical offset of an image’s grid.

New in version 2.4.

grid_set_spacing(xspacing, yspacing)¶

Parameters:

xspacing (float) – The image’s grid horizontal spacing.
yspacing (float) – The image’s grid vertical spacing.

Returns:

True on success.

Return type:

bool

Sets the spacing of an image’s grid.

This procedure sets the horizontal and vertical spacing of an image’s grid.

New in version 2.4.

grid_set_style(style)¶

Parameters:: style (Gimp.GridStyle) – The image’s grid style.
Returns:: True on success.
Return type:: bool

Sets the style unit of an image’s grid.

This procedure sets the style of an image’s grid. It takes the image and the new style as parameters.

New in version 2.4.

import_paths_from_file(file, merge, scale)¶

Parameters:

file (Gio.File) – The SVG file to import.
merge (bool) – Merge paths into a single path object.
scale (bool) – Scale the SVG to image dimensions.

Returns:

True on success.

paths:: The list of newly created paths.

Return type:

(bool, paths: [Gimp.Path])

Import paths from an SVG file.

This procedure imports paths from an SVG file. SVG elements other than paths and basic shapes are ignored.

New in version 2.4.

import_paths_from_string(string, length, merge, scale)¶

Parameters:

string (str) – A string that must be a complete and valid SVG document.
length (int) – Number of bytes in string or -1 if the string is None terminated.
merge (bool) – Merge paths into a single path object.
scale (bool) – Scale the SVG to image dimensions.

Returns:

True on success.

paths:: The list of newly created paths.

Return type:

(bool, paths: [Gimp.Path])

Import paths from an SVG string.

This procedure works like [method`Gimp`.Image.import_paths_from_file] but takes a string rather than reading the SVG from a file. This allows you to write scripts that generate SVG and feed it to GIMP.

New in version 2.4.

insert_channel(channel, parent, position)¶

Parameters:

channel (Gimp.Channel) – The channel.
parent (Gimp.Channel or None) – The parent channel.
position (int) – The channel position.

Returns:

True on success.

Return type:

bool

Add the specified channel to the image.

This procedure adds the specified channel to the image at the given position. Since channel groups are not currently supported, the parent argument must always be 0. The position argument specifies the location of the channel inside the stack, starting from the top (0) and increasing. If the position is specified as -1, then the channel is inserted above the active channel.

insert_layer(layer, parent, position)¶

Parameters:

layer (Gimp.Layer) – The layer.
parent (Gimp.Layer or None) – The parent layer.
position (int) – The layer position.

Returns:

True on success.

Return type:

bool

Add the specified layer to the image.

This procedure adds the specified layer to the image at the given position. If the specified parent is a valid layer group (See Gimp.Item.is_group() and gimp_layer_group_new()) then the layer is added inside the group. If the parent is 0, the layer is added inside the main stack, outside of any group. The position argument specifies the location of the layer inside the stack (or the group, if a valid parent was supplied), starting from the top (0) and increasing. If the position is specified as -1 and the parent is specified as 0, then the layer is inserted above the active layer, or inside the group if the active layer is a layer group. The layer type must be compatible with the image base type.

insert_path(path, parent, position)¶

Parameters:

path (Gimp.Path) – The path.
parent (Gimp.Path or None) – The parent path.
position (int) – The path position.

Returns:

True on success.

Return type:

bool

Add the specified path to the image.

This procedure adds the specified path to the image at the given position. Since path groups are not currently supported, the parent argument must always be 0. The position argument specifies the location of the path inside the stack, starting from the top (0) and increasing. If the position is specified as -1, then the path is inserted above the active path.

is_dirty()¶

Returns:: True if the image has unsaved changes.
Return type:: bool

Checks if the image has unsaved changes.

This procedure checks the specified image’s dirty count to see if it needs to be saved. Note that saving the image does not automatically set the dirty count to 0, you need to call Gimp.Image.clean_all() after calling a save procedure to make the image clean.

is_valid()¶

Returns:: Whether the image is valid.
Return type:: bool

Returns True if the image is valid.

This procedure checks if the given image is valid and refers to an existing image.

New in version 2.4.

lower_item(item)¶

Parameters:: item (Gimp.Item) – The item to lower.
Returns:: True on success.
Return type:: bool

Lower the specified item in its level in its item tree

This procedure lowers the specified item one step in the item tree. The procedure call will fail if there is no item below it.

New in version 2.8.

lower_item_to_bottom(item)¶

Parameters:: item (Gimp.Item) – The item to lower to bottom.
Returns:: True on success.
Return type:: bool

Lower the specified item to the bottom of its level in its item tree

This procedure lowers the specified item to bottom of its level in the item tree. It will not move the layer if there is no layer below it.

New in version 2.8.

merge_down(merge_layer, merge_type)¶

Parameters:

merge_layer (Gimp.Layer) – The layer to merge down from.
merge_type (Gimp.MergeType) – The type of merge.

Returns:

The resulting layer.

Return type:

Gimp.Layer

Merge the layer passed and the first visible layer below.

This procedure combines the passed layer and the first visible layer below it using the specified merge type. A merge type of EXPAND_AS_NECESSARY expands the final layer to encompass the areas of the visible layers. A merge type of CLIP_TO_IMAGE clips the final layer to the extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the bottommost layer.

merge_visible_layers(merge_type)¶

Parameters:: merge_type (Gimp.MergeType) – The type of merge.
Returns:: The resulting layer.
Return type:: Gimp.Layer

Merge the visible image layers into one.

This procedure combines the visible layers into a single layer using the specified merge type. A merge type of EXPAND_AS_NECESSARY expands the final layer to encompass the areas of the visible layers. A merge type of CLIP_TO_IMAGE clips the final layer to the extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the bottommost layer.

metadata_save_filter(mime_type, metadata, flags, file)¶

Parameters:

mime_type (str) – The saved file’s mime-type
metadata (Gimp.Metadata) – The metadata to export
flags (Gimp.MetadataSaveFlags) – Flags to specify what of the metadata to save
file (Gio.File) – The file self was saved to or None if file was not saved yet

Raises:

GLib.Error

Returns:

Filtered metadata or None in case of failure. Use [GObject.Object.Object.unref] when returned metadata are no longer needed

Return type:

Gimp.Metadata

Filters the metadata retrieved from the image with [method`Gimp`.Image.metadata_save_prepare], taking into account the passed flags.

*Note: There is normally no need to call this function because it’s already called by [class`ExportProcedure`] after the run() callback.*

Note that the self passed to this function might be different from the image passed to gimp_image_metadata_save_prepare(), due to whatever file export conversion happened in the meantime

This can be used as an alternative to core metadata handling when you want to save metadata yourself and you need only filtering processing.

New in version 3.0.

metadata_save_prepare(mime_type, suggested_flags)¶

Parameters:

mime_type (str) – The saved file’s mime-type
suggested_flags (Gimp.MetadataSaveFlags) – Suggested default values for the metadata to export.

Returns:

The image’s metadata, prepared for saving.

Return type:

Gimp.Metadata

Gets the image metadata for storing it in an exported file.

*Note: There is normally no need to call this function because it’s already called by [class`ExportProcedure`] at the start and the metadata is passed to the run() callback.*

*You may call it separately for instance if you set export_metadata to None in [ctor`Gimp`.ExportProcedure.new] to prevent libgimp from trying to store the metadata in the exported file, yet you wish to process and store the metadata yourself using custom API.*

The suggested_flags are determined from what kind of metadata (Exif, XMP, …) is actually present in the image and the preferences for metadata exporting. The calling application may still ignore suggested_flags, for instance to follow the settings from a previous export in the same session, or a previous export of the same image. But it should not override the preferences without a good reason since it is a data leak.

The suggested value for [flags`Gimp`.MetadataSaveFlags.THUMBNAIL] is determined by whether there was a thumbnail in the previously imported image.

New in version 2.10.

pick_color(drawables, x, y, sample_merged, sample_average, average_radius)¶

Parameters:

drawables ([Gimp.Drawable]) – The drawables to pick from.
x (float) – x coordinate of upper-left corner of rectangle.
y (float) – y coordinate of upper-left corner of rectangle.
sample_merged (bool) – Use the composite image, not the drawables.
sample_average (bool) – Average the color of all the pixels in a specified radius.
average_radius (float) – The radius of pixels to average.

Returns:

True on success.

color:: The return color.

Return type:

(bool, color: Gegl.Color)

Determine the color at the given coordinates

This tool determines the color at the specified coordinates. The returned color is an RGB triplet even for grayscale and indexed drawables. If the coordinates lie outside of the extents of the specified drawables, then an error is returned. All drawables must belong to the image and be of the same type. If only one drawable is given and it has an alpha channel, the algorithm examines the alpha value of the drawable at the coordinates. If the alpha value is completely transparent (0), then an error is returned. With several drawables specified, the composite image with only these drawables is used. If the sample_merged parameter is True, the data of the composite image will be used instead of that for the specified drawables. This is equivalent to sampling for colors after merging all visible layers. In the case of a merged sampling, the supplied drawables are ignored.

pick_correlate_layer(x, y)¶

Parameters:

x (int) – The x coordinate for the pick.
y (int) – The y coordinate for the pick.

Returns:

The layer found at the specified coordinates.

Return type:

Gimp.Layer

Find the layer visible at the specified coordinates.

This procedure finds the layer which is visible at the specified coordinates. Layers which do not qualify are those whose extents do not pass within the specified coordinates, or which are transparent at the specified coordinates. This procedure will return -1 if no layer is found.

policy_color_profile(interactive)¶

Parameters:: interactive (bool) – Querying the user through a dialog is a possibility.
Returns:: True on success.
Return type:: bool

Execute the color profile conversion policy.

Process the image according to the color profile policy as set in Preferences. If GIMP is running as a GUI and interactive is True, a dialog may be presented to the user depending on the policy. Otherwise, if the policy does not mandate the conversion to perform, the conversion to the preferred RGB or grayscale profile will happen, defaulting to built-in profiles if no preferred profiles were set in Preferences. This function should be used only if you want to follow user settings. If you intend to convert to a specific profile, call preferably Gimp.Image.convert_color_profile(). And if you wish to leave whatever profile an image has, do not call any of these functions. Finally it is unnecessary to call this function in a format load procedure because this is called automatically by the core code when loading any image. You should only call this function explicitly when loading an image through a PDB call.

New in version 3.0.

policy_rotate(interactive)¶

Parameters:: interactive (bool) – Querying the user through a dialog is a possibility.
Returns:: True on success.
Return type:: bool

Execute the \”Orientation\” metadata policy.

Process the image according to the rotation policy as set in Preferences. If GIMP is running as a GUI and interactive is True, a dialog may be presented to the user depending on the set policy. Otherwise, if the policy does not mandate the action to perform, the image will be rotated following the Orientation metadata. If you wish absolutely to rotate a loaded image following the Orientation metadata, do not use this function and process the metadata yourself. Indeed even with interactive to False, user settings may leave the image unrotated. Finally it is unnecessary to call this function in a format load procedure because this is called automatically by the core code when loading any image. You should only call this function explicitly when loading an image through a PDB call.

New in version 3.0.

raise_item(item)¶

Parameters:: item (Gimp.Item) – The item to raise.
Returns:: True on success.
Return type:: bool

Raise the specified item in its level in its item tree

This procedure raises the specified item one step in the item tree. The procedure call will fail if there is no item above it.

New in version 2.8.

raise_item_to_top(item)¶

Parameters:: item (Gimp.Item) – The item to raise to top.
Returns:: True on success.
Return type:: bool

Raise the specified item to the top of its level in its item tree

This procedure raises the specified item to top of its level in the item tree. It will not move the item if there is no item above it.

New in version 2.8.

remove_channel(channel)¶

Parameters:: channel (Gimp.Channel) – The channel.
Returns:: True on success.
Return type:: bool

Remove the specified channel from the image.

This procedure removes the specified channel from the image. If the channel doesn’t exist, an error is returned.

remove_layer(layer)¶

Parameters:: layer (Gimp.Layer) – The layer.
Returns:: True on success.
Return type:: bool

Remove the specified layer from the image.

This procedure removes the specified layer from the image. If the layer doesn’t exist, an error is returned. If there are no layers left in the image, this call will fail. If this layer is the last layer remaining, the image will become empty and have no active layer.

remove_path(path)¶

Parameters:: path (Gimp.Path) – The path object.
Returns:: True on success.
Return type:: bool

Remove the specified path from the image.

This procedure removes the specified path from the image. If the path doesn’t exist, an error is returned.

New in version 2.4.

reorder_item(item, parent, position)¶

Parameters:

item (Gimp.Item) – The item to reorder.
parent (Gimp.Item or None) – The new parent item.
position (int) – The new position of the item.

Returns:

True on success.

Return type:

bool

Reorder the specified item within its item tree

Reorders or moves item within an item tree. Requires parent is None or a GroupLayer, else returns error. When parent is not None and item is in parent, reorders item within parent group. When parent is not None and item is not in parent, moves item into parent group. When parent is None, moves item from current parent to top level.

Requires item is in same tree as not None parent, else returns error. Layers, Channels, and Paths are in separate trees.

Requires item is not ancestor of parent, else returns error, to preclude cycles.

New in version 2.8.

resize(new_width, new_height, offx, offy)¶

Parameters:

new_width (int) – New image width.
new_height (int) – New image height.
offx (int) – x offset between upper left corner of old and new images: (new - old).
offy (int) – y offset between upper left corner of old and new images: (new - old).

Returns:

True on success.

Return type:

bool

Resize the image to the specified extents.

This procedure resizes the image so that it’s new width and height are equal to the supplied parameters. Offsets are also provided which describe the position of the previous image’s content. All channels within the image are resized according to the specified parameters; this includes the image selection mask. All layers within the image are repositioned according to the specified offsets.

resize_to_layers()¶

Returns:: True on success.
Return type:: bool

Resize the image to fit all layers.

This procedure resizes the image to the bounding box of all layers of the image. All channels within the image are resized to the new size; this includes the image selection mask. All layers within the image are repositioned to the new image area.

New in version 2.2.

rotate(rotate_type)¶

Parameters:: rotate_type (Gimp.RotationType) – Angle of rotation.
Returns:: True on success.
Return type:: bool

Rotates the image by the specified degrees.

This procedure rotates the image.

scale(new_width, new_height)¶

Parameters:

new_width (int) – New image width.
new_height (int) – New image height.

Returns:

True on success.

Return type:

bool

Scale the image using the default interpolation method.

This procedure scales the image so that its new width and height are equal to the supplied parameters. All layers and channels within the image are scaled according to the specified parameters; this includes the image selection mask. The interpolation method used can be set with Gimp.context_set_interpolation().

select_color(operation, drawable, color)¶

Parameters:

operation (Gimp.ChannelOps) – The selection operation.
drawable (Gimp.Drawable) – The affected drawable.
color (Gegl.Color) – The color to select.

Returns:

True on success.

Return type:

bool

Create a selection by selecting all pixels (in the specified drawable) with the same (or similar) color to that specified.

This tool creates a selection over the specified image. A by-color selection is determined by the supplied color under the constraints of the current context settings. Essentially, all pixels (in the drawable) that have color sufficiently close to the specified color (as determined by the threshold and criterion context values) are included in the selection. To select transparent regions, the color specified must also have minimum alpha.

This procedure is affected by the following context setters: Gimp.context_set_antialias(), Gimp.context_set_feather(), Gimp.context_set_feather_radius(), Gimp.context_set_sample_merged(), Gimp.context_set_sample_criterion(), Gimp.context_set_sample_threshold(), Gimp.context_set_sample_transparent().

In the case of a merged sampling, the supplied drawable is ignored.

New in version 2.8.

select_contiguous_color(operation, drawable, x, y)¶

Parameters:

operation (Gimp.ChannelOps) – The selection operation.
drawable (Gimp.Drawable) – The affected drawable.
x (float) – x coordinate of initial seed fill point: (image coordinates).
y (float) – y coordinate of initial seed fill point: (image coordinates).

Returns:

True on success.

Return type:

bool

Create a selection by selecting all pixels around specified coordinates with the same (or similar) color to that at the coordinates.

This tool creates a contiguous selection over the specified image. A contiguous color selection is determined by a seed fill under the constraints of the current context settings. Essentially, the color at the specified coordinates (in the drawable) is measured and the selection expands outwards from that point to any adjacent pixels which are not significantly different (as determined by the threshold and criterion context settings). This process continues until no more expansion is possible. If antialiasing is turned on, the final selection mask will contain intermediate values based on close misses to the threshold bar at pixels along the seed fill boundary.

This procedure is affected by the following context setters: Gimp.context_set_antialias(), Gimp.context_set_feather(), Gimp.context_set_feather_radius(), Gimp.context_set_sample_merged(), Gimp.context_set_sample_criterion(), Gimp.context_set_sample_threshold(), Gimp.context_set_sample_transparent(), Gimp.context_set_diagonal_neighbors().

In the case of a merged sampling, the supplied drawable is ignored. If the sample is merged, the specified coordinates are relative to the image origin; otherwise, they are relative to the drawable’s origin.

New in version 2.8.

select_ellipse(operation, x, y, width, height)¶

Parameters:

operation (Gimp.ChannelOps) – The selection operation.
x (float) – x coordinate of upper-left corner of ellipse bounding box.
y (float) – y coordinate of upper-left corner of ellipse bounding box.
width (float) – The width of the ellipse.
height (float) – The height of the ellipse.

Returns:

True on success.

Return type:

bool

Create an elliptical selection over the specified image.

This tool creates an elliptical selection over the specified image. The elliptical region can be either added to, subtracted from, or replace the contents of the previous selection mask.

This procedure is affected by the following context setters: Gimp.context_set_antialias(), Gimp.context_set_feather(), Gimp.context_set_feather_radius().

New in version 2.8.

select_item(operation, item)¶

Parameters:

operation (Gimp.ChannelOps) – The desired operation with current selection.
item (Gimp.Item) – The item to render to the selection.

Returns:

True on success.

Return type:

bool

Transforms the specified item into a selection

This procedure renders the item’s outline into the current selection of the image the item belongs to. What exactly the item’s outline is depends on the item type: for layers, it’s the layer’s alpha channel, for vectors the vector’s shape.

This procedure is affected by the following context setters: Gimp.context_set_antialias(), Gimp.context_set_feather(), Gimp.context_set_feather_radius().

New in version 2.8.

select_polygon(operation, segs)¶

Parameters:

operation (Gimp.ChannelOps) – The selection operation.
segs ([float]) – Array of points: { p1.x, p1.y, p2.x, p2.y, …, pn.x, pn.y}.

Returns:

True on success.

Return type:

bool

Create a polygonal selection over the specified image.

This tool creates a polygonal selection over the specified image. The polygonal region can be either added to, subtracted from, or replace the contents of the previous selection mask. The polygon is specified through an array of floating point numbers and its length. The length of array must be 2n, where n is the number of points. Each point is defined by 2 floating point values which correspond to the x and y coordinates. If the final point does not connect to the starting point, a connecting segment is automatically added.

This procedure is affected by the following context setters: Gimp.context_set_antialias(), Gimp.context_set_feather(), Gimp.context_set_feather_radius().

New in version 2.8.

select_rectangle(operation, x, y, width, height)¶

Parameters:

operation (Gimp.ChannelOps) – The selection operation.
x (float) – x coordinate of upper-left corner of rectangle.
y (float) – y coordinate of upper-left corner of rectangle.
width (float) – The width of the rectangle.
height (float) – The height of the rectangle.

Returns:

True on success.

Return type:

bool

Create a rectangular selection over the specified image;

This tool creates a rectangular selection over the specified image. The rectangular region can be either added to, subtracted from, or replace the contents of the previous selection mask.

This procedure is affected by the following context setters: Gimp.context_set_feather(), Gimp.context_set_feather_radius().

New in version 2.8.

select_round_rectangle(operation, x, y, width, height, corner_radius_x, corner_radius_y)¶

Parameters:

operation (Gimp.ChannelOps) – The selection operation.
x (float) – x coordinate of upper-left corner of rectangle.
y (float) – y coordinate of upper-left corner of rectangle.
width (float) – The width of the rectangle.
height (float) – The height of the rectangle.
corner_radius_x (float) – The corner radius in X direction.
corner_radius_y (float) – The corner radius in Y direction.

Returns:

True on success.

Return type:

bool

Create a rectangular selection with round corners over the specified image;

This tool creates a rectangular selection with round corners over the specified image. The rectangular region can be either added to, subtracted from, or replace the contents of the previous selection mask.

This procedure is affected by the following context setters: Gimp.context_set_antialias(), Gimp.context_set_feather(), Gimp.context_set_feather_radius().

New in version 2.8.

set_color_profile(profile)¶

Parameters:: profile (Gimp.ColorProfile or None) – A Gimp.ColorProfile, or None.
Returns:: True on success.
Return type:: bool

Sets the image’s color profile

This procedure sets the image’s color profile.

New in version 2.10.

set_color_profile_from_file(file)¶

Parameters:: file (Gio.File) – The file containing the new color profile.
Returns:: True on success.
Return type:: bool

Sets the image’s color profile from an ICC file

This procedure sets the image’s color profile from a file containing an ICC profile, or unsets it if None is passed as ‘file’. This procedure does no color conversion. However, it will change the pixel format of all layers to contain the babl space matching the profile. You must call this procedure before adding layers to the image.

New in version 2.10.

set_component_active(component, active)¶

Parameters:

component (Gimp.ChannelType) – The image component.
active (bool) – Component is active.

Returns:

True on success.

Return type:

bool

Sets if the specified image’s image component is active.

This procedure sets if the specified image’s image component (i.e. Red, Green, Blue intensity channels in an RGB image) is active or inactive – whether or not it can be modified. If the specified component is not valid for the image type, an error is returned.

set_component_visible(component, visible)¶

Parameters:

component (Gimp.ChannelType) – The image component.
visible (bool) – Component is visible.

Returns:

True on success.

Return type:

bool

Sets if the specified image’s image component is visible.

This procedure sets if the specified image’s image component (i.e. Red, Green, Blue intensity channels in an RGB image) is visible or invisible – whether or not it can be seen. If the specified component is not valid for the image type, an error is returned.

set_file(file)¶

Parameters:: file (Gio.File) – The new image file.
Returns:: True on success.
Return type:: bool

Sets the specified XCF image’s file.

This procedure sets the specified image’s file. This is to set the XCF file associated with your image. In particular, do not use this function to set the imported file in file import plug-ins. This is done by the core process.

set_metadata(metadata)¶

Parameters:: metadata (Gimp.Metadata) – The exif/ptc/xmp metadata.
Returns:: True on success.
Return type:: bool

Set the image’s metadata.

Sets exif/iptc/xmp metadata on the image, or deletes it if metadata is None.

New in version 2.10.

set_palette(new_palette)¶

Parameters:: new_palette (Gimp.Palette) – The palette to copy from.
Returns:: The image’s colormap palette.
Return type:: Gimp.Palette

Set the image’s colormap to a copy of palette

This procedure changes the image’s colormap to an exact copy of palette and returns the palette of self. If the image is not in Indexed color mode, nothing happens and None is returned.

New in version 3.0.

set_resolution(xresolution, yresolution)¶

Parameters:

xresolution (float) – The new image resolution in the x-axis, in dots per inch.
yresolution (float) – The new image resolution in the y-axis, in dots per inch.

Returns:

True on success.

Return type:

bool

Sets the specified image’s resolution.

This procedure sets the specified image’s resolution in dots per inch. This value is independent of any of the layers in this image. No scaling or resizing is performed.

set_selected_channels(channels)¶

Parameters:: channels ([Gimp.Channel]) – The list of channels to select.
Returns:: True on success.
Return type:: bool

Sets the specified image’s selected channels.

The channels are set as the selected channels in the image. Any previous selected layers or channels are unselected. An exception is a previously existing floating selection, in which case this procedure will return an execution error.

New in version 3.0.0.

set_selected_layers(layers)¶

Parameters:: layers ([Gimp.Layer]) – The list of layers to select.
Returns:: True on success.
Return type:: bool

Sets the specified image’s selected layers.

The layers are set as the selected layers in the image. Any previous selected layers or channels are unselected. An exception is a previously existing floating selection, in which case this procedure will return an execution error.

New in version 3.0.0.

set_selected_paths(paths)¶

Parameters:: paths ([Gimp.Path]) – The list of paths to select.
Returns:: True on success.
Return type:: bool

Sets the specified image’s selected paths.

The paths are set as the selected paths in the image.

New in version 3.0.0.

set_simulation_bpc(bpc)¶

Parameters:: bpc (bool) – The Black Point Compensation status.
Returns:: True on success.
Return type:: bool

Sets whether the image has Black Point Compensation enabled for its simulation

This procedure whether the image has Black Point Compensation enabled for its simulation

New in version 3.0.

set_simulation_intent(intent)¶

Parameters:: intent (Gimp.ColorRenderingIntent) – A Gimp.ColorRenderingIntent.
Returns:: True on success.
Return type:: bool

Sets the image’s simulation rendering intent

This procedure sets the image’s simulation rendering intent.

New in version 3.0.

set_simulation_profile(profile)¶

Parameters:: profile (Gimp.ColorProfile or None) – A Gimp.ColorProfile, or None.
Returns:: True on success.
Return type:: bool

Sets the image’s simulation color profile

This procedure sets the image’s simulation color profile.

New in version 3.0.

set_simulation_profile_from_file(file)¶

Parameters:: file (Gio.File) – The file containing the new simulation color profile.
Returns:: True on success.
Return type:: bool

Sets the image’s simulation color profile from an ICC file

This procedure sets the image’s simulation color profile from a file containing an ICC profile, or unsets it if None is passed as ‘file’. This procedure does no color conversion.

New in version 3.0.

set_tattoo_state(tattoo_state)¶

Parameters:: tattoo_state (int) – The new image tattoo state.
Returns:: True on success.
Return type:: bool

Set the tattoo state associated with the image.

This procedure sets the tattoo state of the image. Use only by save/load plug-ins that wish to preserve an images tattoo state. Using this function at other times will produce unexpected results. A full check of uniqueness of states in layers, channels and paths will be performed by this procedure and a execution failure will be returned if this fails. A failure will also be returned if the new tattoo state value is less than the maximum tattoo value from all of the tattoos from the paths, layers and channels. After the image data has been loaded and all the tattoos have been set then this is the last procedure that should be called. If effectively does a status check on the tattoo values that have been set to make sure that all is OK.

set_unit(unit)¶

Parameters:: unit (Gimp.Unit) – The new image unit.
Returns:: True on success.
Return type:: bool

Sets the specified image’s unit.

This procedure sets the specified image’s unit. No scaling or resizing is performed. This value is independent of any of the layers in this image. See the gimp_unit_*() procedure definitions for the valid range of unit IDs and a description of the unit system.

take_selected_channels(channels)¶

Parameters:: channels ([Gimp.Channel]) – The list of channels to select.
Returns:: True on success.
Return type:: bool

The channels are set as the selected channels in the image. Any previous selected layers or channels are unselected. An exception is a previously existing floating selection, in which case this procedure will return an execution error.

New in version 3.0.

take_selected_layers(layers)¶

Parameters:: layers ([Gimp.Layer]) – The list of layers to select.
Returns:: True on success.
Return type:: bool

The layers are set as the selected layers in the image. Any previous selected layers or channels are unselected. An exception is a previously existing floating selection, in which case this procedure will return an execution error.

New in version 3.0.

take_selected_paths(paths)¶

Parameters:: paths ([Gimp.Path]) – The list of paths to select.
Returns:: True on success.
Return type:: bool

The paths are set as the selected paths in the image. Any previous selected paths are unselected.

New in version 3.0.

thaw_channels()¶

Returns:: True on success.
Return type:: bool

Thaw the image’s channel list.

This procedure thaws the channel list of the image, re-enabling updates to the Channels dialog.

This procedure should match a corresponding call to Gimp.Image.freeze_channels().

New in version 2.10.2.

thaw_layers()¶

Returns:: True on success.
Return type:: bool

Thaw the image’s layer list.

This procedure thaws the layer list of the image, re-enabling updates to the Layers dialog.

This procedure should match a corresponding call to Gimp.Image.freeze_layers().

New in version 2.10.2.

thaw_paths()¶

Returns:: True on success.
Return type:: bool

Thaw the image’s path list.

This procedure thaws the path list of the image, re-enabling updates to the Paths dialog.

This procedure should match a corresponding call to Gimp.Image.freeze_paths().

New in version 2.10.2.

undo_disable()¶

Returns:: True if the image undo has been disabled.
Return type:: bool

Disable the image’s undo stack.

This procedure disables the image’s undo stack, allowing subsequent operations to ignore their undo steps. This is generally called in conjunction with Gimp.Image.undo_enable() to temporarily disable an image undo stack. This is advantageous because saving undo steps can be time and memory intensive.

undo_enable()¶

Returns:: True if the image undo has been enabled.
Return type:: bool

Enable the image’s undo stack.

This procedure enables the image’s undo stack, allowing subsequent operations to store their undo steps. This is generally called in conjunction with Gimp.Image.undo_disable() to temporarily disable an image undo stack.

undo_freeze()¶

Returns:: True if the image undo has been frozen.
Return type:: bool

Freeze the image’s undo stack.

This procedure freezes the image’s undo stack, allowing subsequent operations to ignore their undo steps. This is generally called in conjunction with Gimp.Image.undo_thaw() to temporarily disable an image undo stack. This is advantageous because saving undo steps can be time and memory intensive. Gimp.Image.undo_freeze() / Gimp.Image.undo_thaw() and Gimp.Image.undo_disable() / Gimp.Image.undo_enable() differ in that the former does not free up all undo steps when undo is thawed, so is more suited to interactive in-situ previews. It is important in this case that the image is back to the same state it was frozen in before thawing, else ‘undo’ behavior is undefined.

undo_group_end()¶

Returns:: True on success.
Return type:: bool

Finish a group undo.

This function must be called once for each Gimp.Image.undo_group_start() call that is made.

undo_group_start()¶

Returns:: True on success.
Return type:: bool

Starts a group undo.

This function is used to start a group undo–necessary for logically combining two or more undo operations into a single operation. This call must be used in conjunction with a Gimp.Image.undo_group_end() call.

undo_is_enabled()¶

Returns:: True if undo is enabled for this image.
Return type:: bool

Check if the image’s undo stack is enabled.

This procedure checks if the image’s undo stack is currently enabled or disabled. This is useful when several plug-ins or scripts call each other and want to check if their caller has already used Gimp.Image.undo_disable() or Gimp.Image.undo_freeze().

undo_thaw()¶

Returns:: True if the image undo has been thawed.
Return type:: bool

Thaw the image’s undo stack.

This procedure thaws the image’s undo stack, allowing subsequent operations to store their undo steps. This is generally called in conjunction with Gimp.Image.undo_freeze() to temporarily freeze an image undo stack. Gimp.Image.undo_thaw() does NOT free the undo stack as Gimp.Image.undo_enable() does, so is suited for situations where one wishes to leave the undo stack in the same state in which one found it despite non-destructively playing with the image in the meantime. An example would be in-situ plug-in previews. Balancing freezes and thaws and ensuring image consistency is the responsibility of the caller.

unset_active_channel()¶

Returns:: True on success.
Return type:: bool

Unsets the active channel in the specified image.

If an active channel exists, it is unset. There then exists no active channel, and if desired, one can be set through a call to ‘Set Active Channel’. No error is returned in the case of no existing active channel.

Property Details¶

Gimp.Image.props.id¶

Name:: id
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The image id for internal use