= Bossa tutorial = == Create a Bossa server == [ServerIntro Install the BOINC software] on a Linux system (or run the [VmServer BOINC virtual server] in a VMWare player on any computer). Use [MakeProject make_project] to create a BOINC project named "test": {{{ > cd boinc/tools > make_project --web_only test }}} Read '''~/projects/test/test.readme''' and do what it says. Let's say your server's domain name is "a.b.c". * Visit http://a.b.c/test/create_account.php and create an account for yourself. * Visit http://a.b.c/test_ops/bossa_admin.php. Follow the instructions to create the Bossa database. == Example application == We'll create an application in which volunteers view synthetic images, looking for ellipses on a noisy background. Their task is to click on the center of the ellipse, or to indicate that there is no ellipse. Here's an example: [[Image(bossa_test.png, nolink)]] (there's an ellipse slightly below/left of center). Visit http://a.b.c/test_ops/bossa_ops.php, and create an application with short name "bossa_example". The application is define by three scripts in ~/projects/test/html/: * '''ops/bossa_example_make_files.php''': a script that creates image files. * '''ops/bossa_example_make_jobs.php''': a script that creates jobs. * '''inc/bossa_example.inc''': display and policy functions. We'll go through these scripts and explain how they work. To develop your own Bossa applications you'll need to write corresponding scripts. == Creating jobs == First we'll create some image files using the script [source:/trunk/boinc/html/ops/bossa_example_make_files.php html/ops/bossa_example_make_files.php]. {{{ cd ~/projects/test/html/ops mkdir ../user/example php bossa_example_make_files.php --nfiles 10 --dir example }}} This creates (in the '''examples/''' directory) 10 image files '''0.png''' to '''9.png''', and corresponding "answer" files '''0.ans''' to '''9.ans'''. Roughly half the images will have ellipses (you can specify this probability with '''--ellipse_frac x'''). Now, create jobs using [source:/trunk/boinc/html/ops/bossa_example_make_jobs.php html/ops/bossa_example_make_jobs.php]: {{{ php bossa_example_make_jobs --app_name bossa_example --dir example }}} This makes 10 jobs (one for each image in the directory) and collects them into a "batch". == Display and policy functions == The file ([source:/trunk/boinc/html/inc/bossa_example.inc html/inc/bossa_example.inc]) contains display and policy functions. The display function is: {{{ function job_show($job, $inst, $user) { $info = $job->get_info($job); $path = $info->path; page_head("Find the Ellipse"); echo "
Click on the center of the ellipse. If you don't see one, click here:

id>
"; page_tail(); } }}} The policy functions are as follows. {{{ function job_issued($job, $inst, $user) { $job->set_priority(0); } }}} This is called when a job is issued. It sets the job's priority to zero so that no further instances will be issued (unless this one times) out. {{{ function job_finished($job, $inst) { $response = null; if (get_str('submit', true)) { $response->have_ellipse = 0; } else { $response->have_ellipse = 1; $response->cx = get_int('pic_x'); $response->cy = get_int('pic_y'); } $inst->update_info($response); } }}} This is called when a job instance is finished. It gets the user's response to the job, and stores it in the instance's app data field. {{{ function job_timed_out($job, $inst, $user) { $job->set_priority(1); } }}} This is called when a job times out. It restores the priority to one so that the job will be issued to another volunteer. The remaining functions return short strings that show the app data for jobs, instances, and users on the Admin page: {{{ function job_summary($job) { $info = $job->get_info(); return "path>View image"; } function instance_summary($inst) { $info = $inst->get_info(); if ($info->have_ellipse) { return "($info->cx, $info->cy)"; } else { return "no ellipse"; } } function show_user_summary($user) { } }}}