Merge lp:~zorba-coders/zorba/bug867259 into lp:zorba

Proposed by Rodolfo Ochoa on 2013-04-23
Status: Merged
Approved by: Rodolfo Ochoa on 2013-04-24
Approved revision: 11382
Merged at revision: 11404
Proposed branch: lp:~zorba-coders/zorba/bug867259
Merge into: lp:zorba
Diff against target: 249 lines (+223/-0)
2 files modified
doc/zorba/indexpage.dox.in (+1/-0)
doc/zorba/tut_image.dox (+222/-0)
To merge this branch: bzr merge lp:~zorba-coders/zorba/bug867259
Reviewer Review Type Date Requested Status
Rodolfo Ochoa Approve on 2013-04-24
William Candillon 2013-04-23 Approve on 2013-04-24
Review via email: mp+160515@code.launchpad.net

Commit Message

Added tutorial to documentation

Description of the Change

Added tutorial to documentation

To post a comment you must log in.
review: Approve
William Candillon (wcandillon) wrote :

Looks great!

review: Approve
Zorba Build Bot (zorba-buildbot) wrote :

Validation queue job bug867259-2013-04-24T11-56-52.859Z is finished. The final status was:

All tests succeeded!

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/zorba/indexpage.dox.in'
2--- doc/zorba/indexpage.dox.in 2013-02-07 17:24:36 +0000
3+++ doc/zorba/indexpage.dox.in 2013-04-23 22:24:25 +0000
4@@ -62,4 +62,5 @@
5
6 \section tutorials Tutorials
7 - \ref web_crawler_tutorial
8+ - \ref image_processing_tutorial
9 */
10
11=== added file 'doc/zorba/tut_image.dox'
12--- doc/zorba/tut_image.dox 1970-01-01 00:00:00 +0000
13+++ doc/zorba/tut_image.dox 2013-04-23 22:24:25 +0000
14@@ -0,0 +1,222 @@
15+/**
16+\page image_processing_tutorial Image Processing with Zorba
17+
18+\section image_proc Image Representation And Formats
19+
20+\subsection images Images
21+
22+Images are passed to the functions of the imaging library as xs:base64Binary types and
23+any function returning an image will return it as xs:base64Binary type. For example,
24+images read by the Zorba file module are already returned as xs:base64Binary and are
25+ready to be used. Also, images written to disk using the file module will be ordinary
26+binary data if one passes \c binary as serialization option.
27+
28+
29+\subsection image_formats Image Formats
30+
31+Currently, the imaging library supports the following popular image formats: GIF, JPEG, TIFF, PNG and SVG.
32+If any other format is needed, please contact us and we will see if it is possible to support the format.
33+
34+\subsection functions Functions
35+
36+All functions provided by the image library are functional and will either return the right value
37+or raise an error. The library additionally offers interfaces with schema types in the function
38+signatures (\c basicschema.xq, \c manipulationschema.xq, \c paintschema.xq, \c animationschema.xq) which can
39+be used to directly validate certain types (e.g. color strings).
40+
41+
42+\subsection colors Colors
43+
44+Colors are represented as strings in the same way they are used in html. A leading '#' character
45+with 6 hexadecimal numbers following for red, green and blue values.
46+
47+Examples are:
48+- Black: #000000
49+- Red: #FF00000
50+- Green: #00FF00
51+- Blue: #0000FF
52+
53+\subsection modules Modules
54+
55+Zorba provides the following four modules for image processing:
56+
57+- <a href="/html/modules/zorba/image/basic">http://www.zorba-xquery.com/modules/image/basic</a> which is concerned with accessing basic image attributes, creating new images and converting their format.
58+- <a href="/html/modules/zorba/image/manipulation">http://www.zorba-xquery.com/modules/image/manipulation</a> which is concerned with image manipulations like zooming, special effects etc.
59+- <a href="/html/modules/zorba/image/paint">http://www.zorba-xquery.com/modules/image/paint</a> which is concerned with drawing different geometrical shapes and text to images.
60+- <a href="/html/modules/zorba/image/manipulation">http://www.zorba-xquery.com/modules/image/animation</a> which is concerned with creating animated GIF images.
61+
62+This tutorial contains a small example for each of the modules.
63+
64+
65+\section basic_imaging_functions Basic Imaging Functions
66+
67+\subsection creating_an_image Creating An Image
68+
69+In this example, we create a new image and return the width and type (image format) of the newly created image.
70+
71+\code
72+import module namespace basic = "http://www.zorba-xquery.com/modules/image/basic";
73+
74+let $new-image as xs:base64Binary := basic:create(xs:unsignedInt(100), xs:unsignedInt(100), "GIF")
75+let $width := basic:width($new-image)
76+let $format := basic:type($new-image)
77+return ($width, $format)
78+\endcode
79+
80+
81+\subsection explanation Explanation
82+
83+In line 3 \c $new-image is assigned the result of the basic:create command, so \c $new-image contains
84+the xs:base64Binary representation of a plain white GIF image.
85+
86+In line 4 we use the basic:width command with new-image as argument to get the width of the image
87+and in line 5 the basic:type function to get the format which are both passed back in line 6.
88+
89+\subsection expected_output Expected Output
90+
91+\code
92+<?xml version="1.0" encoding="UTF-8"?>
93+100 GIF
94+\endcode
95+
96+\subsection accessing_efix_information Accessing Exif Information
97+
98+This example shows how to access the Exif information in JPEG images (also possible with TIFF images).
99+
100+\code
101+import module namespace http = "http://expath.org/ns/http-client";
102+import module namespace basic = "http://www.zorba-xquery.com/modules/image/basic";
103+declare namespace h = "http://expath.org/ns/http-client";
104+
105+(: Get image from web :)
106+let $req := <h:request method="GET"
107+ href="http://www.zorba-xquery.com/tutorials/tutorialimages/exif.jpg"
108+ auth-method="Basic"
109+ send-authorization="true"
110+ username="zorba"
111+ password="blub"></h:request>
112+let $res := http:read($req, ())[2]
113+(: Using Image Library to extract exif tag :)
114+return basic:exif($res, "DateTimeOriginal")
115+\endcode
116+
117+\subsection explanation2 Explanation
118+
119+Lines 6 and 7 use the Zorba http library to get an image from the web.
120+Then, in line 9 we pass the image to the \c basic:exif function requesting the value of the \c DateTimeOriginal tag, which we return.
121+
122+\subsection expected_output2 Expected Output
123+\code
124+<?xml version="1.0" encoding="UTF-8"?>
125+2007-03-15T20:12:46+02:00
126+\endcode
127+
128+\section manipulatin_images Manipulating Images
129+
130+In this example, we first download an image from the web using Zorba's http client and then
131+apply a charcoal effect to that image returning the charcoaled image.
132+
133+\code
134+import module namespace http = "http://expath.org/ns/http-client";
135+import module namespace manipulation = "http://www.zorba-xquery.com/modules/image/manipulation";
136+declare namespace h = "http://expath.org/ns/http-client";
137+
138+(: Get image from web :)
139+let $req := <h:request method="GET" href="http://www.zorba-xquery.com/http-client/download.png" auth-method="Basic" send-authorization="true" username="zorba" password="blub" ></h:request>
140+let $res := http:read($req, ())[2]
141+(: Using Image Library to manipulate image :)
142+let $manipulated-image := manipulation:charcoal($res, 2.0, 3.0)
143+return $manipulated-image
144+\endcode
145+
146+\subsection explanation3 Explanation
147+
148+Lines 6 and 7 use the Zorba http client to retrieve an image from the web.
149+Then, in line 9, we assign \c $manipulated-image a manipulated version of the
150+image by passing the fetched image to the \c manipulation:charcoal function
151+that takes the image, performs the charcoal effect on it returns a charcoaled
152+version of the image.
153+
154+\subsection expected_output3 Expected Output
155+
156+\image html tutorialimages/charcoaled.gif
157+
158+\section painting_images Painting Images
159+
160+In this example, we create a new blank image and then paint a circle and a rectangle on it before returning it.
161+
162+\code
163+import module namespace basic = "http://www.zorba-xquery.com/modules/image/basic";
164+import module namespace paint = "http://www.zorba-xquery.com/modules/image/paint";
165+
166+let $blank-image := basic:create(xs:unsignedInt(150), xs:unsignedInt(150), "PNG")
167+let $image-circle := paint:draw-circle($blank-image, 75, 75, 50, "#00FF00", "#0000FF", 2, true())
168+let $image-circle-and-rectangle := paint:draw-rectangle($image-circle, 25, 25, 75, 75, "#FF00FF", "#5F08AA", 1, true())
169+return $image-circle-and-rectangle
170+\endcode
171+
172+\subsection explanation4 Explanation
173+
174+In line 4 a blank image with PNG format is created (like in the first example of this tutorial).
175+Then in line 5 we pass the blank image to the \c paint:draw-circle method which returns a version
176+of the blank image with a circle on it.
177+In line 6 we pass the image which already has a circle on it to the \c paint:draw-rectangle function
178+which returns an additional rectangle painted on it.
179+
180+\subsection expected_output4 Expected Output
181+
182+\image html tutorialimages/painted.png
183+
184+\section creating_animated_gifs Creating Animated GIFS
185+
186+In this example, we create two blank images, paint a line on each, and use them to create an animated gif.
187+
188+\code
189+import module namespace basic = "http://www.zorba-xquery.com/modules/image/basic";
190+import module namespace paint = "http://www.zorba-xquery.com/modules/image/paint";
191+import module namespace anim = "http://www.zorba-xquery.com/modules/image/animation";
192+
193+let $blank-image := basic:create(xs:unsignedInt(100), xs:unsignedInt(100), "GIF")
194+let $first-image := paint:draw-line($blank-image, 50, 25, 50, 75, (), (), true())
195+let $second-image := paint:draw-line($blank-image, 25, 50, 75, 50, (), (), true())
196+return anim:create-animated-gif(($first-image, $second-image), xs:unsignedInt(15), xs:unsignedInt(0))
197+\endcode
198+
199+\subsection explanation5 Explanation
200+
201+In lines 6 and 7, we create 2 images each containing a line painted on them.
202+Then, in line 8, we return the output of anim:create-animated-gif (which is a GIF image)
203+for which we pass the images from lines 6 and seven as arguments. The function composes
204+them to an animated GIF image.
205+
206+\subsection expected_output5 Expected Output
207+
208+\image html tutorialimages/animated.gif
209+
210+\section putting_it_all_thogether Putting it all together: A More Extensive Example
211+
212+In this example, we will create an image displaying a scrolling text using different techniques from the examples above.
213+
214+\code
215+import module namespace basic = "http://www.zorba-xquery.com/modules/image/basic";
216+import module namespace paint = "http://www.zorba-xquery.com/modules/image/paint";
217+import module namespace anim = "http://www.zorba-xquery.com/modules/image/animation";
218+
219+let $blank-image := basic:create(xs:unsignedInt(100), xs:unsignedInt(100), "GIF")
220+let $i1 := paint:draw-text($blank-image, "Zorba Rocks", -10, 40, "Arial", (), "#FF0000")
221+let $i2 := paint:draw-text($blank-image, "Zorba Rocks", 20, 40, "Arial", (), "#FF0000")
222+let $i3 := paint:draw-text($blank-image, "Zorba Rocks", 40, 40, "Arial", (), "#FF0000")
223+let $i4 := paint:draw-text($blank-image, "Zorba Rocks", 60, 40, "Arial", (), "#FF0000")
224+let $i5 := paint:draw-text($blank-image, "Zorba Rocks", 80, 40, "Arial", (), "#FF0000")
225+let $i6 := paint:draw-text($blank-image, "Zorba Rocks", 100, 40, "Arial", (), "#FF0000")
226+let $i7 := paint:draw-text($blank-image, "Zorba Rocks", 20, 40, "Arial", (), "#FF0000")
227+let $i8 := paint:draw-text($blank-image, "Zorba Rocks", 120, 40, "Arial", (), "#FF0000")
228+return anim:create-morphed-gif(($i1, $i2, $i3, $i4, $i5, $i6, $i7, $i8), xs:unsignedInt(2), xs:unsignedInt(0), xs:unsignedInt(4))
229+\endcode
230+
231+\subsection expected_output6 Expected Output
232+
233+\image html tutorialimages/extended.gif
234+
235+
236+*/
237\ No newline at end of file
238
239=== added directory 'doc/zorba/tutorialimages'
240=== added file 'doc/zorba/tutorialimages/animated.gif'
241Binary files doc/zorba/tutorialimages/animated.gif 1970-01-01 00:00:00 +0000 and doc/zorba/tutorialimages/animated.gif 2013-04-23 22:24:25 +0000 differ
242=== added file 'doc/zorba/tutorialimages/charcoaled.gif'
243Binary files doc/zorba/tutorialimages/charcoaled.gif 1970-01-01 00:00:00 +0000 and doc/zorba/tutorialimages/charcoaled.gif 2013-04-23 22:24:25 +0000 differ
244=== added file 'doc/zorba/tutorialimages/exif.jpg'
245Binary files doc/zorba/tutorialimages/exif.jpg 1970-01-01 00:00:00 +0000 and doc/zorba/tutorialimages/exif.jpg 2013-04-23 22:24:25 +0000 differ
246=== added file 'doc/zorba/tutorialimages/extended.gif'
247Binary files doc/zorba/tutorialimages/extended.gif 1970-01-01 00:00:00 +0000 and doc/zorba/tutorialimages/extended.gif 2013-04-23 22:24:25 +0000 differ
248=== added file 'doc/zorba/tutorialimages/painted.png'
249Binary files doc/zorba/tutorialimages/painted.png 1970-01-01 00:00:00 +0000 and doc/zorba/tutorialimages/painted.png 2013-04-23 22:24:25 +0000 differ

Subscribers

People subscribed via source and target branches