Module: FreeImage::Modify
- Included in:
- Bitmap
- Defined in:
- lib/free-image/modules/modify.rb
Overview
The Modify module provides methods that can copy, paste, composite, and enlarge images. It also allows the creation of thumbnails and filling background colors.
Instance Method Summary collapse
-
#composite(background_bitmap) ⇒ Object
Composites a transparent foreground image against a background image.
-
#composite_with_color(background_color) ⇒ Object
Composites a transparent foreground image against a background color.
-
#copy(left, top, right, bottom) ⇒ Object
Copy a subpart of the current image.
-
#enlarge_canvas(left, top, right, bottom, color, options = 0) ⇒ Object
Enlarges or shrinks an image selectively per side and fills newly added areas with the specified background color.
-
#fill_background!(color, options = 0) ⇒ Object
Sets all pixels of an image to the specified color.
-
#make_thumbnail(max_pixel_size, convert = true) ⇒ Object
:call-seq: bitmap.make_thumbnail(max_pixel_size, convert = true) -> bitmap.
-
#paste!(other, left, top, alpha) ⇒ Object
Combines or blends a subpart of another image with the current image.
-
#rescale(width, height, filter = :bilinear) ⇒ Object
:call-seq: bitmap.rescale(width, height, filter) -> bitmap.
Instance Method Details
#composite(background_bitmap) ⇒ Object
Composites a transparent foreground image against a background image. The equation for computing a composited sample value is:
output = alpha * foreground + (1-alpha) * background
Where alpha and the input and output sample values are expressed as fractions in the range 0 to 1. For color images, the computation is done separately for R, G, and B samples.
56 57 58 59 60 |
# File 'lib/free-image/modules/modify.rb', line 56 def composite(background_bitmap) ptr = FreeImage.FreeImage_Composite(self, false, nil, background_bitmap) FreeImage.check_last_error self.class.new(ptr) end |
#composite_with_color(background_color) ⇒ Object
Composites a transparent foreground image against a background color. The equation for computing a composited sample value is:
output = alpha * foreground + (1-alpha) * background
Where alpha and the input and output sample values are expressed as fractions in the range 0 to 1. For color images, the computation is done separately for R, G, and B samples.
70 71 72 73 74 |
# File 'lib/free-image/modules/modify.rb', line 70 def composite_with_color(background_color) ptr = FreeImage.FreeImage_Composite(self, false, background_color, nil) FreeImage.check_last_error self.class.new(ptr) end |
#copy(left, top, right, bottom) ⇒ Object
Copy a subpart of the current image. The rectangle defined by the left, top, right, bottom parameters is first normalized such that the value of the left coordinate is less than the right and the top is less than the bottom. Then, the returned bitmap is defined by a width equal to (right - left) and a height equal to (bottom - top).
The function returns the subimage if successful and returns nil otherwise.
83 84 85 86 87 |
# File 'lib/free-image/modules/modify.rb', line 83 def copy(left, top, right, bottom) ptr = FreeImage.FreeImage_Copy(self, left, top, right, bottom) FreeImage.check_last_error self.class.new(ptr) end |
#enlarge_canvas(left, top, right, bottom, color, options = 0) ⇒ Object
Enlarges or shrinks an image selectively per side and fills newly added areas with the specified background color. The common use case is to add borders to an image.
To add a border to any of the image’s sides, a positive integer value must be passed in any of the parameters left, top, right or bottom. This value represents the border’s width in pixels. Newly created parts of the image (the border areas) are filled with the specified color.
Specifying a negative integer value for a certain side, will shrink or crop the image on this side. Consequently, specifying zero for a certain side will not change the image’s extension on that side.
For palletized images, the palette of the current image src is transparently copied to the newly created enlarged or shrunken image, so any color look-ups are performed on this palette.
Parameters:
- left
-
The number of pixels the image should be enlarged on its left side. Negative values shrink the image on its left side.
- top
-
The number of pixels the image should be enlarged on its top side. Negative values shrink the image on its top side.
- right
-
The number of pixels the image should be enlarged on its right side. Negative values shrink the image on its right side.
- bottom
-
The number of pixels, the image should be enlarged on its bottom side. Negative values shrink the image on its bottom side.
- color
-
The color value to be used for filling the image. See #fill_background for more details.
- options
-
Used to control color search process for palletized images. See #fill_background for more details.
Returns a new image on success or nil.
122 123 124 125 126 |
# File 'lib/free-image/modules/modify.rb', line 122 def enlarge_canvas(left, top, right, bottom, color, = 0) ptr = FreeImage.FreeImage_EnlargeCanvas(self, left, top, right, bottom, color, ) FreeImage.check_last_error self.class.new(ptr) end |
#fill_background!(color, options = 0) ⇒ Object
Sets all pixels of an image to the specified color.
Parameters:
- color
-
The color value to be used for filling the image.
The type of the color parameter depends on the {image type}[rdoc-ref:FreeImage.image_types] bitmap:: RGBQuad rgb16:: RGB16 rgba16:: RGBA16 rgbf:: RGBF rgbaf:: RGBFA complex:: Complex others:: A value of the specific type (double, int, etc.).
- options
-
Used to control color search process for palletized images.
Allowed values are defined as constants on the FreeImage module and include: COLOR_IS_RGB_COLOR = 0x00 COLOR_IS_RGBA_COLOR = 0x01 COLOR_FIND_EQUAL_COLOR = 0x02 COLOR_ALPHA_IS_INDEX = 0x04 COLOR_PALETTE_SEARCH_MASK = (FI_COLOR_FIND_EQUAL_COLOR | FI_COLOR_ALPHA_IS_INDEX)
Returns true on success, false on failure.
156 157 158 159 160 |
# File 'lib/free-image/modules/modify.rb', line 156 def fill_background!(color, = 0) result = FreeImage.FreeImage_FillBackground(self, color, ) FreeImage.check_last_error result end |
#make_thumbnail(max_pixel_size, convert = true) ⇒ Object
:call-seq:
bitmap.make_thumbnail(max_pixel_size, convert = true) -> bitmap
Creates a thumbnail image that fits inside a square of size max_pixel_size, keeping the original aspect ratio intact. Downsampling is done using a bilinear filter.
Parameters:
- max_pixel_size
-
The maximum width/height of the returned image
- convert
-
When set to true, High Dynamic Range images (FIT_UINT16, FIT_RGB16, FIT_RGBA16, FIT_FLOAT) are transparently converted to standard images (i.e. 8-, 24 or 32-bit images). The default value is true.
177 178 179 180 181 |
# File 'lib/free-image/modules/modify.rb', line 177 def make_thumbnail(max_pixel_size, convert = true) ptr = FreeImage.FreeImage_MakeThumbnail(self, max_pixel_size, convert) FreeImage.check_last_error self.class.new(ptr) end |
#paste!(other, left, top, alpha) ⇒ Object
Combines or blends a subpart of another image with the current image.
Parameters:
- other
-
Source subimage
- left
-
Specifies the left position of the sub image.
- top
-
Specifies the top position of the sub image.
- alpha
-
Alpha blend factor. If alpha is 0..255, the other images is
alpha blended withe current image. If alpha > 255, then the other image is combined to the current image.
The function returns true if successful, otherwise false.
196 197 198 199 200 |
# File 'lib/free-image/modules/modify.rb', line 196 def paste!(other, left, top, alpha) result = FreeImage.FreeImage_Paste(self, other, left, top, alpha) FreeImage.check_last_error result end |
#rescale(width, height, filter = :bilinear) ⇒ Object
:call-seq:
bitmap.rescale(width, height, filter) -> bitmap
Resamples an image to the desired width and height. Resampling changes the pixel dimensions (and therefore display size) of an image. When you downsample (or decrease the number of pixels), information is deleted from the image. When you upsample (or increase the number of pixels), new pixels are added based on color values of existing pixels. You can specify an interpolation filter to determine how pixels are added or deleted using the filter parameter.
Returns the newly resample image or nil if the image cannot be resampled.
Parameters:
- width
-
The width of the new image
- height
-
The height of the new image
- filter
-
The filter to use when rescaling
Filter options include:
- :box
-
The simplest and fastest of the scaling algorithms. The technique achieves magnification by pixel replication, and minification by sparse point sampling. For large-scale changes, box interpolation produces images with a blocky appearance. In addition, shift errors of up to one-half pixel are possible. These problems make this technique inappropriate when sub-pixel accuracy is required.
- :bicubic
-
An advanced parameterized scaling filter. It uses a cubic to produce very smooth output while maintaining dynamic range and sharpness. Bicubic scaling takes approximately twice the processing time as Bilinear. This filter can be used for any scaling application, especially when scaling factors are 2X or greater.
- :bilinear
-
The second-fastest scaling function. It employs linear interpolation to determine the output image. Bilinear scaling provides reasonably good results at moderate cost for most applications where scale factors are relatively small (4X or less).
- :bspline
-
Produces the smoothest output, but tends to smooth over fine details. This function requires the same processing time as :bicubic filter. It is recommended for applications where the smoothest output is required.
- :catmullrom
-
The Catmull-Rom filter is generally accepted as the best cubic interpolant filter.
- :lanczos3
-
A sinc based filter. It is the most theoretically correct filter that produces the best output for photographic images that do not have sharp transitions in them. However, Lanczos will produce ripple artefacts especially for block text, due to aliasing. It requires three times the processing time of Bilinear. Lanczos is not recommended except in very rare applications using band-limited photographic images with no sharp edges.
255 256 257 258 259 |
# File 'lib/free-image/modules/modify.rb', line 255 def rescale(width, height, filter = :bilinear) ptr = FreeImage.FreeImage_Rescale(self, width, height, filter) FreeImage.check_last_error self.class.new(ptr) end |