Bossa tutorial

Create a Bossa server

Install the BOINC software on a Linux system (or run the BOINC server virtual machine in a VMWare player on any computer).

Use make_project to create a BOINC project named "test":

> cd boinc/tools
> make_project --web_only test

Edit httpd.conf as directed (you'll need root access to do this). 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.

Example application

We'll create an application in which volunteers view 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:

(this has 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_workgen.php: this generates more jobs.
• user/bossa_example_display.php: show a job, and handle user response.
• inc/bossa_example_backend.php: compare and handle completed jobs.

We'll go through these scripts and explain how they work. To develop your own Bossa applications you'll need to write corresponding scripts.

A script to generate jobs

First, let's generate some jobs. We'll do this with a PHP script, html/ops/bossa_example_workgen.php.

The first part of this script is code for generating an image; the key functions are make_test_case(), which generates a structure saying if and where there's an ellipse, and make_image(), which generates an image given this info.

Next we have

function make_job($app, $batch, $i, $config) {
    // create the image file;
    // store it in the download directory hierarchy
    //
    $jobname = "job_$batch_$i";
    $case = make_test_case();
    $filename = "$jobname.png";
    $path = dir_hier_path(
        $filename, $config->download_dir, $config->uldl_dir_fanout
    );
    $url = dir_hier_url(
        $filename, $config->download_url, $config->uldl_dir_fanout
    );
    imagepng(make_image($case), $path);
    $case->url = $url;

    // make a job record in the Bossa database
    //
    $job = new BossaJob;
    $job->app_id = $app->id;
    $job->batch = $batch;
    $job->time_estimate = 30;
    $job->time_limit = 600;
    $job->name = $jobname;
    $job->info = json_encode($case);

    if (!$job->insert()) {
        echo "BossaJob::insert failed: ", mysql_error(), "\n";
        exit(1);
    }
}

This function creates one job, as follows:

• Choose a name for the job, and a name for the corresponding image file.
• Decide where the file goes in the project's download hierarchy.
• Generate a random case (ellipse presence and position)
• Create the image file.
• Create a job record in the Bossa database. Assign a time estimate (in seconds) and a time limit. Store a description of the job, encoded in JSON, in the job record.

Finally we have:

function make_jobs($njobs) {
    $c = get_config();
    $config = null;
    $config->download_dir = parse_config($c, "<download_dir>");
    $config->download_url = parse_config($c, "<download_url>");
    $config->uldl_dir_fanout = parse_config($c, "<uldl_dir_fanout>");
    $app = BossaApp::lookup_name("Find the ellipse");
    if (!$app) {
        echo "Application $appname not found\n";
        exit(1);
    }
    $batch = time();
    for ($i=0; $i<$njobs; $i++) {
        make_job($app, $batch, $i, $config);
    }
    echo "Created $njobs jobs";
}

$njobs = get_int('make_jobs', true);
if ($njobs) {
    make_jobs($njobs);
} else {
    header ("Content-type: image/png");
    imagepng(make_image(make_test_case()));
}

make_jobs() parses the project configuration file, looks up the application in the database, and creates some jobs. You can invoke this by visiting ​http://a.b.c/test_ops/bossa_example_workgen.php?make_jobs=10 (or use the link on the ​http://a.b.c/test_ops/bossa_ops.php).

Displaying jobs

Next we'll explain the script that displays a job to a volunteer and handles their response: bossa_example_display.php.

function show_job($bj, $bji) {
    $info = json_decode($bj->info);
    $img_url = $info->url;
    echo "
        <form method=get action='bossa_example_display.php'>
        Click on the center of the ellipse.
        If you don't see one, click here:
        <br><br><input type=submit name=submit value=None>
        <input type=hidden name=bji value=$bji->id>
        <input type=hidden name=completion value=1>
        <input type=image name=pic src='$img_url'>
        </form>
    ";
}

function handle_job_completion($bj, $bji) {
    $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');
    }
    $bji->info = json_encode($response);
    $bji->completed($bj);
    Bossa::show_next_job($bj);    // show another job immediately
}

Bossa::script_init($user, $bj, $bji);

if (isset($_GET['completion'])) {
    handle_job_completion($bj, $bji);
} else {
    show_job($bj, $bji);
}

The script calls Bossa::script_init() to get PHP objects describing the user, the job, and the job instance.

show_job() decodes the job description to get the image URL, and displays the image in an HTML page that lets the user click on the image or on a "No ellipse" button.

handle_job_completion() gets the user's response (from form variables). It calls the completed() method of the job, passing it a JSON encoding of the response. I then calls Bossa::show_next_job() to immediately display another job.

Handling completed results

Finally, we need to specify how results are handled. This is specified in bossa_example_backend.inc.

This defines two functions, which must have names X_compare and X_handle where X is the application's short name.

The first function compares two instances and decides if they are compatible:

function bossa_example_compare($r1, $r2) {
    if ($r1->have_ellipse) {
        if ($r2->have_ellipse) {
            $dx = ($r1->cx - $r2->cx);
            $dy = ($r1->cy - $r2->cy);
            $dsq = $dx*$dx + $dy*$dy;
            return ($dsq < 400);
        } else return false;
    } else {
        return !$r2->have_ellipse;
    }
}

In this case, two instances are considered compatible if either

• neither of them found an ellipse, or
• they both found an ellipse and the centers are within 20 pixels

The second function specifies what happens when a job has been completed, i.e. a consensus set has been found:

function bossa_example_handle($bj, $c) {
    $res = $c[0];
    if ($res->have_ellipse) {
        $res->cx = 0;
        $res->cy = 0;
        foreach ($c as $r) {
            $res->cx += $r->cx;
            $res->cy += $r->cy;
        }
        $res->cx /= count($c);
        $res->cy /= count($c);
    }

    $info = json_decode[$bj->info);
    $info->result = $res;
    $i = json_encode($info);
    $bj->update("info='$i'");
}

This function is called with the BossaJob? record ($bj) and an array of job instances in the consensus set ($c). In this case, we average the center positions (if an ellipse was found) and store the JSON-encoded result in the info field of the job record.