Section 3.1 - Software Description

There are two php programs associated with this project so far. The first script load_region_table.php loads the Regions.ini file into a database table. Thie table is used to change between the region based location system and the global location system. In the versions of Open Simulator being run on this site, teh REgions table in teh opensim database is empty and none of the region names are visible in the tables.

Section 3.2 - Required Support Programs

This program runs using the Qt environment primarilty on Windows or Linux.

To run this system, the following programs must also be installed on the system running the program "os_global_calcs":
(1) Open Simulator Virtual World Platform (or access to such a system).
(2) MariaDB (or MySQL) database.
(3) PHP General Purpose Scripting language for web development.

Section 3.3 - Creating the Region Table ls_os_region

-- ls_os_support.ls_os_region definition
 
CREATE TABLE `ls_os_region` (
  `lor_index` int(10) unsigned NOT NULL AUTO_INCREMENT COMMENT 'Index Field',
  `lor_name` varchar(128) NOT NULL COMMENT 'The name ofthe Region',
  `lor_location_x` bigint(20) unsigned NOT NULL COMMENT 'Edge Corner X Location',
  `lor_location_y` bigint(20) unsigned NOT NULL COMMENT 'Edge Corner Y Location',
  `lor_size_x` int(10) unsigned NOT NULL COMMENT 'Size of the region in the X direction',
  `lor_size_y` int(10) unsigned NOT NULL COMMENT 'Size of the region in the Y direction',
  `lor_size_z` int(10) unsigned NOT NULL COMMENT 'Size of the region in the Z direction',
  `lor_uuid` varchar(36) DEFAULT NULL COMMENT 'UUID of the Region',
  `lor_map_uuid` varchar(36) NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000' COMMENT 'UUID of the Region Static Map',
  `lor_edge_upper` bigint(20) unsigned DEFAULT NULL COMMENT 'Upper Edge of the Region (Global Coordinates)',
  `lor_edge_lower` bigint(20) unsigned DEFAULT NULL COMMENT 'Lower Edge of the Region (Global Coordinates)',
  `lor_edge_left` bigint(20) unsigned DEFAULT NULL COMMENT 'Left Edge of the Region (Global Coordinates)',
  `lor_edge_right` bigint(20) unsigned DEFAULT NULL COMMENT 'Right Edge of the Region (Global Coordinates)',
  PRIMARY KEY (`lor_index`),
  UNIQUE KEY `ls_os_region_unique` (`lor_name`)
) ENGINE=InnoDB AUTO_INCREMENT=32 DEFAULT CHARSET=latin1 COLLATE=latin1_swedish_ci;

The region table needs to be created in a database that will be available for read access by the php scripts that can hold the class that handles the local to global and abck conversions.

Section 3.4 - OS Script load_region_table.php

This script is used to fill the ls_os_region table with the information from the OpenSim REgions.ini file. This program only needs to be run initially and is then only needed if the configuration of the regions is altered. It should be noted that in the current configuration of opensim, it's Regions table is empty and the names of the regions are not held in any of the opensim table. It is beleived that this information may become available via the opensim developers so this setup may have a limited lifespan.

NOTE: The php script that loads the regions table has next to no error management, since it is assumed that the input file will be one that allows opensim to load up correctly. The source code will need to be altered to point to the correct Regions.ini file to read. As per the other scripts, even though this script is not run via the webserver, the database name, the host, as well as the username and password are stored in a file that is not available to the web server. It should also be noted the username must have write access to the table to allow the information to be inserted into the database table. For a Linux based system, the script can by going into the directory holding the script and running "<I>php load_region_table.php</I>".

Section 3.4 - OS Script os_global_calcs.php

This script is not really a standalone script for use in open simulator, rather it provides a PHP class that uses the ls_os_region table to do conversions back and forth between global coordinates and local coordinates. It also provides function calculate distance, bearing and elevation between any two points in the simulator. It can also calculate a new postion anywhere in the simulator based on an origin, the distance, bearing and elevation.

The progam will calculate global positions that are out of the bounds of the simulator without flagging an error, but if a region address is attempted for such a location, it will return with a blank region name and the xYZ coordinates set to -1 which is also an error condition as the values should be greater than or equal to 0.