wxRuby Documentation Home

# Wx::Image

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.

An Image cannot (currently) be drawn directly to a DC. Instead,
a platform-specific Bitmap object must be created from it
using the Bitmap.from_image class method.
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.

## Alpha channel support

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).

## Available image handlers

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.

## Derived from

Object

## See also

Bitmap,

## Methods

- Image.new
- Image.from_bitmap
- Image.read
- Image#blur
- Image#blur_horizontal
- Image#blur_vertical
- Image#compute_histogram
- Image#convert_alpha_to_mask
- Image#convert_to_bitmap
- Image#convert_to_greyscale
- Image#convert_to_mono
- Image#copy
- Image#create
- Image#destroy
- Image#find_first_unused_colour
- Image#get_image_ext_wildcard
- Image#get_alpha
- Image#get_alpha_data
- Image#get_blue
- Image#get_data
- Image#get_rgb_data
- Image#get_green
- Image#get_image_count
- Image#get_height
- Image#get_mask_blue
- Image#get_mask_green
- Image#get_mask_red
- Image#get_or_find_mask_colour
- Image#get_palette
- Image#get_red
- Image#get_sub_image
- Image#get_width
- HSVValue::HSVValue
- Image#hs_vto_rgb
- Image#has_alpha
- Image#has_mask
- Image#get_option
- Image#get_option_int
- Image#has_option
- Image#init_alpha
- Image#is_transparent
- Image#load_file
- Image#load_stream
- Image#is_ok
- RGBValue::RGBValue
- Image#rg_bto_hsv
- Image#mirror
- Image#replace
- Image#rescale
- Image#resize
- Image#rotate
- Image#rotate_hue
- Image#rotate_90
- Image#save_file
- Image#scale
- Image#size
- Image#set_alpha
- Image#set_alpha_data
- Image#set_data
- Image#set_rgb_data
- Image#set_mask
- Image#set_mask_colour
- Image#set_mask_from_image
- Image#set_option
- Image#set_palette
- Image#set_rgb
- Image#write

### Image.new

Image.new(%(arg-type)Image% image)

Copy constructor, uses reference counting.

Image.new(%(arg-type)String% file_name, Integer type = BITMAP_TYPE_ANY, Integer index = -1) Image.new(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)String% xpmData)

Creates an image from XPM data.

#### Parameters

- width Specifies the width of the image.
- height Specifies the height of the image.
- name Name of the file from which to load the image.
- type May be one of the following:

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.

- mimetype MIME type string (for example ‘image/jpeg’)
- index Index of the image to load in the case that the image file contains multiple images.
  This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
  “choose the default image” and is interpreted as the first image (index=0) by
  the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.
- xpmData A pointer to XPM image data.

#### Remarks

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)

#### See also

Image#load_file

### Image.from_bitmap

Image.from_bitmap(%(arg-type)Bitmap% bitmap)

Creates a new image from an platform-dependent bitmap, preserving mask
information.

### Image.read

