This document describes how to use ImageMagick, a free open source software suite for image manipulation, with PowerBuilder. It provides an overview of key ImageMagick methods for identifying image properties, converting formats, resizing images, adding text, cropping, and creating thumbnail folders. Code examples are given to demonstrate how to integrate these ImageMagick features into a PowerBuilder application using the COM interface and command line calls. The document also covers installing and setting up ImageMagick to work with PowerBuilder.

1. DESIGN AND DEVELOPMENT
Image Magic for PowerBuilder
A Free Software Package For Easy Image Manipulations
Using PowerBuilder
By Marco Cimaroli
S
ix months ago, I was work- the key features for ImageMagick/Pow-
ing with my team on a soft- erBuilder integration. Some of these
ware project for an enterprise features include:
customer on a tool to manage salesman
‘in store merchandising visitation’ . Our 1.) The ‘Identify’ method to retrieve
development tools were PowerBuilder the properties image.
10.5 and SQLAnywhere 10. For this
project, we had a particular require- 2.) The ‘Convert’ method to:
ment to convert and show TIFF images • Re-size an image by a percent.
inside the application using a free • Re-size an image by a fixed size.
image library. • Superimpose text over an exist-
After some google searching, I ing image.
discovered an image library called ‘Ima- • Create text images from scratch.
geMagick’ that allowed us to convert • Create a JPEG from a PDF file.
TIFF files on the fly from PowerScript. • Crop a selection of an image.
ImageMagick (www.imagemagick.
org) is a free software suite that is 3.) The ‘Mogrify’ method to create
distributed with a GPL compatible thumbnails folders.
license. It offer several interfaces such as
C lib, Dll, COM library and a com- 4.) The ‘Montage’ method to create an
mand line converter tool to transform image index from selected thumb-
images. nails.
Obviously, it doesn’t reach a full
integration with PowerBuilder like The ImageMagick Setup
some professional image tools (i.e. The first thing to do is to download
Marco Cimaroli is a registered Gold Pegasus, Lead-Tools) delivered as ImageMagick (www.imagemagick.
ISUG member who works at Selda Activex, but it’s free, and it allowed us org) and to choose the Windows setup.
Informatica, an Italian software company to easily manipulate many images using The current version is ImageMagick-
located in Ascoli Piceno (Marche,Italy). PowerBuilder objects. Some of these 6.5.9-0-Q16-windows-dll.exe.exe.
Marco has used Sybase technology since manipulations include picture control, Run the setup following the setup
1994, starting with PowerBuilder 4.0
and Watcom SQL. Currently, Marco is
DataWindow picture control and wizard panels. It is important to have
using PowerBuilder 11.5,PocketBuilder bitmap computed columns. ‘administrator’ rights and to check the
2.5, and SQLAnywhere 11 on various For this article, I have created a ‘ImageMagick OLE control’ option.
platforms. PowerBuilder 11 example applica- After setup completion, it’s possible to
tion, and I have used both the COM verify that environment variables are
interface and the “montage” console set correctly simply by calling the fol-
command to help explain the some of lowing commands from CMD session:
10 ISUG TECHNICAL JOURNAL

