A Class to do global to local conversion and some global calculations. More...

Public Member Functions
	__construct ($Database, $Host, $Username, $Password)
	Open the Support Database for Use.
	GlobalToLocal ($GlobalArray)
	LocalToGlobal ($LocalArray)
	Convert a local regional location into a global location.
	CourseFromTo ($FromLocalArray, $ToLocalArray)
	Find the course and distance from one point to another using local coordinates.
	FromCourseTo ($FromLocalArray, $CourseArray)
	Routine to Calculate a Destination from an origin and a Course.
	__construct ($Database, $Host, $Username, $Password)
	GlobalToLocal ($GlobalArray)
	LocalToGlobal ($LocalArray)
	CourseFromTo ($FromLocalArray, $ToLocalArray)
	FromCourseTo ($FromLocalArray, $CourseArray)
	RegionBoundsGlobal ($RegionName)
	Find the Bottom Left Corner and Top Right Corners in Global Coordinates.
	AddGlobal ($FromGlobal, $DeltaGlobal)
	DeltaGlobal ($FromGlobal, $ToGlobal)
	RegionToDeltaLocal ($FromLocal, $ToLocal)
	DeltaLocalToLocal ($DeltaLocal)
	Convert a region based Location using global delta off to local coordinates.

Public Attributes
	$Database
	The name of the Database.
	$Host
	The Host running the Database.
	$Username
	The Username to access the Database.
	$Password
	The password to access the Database.

Detailed Description

A Class to do global to local conversion and some global calculations.

This class uses the Region Table to convert between global and local units for the Open Simulator.

It can also be used to calculate positions using distance and bearing information that spans across any number of regions in the simulator by using global measurements.

Definition at line 32 of file os_global_calcs.php.

Constructor & Destructor Documentation

◆ __construct() [1/2]

OS_GLOBAL_CALCS::__construct	(	$Database,
		$Host,
		$Username,
		$Password )

Open the Support Database for Use.

Parameters

$Database	The Name of the Database to Open
$Host	The name of the computer use to conenct to the Database
$Username	The username to access the Database
$Password	The password to access the database.

If this routine fails, it will case the program to abort because it is assumed that not being able to convert between coordinate system will be fatal.

