1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
|
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title/>
<meta name="generator"
content="StarOffice/OpenOffice.org XSLT (http://xml.openoffice.org/sx2ml)"/>
<meta name="author" content="Adam Zammit"/>
<meta name="created" content="2008-01-14T14:45:16"/>
<meta name="changedby" content="Adam Zammit"/>
<meta name="changed" content="2008-01-16T16:03:47"/>
<base href="."/>
<style type="text/css">
@page {
size: 20.999cm 29.699cm;
margin-top: 2cm;
margin-bottom: 2cm;
margin-left: 2cm;
margin-right: 2cm
}
table {
border-collapse:collapse;
border-spacing:0;
empty-cells:show
}
td, th {
vertical-align:top;
}
h1, h2, h3, h4, h5, h6 {
clear:both
}
ol, ul {
padding:0;
}
* {
margin:0;
}
*.Graphics {
font-size:12pt;
vertical-align:top;
text-align:center;
}
*.Caption {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0.212cm;
margin-bottom:0.212cm;
font-style:italic;
}
*.Heading {
font-family:Arial;
font-size:14pt;
margin-top:0.423cm;
margin-bottom:0.212cm;
}
*.Heading1 {
font-family:Arial;
font-size:115%;
margin-top:0.423cm;
margin-bottom:0.212cm;
font-weight:bold;
}
*.Heading2 {
font-family:Arial;
font-size:14pt;
margin-top:0.423cm;
margin-bottom:0.212cm;
font-style:italic;
font-weight:bold;
}
*.Heading3 {
font-family:Arial;
font-size:14pt;
margin-top:0.423cm;
margin-bottom:0.212cm;
font-weight:bold;
}
*.Heading4 {
font-family:Arial;
font-size:85%;
margin-top:0.423cm;
margin-bottom:0.212cm;
font-style:italic;
font-weight:bold;
}
*.Index {
font-family:'Times New Roman';
font-size:12pt;
}
*.List {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.ListIndent {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
margin-left:5.001cm;
margin-right:0cm;
text-indent:-4.5cm;
}
*.P1 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.P2 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
margin-left:5.001cm;
margin-right:0cm;
text-indent:-4.5cm;
text-align:left ! important;
}
*.P3 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.P4 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.P5 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.P6 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
text-align:left ! important;
}
*.P7 {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.Standard {
font-family:'Times New Roman';
font-size:12pt;
}
*.Textbody {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
}
*.Textbodyindent {
font-family:'Times New Roman';
font-size:12pt;
margin-top:0cm;
margin-bottom:0.212cm;
margin-left:0.499cm;
margin-right:0cm;
text-indent:0cm;
}
*.BulletSymbols {
font-family:StarSymbol;
font-size:9pt;
}
*.Internetlink {
color:#000080;
text-decoration:underline;
}
*.NumberingSymbols {
}
*.T1 {
vertical-align:sup;
}</style>
</head>
<body dir="ltr">
<h1 class="Heading1"><a name="queXF_Manual"/>queXF Manual</h1>
<p class="Standard"> </p>
<h2 class="Heading2"><a name="About_3A"/>About:</h2>
<p class="Textbodyindent">queXF was written by Adam Zammit for DCARF (Deakin Computer
Assisted Research Facility). queXF takes paper forms generated using queXML (see <a
href="http://quexml.sourceforge.net/">http://quexml.sourceforge.net</a>) and reads
them. Operators can then verify that queXF has read the form correctly. Once this is
done, the data collected can be exported in a fixed width ASCII file with a DDI (see <a
href="http://ddialliance.org/">http://ddialliance.org</a>) data description.</p>
<p class="Textbodyindent">queXF can be used as an Open Source replacement to programs such
as Cardiff's Teleform, although it has a much more limited scope. </p>
<h2 class="Heading2"><a name="queXF_Scope_3A"/>queXF Scope:</h2>
<ul style="margin-left:1.25cm;">
<li class="P1" style="margin-left:0cm;">
<p class="P1" style="margin-left:0.25cm;">Work with any document generated using
queXML </p>
</li>
<li class="P1" style="margin-left:0cm;">
<p class="P1" style="margin-left:0.25cm;">Allow for an unlimited number of verifiers
to work at a time (given hardware/network constraints) </p>
</li>
<li class="P1" style="margin-left:0cm;">
<p class="P1" style="margin-left:0.25cm;">Produce data in ASCII format with a DDI
description file </p>
</li>
<li class="P1" style="margin-left:0cm;">
<p class="P1" style="margin-left:0.25cm;">Work with the Firefox browser as a
client </p>
</li>
</ul>
<h2 class="Heading2"><a name="Software_requirements_3A"/>Software requirements:</h2>
<p class="Standard"> </p>
<p class="ListIndent"><a href="http://php.net/">PHP</a> 4 or 5</p>
<p class="ListIndent">
<a href="http://adodb.sourceforge.net/">ADOdb</a>
</p>
<p class="ListIndent"><a href="http://www.mysql.org/">MySQL 5</a> with the InnoDB Engine
(currently uses views and transactions)</p>
<p class="ListIndent"><a href="http://pages.cs.wisc.edu/~ghost/">Ghostscript</a> version 8</p>
<p class="ListIndent"><a href="http://www.mozilla.com/firefox/">Firefox</a> browser with a
screen size of 1024x768 or larger</p>
<p class="ListIndent"> </p>
<h2 class="Heading2"><a name="Software_options__28OCR_29_3A"/>Software options (OCR):</h2>
<p class="Standard"> </p>
<p class="ListIndent"><a href="http://code.google.com/p/tesseract-ocr/">Tesseract OCR</a> –
For reading text or number fields</p>
<p class="P2"><a href="http://www.imagemagick.org/">ImageMagick</a> – For converting images
to work with tesseract</p>
<p class="Standard"> </p>
<h2 class="Heading2"><a name="Installing_queXF_3A"/>Installing queXF:</h2>
<p class="Textbody"> </p>
<p class="Textbody">Security warning: The default installation of queXF has no security
enabled. This package is designed to be run on a trusted internal network. Although with
directory level security it should be quite safe. </p>
<p class="Textbody"> </p>
<ol style="margin-left:1.25cm;list-style-type:decimal; ">
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Extract queXF to your web server root </p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Enable security (skip this only if you
deem it safe): </p>
<ol style="margin-left:0.75cm;list-style-type:decimal; ">
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">See: <a
href="http://httpd.apache.org/docs/2.0/howto/auth.html">Apache
Authentication</a></p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Restrict the root directory to to
a group of trusted users </p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Restrict the Admin directory to a
trusted user using directory based authentication </p>
</li>
</ol>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Create the queXF database </p>
<ol style="margin-left:0.75cm;list-style-type:decimal; ">
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">It is recommended to also create a
user with privileges only to the queXF database </p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Create the tables using the script
in the database directory of the package </p>
</li>
</ol>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Modify the configuration file </p>
<ol style="margin-left:0.75cm;list-style-type:decimal; ">
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Edit the file config.inc.php in
the root directory of the package </p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Make sure the path to ADOdb is
correct </p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Make sure the database parameters
are correct </p>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">If you wish to enable OCR, make
sure you set the path to tesseract (see and convert from the
ImageMagick package. Then set OCR_ENABLED to true</p>
</li>
</ol>
</li>
<li class="P3" style="margin-left:0cm;">
<p class="P3" style="margin-left:0.25cm;">Test your configuration settings by
running the admin/testconfig.php script </p>
<p class="P3" style="margin-left:0.25cm;"> </p>
</li>
</ol>
<p class="Textbody"> </p>
<h2 class="Heading2"><a name="Forms_that_currently_work_with_queXF"/>Forms that currently
work with queXF</h2>
<p class="Textbody"> </p>
<p class="Textbody">All forms created using <a href="http://quexml.sourceforge.net/"
>queXML</a> should work with queXF.</p>
<p class="Textbody"> </p>
<p class="Textbody">If you have a customised form, queXF requires the following to operate: </p>
<ol style="margin-left:1.25cm;list-style-type:decimal; ">
<li class="P4" style="margin-left:0cm;">
<p class="P4" style="margin-left:0.25cm;">A unique <a
href="http://en.wikipedia.org/wiki/Interleaved_2_of_5">interleaved 2 of
5</a> barcode in the top right hand corner of each page</p>
</li>
</ol>
<ul style="margin-left:1.25cm;list-style-type:none; ">
<li class="P5" style="margin-left:0cm;">
<ul style="margin-left:0.75cm;">
<li class="P5" style="margin-left:0cm;">
<p class="P5" style="margin-left:0.25cm;">Please note that the barcode must
be unique for each page across all forms in the queXF system. </p>
</li>
</ul>
</li>
</ul>
<ol style="margin-left:1.25cm;list-style-type:decimal; ">
<li class="P4" style="margin-left:0cm;">
<p class="P4" style="margin-left:0.25cm;">A vertical and horizontal line in each
corner of the page (for alignment) </p>
</li>
<li class="P4" style="margin-left:0cm;">
<p class="P4" style="margin-left:0.25cm;">Boxes to be filled in should be square or
rectangular (not circular) </p>
<p class="P4" style="margin-left:0.25cm;"> </p>
</li>
</ol>
<p class="Textbody">Please note that the author has not tested a form that was not created
in queXML, therefore can make no guarantees that it will work (Although it should). If
you have any forms that you have trouble with (that comply with the 3 points above),
please send in an example for testing. </p>
<h2 class="Heading2"><a name="Using_queXF_3A"/>Using queXF:</h2>
<p class="Textbody"> </p>
<p class="Textbody">Please note that queXF has only been tested on a LAMP system (Linux,
Apache, MySQL and PHP) and this guide assumes the reader is using a similar system. </p>
<p class="Textbody"> </p>
<h3 class="Heading3"><a name="Administrative_Tasks_3A"/>Administrative Tasks:</h3>
<p class="Textbody">These tasks are accessible from the /admin directory of the package (eg:
/quexf/admin) </p>
<h4 class="Heading4"><a name="Import_a_form"/>Import a form</h4>
<p class="Textbody">It is best to import a form that is scanned in the same way as the
completed forms will be scanned in. Therefore if you have used queXML to produce a form
like this <a href="test_original.pdf"
>example</a>, scan it using your scan software to a PDF file like this <a
href="test_blank.pdf">example</a>.</p>
<p class="Textbody">Go to the page: <a
href="../admin/new.php">Import a new form from a PDF
file</a> (new.php) and select the pdf file to import. (An example is test_blank.pdf
in the doc directory). Enter a description such as 'test questionnaire'.</p>
<p class="Textbody">You should see a result such as: </p>
<p class="Textbody"> </p>
<p class="Textbody">BARCODE: 00000100 </p>
<p class="Textbody">BARCODE: 00000102 </p>
<p class="Textbody">BARCODE: 00000103 </p>
<p class="Textbody">SUCCESSFULLY INSERTED NEW QUESTIONNAIRE </p>
<p class="Textbody"> </p>
<p class="Textbody">If you try to import the same form again, or another form that has a
page with the same barcode as a previous form, you will get an error like this:</p>
<p class="Textbody"> </p>
<p class="Textbody">BARCODE: 00000100 </p>
<p class="Textbody">BARCODE: 00000102 </p>
<p class="Textbody">BARCODE: 00000103 </p>
<p class="Textbody">FAILED to insert new questionnaire. Could have conflicting page id's </p>
<p class="Textbody"> </p>
<p class="Textbody">This is because queXF identifies each page by the barcode, therefore
there cannot be a duplicate. </p>
<h4 class="Heading4"><a name="Band_a_form"/>Band a form</h4>
<p class="Textbody">'Banding' a form is the act of telling queXF where the fields are that
respondents will fill in. queXF is able to detect single choice and multiple choice
check boxes, text and number boxes and also VAS (Visual Analog Scale) question types. </p>
<p class="Textbody">Banding a form works in two stages, firstly identifying the fields, then
assigning the fields a name and type. Identifying the field is done by clicking once on
the form at the upper left corner of the field, outside the field boxes, then clicking
for a second time in the bottom right corner of the field, outside the field boxes.
queXF will then identify the boxes within the field and display them in red. The second
task is to click on the boxes to bring up a window to assign the field name and type, or
delete the field if it has been detected unsatisfactorily. </p>
<p class="Textbody">Banding is done from the <a
href="../admin/band.php">banding page</a>.</p>
<p class="Textbody">
<a href="banding.html">Here is a run down of how to band using pictures</a>
</p>
<p class="Textbody">Once the form has been banded, go back to the main banding page and
select 'reorder variables'. This will automatically order the form from top to bottom,
left to right so that when the form is verified, it will go through in a logical order </p>
<p class="Textbody"> </p>
<h4 class="Heading4"><a name="Add_users"/>Add users</h4>
<p class="Textbody">Users must be added to the system that match the underlying
authentication system from the <a
href="../admin/operators.php">add users page</a>.</p>
<h4 class="Heading4"><a name="Assign_forms_to_users"/>Assign forms to users</h4>
<p class="Textbody">Once the users have been added, <a
href="../admin/verifierquestionnaire.php">assign the
users </a>you want to work on each form</p>
<h4 class="Heading4"><a name="Import_a_directory_of_forms"/>Import a directory of forms</h4>
<p class="Textbody">Once the form has been banded, go to the<a
href="../admin/import.directory.php"> import a
directory</a> page to import PDF forms to the system. Make sure you know the full
path to where the files are stored on the web server, and that they are read accessible
by the web server process. There are 2 filled example forms in the 'filled' directory of
the doc directory.</p>
<p class="Textbody">If queXF is stored on the server here: /var/www/quexf – then enter:
/var/www/quexf/doc/filled to process the forms in the filled directory. </p>
<p class="Textbody">Please note that processing forms does take some time so please be
patient. </p>
<h4 class="Heading4"><a name="Handle_missing_pages"/>Handle missing pages</h4>
<p class="Textbody">The <a href="../admin/missingpages.php"
>missing pages form</a> allows you to manually tell queXF what page has been scanned
where queXF fails to detect it automatically. queXF sometimes fails to detect a page if
the barcode has been modified or scanned in poorly.</p>
<p class="Textbody">The page on the left is the 'missing page' and the page on the right is
the page that queXF thinks is a match. If queXF does not produce any matches, then the
page is probably blank, or has been scanned in twice for that form. In that case, press
the 'delete' link to delete the page from the system. If the page on the left has useful
information on it, queXF should produce a list of possible pages on the right. If the
page matches, press the 'accept' link. If the page does not match, there may be more
available using the page numbers on the top of the right hand image. Once you have found
the correct one, press the 'accept' link. </p>
<h4 class="Heading4"><a name="Output_data"/>Output data</h4>
<p class="Textbody">The <a href="../admin/output.php">output
data form</a> is used to export data from queXF. It will only export the data that a
verifier has confirmed, not what has been automatically detected by the system.</p>
<h4 class="Heading4"><a name="Display_Progress"/>Display Progress</h4>
<p class="Textbody">The <a href="../admin/progress.php">progress page</a> displays the progress of form verification.</p>
<h3 class="Heading3"><a name="Operator_Tasks_3A"/>Operator Tasks:</h3>
<h4 class="Heading4"><a name="Verification"/>Verification</h4>
<p class="Textbody"> </p>
<p class="Textbody"><a href="../verifyjs.php"
>Verification</a> is where an operator runs through each question in a questionnaire to
confirm that queXF has correctly guessed what has been written on the form. If there is
a discrepancy, the operator can correct it.</p>
<p class="Textbody">Each question is run through. The question that the operator is working
on will be highlighted orange. The guessed answer will be shown in green. The operator
may use the mouse to select/deselect an answer by clicking on the appropriate box, or
may use the keyboard as shown below: </p>
<p class="Textbody"> </p>
<p class="Textbody">Keys for single choice and multiple choice question types: </p>
<ul style="margin-left:1.25cm;">
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">Enter: Accept the current answer and move
to the next question </p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">Ctrl: Move back to the previous question
</p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">1-9: Select/Deselect the 1<span class="T1"
>st</span>,2<span class="T1">nd</span>...9<span class="T1">th</span>
choice</p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">left, up: Move the cursor to the next
choice left or up </p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">right, down: Move the cursor to the next
choice right or down </p>
</li>
</ul>
<p class="Textbody"> </p>
<p class="Textbody">Keys for text and number question types: </p>
<ul style="margin-left:1.25cm;">
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">Enter: Accept the current answer </p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">Ctrl: Move back to the previous
question </p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">Backspace: Move back a box </p>
</li>
<li class="P7" style="margin-left:0cm;">
<p class="P7" style="margin-left:0.25cm;">Space bar: Leave the next box blank </p>
</li>
</ul>
<p class="Textbody"> </p>
<p class="Textbody"> </p>
</body>
</html>
|