HELIO World Manual

Basics

The HELIO World package contains 3 files:

i_helio_world.php
contains the PHP class.
i_helio_world_borders.php
contains the country borders coordindates.
i_helio_world_country_names.php
contains the country names.

To use HELIO World, your must include i_helio_world.php and create a new helio_world. The following code creates a 200x200 pixel image.

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->render();

?>

Positioning

As you can see, the map is centered by default on Africa. Why? Because the map is pixel wide by pixel height. By default, the map is centered in its middle (,).

You can move the map to different coordinates by using set_center_xy(x,y). In the following example, we will center the map on Japan:

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->set_center_xy (1750, 420);

$world->render();

?>

This example may be fine assuming you know by heart each country's coordinates. To center the map on a given country, use center_on_country(ISO_code[,autozoom=false]).

In the following example, we will center the map on the United States of America (ISO code: us).

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->center_on_country ("us", false);

$world->render();

?>

As you can see, the map is centered on the USA but the full country isn't visible. You could ajust the zoom using set_zoom_factor(z). z=1 is the default. z=2 make the countries twice bigger, z=0.5 make the countries twice smaller etc... Instead, you can also set the autozoom parameter to true. Here is the result:

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->center_on_country ("us", true);

$world->render();

?>

To center the map on a region, use center_on_region(region_id[,autozoom=false]), for example:

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->center_on_region (HELIO_WORLD_EUROPE, true);

$world->render();

?>

The following regions are available:

HELIO_WORLD_AFRICA
HELIO_WORLD_ASEAN
HELIO_WORLD_ASIA
HELIO_WORLD_AMERICAS
HELIO_WORLD_EASTERN_EUROPE
HELIO_WORLD_EUROPE
HELIO_WORLD_LATIN_AMERICA
HELIO_WORLD_MIDDLE_EAST
HELIO_WORLD_ALL

Colors

You can change the sea, country and country border colors using:

set_country_color(red,green,blue)
set_country_border_color(red,green,blue)
set_bg_color(red,green,blue)

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->set_country_bg_color (244, 23, 100);
$world->set_country_border_color (255, 255, 255);
$world->set_bg_color (0, 0, 255);

$world->center_on_region (HELIO_WORLD_LATIN_AMERICA, true);

$world->render();

?>

A background image can be used to represent the sea using the function set_bg_image(image):

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->set_bg_image ("ondulations_bleues.jpg");

$world->center_on_region (HELIO_WORLD_LATIN_AMERICA, true);

$world->render();

?>

How to select countries

Now that you know how to position the map, you will learn how to assign colors and values to countries.

To highlight a given country, use select_country(country_code [,value, red, green, blue]).

You can also add a caption to help people understand your colors by using helio_world_caption()

<?php

include "i_helio_world.php";

// Create the HELIO World object
$world = new helio_world (200, 200);

// Center the map on Latin America
$world->center_on_region (HELIO_WORLD_LATIN_AMERICA, true);

// Assign colors to Brazil (br), Argentina (ar) and Chile (cl)
// with no particular value (false)
$world->select_country ("br", false, 255, 0, 0);
$world->select_country ("ar", false, 255, 255, 0);
$world->select_country ("cl", false, 0, 255, 0);

// Create a caption
$caption = new helio_world_caption ();
$caption->add_entry ("Brazil", 255, 0, 0);
$caption->add_entry ("Argentina", 255, 255, 0);
$caption->add_entry ("Chile", 0, 255, 0);

// Set the caption size and font size
$caption->set_size (10);
$caption->set_font_size (1);
$caption->set_position (130, 150); // from the top left corner of the image

// Assign the caption to the map
$world->set_caption ($caption);

$world->render();

?>

Gradients

Let's imagine that you would like to graphically represent your website users countries, depending on the value assigned to each of them. To do so, use the object named helio_world_gradient().

There are 2 ways to use helio_world_gradient():

Use the predefined gradient (see function set_auto_colors (min_value, max_value, nb_of_entries_in_the_caption))

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->center_on_region (HELIO_WORLD_EUROPE, true);

$gradient = new helio_world_gradient ();

// set_auto_colors (min_value, max_value, division)
$gradient->set_auto_colors (0, 100, 6);


// Could also be retrive from a database for example
$values_by_country = array ("be"=>5, "fr"=>8, "de"=>35, "ch"=>45, "it"=>51,
                                "pt"=>70, "es"=>52, "nl"=>80, "gb"=>123);

foreach(array_keys($values_by_country) as $current_iso_code)
{
        $world->select_country_with_gradient ($current_iso_code,
                                                $values_by_country[$current_iso_code],
                                                $gradient);
}

$auto_caption = $gradient->get_auto_caption ();
$auto_caption->set_text_color (255, 255, 255);

$world->set_caption ($auto_caption);

$world->render();


?>

Define a new one, using set_colors() as shown in the example below:

<?php

include "i_helio_world.php";

$world = new helio_world (200, 200);

$world->center_on_region (HELIO_WORLD_EUROPE, true);

$gradient = new helio_world_gradient ();

// Define a custom gradient:
// for values < 10 color is r=240, g=240, b=240
// for values < 60 color is r=210, g=210, b=210
// ...
// for values > 90 color is r=20, g=20, b=20
$gradient->set_colors (
                "10, 240, 240, 240,
                30, 210, 210, 210,
                60, 180, 180, 180,
                90, 50, 50, 50, 
                20, 20, 20"
                );

// Could also be retrive from a database for example
$values_by_country = array ("be"=>5, "fr"=>8, "de"=>35, "ch"=>45, "it"=>51,
                                "pt"=>70, "es"=>52, "nl"=>80, "gb"=>123);

foreach(array_keys($values_by_country) as $current_iso_code)
{
        $world->select_country_with_gradient ($current_iso_code,
                                                $values_by_country[$current_iso_code],
                                                $gradient);
}

$auto_caption = $gradient->get_auto_caption ();
$auto_caption->set_text_color (255, 255, 255);

$world->set_caption ($auto_caption);

$world->render();

?>

	The French Tutorial	HELIO World	Viaduc d'Auteuil	World Cup 1998
HELIO World home	Manual	Download