Table of Contents

23.4.2.3 Class Image (gb.image)

This class implements an image as an image. The image content is stored in the process memory, not in the display server like a picture.

To obtain or set individual pixel values, you can treat the Image class as a two-dimensional array: Image[x,y] would refer to the pixel at position (x, y) within the image. All methods change the image and return themselves. However, this does not apply to the Copy() method.

23.4.2.3.1 Constants

The Image class has these two integer constants:

ConstantValueDescription
Default0This constant represents an image whose pixels are encoded in ARGB format. Each pixel is encoded with four bytes in memory. The first byte is the alpha component, where 0 is completely transparent and 255 is completely opaque. The second byte is the red component. The third byte is the green component. The fourth byte is the blue component.
Premultiplied1This constant represents an image whose pixels are encoded in premultiplied ARGB format. Each pixel is coded with four bytes in the memory. The first byte is the alpha component, where 0 is completely transparent and 255 is completely opaque. The second byte is the red component, which has already been multiplied by the alpha component divided by 255. The third byte is the green component, already multiplied by the alpha component divided by 255. The fourth byte is the blue component, already multiplied by the alpha component divided by 255.

Table 23.4.2.3.1 : Constants of the Image class

The static property Debug defines the debugging mode or returns the boolean value whether the debugging mode is activated or not. If the debugging mode is activated, a message is displayed on the standard error output for each internal image conversion.

23.4.2.3.2 Properties

The Image class (gb.image) has these properties:

PropertyData typeDescription
DataPointerReturns a pointer to the image data.
DepthIntegerReturns the depth of the image in bits.
Format StringReturns the internal image format as a string. The format string can be “RGBA”, “ARGB”, “BGRA” etc.
Height or HIntegerReturns the height of the image (unit pixel).
Width or WIntegerReturns the width of the image (unit pixels).
Pixels Integer[ ]Since Gambas version 3.5. returns a copy of the colours of the image pixels as an array of 32-bit integers.

Table 23.4.2.3.2 : Properties of the Image class

Notes

23.4.2.3.3 Methods

The Image class has these methods:

MethodReturn typeDescription
BeginBalance ( )ImageSince Gambas version 3.5. start of a global image balance. All calls to the following methods: Brightness, Contrast, Saturation, Luminosity, Hue and Gamma are postponed until the EndBalance method is called. Grouping the adjustment in this way is faster than calling each method individually.
EndBalance ( )ImageSince Gambas version 3.5. ends a global image balance. Grouping the balance with BeginBalance() and EndBalance() is faster than calling each method - see BeginBalance() - individually.
Brightness ( Brightness As Float )ImageSince Gambas version 3.5. adjusts the image brightness. Brightness is a number between -1.0 and +1.0. If it is 0.0, nothing is changed.
Clear ( )-Clears the image.
Colorize ( Color As Integer )ImageColours the image content using the specified colour. Only the hue and saturation are used. The value component remains unchanged.
Contrast ( Contrast As Float )ImageSince Gambas version 3.5. sets the image contrast. Contrast is a number between -1.0 and +1.0. Nothing is changed with a value of 0.0.
Copy ( [ X As Integer, Y As Integer, Width As Integer, Height As Integer ] )ImageReturns a copy of the image or a copy of a part of the image.
Desaturate ( )ImageDesaturates an image; converts it to greyscale.
DrawAlpha ( Image As Image [ , X As Integer, Y As Integer, SrcX As Integer, SrcY As Integer, SrcWidth As Integer, SrcHeight As Integer ] )ImageCopies the alpha channel from Image to the current image. X, Y are the target of the copy. The default is the origin of the current image. SrcX, SrcY, SrcWidth, SrcHeight determine the part of Image to be copied. By default, the entire image is copied.
DrawImage ( Image As Image [ , X As Integer, Y As Integer, Width As Integer, Height As Integer, SrcX As Integer, SrcY As Integer, SrcWidth As Integer, SrcHeight As Integer ] )ImageCopies the image within the current image. X, Y is the destination of the drawing. By default, this is the origin of the current image. Width, Height are the dimensions of the copy.
Erase ( [ Color As Integer ] )ImageCreates an alpha channel in the image by erasing the specified colour. The white colour is used by default.
Fill ( Color As Integer )ImageFills the image with the specified colour.
FillRect ( X As Integer, Y As Integer, Width As Integer, Height As Integer, Color As Integer ) ImageFills the defined rectangle in the image with the specified colour. X, Y, Width, Height define the rectangle to be filled. Color is the fill colour and can also be a transparent colour.
Fuzzy ( [ Radius As Integer ] )ImageBlurs an image and returns itself. Radius is the blur radius in pixels (8 by default). If the radius is less than or equal to 0 or greater than or equal to 256, the method has no effect.
Gamma ( Gamma As Float )ImageSince Gambas version 3.5. adjusts the gamma of the image. Gamma is a number between -1.0 and +1.0. Nothing is changed with a value of 0.0.
Gray ( ) ImageConverts an image to greyscale.
Hue ( Hue As Float )ImageSince Gambas version 3.5. adjusts the colour tone of the image. The hue is a number between -1.0 and +1.0. Nothing is changed with a value of 0.0.
Invert ( [ KeepHue As Boolean ] )ImageInverts an image and returns it. If KeepHue is TRUE, the hue component of the colour is retained. If KeepHue is FALSE (default setting), all colour components are inverted.
Lightness ( Lightness As Float )ImageSince Gambas version 3.5. adjusts the brightness of the image. Lightness is a number between -1.0 and +1.0. Nothing is changed with a value of 0.0.
Mask ( Color As Integer )ImageMultiplies each colour component of each pixel by the colour component of the specified colour.
Mirror ( Horizontal As Boolean, Vertical As Boolean )ImageReturns the vertically and/or horizontally mirrored image.
Opacity ( Opacity As Float )ImageSince Gambas version 3.2. changes the opacity of an image. Opacity is the multiplication factor of the opacity between 0 and 1. If it is 0, the image becomes completely transparent. If it is 1, the opacity remains unchanged.
Replace ( OldColor As Integer, NewColor As Integer [ , NotEqual As Boolean ] )ImageReplaces one colour with another.
Resize ( Width As Integer, Height As Integer )ImageChanges the size of the image. The image content is cut out, but not stretched or expanded.
RotateLeft ( )ImageSince Gambas version 3.3. rotates an image 90° to the left and returns it.
RotateRight ( )ImageSince Gambas version 3.3. rotates an image 90° to the right and returns it.
Saturation ( Saturation As Float )ImageSince Gambas version 3.5. adjusts the saturation of the image. Saturation is a number between -1.0 and +1.0. If the value is 0.0, nothing is changed.
Transparent ( [ Color As Integer ] )ImageMakes the image transparent with the specified colour. The closer a pixel colour is to the specified colour, the more transparent it becomes. If the optional parameter is not specified, it is assumed to be white.