2. IMAGE MAGIC FOR POWERBUILDER
co n v e rt l o g o : l o g o. m iff The Convert Method
imdi s pl ay l o g o .m iff The ‘Convert’ method is quite powerful as it provides the
modification functionality that is necessary for changing
If the installation was suc- an image’s format, re-sizing an image, blurring an image,
cessful, the ImageMagick cropping an image, flipping an image, joining an image, and
picture will be showed as drawing on an existing image as well as much more.
in Figure 1. All of the
ImageMagick methods that Re-sizing An Image By A Percentage
I’ll be covering in this article If we want to convert the size of an image by a percentage,
are stored in a PowerBuilder we invoke the ‘Convert’ method passing it a source image, a
non-visual object called destination image and re-size factor to apply to the original
Figure 1: ImageMagick n_nvo_magick. This object image. For example passing a re-size factor of 50, we obtain
is used as a service object a new image with reduced size of 50%. The syntax for this
to call the ImageMagick API. I also use some structures to conversion is as follows:
store image attributes as well as two DataWindows to display iole_ img . Conver t ( Ò -r esize Ó , st r ing (per c-r esize) + Ó % Ó ,
both the full image and the thumbnails. Within the COM a s_ fr om_ ima g e, a s_ t o_ ima g e)
interface, the connection to the COM server is identified by
‘ImageMagickObject.MagickImage.1’ class name. If you have The method requires four arguments: ‘-resize’ command,
problems connecting to the OLE Server, you need to register percentage value, source image, and destination image. The
the ImageMagickObject.dll manually using the command: convert method returns a ‘any’ value containing 3 comma
regsvr32 /c /s <installation path>ImageMagickObject.dll . separated parameters containing the width, the height and
the type of the new image. This can be useful information
The Identify Method that we can reuse inside our code.
To extract the information from the image via the Image- Note : One particularity of ImageMagick is that it
Magick’s ‘Identify’ method, you will need to provide three creates a new image on the hard disk for each image
arguments : an identification option, an attribute mask and transformation.
an image filename. The syntax for the ‘Identify’ method is
below: Re-sizing An Image By A Fixed Size
We can also use the ‘Convert’ method with the ‘-resize’ com-
iol e _i m g .I de n t i fy ( a s _ id _ ty p e, Ò %w, %h, %b , %f,% c,% g Ó ,
mand passing it the source and destination images and new
as _i m g _f i l e )
fixed dimension for the width and/or height to apply to the
The iole_img is the OleObject variable that is connected to original image. For example, if pass only a new width dimen-
ImageMagick OleServer. Using the ‘-format ‘ identification sion of 200 pixels, you obtain a new thumbnail image with
type we can obtain some important information as specified a max width of 200 pixels and a new relative proportional
by the above attribute mask such that: height. This method also requires four arguments: ‘-resize’
• %w returns the width command, a new width (as_dim = “200”), source image, and
• %h returns the height destination image. The syntax for the method is:
• %b returns the filesize
iole_ img . Conver t ( Ò -r esize Ó , a s_ d im, a s_ fr om_i mage,
• %f returns the filename
a s_ t o_ ima g e)
• %c returns the image comment
• %g returns the page geometry Superimpose Text Over An Existing Image
We can also use the ‘Convert’ method to draw graphic text
For a detailed list of possible ‘-format’ arguments you can see on existing image. To do so, we use the ‘Convert’ method
http://www.imagemagick.org/script/escape.php web page . with a direct call to the convert.exe program, passing along all
The width and height are expressed in pixels and they are the arguments it requires. To run it with a synchronous call,
our starting point for calculating the dimensions in PbUnits, we make use of the uo_syncproc Pb object from topwizpro-
thereby, allowing us to correctly display our source image on gramming . However, all the work is done by n_nvo_magick
a DataWindow computed bitmap column. with the following method:
FEBRUARY 2010 11

3. IMAGE MAGIC FOR POWERBUILDER
n _n v o _m ag i c k .of_ im g _ d r a w_ tex t ( as_fill_color - color name to fill the text.
s t ri n g as _f ro m _ im a g e, s tr in g a s _ to_ im a g e, as_stroke_color - color name for the stroke of text.
l o n g al _x _pos , lon g a l_ y _ p os , as_text - the text to draw inside the image.
s t ri n g as _f o n t_ n a m e, lon g a l_ p oin t_ s iz e,
s t ri n g as _f i ll_ color , s tr in g a s _ s tr ok e_ colo r ,
In my example application, I have created an image displaying
s t ri n g as _t e x t)
the text ‘PowerBuilder 11’ shown below in Figure 3.
The above method requires the caller to pass the source
image path, the destination image path, the x position in
pixels, the y position in pixels, the desired font name , the Figure 3: Text Image From Scratch
point size, the fill color, the stroke color, and the desired text
Create An Image From A PDF File
to be drawn. For example, if I call the method with :
This function is similar to the other ‘Convert’ options we
n _n v o _m ag i c k .of_ im g _ d r a w_ tex t ( ls _ fr om _ ima g e, have already seen with the only difference being that the
l s _t o _i m ag e , 1 0 , 30 , Ô T ha om a Õ , 2 4 , source file is not an image but a PDF file. The method to use
Ô W h i t e Ô , Õ W h i te Õ , Ô C hies a d i Sa n Fr a n ces co , is as follows:
A s c o l i P i c e n o - I ta lia Õ )
n_ nvo_ ma g ick. of_ img _ conver t _ pd f (
st r ing a s_ fr om_ ima g e, st r ing a s_ t o_ ima g e,
The following text drawn will be drawn on my image which
boolea n a b_ one_ ima g e)
is shown below in Figure 2.
To do the conversion, the caller must supply the name of
PDF file to convert, the name of the destination image and a
switch to force the composition of one PDF file when Image-
Magick produces more JPEGs from the PDF source file.
Crop A Selection Of A Source Image
Cropping an image is a familiar operation that everyone uses
Figure 2: Image With Annotation to obtain a new image by selecting a portion of an original
Create A Text Image From Scratch image and deleting the rest. The method to call to crop an
Using the ‘Convert’ method withthis option allows you to image is:
create a new image from scratch adding a graphic text to n_ nv nvo_ ma g ick. of_ img _ cr op (
display inside it. The signature for the method is as follows: st r ing a s_ fr om_ ima g e, st r ing a s_ t o_ ima g e,
long a l_ w id t h, long a l_ heig ht , long a l_ x_ pos,
n _n v o _m ag i c k .of_ im g _ tex t_ fr om _ s cr a tch (
long a l_ y_ pos)
s t ri n g as _t o _ im a g e, lon g a l_ wid th_ s iz e,
l o n g al _h e i g ht_ s iz e, s tr in g a s _ b a ck _ color , You need to pass it the name of the source image, the name
l o n g al _x _pos , lon g a l_ y _ p os ,
of the destination image, the width and height of the area to
s t ri n g as _f o n t_ n a m e, lon g a l_ p oin t_ s iz e,
crop, and the coordinate of the top left corner of the area. I
s t ri n g as _f i ll_ color , s tr in g a s _ s tr ok e_ colo r ,
have used a floating DataWindow rectangle (See Figure 4
s t ri n g as _t e x t)
and 5) to dynamically show the cropping area to select .
The arguments to pass it are the following:
as_to_image - name of the destination image.
al_width_size - width in pixels.
al_height_size - height in pixels.
as_back_color - name of the background color.
al_x_pos - x coordinate of the text starting point.
al_y_pos - y coordinate of the text starting point.
as_font_name - name of the font to use. Figure 5: Result Of
al_point_size - size of the font. Figure 4: Crop Area Selection Crop Operation
12 ISUG TECHNICAL JOURNAL

