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.
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.
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.
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.
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.
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:
Creates a new image from an platform-dependent bitmap, preserving mask
information.
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.
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.
Blurs the image in the horizontal direction only. This should not be used
when using a single mask colour for transparency.
h4. See also
Blurs the image in the vertical direction only. This should not be used
when using a single mask colour for transparency.
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:
Returns number of colours in the histogram.
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.
Deprecated, use equivalent Bitmap constructor
(which takes Image and depth as its arguments) instead.
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).
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.
Returns an identical copy of the image.
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.
Destroys the image data.
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.
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.
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.
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.
Returns the blue intensity at the given coordinate.
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:
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.
Returns the green intensity at the given coordinate.
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).
Gets the height of the image in pixels.
Gets the blue value of the mask colour.
Gets the green value of the mask colour.
Gets the red value of the 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.
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).
Returns the red intensity at the given coordinate.
Returns a sub image of the current one as long as the rect belongs entirely to
the image.
Gets the width of the image in pixels.
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.
Converts a color in HSV color space to RGB color space.
Returns true if this image has alpha channel, false otherwise.
Returns true if there is a mask active, false otherwise.
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
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
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
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.
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.
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:
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.
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.
Returns true if image data is present.
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.
Converts a color in RGB color space to HSV color space.
Returns a mirrored copy of the image. The parameter horizontally
indicates the orientation.
Replaces the colour specified by r1,g1,b1 by the colour r2,g2,b2.
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.
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.
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.
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.
Returns a copy of the image rotated 90 degrees in the direction
indicated by clockwise.
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.
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):
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:
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.
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.
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.
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.
Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
Sets the mask colour for this image (and tells the image to use 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.
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.
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
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.
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.
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-13 21:31:38 +0000]