Image.read(%(arg-type)IO% an_io, Integer type = BITMAP_TYPE_ANY, Integer index = -1) ) Image.read(%(arg-type)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

Image blur(%(arg-type)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.

#### See also
v
blur_horizontal
blur_vertical

### Image#blur_horizontal

Image blur_horizontal(%(arg-type)Integer% blurRadius)

Blurs the image in the horizontal direction only. This should not be used
when using a single mask colour for transparency.
h4. See also

Blur
blur_vertical

### Image#blur_vertical

Image blur_vertical(%(arg-type)Integer% blurRadius)

Blurs the image in the vertical direction only. This should not be used
when using a single mask colour for transparency.

#### See also

Blur
blur_horizontal

### Image#compute_histogram

Integer compute_histogram(%(arg-type)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);

#### Return value

Returns number of colours in the histogram.

### Image#convert_alpha_to_mask

Boolean convert_alpha_to_mask(%(arg-type)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.

#### Return value

if FindFirstUnusedColour returns , otherwise.

### Image#convert_to_bitmap

Bitmap convert_to_bitmap()

Deprecated, use equivalent Bitmap constructor
(which takes Image and depth as its arguments) instead.

### Image#convert_to_greyscale

Image convert_to_greyscale(%(arg-type)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

Image convert_to_mono(%(arg-type)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

Image copy()

Returns an identical copy of the image.

### Image#create

Boolean create(%(arg-type)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.

#### Parameters

- width The width of the image in pixels.
- height The height of the image in pixels.

#### Return value

true if the call succeeded, false otherwise.

### Image#destroy

destroy()

Destroys the image data.

### Image#find_first_unused_colour

Boolean find_first_unused_colour(%(arg-type)Integer% r, Integer g, Integer b, Integer startR = 1, Integer startG = 0, Integer startB = 0)

#### Parameters

- r,g,b Pointers to variables to save the colour.
- startR,startG,startB Initial values of the colour. Returned colour
  will have RGB values equal to or greater than these.

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.

#### Return value

Returns false if there is no unused colour left, true on success.

#### Notes

Note that this method involves computing the histogram, which is
computationally intensive operation.

### Image#get_image_ext_wildcard

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.

#### Return value

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.

### Image#get_alpha

Integer get_alpha(%(arg-type)Integer% x, Integer y)

Returns the alpha value for the given pixel. This function may only be called
for 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.

### Image#get_alpha_data

String get_alpha_data()

Returns the raw alpha 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 alpha value
of a pixel in the range 0 to 255.

### Image#get_blue

Integer get_blue(%(arg-type)Integer% x, Integer y)

Returns the blue intensity at the given coordinate.

### Image#get_rgb_data

String get_rgb_data() 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.rgb_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_rgb_data, for example:

my_image.rgb_data = my_image.rgb_data.reverse

This 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.

The get_data form is provided for backward compatibility but is not recommended. It
may be deprecated in a subsequent version of wxRuby.

### Image#get_green

Integer get_green(%(arg-type)Integer% x, Integer y)

Returns the green intensity at the given coordinate.

### Image#get_image_count

Integer get_image_count(%(arg-type)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.

- name Name of the file to query.
- type May be one of the following:

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.

#### Return value

Number of available images. For most image handlers, this is 1 (exceptions
are TIFF and ICO formats).

### Image#get_height

Integer get_height()

Gets the height of the image in pixels.

### Image#get_mask_blue

Integer get_mask_blue()

Gets the blue value of the mask colour.

### Image#get_mask_green

Integer get_mask_green()

Gets the green value of the mask colour.

### Image#get_mask_red

Integer get_mask_red()

Gets the red value of the mask colour.

### Image#get_or_find_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.

### Image#get_palette

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).

### Image#get_red

Integer get_red(%(arg-type)Integer% x, Integer y)

Returns the red intensity at the given coordinate.

### Image#get_sub_image

Image get_sub_image(%(arg-type)Rect% rect)

Returns a sub image of the current one as long as the rect belongs entirely to
the image.

### Image#get_width

Integer get_width()

Gets the width of the image in pixels.

#### See also

Image#get_height

### HSVValue::HSVValue

hsv_value(%(arg-type)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#hs_vto_rgb

Image::RGBValue hs_vto_rgb(%(arg-type)HSVValue% hsv)

Converts a color in HSV color space to RGB color space.

### Image#has_alpha

Boolean has_alpha()

Returns true if this image has alpha channel, false otherwise.

#### See also

get_alpha, set_alpha

### Image#has_mask

Boolean has_mask()

Returns true if there is a mask active, false otherwise.

### Image#get_option

String get_option(%(arg-type)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).

#### See also

Image#set_option, Image#get_option_int, Image#has_option

### Image#get_option_int

Integer get_option_int(%(arg-type)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.

#### See also

Image#set_option, Image#get_option

### Image#has_option

Boolean has_option(%(arg-type)String% name)

Returns true if the given option is present. The function is case-insensitive to name.

#### See also

Image#set_option, Image#get_option, Image#get_option_int

### Image#init_alpha

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.

### Image#is_transparent

Boolean is_transparent(%(arg-type)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.

### Image#load_file

Boolean load_file(%(arg-type)String% name, Integer type = BITMAP_TYPE_ANY, Integer index = -1) Boolean load_file(%(arg-type)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.

#### Parameters

- name Name of the file from which to load the image.
- type One of the following values:

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.

- mimetype MIME type string (for example ‘image/jpeg’)
- index Index of the image to load in the case that the image file contains multiple images.
  This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
  “choose the default image” and is interpreted as the first image (index=0) by
  the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.

#### Remarks

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);

#### Return value

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.

#### See also

Image#save_file

### Image#load_stream

Boolean load_stream(%(arg-type)IO% an_io, Integer type = BITMAP_TYPE_ANY, Integer index = -1) Boolean load_stream(%(arg-type)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.

### Image#is_ok

Boolean is_ok()

Returns true if image data is present.

### RGBValue::RGBValue

rgb_value(%(arg-type)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#rg_bto_hsv

Image::HSVValue rg_bto_hsv(%(arg-type)RGBValue% rgb)

Converts a color in RGB color space to HSV color space.

### Image#mirror

Image mirror(%(arg-type)Boolean% horizontally = true)

Returns a mirrored copy of the image. The parameter horizontally
indicates the orientation.

### Image#replace

replace(%(arg-type)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

Image rescale(%(arg-type)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.

#### See also

Scale

### Image#resize

Image resize(%(arg-type)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.

#### See also

Size

### Image#rotate

Image rotate(%(arg-type)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.

### Image#rotate_hue

rotate_hue(%(arg-type)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

Image rotate_90(%(arg-type)Boolean% clockwise = true)

Returns a copy of the image rotated 90 degrees in the direction
indicated by clockwise.

### Image#save_file

Boolean save_file(%(arg-type)String% name, Integer type) Boolean save_file(%(arg-type)String% name, String mimetype)

Saves an image in the named file.

Boolean save_file(%(arg-type)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.

#### Parameters

- name Name of the file to save the image to.
- type Currently these types can be used:

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).

- mimetype MIME type.

#### Return value

true if the operation succeeded, false otherwise.

#### Remarks

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);

#### See also

Image#load_file, Image#write

### Image#scale

Image scale(%(arg-type)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.

- quality Determines what method to use for resampling the image. Can be one of the following:

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:

1. get the bitmap from somewhere
   bmp = Wx::Bitmap.new(…)

1. rescale it to have size of 32*32
   if bmp.width != 32 or bmp.height != 32 )
   img = Wx::Image.from_bitmap(bmp)
   bmp = Wx::Bitmap.from_image( img.scale(32, 32) )
   end

#### See also

Rescale

### Image#size

Image size(%(arg-type)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.

#### See also

Resize

### Image#set_alpha

set_alpha(%(arg-type)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.

### Image#set_alpha_data

set_alpha_data(%(arg-type)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_rgb_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.

### Image#set_rgb_data

set_rgb_data(%(arg-type)String% data) set_data(%(arg-type)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*”)

The set_data form is provided for backward compatibility but is not recommended. It
may be deprecated in a subsequent version of wxRuby.

### Image#set_mask

set_mask(%(arg-type)Boolean% has_mask = true)

Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.

### Image#set_mask_colour

set_mask_colour(%(arg-type)Integer% red, Integer green, Integer blue)

Sets the mask colour for this image (and tells the image to use the mask).

### Image#set_mask_from_image

Boolean set_mask_from_image(%(arg-type)Image% mask, Integer mr, Integer mg, Integer mb)

#### Parameters

- mask The mask image to extract mask shape from. Must have same dimensions as the image.
- mr,mg,mb RGB value of pixels in mask that will be used to create the mask.

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.

#### Return 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.

#### Notes

Note that this method involves computing the histogram, which is
computationally intensive operation.

### Image#set_option

set_option(%(arg-type)String% name, String value) set_option(%(arg-type)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).

#### See also

Image#get_option, Image#get_option_int, Image#has_option

### Image#set_palette

set_palette(%(arg-type)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.

### Image#set_rgb

set_rgb(%(arg-type)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 use the set_rgb_data method.

### Image#write

Boolean write(%(arg-type)IO% an_io, Integer type) Boolean write(%(arg-type)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 2023-06-09 00:45:32 +0000]