GoostImage

Inherits: Object

An Image processing, analysis and utility singleton.

Description

A singleton which handles various Image processing and analysis tasks. Most methods accept an image as an input.

Methods

void binarize ( Image image, float threshold=-1, bool invert=false )
Image bucket_fill ( Image image, Vector2 at, Color fill_color, bool fill_image=true, Connectivity connectivity=0 )
void dilate ( Image image, int kernel_size=3 )
void erode ( Image image, int kernel_size=3 )
Vector2 get_centroid ( Image image )
Color get_pixel_average ( Image image, Rect2 rect=Rect2( 0, 0, 0, 0 ), Image mask=null )
Variant get_pixel_or_null ( Image image, int x, int y )
Variant get_pixelv_or_null ( Image image, Vector2 pos )
bool has_pixel ( Image image, int x, int y )
bool has_pixelv ( Image image, Vector2 pos )
void morph ( Image image, MorphOperation operation, Vector2 kernel_size=Vector2( 3, 3 ) )
Image render_polygon ( PoolVector2Array polygon, bool fill=false, Color foreground_color=Color( 1, 1, 1, 1 ), Color background_color=Color( 0, 0, 0, 0 ) )
Image render_svg ( String svg_document, float scale=1.0 )
Image repeat ( Image image, Vector2 count, WrapMode wrap_mode=0, Vector2 max_size=Vector2( 16384, 16384 ) )
void replace_color ( Image image, Color color, Color with_color )
void resize_hqx ( Image image, int scale=2 )
void rotate ( Image image, float angle, bool expand=true )
void rotate_180 ( Image image )
void rotate_90 ( Image image, Direction direction )
Image tile ( Image image, Vector2 size, WrapMode wrap_mode=0 )

Enumerations

enum Connectivity:

  • FOUR_CONNECTED = 0 — Describes the Neumann neighborhood.
  • EIGHT_CONNECTED = 1 — Describes the Moore neighborhood.

enum MorphOperation:

  • MORPH_DILATE = 0 — Causes bright regions within an image to grow.
  • MORPH_ERODE = 1 — Causes bright regions within an image to shrink.
  • MORPH_OPEN = 2 — Erosion followed by dilation. Useful for removing noise.
  • MORPH_CLOSE = 3 — Dilation followed by erosion. Useful for closing small holes inside the foreground objects.

enum Direction:

  • CW = 1 — Clockwise direction or orientation.
  • CCW = -1 — Counterclockwise (a.k.a. Anticlockwise) direction or orientation.

enum WrapMode:

  • TILE = 0 — Tiles an image over a region by making copies of it. Similar to Texture.FLAG_REPEAT.
  • TILE_FLIP_X = 1 — Tiles an image over a region by flipping it horizontally repeatedly.
  • TILE_FLIP_Y = 2 — Tiles an image over a region by flipping it vertically repeatedly.
  • TILE_FLIP_XY = 3 — Tiles an image over a region by mirroring it both horizontally in vertically. Similar to Texture.FLAG_MIRRORED_REPEAT.

Method Descriptions

  • void binarize ( Image image, float threshold=-1, bool invert=false )

Converts the image into grayscale binary image Image.FORMAT_L8. If the pixel value is smaller than the threshold, it is set to 0, otherwise it is set to a maximum value.

The default threshold of -1 tells the method to apply adaptive threshold, which is determined by analyzing the image for different lighting in different areas.

If invert is true, flips all values to either zero or one.

Fills the area with a fill_color confined by other opaque pixels. If fill_image is false, the filled image chunk shall not overwrite the original image. The filled chunk is returned as another Image in all cases.

Connectivity specifies the flood fill algorithm. FOUR_CONNECTED allows the filling pixels to go through diagonally placed opaque pixels and is slightly more efficient compared to EIGHT_CONNECTED.

  • void dilate ( Image image, int kernel_size=3 )

Does image dilation, similar to morph with MORPH_DILATE, but accepts a uniform kernel size.

  • void erode ( Image image, int kernel_size=3 )

Does image erosion, similar to morph with MORPH_ERODE, but accepts a uniform kernel size.

Finds a relative geometrical center within the image.

Returns the average color by averaging each color component. If rect is not empty, computes the average over the region of the image only. Similarly, an image mask can be specified with opaque pixels acting as a filter of all the pixels of interest. Both the rect and the mask can be used simultaneously.

Returns a Color pixel at specified image coordinates. Returns null if coordinates lie outside the image boundaries.

Same as get_pixel_or_null but accepts Vector2 for specifying image coordinates.

Returns true if the specified coordinates lie in between image boundaries determined by its size.

Same as has_pixel but uses Vector2 for specifying image coordinates.

Performs basic image morphing operations. The structuring element (kernel) is a brick, with the origin being implicitly in the center. The width and height of the kernel must be an odd number, but they can differ. The operation does the morphing on each color component separately, which are later combined.

Renders a binary representation of the polygon as a new image. If fill is true, fills the interior of the polygon with foreground_color (white by default), else just renders the polygon’s outline alone with the same color. The boundary pixels are always FOUR_CONNECTED. The image background_color can also be overridden (transparent by default).

Rasterizes a SVG document as a new image. Any positive scale can be set, as long as the resulting image does not exceed maximum image size determined by Image.MAX_WIDTH and Image.MAX_HEIGHT constants. Returns null if SVG is corrupt.

In order to render a SVG from a File:

var file = File.new()
file.open("res://icon.svg", File.READ)
var svg = file.get_as_text()
var image = GoostImage.render_svg(svg)
file.close()

Known limitations:

This method reuses nanosvg implementation bundled with Godot for rendering editor icons and importing simple SVG images, so the functionality may be limited for more complex images.

Note: this method is not available in Godot builds with SVG module disabled (enabled by default).

Repeats an image in both horizontal and vertical directions several times as determined by the X and Y components of count respectively. The wrap_mode specifies how the image is tiled. The max_size can be overridden to prevent the resulting image from exceeding some size, and the default maximum size is determined by Image.MAX_WIDTH and Image.MAX_HEIGHT. See also tile.

Replaces all occurrences of a given color with another one within the image.

  • void resize_hqx ( Image image, int scale=2 )

Expands the image using HQ2X algorithm with the scale set to 2 or the HQ3X algorithm with the scale set to 3.

See also Image.expand_x2_hq2x.

Rotates the image around its center. The angle is specified in radians. If angle is positive, rotates the image in clockwise direction. If expand is true, the size is expanded to preserve all image details (prevents clipping) given non-orthogonal angles (90, 180, 270 degrees).

# Rotate Godot icon by 45 degrees.
var texture = preload("res://icon.png")
var image = texture.get_data()
GoostImage.rotate(image, deg2rad(45))
image.save_png("res://icon_rotated.png")
  • void rotate_180 ( Image image )

Rotates the image by 180 degrees. The result is equivalent to:

image.flip_x()
image.flip_y()

See Image.flip_x, Image.flip_y.

Rotates the image by 90 degrees in either clockwise or counterclockwise Direction. The method performs faster and doesn’t lose any image pixel information as opposed to rotate with the angle parameter set to PI / 2.

Tiles an image in both horizontal and vertical directions over a region limited by size onto a new image. The wrap_mode specifies how the image is tiled. See also repeat.