Table 23.4.2.3.3 : Methods of the Shape class

Notes

23.4.2.3.4 Examples

An example is presented for each of the above methods of the Image (gb.image) class. If the methods use parameters, these and the images - the original and the modified one - are displayed. The source code used in each case is also shown in extracts.

Example 1 - Image.Desaturate() method

The method converts the original into a greyscale image. Note: The Gray() method is considered obsolete and should be replaced by the Desaturate() method.

BILD Desaturate

Figure 23.4.2.3.1: Desaturate() method

Source code snippet

Public Sub btnDoGray_Click()
 
    lblChanged.Text = "C H A N G E D  >>  " & "G R A Y S C A L E ( )"
'-- imgChanged = imgOriginal.Gray()
'-- Warning: Image.Gray is deprecated, use Image.Desaturate instead.
    imgChanged = imgOriginal.Desaturate()
    pboxChanged.Picture = imgChanged.Picture
 
End

Example 2 - Method mix

In this example, 6 methods are used to manipulate the original one after the other:

BILD Mix

Figure 23.4.2.3.2: Method_mix (balance)

Source code snippet

Public Sub btnDoBalanceMix_Click()
 
    imgChanged = imgOriginal
 
    imgChanged = imgChanged.Brightness(-0.2)
    imgChanged = imgChanged.Contrast(0.4)
    imgChanged = imgChanged.Saturation(-0.1)
    imgChanged = imgChanged.Lightness(0.3)
    imgChanged = imgChanged.Hue(-0.4)
    imgChanged = imgChanged.Gamma(-0.33)
 
    pboxChanged.Picture = imgChanged.Picture
 
End

Example 3 - Image.Implode(…) method

The method gives the original an effect that appears to implode the image content in the centre:

BILD Implode

Figure 23.4.2.3.3: Implode() method

Source code snippet

  lblChanged.Text = "C H A N G E D  >>  " & "I M P L O D E (...)"
  lblValue.Text = hSliderV.Value / 100
  imgChanged = imgOriginal.Implode(hSliderV.Value / 100, Color.Red)
  pboxChanged.Picture = imgChanged.Picture