Definition at line 71 of file os_global_calcs.php.

    {
        global $pdo;
        
        // Data Source Name (DSN) string
        $dsn = "mysql:host=$Host;dbname=$Database;charset=utf8mb4";
 
        // Set PDO options for better error handling and security
        $options = [
                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION, // Throw exceptions on errors
                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,       // Set default fetch mode to associative array
                PDO::ATTR_EMULATE_PREPARES   => true,                  // Disable emulated prepares for better security
               ];
               
        try
        {
            // Create a new PDO connection instance
            $pdo = new PDO($dsn, $Username, $Password, $options);    
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $Database, $Host, $Password, $pdo, and $Username.

◆ __construct() [2/2]

OS_GLOBAL_CALCS::__construct	(	$Database,
		$Host,
		$Username,
		$Password )

Definition at line 71 of file os_global_calcs_dev.php.

    {
        global $pdo;
        
        // Data Source Name (DSN) string
        $dsn = "mysql:host=$Host;dbname=$Database;charset=utf8mb4";
 
        // Set PDO options for better error handling and security
        $options = [
                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION, // Throw exceptions on errors
                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,       // Set default fetch mode to associative array
                PDO::ATTR_EMULATE_PREPARES   => true,                  // Disable emulated prepares for better security
               ];
               
        try
        {
            // Create a new PDO connection instance
            $pdo = new PDO($dsn, $Username, $Password, $options);    
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $Database, $Host, $Password, $pdo, and $Username.

Member Function Documentation

◆ AddGlobal()

OS_GLOBAL_CALCS::AddGlobal	(		$FromGlobal,
			$DeltaGlobal )

Definition at line 363 of file os_global_calcs_dev.php.

     {
        $result['global_x'] = $ToGlobal['global_x'] + $DeltaGlobal['global_x'];
        $result['global_y'] = $ToGlobal['global_y'] + $DeltaGlobal['global_y'];
        $result['global_z'] = $ToGlobal['global_z'] + $DeltaGlobal['global_z'];
        return $result;
    }     

References $result.

◆ CourseFromTo() [1/2]

OS_GLOBAL_CALCS::CourseFromTo	(		$FromLocalArray,
			$ToLocalArray )

Find the course and distance from one point to another using local coordinates.

Parameters

$FromLocalArray	The region position of the origin point
$ToLocalArray	The region position of the desired destination point

Returns: A course array holding the distance in metres, the bearing in radians and the elevation angle in radians

This routine will convert origin & destination into global coordinates, then calculate the delta-X, delta-Y and delta-Z measurements. From those measurements, it first calculates the ground range and the height change. From that the actal distance between the two points is calculated. Then the ground bearing from the Origin to Destination is calculated and finally the elevation angle from the source to the destination is calculated.

If you desire the ground range to be returned, rather the point to point distance, set the Z value to the same value for the source and destination.

See the GlobalToLocal($GlobalArray) documentation for an explanation of the formats of the $GlobalArray and the $LocalArray. The format of the $CourseArray is as follows:

distance The 3D distance between the source and origin. That is, the height difference is included in the calculation.
bearing The ground bearing from the source to the origin locations in radians.
elevation The elevation angle from the source to the destination in radians.

Definition at line 230 of file os_global_calcs.php.

    {
        $FromGlobal = self::LocalToGlobal($FromLocalArray); $ToGlobal = self::LocalToGlobal($ToLocalArray);
        $delta_global['global_x'] = $ToGlobal['global_x'] - $FromGlobal['global_x'];
        $delta_global['global_y'] = $ToGlobal['global_y'] - $FromGlobal['global_y'];
        $delta_global['global_z'] = $ToGlobal['global_z'] - $FromGlobal['global_z'];
        $ground_distance = sqrt($delta_global['global_x'] ** 2.0 + $delta_global['global_y'] ** 2.0);
        $result['distance'] = sqrt($ground_distance ** 2.0 + $delta_global['global_z'] ** 2);
        $result['bearing']  = atan2($delta_global['global_x'], $delta_global['global_y']);
        $result['elevation'] = atan2($delta_global['global_z'], $ground_distance) ;
        return $result;
    }

References $result, and LocalToGlobal().

Here is the call graph for this function:

◆ CourseFromTo() [2/2]

OS_GLOBAL_CALCS::CourseFromTo	(		$FromLocalArray,
			$ToLocalArray )

Definition at line 230 of file os_global_calcs_dev.php.

    {
        $FromGlobal = self::LocalToGlobal($FromLocalArray); $ToGlobal = self::LocalToGlobal($ToLocalArray);
        $delta_global['global_x'] = $ToGlobal['global_x'] - $FromGlobal['global_x'];
        $delta_global['global_y'] = $ToGlobal['global_y'] - $FromGlobal['global_y'];
        $delta_global['global_z'] = $ToGlobal['global_z'] - $FromGlobal['global_z'];
        $ground_distance = sqrt($delta_global['global_x'] ** 2.0 + $delta_global['global_y'] ** 2.0);
        $result['distance'] = sqrt($ground_distance ** 2.0 + $delta_global['global_z'] ** 2);
        $result['bearing']  = atan2($delta_global['global_x'], $delta_global['global_y']);
        $result['elevation'] = atan2($delta_global['global_z'], $ground_distance) ;
        return $result;
    }

References $result, and LocalToGlobal().

Here is the call graph for this function:

◆ DeltaGlobal()

OS_GLOBAL_CALCS::DeltaGlobal	(		$FromGlobal,
			$ToGlobal )

Definition at line 380 of file os_global_calcs_dev.php.

     {
        $result['global_x'] = $ToGlobal['global_x'] - $FromGlobal['global_x'];
        $result['global_y'] = $ToGlobal['global_y'] - $FromGlobal['global_y'];
        $result['global_z'] = $ToGlobal['global_z'] - $FromGlobal['global_z'];
        return $result;
    }     

References $result.

Referenced by RegionToDeltaLocal().

Here is the caller graph for this function:

◆ DeltaLocalToLocal()

OS_GLOBAL_CALCS::DeltaLocalToLocal ( $DeltaLocal )

Convert a region based Location using global delta off to local coordinates.

$DeltaLocal The Local Format coordinates with locations that can extend outside of the Region

Returns: Standard local coordinates where the position is located inside the Tegion's boundaries

This routine converters the position based on the bottom left corner of the region into true global coordinates and then converts them bacl to local coordinates where hte position is locatied within the limits of the named region.

Definition at line 422 of file os_global_calcs_dev.php.

     {
        $region_boundaries = self::RegionBoundsGlobal($DeltaLocal['region_name']);
        $location_global['global_x'] = $DeltaLocal['global_x'] + $region_boundaries['global_left'];
        $location_global['global_y'] = $DeltaLocal['global_y'] + $region_boundaries['global_bottom'];
        $location_global['global_z'] = $DeltaLocal['global_z'] + $region_boundaries['global_low'];
        $local_array = self::GlobalToLocal($location_global);
        return $local_array;
     }

References GlobalToLocal(), and RegionBoundsGlobal().

Here is the call graph for this function:

◆ FromCourseTo() [1/2]

OS_GLOBAL_CALCS::FromCourseTo	(		$FromLocalArray,
			$CourseArray )

Routine to Calculate a Destination from an origin and a Course.

Parameters

$FromLocalArray	An array holding the local position of the Origin Point
$CourseArray	An array holding the information about the Course to follow

Returns: Destination point in local position format

This routine takes an origin location in local coordinates, converts it into global coordinates, changes the location based on the course data, and then converts it back into local coordinates.

NOTE If the destination is not contained within a defined region in the simulation, the result returned will have an empty string as the regions name and the XYZ coordinates will be -1 which also indicates that an error has occured.

Definition at line 259 of file os_global_calcs.php.

    {
        $FromGlobal = self::LocalToGlobal($FromLocalArray);
        $total_distance = $CourseArray['distance'];
        $elevation_angle = $CourseArray['elevation'];
        $bearing_angle = $CourseArray['bearing'];
        
        $ground_distance = $total_distance * cos($elevation_angle);
        $delta_z         = $total_distance * sin($elevation_angle);
        
        $delta_x = $ground_distance * sin($bearing_angle);
        $delta_y = $ground_distance * cos($bearing_angle);
        
        $GlobalArray['global_x'] = $FromGlobal['global_x'] + $delta_x;
        $GlobalArray['global_y'] = $FromGlobal['global_y'] + $delta_y;
        $GlobalArray['global_z'] = $FromGlobal['global_z'] + $delta_z;
        
        return self::GlobalToLocal($GlobalArray);
    }

References GlobalToLocal(), and LocalToGlobal().

Here is the call graph for this function:

◆ FromCourseTo() [2/2]

OS_GLOBAL_CALCS::FromCourseTo	(		$FromLocalArray,
			$CourseArray )

Definition at line 259 of file os_global_calcs_dev.php.

    {
        $FromGlobal = self::LocalToGlobal($FromLocalArray);
        $total_distance = $CourseArray['distance'];
        $elevation_angle = $CourseArray['elevation'];
        $bearing_angle = $CourseArray['bearing'];
        
        $ground_distance = $total_distance * cos($elevation_angle);
        $delta_z         = $total_distance * sin($elevation_angle);
        
        $delta_x = $ground_distance * sin($bearing_angle);
        $delta_y = $ground_distance * cos($bearing_angle);
        
        $GlobalArray['global_x'] = $FromGlobal['global_x'] + $delta_x;
        $GlobalArray['global_y'] = $FromGlobal['global_y'] + $delta_y;
        $GlobalArray['global_z'] = $FromGlobal['global_z'] + $delta_z;
        
        return self::GlobalToLocal($GlobalArray);
    }

References GlobalToLocal(), and LocalToGlobal().

Here is the call graph for this function:

◆ GlobalToLocal() [1/2]

OS_GLOBAL_CALCS::GlobalToLocal ( $GlobalArray )

Parameters

$GlobalArray

Returns: Array holding the Localation using the Region name and Local Coordinates

The $GlobalArray that is passed to this routines is formatted so that it can be used without change the SQL Query used to convert the global location parameters into the local address. The Global Array has the following keys:

global_x => The X position in global coordinates (metres)

global_y => The Y position in global coordinates (metres)

global_z => The Z position in global coordinates - same as local coordinates (metres)

The $LocalArray that is return is also in a format that can directly be used in subsequent SQL statements and has the following format

region_name => The text name of the Region

local_x => The in-region X coordinates

local_y => The in-region Y coordinates

local_z => The in-region Z coordinates

If the Global location cannot be transformed into a set of Regional coordinates, the routine returns a Local Array where the Region name is blank and the local coordinates are set to -1 since negative number wuold never appear in a real location.

The conversion from global to local coordinates can be done with a single SQL query as the edge of the region has already been calulated in global measurements, making the calculations simple comparisons and subtractions.

Definition at line 130 of file os_global_calcs.php.

    {
        global $pdo;
        $sql_query = " select lor_name  as region_name, :global_x - lor_edge_left as local_x, :global_y - lor_edge_lower as local_y, :global_z as local_z from ls_os_region ";
        $sql_query .= " where :global_x >= lor_edge_left and :global_x <= lor_edge_right and :global_y >= lor_edge_lower  and :global_y <= lor_edge_upper ";
        
        try
        {
            $stmt = $pdo->prepare($sql_query);
            $stmt->execute($GlobalArray);
            $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
 
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            if ($results)
            {
                return $results[0];
            }
            
            // If the Code gets here, then the global location is outside of the known world.
            else
            {
                $result['region_name'] = ""; // Flag no known Region
                $result['local_x'] = -1.0;   // Flag bad X reading
                $result['local_y'] = -1.0;   // Flag bad Y reading
                $result['local_z'] = -1.0;   // Flag bad Z reading
                return $result;
            }
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $pdo, and $result.

Referenced by DeltaLocalToLocal(), and FromCourseTo().

Here is the caller graph for this function:

◆ GlobalToLocal() [2/2]

OS_GLOBAL_CALCS::GlobalToLocal ( $GlobalArray )

Definition at line 130 of file os_global_calcs_dev.php.

    {
        global $pdo;
        $sql_query = " select lor_name  as region_name, :global_x - lor_edge_left as local_x, :global_y - lor_edge_lower as local_y, :global_z as local_z from ls_os_region ";
        $sql_query .= " where :global_x >= lor_edge_left and :global_x <= lor_edge_right and :global_y >= lor_edge_lower  and :global_y <= lor_edge_upper ";
        
        try
        {
            $stmt = $pdo->prepare($sql_query);
            $stmt->execute($GlobalArray);
            $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
 
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            if ($results)
            {
                return $results[0];
            }
            
            // If the Code gets here, then the global location is outside of the known world.
            else
            {
                $result['region_name'] = ""; // Flag no known Region
                $result['local_x'] = -1.0;   // Flag bad X reading
                $result['local_y'] = -1.0;   // Flag bad Y reading
                $result['local_z'] = -1.0;   // Flag bad Z reading
                return $result;
            }
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $pdo, and $result.

◆ LocalToGlobal() [1/2]

OS_GLOBAL_CALCS::LocalToGlobal ( $LocalArray )

Convert a local regional location into a global location.

See the GlobalToLocal($GlobalArray) documentation for an explanation of the formats of the $GlobalArray and the $LocalArray

As can be seen the conversion is carried out by a single line SQL because the region table has the edge of the regions precalculated and add that is needed in simple additions and one comparison to find the regions's information.

Definition at line 179 of file os_global_calcs.php.

    {
        global $pdo;
        
        $sql_query = "select lor_edge_left + :local_x as global_x, lor_edge_lower + :local_y as global_y, :local_z as global_z  from ls_os_region where lor_name = :region_name";
        
        try
        {
            $stmt = $pdo->prepare($sql_query);
            $stmt->execute($LocalArray);
            $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
 
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            if ($results)
            {
                return $results[0];
            }
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $pdo.

Referenced by CourseFromTo(), FromCourseTo(), and RegionToDeltaLocal().

Here is the caller graph for this function:

◆ LocalToGlobal() [2/2]

OS_GLOBAL_CALCS::LocalToGlobal ( $LocalArray )

Definition at line 179 of file os_global_calcs_dev.php.

    {
        global $pdo;
        
        $sql_query = "select lor_edge_left + :local_x as global_x, lor_edge_lower + :local_y as global_y, :local_z as global_z  from ls_os_region where lor_name = :region_name";
        
        try
        {
            $stmt = $pdo->prepare($sql_query);
            $stmt->execute($LocalArray);
            $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
 
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            if ($results)
            {
                return $results[0];
            }
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $pdo.

◆ RegionBoundsGlobal()

OS_GLOBAL_CALCS::RegionBoundsGlobal ( $RegionName )

Find the Bottom Left Corner and Top Right Corners in Global Coordinates.

Parameters

$RegionName The name of the requested Region

Returns: Global position of Bottom Left and Top Right corners in Global Units

This function return the global ccorsinates of the bootom Left and upper right Corners of the requested Region. If the region is found, only the x and y coordinates are are used, and the low_global coordinate is set to 0 to indicate success.

If the query fails, the high_global coordinate are set to -1 to indicate that the query failed.

The results are returned in the following format:

region_name The region name being queries

global_left The Left X coordinate in global coordinates.

global_bottom The Bottom Y coordinate in global coordinates.

global_right The Right X coordinate in global coodinates.

global_top The Top Y coordinate in global coordinates

global_low The lowest altitude in global coordinates.

global_high The higest altitude in global coordinates.

Definition at line 309 of file os_global_calcs_dev.php.

     {
        global $pdo;
        
        $sql_query  = "select :region_name as region_name, ";
        $sql_query .= "lor_edge_left as global_left,   lor_edge_lower as global_bottom, 0 as global_low, ";
        $sql_query .= "lor_edge_right as global_right, lor_edge_upper as global_top,    lor_size_z as global_high ";
        $sql_query .= "from ls_os_region where lor_name = :region_name";
        
        try
        {
            $stmt = $pdo->prepare($sql_query);
            $stmt->execute(['region_name' => $RegionName]);
            $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
 
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            if ($results)
            {
                return $results[0];
            }
            else
            {
                $result['region_name'] = "";
                $result['global_left'] = -1;
                $result['global_bottom'] = -1;
                $result['global_right'] = -1;
                $result['global_top'] = -1;
                $result['global_low'] = -1;
                $result['global_high'] = -1;
                return $result;
            }   
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
    }

References $pdo, and $result.

Referenced by DeltaLocalToLocal().

Here is the caller graph for this function:

◆ RegionToDeltaLocal()

OS_GLOBAL_CALCS::RegionToDeltaLocal	(		$FromLocal,
			$ToLocal )

Parameters

$FromLocal	The Origin point using local Coordinates
$ToLocal	The Destination Point in Local Coordinates

Returns: Local coordinates from the region's left bottom to the destination

This routine converts the Destination ($ToLocal) into global coordinates and get the difference from the Origin point of the Starting region ($FromLocal). These coordinates can be used by by the osTeleportObject() routine to teleport the object to another region.

NOTE: If the $toLocal is outside of the $FromLocal region, the result will use the $FromLocal region and the location will contain at least one value larger than the size of the region.

Definition at line 402 of file os_global_calcs_dev.php.

     {
        // Set the Local Position to the start of the Region
        $FromLocal['local_x'] = 0; $FromLocal['local_y'] = 0; $FromLocal['local_z'] = 0;
        $from_global = self::LocalToGlobal($FromLocal); $to_global = self::LocalToGlobal($ToLocal);
        $delta_global = self::DeltaGlobal($from_global, $to_global);
        $delta_global['region_name'] = $FromLocal['region_name'];
        return $delta_global;
     }

References $FromLocal, $ToLocal, DeltaGlobal(), and LocalToGlobal().

Here is the call graph for this function:

Member Data Documentation

◆ $Database

OS_GLOBAL_CALCS::$Database

The name of the Database.

Definition at line 40 of file os_global_calcs.php.

Referenced by __construct().

◆ $Host

OS_GLOBAL_CALCS::$Host

The Host running the Database.

Definition at line 46 of file os_global_calcs.php.

Referenced by __construct().

◆ $Password

OS_GLOBAL_CALCS::$Password

The password to access the Database.

Definition at line 58 of file os_global_calcs.php.

Referenced by __construct().

◆ $Username

OS_GLOBAL_CALCS::$Username

The Username to access the Database.

Definition at line 52 of file os_global_calcs.php.

Referenced by __construct().

The documentation for this class was generated from the following files:

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct() [1/2]

◆ __construct() [2/2]

Member Function Documentation

◆ AddGlobal()

◆ CourseFromTo() [1/2]

◆ CourseFromTo() [2/2]

◆ DeltaGlobal()

◆ DeltaLocalToLocal()

◆ FromCourseTo() [1/2]

◆ FromCourseTo() [2/2]

◆ GlobalToLocal() [1/2]

◆ GlobalToLocal() [2/2]

◆ LocalToGlobal() [1/2]

◆ LocalToGlobal() [2/2]

◆ RegionBoundsGlobal()

◆ RegionToDeltaLocal()

Member Data Documentation

◆ $Database

◆ $Host

◆ $Password

◆ $Username