#Line

A line consists of two points, i.e. instances of the Coordinate class.

#Length

The Line class provides a method to calculate its own length. The method expects an instance of a class which implements the DistanceInterface.

<?php

use Location\Coordinate;
use Location\Distance\Haversine;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$length = $line->getLength(new Haversine());

printf("The line has a length of %.3f meters\n", $length);

Haversine is one of the currently two available classes for distance calculation. The other one is named Vincenty.

The code above will produce the output below:

The line has a length of 13013.849 meters

#Midpoint

The midpoint of a line is calculated by following the Great Circle (defined by the two endpoints) and dividing the line into two halves.

<?php

declare(strict_types=1);

use Location\Coordinate;
use Location\Distance\Haversine;
use Location\Line;

$line = new Line(
    new Coordinate(35, 45),
    new Coordinate(35, 135)
);

$midpoint = $line->getMidpoint();

printf(
    'The midpoint of the line is located at %.3f degrees latitude and %.3f degrees longitude.%s',
    $midpoint->getLat(),
    $midpoint->getLng(),
    PHP_EOL
);

printf(
    'Its distance from the first point is %.1f meters, its distance from the second point is %.1f meters.%s',
    $line->getPoint1()->getDistance($midpoint, new Haversine()),
    $line->getPoint2()->getDistance($midpoint, new Haversine()),
    PHP_EOL
);

The code above produces the output below:

The midpoint of the line is located at 44.719 degrees latitude and 90.000 degrees longitude.
Its distance from the first point is 3935890.0 meters, its distance from the second point is 3935890.0 meters.

#Intermediate Point

Similar to the midpoint calculation but divides the line at the given fraction (between 0.0 … 1.0; but values outside that range work as well).

<?php

declare(strict_types=1);

use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalMinutes;
use Location\Line;

$line = new Line(
    new Coordinate(0, 0),
    new Coordinate(1, 1)
);

$result = $line->getIntermediatePoint(0.25);

printf(
    'The first quarter of the line ends at %s%s',
    $result->format(new DecimalMinutes(' ')),
    PHP_EOL
);

The code above produces the output below:

The first quarter of the line ends at 00° 15.001′ 000° 14.999′

#Bearing

The bearing of an instance can be calculated using the getBearing() method. An instance of BearingInterface must be provided as method argument.

<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$bearing = $line->getBearing(new BearingEllipsoidal());

printf("The line has a bearing of %.2f degrees\n", $bearing);

BearingEllipsoidal is one of the currently two available classes for bearing calculation. The other one is named BearingSpherical.

The code above will produce the output below:

The line has a bearing of 328.67 degrees

This is the so-called initial bearing. There exist another bearing angle, called the final bearing. It can be calculated as well:

<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$bearing = $line->getFinalBearing(new BearingEllipsoidal());

printf("The line has a final bearing of %.2f degrees\n", $bearing);

The code above will produce the output below:

The line has a final bearing of 328.59 degrees

See Bearing between two points @TODO Link for more information about bearings.