62 Image

Introduction

This package is available with require("aprilann.Image").

Two globals are declared in this package: Image and ImageRGB. Both classes represent its internal data using floats, in the case of Image with one float, in the case of ImageRGB with 3 floats (Red, Green, Blue). So, usually 8 bits per color images will be transformed to be the color 0=0.0 and the color 255=1.0.

Serialization and deserialization

Images cannot be serialized as a Lua object into a .lua filename using util.serialize() and util.deserialize() functions. Instead of that, it is possible to write images into png, tiff or jpeg files by using the package ImageIO. This package allows to write Image or ImageRGB images.

Visualization

A tool module has been deployed to facilitate visualization of images and matrices. It depends on lgi binding library for Lua 5.2, and uses the GTK binding. In order to do the require "tools.lgi.gtk" you need to have the APRIL-ANN ROOT directory in your package.path Lua variable, or in your LUA_PATH environment variable. By default, the current directory is included, so if you execute the require being your working directory the APRIL-ANN GIT root directory, it will work. In any case, NEVER add the april_tools directory to the LUA_PATH, because the lgi module will collide with the tools.lgi module.

> gtk = require "tools.lgi.gtk"
> gtk.show("sheared.png")

If it doesn't work, try add the APRIL-ANN ROOT directory to the package.path variable.

> package.path = "YOUR_APRIL_ANN_PATH/?.lua;" .. package.path
> gtk = require "tools.lgi.gtk"
> gtk.show("sheared.png")

gtk.show(img1, img2, ...)

This function allows to visualize images using GTK library. It receives a variable number of arguments, and every argument will be displayed in a different window. Every argument could be:

• A filename, opening the contained image.

• A matrix, which needs to be bi-dimensional. It will be converted to an Image and then showed.

• An Image or ImageRGB.

Note that the Lua command shell will be blocked after executing GTK main loop. Any of the created windows has an exit button to allow closing the GTK main loop.

Image class

The Image class allows to work with gray-scale images. Every image contains an underlying matrix instance (floats).

Constructor: img = Image(matrix)

The constructor receives a matrix where the image is contained. This matrix must be simple, that is, contiguous in memory, and in row_major. Given a matrix with data, it is possible to load an Image with:

> m = matrix(100,100)
> -- make a gradient
> for sw in m:sliding_window():iterate() do sw:linear():adjust_range(0,1) end
> -- constructor for Image
> img = Image(m)
> = img
# Image 100x100+0+0 [0x2490810 data= 0x25843e0]
> -- you can see the image writing it with ImageIO or using the gtk module
> ImageIO.write(img, "gradient.png")

Image = img:crop(string)

This method allows to select a portion of an Image, and returns a new instance which references the given portion. The crop is given by using a string (like in convert command), with the following format: <width>x<height>{+-}<x>{+-}<y>.

> img2 = img:crop("20x20+10+10")
> = img2
# Image 20x20+10+10 [0x2490810 data= 0x25843e0]

Image = img:crop(width, height, offsetx, offsety)

Similar to previous one, but given the crop using four arguments.

> img2 = img:crop(20, 20, 10, 10)
> = img2
# Image 20x20+10+10 [0x2490810 data= 0x25843e0]

matrix = img:matrix()

This method returns the underlying matrix. Be careful with this method, the memory is shared between the Image object and the returned matrix object.

> m2 = img:matrix()
> = m2
...
# Matrix of size [100,100] in row_major [0x2490810 data= 0x25843e0]
> = m -- the matrix references the original
...
# Matrix of size [100,100] in row_major [0x2490810 data= 0x25843e0]

width,height,offsetx,offsety = img:geometry()

This method returns the geometry information of the image.

> = img2:geometry()
20	20	10	10

number = img:getpixel(x,y)

This method returns the given position (x,y) pixel value.

img:putpixel(x,y,number)

This method assigns the given value at the given (x,y) pixel position.

Image = img:clone()

This method returns a deep-copy of the caller object.

matrix = img:projection_h()

This method returns the horizontal projection of the caller object.