4. IMAGE MAGIC FOR POWERBUILDER
The Mogrify Method st r ing a s_ ba ckg r ound _ color , st r ing a s_ g eo metry,
With the ‘Convert’ re-sizing commands, we have seen how int eg er a i_ t ile_ col_ num, int eg er a i_ t ile_ r ow_nu m,
to create a thumbnail image starting from the original image. boolea n a b_ pola r oid , st r ing a s_ ima g e_ ba ckc ol or,
Now we will discover the ‘Mogrify’ command that allows us boolea n a b_ a d d _ t it le, st r ing a s_ t it le,
to create many thumbnails at once . For this purpose, I have st r ing a s_ t it le_ font , st r ing a s_ t it le_ point si z e)
implemented the following method: This method needs the following arguments:
n _n v o _m ag i c k .o f_ im g _ cr ea te_ fold er _ thu m b s( as_ini_folder - folder path containing thumbnails.
s t ri n g as _s o u r ce_ p a th, as_dest_folder - destination folder path.
s t ri n g as _i m a g e_ ex ten s ion , as_source_images - array of selected thumbnails.
DESIGN AND DEVELOPMENT
s t ri n g as _o u tp u t_ p a th, s tr in g a s _ ou tp u t_ f or ma t , as_dest_image - name of the new image.
l o n g al _t h umb _ wid th, lon g a l_ thu m b _ height , ai_thumb_width - width of the thumbnails.
re f s t _i m g _a ttr ib a s _ im g _ a r r a y [ ] ) ai_thumb_height - height of the thumbnails.
as_border_color - image border color.
It requires the followings arguments:
as_background_color - image background color.
as_source_path - complete path of the folder that
as_geometry - geometry that specifies spaces be-
contains original images.
tween new image thumbnails.
as_image_extension - image extension to convert.
ai_tile_col_num - number of columns to distribute
as_output_path - complete path of the folder that
thumbnails inside the new image.
will contain the thumbnails.
ai_tile_row_num - number of rows to distribute.
as_output_format - output image type (e.g. bmp).
thumbnails inside the new image.
al_thumb_width - width dimension (in pixels).
ab_polaroid - thumbnails’ polaroid effect switch.
al_thumb_height - height dimension (in pixels).
as_image_backcolor - new background color.
as_img_array[] - array of type stimg_attrib contain-
ab_add_title - title switch.
ing thumbnails attributes.
as_title - title of the new image.
as_title_font - title font name (e.g. Arial).
In my example, I have
as_title_pointsize - title font size (e.g. 12).
selected c:temp as the source
folder, JPEG as the image
In my example, I have
extension , c:tempthumbs as
selected five images and
output folder , GIF as the output
I have obtained the new
type and 200x200 pixels as the
image as shown in Figure
thumbnails dimensions. After
6. It is a JPEG image with
the creation of the thumbnails,
3 columns, 2 rows, white
Figure 5: Thumbnails I have used a DataWindow to thumbnails border color ,
display thumbs on the screen as
gray thumbnails background
shown in Figure 5.
Figure 6: New Image color, thumbnails with a
From Five Thumbnails polaroid effect, white image
The Montage Method
background color and a
Lastly, I will explain how to create an image index as a collage
‘ISUG index’ title .
of a collection of selected thumbnails using the ‘Montage’
method. To do this, I have first implemented a script to allow Conclusion
us to select thumbnails from the DataWindow container and I have finished with the explanation of the major features
then I have implemented the following method: of the ImageMagick library. You can find other interesting
n _n v o _m ag i c k .of_ im g _ m a k e_ m on ta g e ( examples and the source code on the ISUG web site (www.
s t ri n g as _i n i_ fold er , s tr in g a s _ d es t_ fold e r , isug.com). Some of these additional examples include raise,
s t ri n g as _s o u r ce_ im a g es [ ] , s tr in g a s _ d es t_ ima g e, blur, swirl, frame, polaroid and flip. Likewise, you can add
i n t e g e r ai _t h u m b _ wid th, other functionalities simply by reading the ImageMagick
i n t e g e r ai _t h u m b _ heig ht, s tr in g a s _ b or d er _ color , documentation and writing them in PowerScript code.
FEBRUARY 2010 13