This class encapsulates a platform-independent image. An image can be created from data, or using Bitmap#convert_to_image. An image can be loaded from a file in a variety of formats. Functions are available to set and get image bits, so it can be used for basic image manipulation.
A Image cannot (currently) be drawn directly to a DC. Instead, a platform-specific Bitmap object must be created from it using the Bitmap::Bitmap constructor. This bitmap can then be drawn in a device context, using DC#draw_bitmap.
One colour value of the image may be used as a mask colour which will lead to the automatic creation of a Mask object associated to the bitmap object.
Wx::Image supports alpha channel data: in addition to a byte for the red, green and blue colour components for each pixel it also stores a byte representing the pixel opacity. An alpha value of 0 corresponds to a transparent pixel (null opacity) while a value of 255$ means that the pixel is 100\% opaque.
Unlike RGB data, not all images have an alpha channel and before using get_alpha you should check if this image contains an alpha channel with has_alpha. Note that currently only images loaded from PNG files with transparency information will have an alpha channel but alpha support will be added to the other formats as well (as well as support for saving images with alpha channel which also isn’t implemented).
The following image handlers are available and are initialised automatically when wxRuby is loaded.
| BMPHandler | For loading and saving, always installed. |
| PNGHandler | For loading (including alpha support) and saving. |
| JPEGHandler | For loading and saving. |
| GIFHandler | Only for loading, due to legal issues. |
| PCXHandler | For loading and saving (see below). |
| PNMHandler | For loading and saving (see below). |
| TIFFHandler | For loading and saving. |
| TGAHandler | For loading only. |
| IFFHandler | For loading only. |
| XPMHandler | For loading and saving. |
| ICOHandler | For loading and saving. |
| CURHandler | For loading and saving. |
| ANIHandler | For loading only. |
When saving in PCX format, PCXHandler will count the number of different colours in the image; if there are 256 or less colours, it will save as 8 bit, else it will save as 24 bit.
Loading PNMs only works for ASCII or raw RGB images. When saving in PNM format, PNMHandler will always save as raw RGB.
Image.new(Image image)Copy constructor, uses reference counting.
Image.new(String file_name, Integer type = BITMAP_TYPE_ANY, Integer index = -1)Image.new(String file_name, String mimetype, Integer index = -1)Loads an image from a file. The type should specify the file type; the index argument is only needed for image file types which support multiple images, such as GIF or TIF.
Image.new(Integer width, Integer height,
Boolean clear=true)Creates an image with the given width and height. If clear is true, the new image will be initialized to black. Otherwise, the image data will be uninitialized.
Image.new(Integer width, Integer height,
String data)Creates an image from given data string, with the given width and height. See set_data for a description of the raw data format. The string’s length should be equal to width x height x 3.
Image.new(String xpmData)Creates an image from XPM data.
| BITMAP_TYPE_BMP | Load a Windows bitmap file. |
| BITMAP_TYPE_GIF | Load a GIF bitmap file. |
| BITMAP_TYPE_JPEG | Load a JPEG bitmap file. |
| BITMAP_TYPE_PNG | Load a PNG bitmap file. |
| BITMAP_TYPE_PCX | Load a PCX bitmap file. |
| BITMAP_TYPE_PNM | Load a PNM bitmap file. |
| BITMAP_TYPE_TIF | Load a TIFF bitmap file. |
| BITMAP_TYPE_TGA | Load a TGA bitmap file. |
| BITMAP_TYPE_XPM | Load a XPM bitmap file. |
| BITMAP_TYPE_ICO | Load a Windows icon file (ICO). |
| BITMAP_TYPE_CUR | Load a Windows cursor file (CUR). |
| BITMAP_TYPE_ANI | Load a Windows animated cursor file (ANI). |
| BITMAP_TYPE_ANY | Will try to autodetect the format. |
Depending on how wxWidgets has been configured, not all formats may be available. In standard wxRuby, all of standard file types listed above are supported on all platforms; the only exceptions are Windows-only icon and cursor files, which are only available on Windows.
Note: you can use get_option_int to get the hotspot for loaded cursor file:
hotspot_x = image.get_option_int(IMAGE_OPTION_CUR_HOTSPOT_X)
hotspot_y = image.get_option_int(IMAGE_OPTION_CUR_HOTSPOT_Y)Image.from_bitmap(Bitmap bitmap)Creates a new image from an platform-dependent bitmap, preserving mask information.
Image.read(IO an_io, Integer type = BITMAP_TYPE_ANY, Integer index = -1) )Image.read(IO an_io, String mimetype, Integer index = -1)Creates a new image using data read from an_io. an_io may be any
ruby object which implements a read method and similar basic IO
operations, such as a File, IO, Socket or StringIO object.
The type and mimetype parameters have the same meaning as in the standard constructor.
Image blur(Integer blurRadius)Blurs the image in both horizontal and vertical directions by the specified pixel blurRadius. This should not be used when using a single mask colour for transparency.
Image blur_horizontal(Integer blurRadius)Image blur_vertical(Integer blurRadius)Blurs the image in the vertical direction only. This should not be used when using a single mask colour for transparency.
Integer compute_histogram(ImageHistogram histogram)Computes the histogram of the image. histogram is a reference to ImageHistogram object. ImageHistogram is a specialization of HashMap “template” and is defined as follows:
class WXDLLEXPORT ImageHistogramEntry
{
public:
ImageHistogramEntry() : index(0), value(0) {}
unsigned long index;
unsigned long value;
};WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, ImageHistogramEntry,
IntegerHash, IntegerEqual,
ImageHistogram);Returns number of colours in the histogram.
Boolean convert_alpha_to_mask(Integer threshold = $128$)If the image has alpha channel, this method converts it to mask. All pixels with alpha value less than threshold are replaced with mask colour and the alpha channel is removed. Mask colour is chosen automatically using find_first_unused_colour.
If the image image doesn’t have alpha channel, ConvertAlphaToMask does nothing.
if FindFirstUnusedColour returns , otherwise.Bitmap convert_to_bitmap()Deprecated, use equivalent Bitmap constructor (which takes Image and depth as its arguments) instead.
Image convert_to_greyscale(Float lr = 0.299,
Float lg = 0.587,
Float lb = 0.114)Returns a greyscale version of the image. The returned image uses the luminance component of the original to calculate the greyscale. Defaults to using ITU-T BT.601 when converting to YUV, where every pixel equals (R * lr) + (G * lg) + (B * lb).
Image convert_to_mono(Integer r, Integer g,
Integer b)Returns monochromatic version of the image. The returned image has white colour where the original has (r,g,b) colour and black colour everywhere else.
Image copy()Returns an identical copy of the image.
Boolean create(Integer width, Integer height,
Boolean clear=true)Creates a fresh image. If clear is true, the new image will be initialized to black. Otherwise, the image data will be uninitialized.
true if the call succeeded, false otherwise.
destroy()Destroys the image data.
Boolean find_first_unused_colour(Integer r, Integer g,
Integer b,
Integer startR = 1,
Integer startG = 0,
Integer startB = 0)Finds the first colour that is never used in the image. The search begins at given initial colour and continues by increasing R, G and B components (in this order) by 1 until an unused colour is found or the colour space exhausted.
Returns false if there is no unused colour left, true on success.
Note that this method involves computing the histogram, which is computationally intensive operation.
String get_image_ext_wildcard()Iterates all registered ImageHandler objects, and returns a string containing file extension masks suitable for passing to file open/save dialog boxes.
The format of the returned string is “(.ext1;.ext2)|.ext1;.ext2”.
It is usually a good idea to prepend a description before passing the result to the dialog.
Integer get_alpha(Integer x, Integer y)Returns the alpha value for the given pixel. This function may only be called for the images with alpha channel, use has_alpha to check for this.
The returned value is the opacity of the image, i.e. the value of $0$ corresponds to the transparent pixels while the value of $255$—to the opaque ones.
Integer get_alpha()Returns pointer to the array storing the alpha values for this image. This
pointer is NULL for the images without the alpha channel. If the image
does have it, this pointer may be used to directly manipulate the alpha values
which are stored as the RGB ones.
Integer get_blue(Integer x, Integer y)Returns the blue intensity at the given coordinate.
String get_data()Returns the raw image data as a string. This is most often used when doing direct image manipulation. The returned string contains a sequence of bytes (characters) each of which represents the value of one red, green or blue component in the range 0 to 255.
The values are in a series of triplets in RGB-RGB-RGB-RGB format from top-to-bottom, left-to-right order. Thus the first RGB triplet corresponds to the pixel first pixel of the first row, the second one to the second pixel of the first row and so on until the end of the first row, with second row following after it and so on.
To extract the integer values for the RGB components, use Ruby’s String.unpack method; for example, to convert the whole data string to a set of integer values:
my_image.data.unpack("C") # returns something like [255, 128, 0, 255 ...]This would mean that the first pixel had a red value of 255, a green value of 128, and a blue value of 0; the second pixel a red value of 255, and so on.
Note that unlike the C++ wxWidgets API, the returned string is a copy of the internal data; methods that alter the string will *not change the Image’s content. If you wish to do this, alter the string then call set_data, for example:
my_image.data = my_image.data.reverseThis would flip the image diagonally around it’s bottom-left to top-right axis, and swap the red and blue components of each pixel, leaving the green the same. If you understand why this is the result, you can consider yourself in a good position to make use of these methods.
Integer get_green(Integer x, Integer y)Returns the green intensity at the given coordinate.
Integer get_image_count(String filename, Integer type = BITMAP_TYPE_ANY)If the image file contains more than one image and the image handler is capable of retrieving these individually, this function will return the number of available images.
| BITMAP_TYPE_BMP | Load a Windows bitmap file. |
| BITMAP_TYPE_GIF | Load a GIF bitmap file. |
| BITMAP_TYPE_JPEG | Load a JPEG bitmap file. |
| BITMAP_TYPE_PNG | Load a PNG bitmap file. |
| BITMAP_TYPE_PCX | Load a PCX bitmap file. |
| BITMAP_TYPE_PNM | Load a PNM bitmap file. |
| BITMAP_TYPE_TIF | Load a TIFF bitmap file. |
| BITMAP_TYPE_XPM | Load a XPM bitmap file. |
| BITMAP_TYPE_ICO | Load a Windows icon file (ICO). |
| BITMAP_TYPE_CUR | Load a Windows cursor file (CUR). |
| BITMAP_TYPE_ANI | Load a Windows animated cursor file (ANI). |
| BITMAP_TYPE_ANY | Will try to autodetect the format. |
Number of available images. For most image handlers, this is 1 (exceptions are TIFF and ICO formats).
Integer get_height()Gets the height of the image in pixels.
Integer get_mask_blue()Gets the blue value of the mask colour.
Integer get_mask_green()Gets the green value of the mask colour.
Integer get_mask_red()Gets the red value of the mask colour.
Array get_or_find_mask_colour()Get the current mask colour or find a suitable unused colour that could be used as a mask colour.
Returns four values. This first is a Boolean: true if the image
currently has a mask, or false if not. The remaining three values are
Integers containing the red, green and blue values of the mask.
Palette get_palette()Not currently supported in wxRuby.
Returns the palette associated with the image. Currently the palette is only used when converting to Bitmap under Windows. Some of the Image handlers have been modified to set the palette if one exists in the image file (usually 256 or less colour images in GIF or PNG format).
Integer get_red(Integer x, Integer y)Returns the red intensity at the given coordinate.
Image get_sub_image(Rect rect)Returns a sub image of the current one as long as the rect belongs entirely to the image.
Integer get_width()Gets the width of the image in pixels.
hsv_value(Float h = 0.0, Float s = 0.0, Float v = 0.0)Constructor for HSVValue, an object that contains values for hue, saturation and value which represent the value of a color. It is used by Image#hs_vto_rgb and Image#rg_bto_hsv, which converts between HSV color space and RGB color space.
Image::RGBValue hs_vto_rgb(HSVValue hsv)Converts a color in HSV color space to RGB color space.
Boolean has_alpha()Returns true if this image has alpha channel, false otherwise.
Boolean has_mask()Returns true if there is a mask active, false otherwise.
String get_option(String name)Gets a user-defined option. The function is case-insensitive to name.
For example, when saving as a JPEG file, the option quality is used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
Image#set_option, Image#get_option_int, Image#has_option
Integer get_option_int(String name)Gets a user-defined option as an integer. The function is case-insensitive to name.
If the given option is not present, the function returns $0$. Use Image#has_option is $0$ is a possibly valid value for the option.
Options for PNGHandler
| IMAGE_OPTION_PNG_FORMAT | Format for saving a PNG file. |
| IMAGE_OPTION_PNG_BITDEPTH | Bit depth for every channel (R/G/B/A). |
Supported values for IMAGE_OPTION_PNG_FORMAT:
| PNG_TYPE_COLOUR | Stores RGB image. |
| PNG_TYPE_GREY | Stores grey image, converts from RGB. |
| PNG_TYPE_GREY_RED | Stores grey image, uses red value as grey. |
Image#set_option, Image#get_option
Boolean has_option(String name)Returns true if the given option is present. The function is case-insensitive to name.
Image#set_option, Image#get_option, Image#get_option_int
init_alpha()Initializes the image alpha channel data. It is an error to call it if the image already has alpha data. If it doesn’t, alpha data will be by default initialized to all pixels being fully opaque. But if the image has a a mask colour, all mask pixels will be completely transparent.
Boolean is_transparent(Integer x, Integer y,
Integer threshold = 128)Returns true if the given pixel is transparent, i.e. either it the
image has a mask, and the pixel has the mask colour, or the image has
alpha channel and alpha value of this pixel is strictly less than
threshold.
Boolean load_file(String name, Integer type = BITMAP_TYPE_ANY,
Integer index = -1)Boolean load_file(String name, String mimetype,
Integer index = -1)Loads an image from a file. If no handler type is provided, the library will try to autodetect the format.
| BITMAP_TYPE_BMP | Load a Windows image file. |
| BITMAP_TYPE_GIF | Load a GIF image file. |
| BITMAP_TYPE_JPEG | Load a JPEG image file. |
| BITMAP_TYPE_PCX | Load a PCX image file. |
| BITMAP_TYPE_PNG | Load a PNG image file. |
| BITMAP_TYPE_PNM | Load a PNM image file. |
| BITMAP_TYPE_TIF | Load a TIFF image file. |
| BITMAP_TYPE_XPM | Load a XPM image file. |
| BITMAP_TYPE_ICO | Load a Windows icon file (ICO). |
| BITMAP_TYPE_CUR | Load a Windows cursor file (CUR). |
| BITMAP_TYPE_ANI | Load a Windows animated cursor file (ANI). |
| BITMAP_TYPE_ANY | Will try to autodetect the format. |
Depending on how Widgets has been configured, not all formats may be available.
Note: you can use get_option_int to get the hotspot for loaded cursor file:
int hotspot_x = image.GetOptionInt(IMAGE_OPTION_CUR_HOTSPOT_X);
int hotspot_y = image.GetOptionInt(IMAGE_OPTION_CUR_HOTSPOT_Y);true if the operation succeeded, false otherwise. If the optional index parameter is out of range, false is returned and a call to Wx::log_error takes place.
Boolean load_stream(IO an_io, Integer type = BITMAP_TYPE_ANY,
Integer index = -1)Boolean load_stream(IO an_io, String mimetype,
Integer index = -1)Loads image data from an IO-like object. It is normally simpler to use Image.read to read data from an IO; see that method for more information on the parameters.
Boolean is_ok()Returns true if image data is present.
rgb_value(Integer r = 0, Integer g = 0, Integer b = 0)Constructor for RGBValue, an object that contains values for red, green and blue which represent the value of a color. It is used by Image#hs_vto_rgb and Image#rg_bto_hsv, which converts between HSV color space and RGB color space.
Image::HSVValue rg_bto_hsv(RGBValue rgb)Converts a color in RGB color space to HSV color space.
Image mirror(Boolean horizontally = true)Returns a mirrored copy of the image. The parameter horizontally indicates the orientation.
replace(Integer r1, Integer g1, Integer b1,
Integer r2,
Integer g2,
Integer b2)Replaces the colour specified by r1,g1,b1 by the colour r2,g2,b2.
Image rescale(Integer width, Integer height,
Integer quality = IMAGE_QUALITY_NORMAL)Changes the size of the image in-place by scaling it: after a call to this function, the image will have the given width and height.
For a description of the quality parameter, see the Scale function.
Returns the (modified) image itself.
Image resize(Size size, Point pos,
Integer red = -1,
Integer green = -1,
Integer blue = -1)Changes the size of the image in-place without scaling it by adding either a border with the given colour or cropping as necessary. The image is pasted into a new image with the given size and background colour at the position pos relative to the upper left of the new image. If red = green = blue = -1 then use either the current mask colour if set or find, use, and set a suitable mask colour for any newly exposed areas.
Returns the (modified) image itself.
Image rotate(Float angle, Point rotationCentre,
Boolean interpolating = true,
Point offsetAfterRotation = nil)Rotates the image about the given point, by angle radians. Passing true to interpolating results in better image quality, but is slower. If the image has a mask, then the mask colour is used for the uncovered pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
Returns the rotated image, leaving this image intact.
rotate_hue(Float angle)Rotates the hue of each pixel in the image by angle, which is a double in the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 corresponds to +360 degrees.
Image rotate_90(Boolean clockwise = true)Returns a copy of the image rotated 90 degrees in the direction indicated by clockwise.
Boolean save_file(String name, Integer type)Boolean save_file(String name, String mimetype)Saves an image in the named file.
Boolean save_file(String name)Saves an image in the named file. File type is determined from the extension of the file name. Note that this function may fail if the extension is not recognized! You can use one of the forms above to save images to files with non-standard extensions.
| BITMAP_TYPE_BMP | Save a BMP image file. |
| BITMAP_TYPE_JPEG | Save a JPEG image file. |
| BITMAP_TYPE_PNG | Save a PNG image file. |
| BITMAP_TYPE_PCX | Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise). |
| BITMAP_TYPE_PNM | Save a PNM image file (as raw RGB always). |
| BITMAP_TYPE_TIF | Save a TIFF image file. |
| BITMAP_TYPE_XPM | Save a XPM image file. |
| BITMAP_TYPE_ICO | Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. A single image is saved in 8 colors at the size supplied). |
| BITMAP_TYPE_CUR | Save a Windows cursor file (CUR). |
true if the operation succeeded, false otherwise.
Depending on how Widgets has been configured, not all formats may be available.
Note: you can use get_option_int to set the hotspot before saving an image into a cursor file (default hotspot is in the centre of the image):
image.set_option(IMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
image.set_option(IMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);Image scale(Integer width, Integer height,
Integer quality = IMAGE_QUALITY_NORMAL)Returns a scaled version of the image. This is also useful for scaling bitmaps in general as the only other way to scale bitmaps is to blit a MemoryDC into another MemoryDC.
| IMAGE_QUALITY_NORMAL | Uses the normal default scaling method of pixel replication |
| IMAGE_QUALITY_HIGH | Uses bicubic and box averaging resampling methods for upsampling and downsampling respectively |
It should be noted that although using IMAGE_QUALITY_HIGH produces much nicer looking results it is a slower method. Downsampling will use the box averaging method which seems to operate very fast. If you are upsampling larger images using this method you will most likely notice that it is a bit slower and in extreme cases it will be quite substantially slower as the bicubic algorithm has to process a lot of data.
It should also be noted that the high quality scaling may not work as expected when using a single mask colour for transparency, as the scaling will blur the image and will therefore remove the mask partially. Using the alpha channel will work.
Example:
Image *size(Size size, Point pos,
Integer red = -1,
Integer green = -1,
Integer blue = -1)Returns a resized version of this image without scaling it by adding either a border with the given colour or cropping as necessary. The image is pasted into a new image with the given size and background colour at the position pos relative to the upper left of the new image. If red = green = blue = -1 then use either the current mask colour if set or find, use, and set a suitable mask colour for any newly exposed areas.
set_alpha(String alpha = nil)This function is similar to set_data, setting the alpha channel from a string. It has similar restrictions; don’t use it if you don’t know what you’re doing.
The string should contain one byte (character) for each pixel, representing the transparency in the range 0 to 255. If necessary, use Ruby’s Array#pack with the C* to create a suitable string.
Unlike set_data this method may be passed nil in which case the
function will allocate the alpha array internally—this is useful to
add alpha channel data to an image which doesn’t have any.
set_alpha(Integer x, Integer y, Integer alpha)Sets the alpha value for the given pixel. This function should only be called if the image has alpha channel data, use has_alpha to check for this.
set_data(String data)Sets the raw image data from a string without performing checks. Don’t use this method if you aren’t sure you know what you are doing.
The string should contain three bytes (characters) for each pixel in the image, representing the red, green and blue components in a range of 0 to 255, reading top-to-bottom, left-to-right. If you were creating this from scratch, you can use Ruby’s Array#pack to create the string.
For example, a four-pixel image with pure-red pixels in the left and pure-blue pixels on the right could be set with string data created thus:
[ 255, 0, 0,
0, 0, 255,
255, 0, 0,
0, 0, 255 ].pack("C")set_maskBoolean% hasMask = true)Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
set_mask_colourInteger% red, Integer green, Integer blue)Sets the mask colour for this image (and tells the image to use the mask).
Boolean *set_mask_from_image(Image mask, Integer mr,
Integer mg,
Integer mb)Sets image’s mask so that the pixels that have RGB value of mr,mg,mb in mask will be masked in the image. This is done by first finding an unused colour in the image, setting this colour as the mask colour and then using this colour to draw all pixels in the image who corresponding pixel in mask has given RGB value.
Returns false if mask does not have same dimensions as the image or if there is no unused colour left. Returns true if the mask was successfully applied.
Note that this method involves computing the histogram, which is computationally intensive operation.
set_option(String name, String value)set_option(String name, Integer value)Sets a user-defined option. The function is case-insensitive to name.
For example, when saving as a JPEG file, the option quality is used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
Image#get_option, Image#get_option_int, Image#has_option
set_palette(Palette palette)Associates a palette with the image. The palette may be used when converting Image to Bitmap (MSW only at present) or in file save operations (none as yet). Not supported in wxRuby.
set_rgb(Integer x, Integer y,
Integer red, Integer green, Integer blue)Sets the colour of the pixel at the given coordinate using red, green and blue intensities. The red, green and blue values should be in the range 0 to 255.
This routine performs bounds-checks for the coordinate so it can be considered a safe way to manipulate the data, but in some cases this might be too slow so that the data will have to be set directly. In that case you will have to get access to the image data using the get_data method.
set_rgb(Rect rect,
Integer red, Integer green, Integer blue)Sets the colour of the pixels within the given rectangle using red, green and blue intensities. The values should be in the range 0 to 255. This routine performs bounds-checks for the coordinate so it can be considered a safe way to manipulate the data.
Boolean write(IO an_io, Integer type)Boolean write(IO an_io, String mimetype)Writes the image data in the specified image format to an IO-like
object. an_io may be any Ruby IO-like object which responds to write
and other basic IO methods. For example, it may be an IO, a File, a
Socket or a StringIO.
See also save_file for more information on the supported output formats.
[This page automatically generated from the Textile source at Thu May 01 00:50:39 +0100 2008]