matrix = img:projection_v()

This method returns the vertical projection of the caller object.

Image = img:shear_h(angle, [, units="rad" [, WHITE=0.0 ] ] )

This method returns an Image which is a shear transformation with the given angle. Optionally, a second argument could be given indicating with the string rad, deg or grad the angle unit, by default it is rad. The thrird argument is also optional, and it indicates which pixel value is taken as white color, by default is 0.0.

> img_sh = img:shear_h(0.1)
> ImageIO.write(img_sh, "sheared.png")

img:shear_h_inplace(angle, [, units="rad" [, WHITE=0.0 ] ] )

This method applies the same transformation as the img:shear_h(...), but instead of returning a new Image, the transformation is performed in-place.

w,h,x,y = img:min_bounding_box(threshold)

This method returns the bounding box of the caller object, using threshold for deciding when a value is considered as background or not.

img:copy(Image, dest_x, dest_y)

This method copies the given Image in the given (dest_x,dest_y) position of the caller object.

Image = img:substract(Image)

This method applies image substraction.

img:threshold(low, high)

This method transforms in-place the caller object with the given range for black/white thresholding.

Image = img:rotate90cw(param)

This method returns a new Image which is a rotation of 90º in clock-wise direction (if param=1) or in counter-clock-wise (if param=-1) of the caller object.

Image = img:invert_colors()

This method returns an image with the colors inverted.

Image = img:remove_blank_columns()

Image = img:add_rows(top, bottom, value)

Image = img:convolution5x5(table [, default_value ])

Image = img:resize(x,y)

Image,x,y = img:affine_transform(AffineTransform2D, default_value)

ImageRGB = img:to_RGB()

matrix = img:comb_lineal_forward(x, y, w, h, w2, h2, LinearCombConFloat)

ImageRGB class

This class is an instantiation of the same C++ template used for Image class. Both classes has similar methods.

Constructor: ImageRGB = ImageRGB(matrix)

ImageRGB class could be loaded from a matrix with 3 dimensions. The last dimension of the matrix has size 3 for the componentes Red, Green, Blue. Be careful with this constructor, the memory is shared between the ImageRGB object and the given matrix object.

> img_rgb = ImageRGB(matrix(100,100,3):linear())
> = img_rgb
# ImageRGB 100x100+0+0 [0x2535700 data= 0x251fc40]

Methods shared with Image class

The following methods are shared between both classes, and their has the same interface:

• ImageRGB = img_rgb:crop(string)

• ImageRGB = img_rgb:crop(width, height, offsetx, offsety)

• width,height,offsetx,offsety = img_rgb:geometry()

• r,g,b = img_rgb:getpixel(x,y)

• img_rgb:putpixel(x,y, r,g,b)

• ImageRGB = img_rgb:clone()

• ImageRGB = img_rgb:shear_h(angle, [, units="rad" [, WHITE=0.0 ] ] )

• img_rgb:shear_h_inplace(angle, [, units="rad" [, WHITE=0.0 ] ] )

• img_rgb:copy(ImageRGB, dest_x, dest_y)

• ImageRGB = img_rgb:rotate90cw(param)

• ImageRGB = img_rgb:invert_colors()

• ImageRGB = img_rgb:convolution5x5(table [, r,g,b ])

• ImageRGB = img_rgb:resize(x,y)

• ImageRGB,x,y = img_rgb:affine_transform(AffineTransform2D, r,g,b)

matrix = img_rgb:matrix()

This method returns the underlying matrix. Be careful with this method, the memory is shared between the ImageRGB object and the returned matrix object.

Image = img_rgb:to_grayscale()

This method returns an instance of Image, transforming the 3 color components into a gray component.

Useful examples

A usual situation is to load a matrix from a PNG image (in RGB color, with 0=BLACK, and 1=WHITE), but transform it to train ANNs in gray-scale with 1=BLACK and 0=WHITE. This could be done by the following code:

> img_matrix = ImageIO.read(filename):to_grayscale():invert_colors():matrix()