Geometry-Bibliothek

  1. Übersicht
  2. Sphärische Geometriekonzepte
    1. Entfernungs- und Flächenfunktionen
    2. Navigationsfunktionen
  3. Geometriecodierung
  4. Polygon- und Polylinienfunktionen
    1. enthältStandort()
    2. isLocationOnEdge()

Übersicht

Die Konzepte in diesem Dokument beziehen sich auf Funktionen, die nur in der google.maps.geometry-Bibliothek verfügbar sind. Diese Bibliothek wird nicht standardmäßig geladen, wenn Sie die Maps JavaScript API laden. Sie muss explizit durch einen libraries-Bootstrap-Parameter angegeben werden. Weitere Informationen finden Sie unter Bibliotheken – Übersicht.

Die Maps JavaScript API-Geometriebibliothek bietet Dienstfunktionen für die Berechnung geometrischer Daten auf der Erdoberfläche. Die Bibliothek umfasst drei Namensräume:

  • spherical enthält sphärische Geometriefunktionen, mit denen Sie Winkel, Entfernungen und Flächen aus Breiten- und Längengraden berechnen können.
  • encoding enthält Dienstprogramme zum Codieren und Decodieren von Polylinienpfaden gemäß dem Algorithmus für codierte Polylinien.
  • poly enthält Dienstfunktionen für Berechnungen zu Polygonen und Polylinien.

Die Bibliothek google.maps.geometry enthält keine Klassen. Sie enthält stattdessen statische Methoden für die oben genannten Namespaces.

Konzepte der sphärischen Geometrie

Die Bilder in der Maps JavaScript API sind zweidimensional und flach. Die Erde ist jedoch dreidimensional und wird oft entweder als abgeflachtes Sphäroid oder eher als Kugel dargestellt. In der Google Maps API wird eine Kugel verwendet. Damit die Erde auf einer zweidimensionalen flachen Oberfläche wie einem Computerbildschirm dargestellt wird, verwendet die Google Maps API eine Projektion.

Bei 2D-Projektionen kann das Erscheinungsbild gelegentlich trügerisch sein. Da die Kartenprojektion zwangsläufig eine gewisse Verzerrung erfordert, ist eine einfache euklidische Geometrie oft nicht anwendbar. Die kürzeste Entfernung zwischen zwei Punkten auf einer Kugel ist keine gerade Linie, sondern ein großer Kreis (eine Art von Geodäte) und die Winkel, die ein Dreieck auf der Oberfläche einer Kugel bilden, ergeben mehr als 180 Grad.

Aufgrund dieser Unterschiede erfordern die geometrischen Funktionen für eine Kugel (oder für ihre Projektion) die Verwendung von sphärischer Geometrie zur Berechnung von Konstrukten wie Entfernung, Richtung und Fläche. Der Namespace google.maps.geometry.spherical der Maps API enthält Dienstprogramme zur Berechnung dieser sphärischen geometrischen Konstrukte. Dieser Namespace bietet statische Methoden zur Berechnung von skalaren Werten aus sphärischen Koordinaten (Breiten- und Längengraden).

Entfernungs- und Bereichsfunktionen

Die Entfernung zwischen zwei Punkten ist die Länge des kürzesten Pfads zwischen ihnen. Der kürzeste Pfad wird als geodätische Linie bezeichnet. Auf einer Kugel sind alle Geodäten Segmente eines Großkreises. Um diese Entfernung zu berechnen, rufen Sie computeDistanceBetween() auf und übergeben Sie zwei LatLng-Objekte.

Sie können stattdessen auch computeLength() verwenden, um die Länge eines bestimmten Pfads zu berechnen, wenn Sie mehrere Standorte haben.

Entfernungsergebnisse werden in Metern ausgedrückt.

Um die Fläche einer Polygonfläche in Quadratmetern zu berechnen, rufen Sie computeArea() auf und übergeben Sie das Array von LatLng-Objekten, die eine geschlossene Schleife definieren.

Bei der Navigation auf einer Kugel ist eine Richtung der Winkel einer Richtung von einem festen Referenzpunkt aus, in der Regel im geografischen Norden. In der Google Maps API wird eine Richtung in Grad vom geografischen Norden definiert, wobei Richtungen im Uhrzeigersinn vom geografischen Norden aus gemessen (0 Grad) gemessen werden. Sie können die Richtung zwischen zwei Standorten mit der Methode computeHeading() berechnen und dafür die beiden Objekte from und to LatLng übergeben.

Mit einer bestimmten Richtung, einem Ausgangsort und der zurückzulegenden Entfernung in Metern können Sie die Zielkoordinaten mit computeOffset() berechnen.

Bei zwei LatLng-Objekten und Werten zwischen 0 und 1 können Sie mithilfe der Methode interpolate() ein Ziel zwischen ihnen berechnen. Diese Methode führt eine sphärische lineare Interpolation zwischen den beiden Standorten durch, wobei der Wert die Teilentfernung angibt, die vom Ausgangs- zum Zielort auf dem Pfad zurückgelegt werden muss.

Im folgenden Beispiel werden zwei Polylinien erstellt, wenn Sie auf zwei Punkte auf der Karte klicken – eine geodätische und eine gerade Linie, die die beiden Standorte verbindet –, und die Richtung für die Reise zwischen den beiden Punkten wird berechnet:

TypeScript

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

let marker1: google.maps.Marker, marker2: google.maps.Marker;
let poly: google.maps.Polyline, geodesicPoly: google.maps.Polyline;

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: 34, lng: -40.605 },
    }
  );

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
    document.getElementById("info") as HTMLElement
  );

  marker1 = new google.maps.Marker({
    map,
    draggable: true,
    position: { lat: 40.714, lng: -74.006 },
  });

  marker2 = new google.maps.Marker({
    map,
    draggable: true,
    position: { lat: 48.857, lng: 2.352 },
  });

  const bounds = new google.maps.LatLngBounds(
    marker1.getPosition() as google.maps.LatLng,
    marker2.getPosition() as google.maps.LatLng
  );

  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, "position_changed", update);
  google.maps.event.addListener(marker2, "position_changed", update);

  poly = new google.maps.Polyline({
    strokeColor: "#FF0000",
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: "#CC0099",
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map,
  });

  update();
}

function update() {
  const path = [
    marker1.getPosition() as google.maps.LatLng,
    marker2.getPosition() as google.maps.LatLng,
  ];

  poly.setPath(path);
  geodesicPoly.setPath(path);

  const heading = google.maps.geometry.spherical.computeHeading(
    path[0],
    path[1]
  );

  (document.getElementById("heading") as HTMLInputElement).value =
    String(heading);
  (document.getElementById("origin") as HTMLInputElement).value = String(
    path[0]
  );
  (document.getElementById("destination") as HTMLInputElement).value = String(
    path[1]
  );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">
let marker1, marker2;
let poly, geodesicPoly;

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: 34, lng: -40.605 },
  });

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
    document.getElementById("info")
  );
  marker1 = new google.maps.Marker({
    map,
    draggable: true,
    position: { lat: 40.714, lng: -74.006 },
  });
  marker2 = new google.maps.Marker({
    map,
    draggable: true,
    position: { lat: 48.857, lng: 2.352 },
  });

  const bounds = new google.maps.LatLngBounds(
    marker1.getPosition(),
    marker2.getPosition()
  );

  map.fitBounds(bounds);
  google.maps.event.addListener(marker1, "position_changed", update);
  google.maps.event.addListener(marker2, "position_changed", update);
  poly = new google.maps.Polyline({
    strokeColor: "#FF0000",
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });
  geodesicPoly = new google.maps.Polyline({
    strokeColor: "#CC0099",
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map,
  });
  update();
}

function update() {
  const path = [marker1.getPosition(), marker2.getPosition()];

  poly.setPath(path);
  geodesicPoly.setPath(path);

  const heading = google.maps.geometry.spherical.computeHeading(
    path[0],
    path[1]
  );

  document.getElementById("heading").value = String(heading);
  document.getElementById("origin").value = String(path[0]);
  document.getElementById("destination").value = String(path[1]);
}

window.initMap = initMap;
Beispiel ansehen

Beispiel ausprobieren

Codierungsmethoden

Pfade in der Maps JavaScript API werden oft als Array von LatLng-Objekten angegeben. Die Übergabe eines solchen Arrays ist jedoch häufig sperrig. Sie können stattdessen den Polycodierungs-Algorithmus von Google verwenden, um einen bestimmten Pfad zu komprimieren, den Sie später durch Decodierung wieder dekomprimieren können.

Die Bibliothek geometry enthält einen encoding-Namespace für Dienstprogramme zur Codierung und Decodierung von Polylinien.

Die statische Methode encodePath() codiert den angegebenen Pfad. Du kannst entweder ein Array von LatLngs oder ein MVCArray (das von Polyline.getPath() zurückgegeben wird) übergeben.

Um einen codierten Pfad zu decodieren, rufen Sie decodePath() auf und übergeben Sie die Methode an den codierten String.

Im nachfolgenden Beispiel ist eine Karte von Oxford, Mississippi dargestellt: Per Mausklick auf die Karte wird ein Punkt zu einer Polylinie hinzugefügt. Die Polylinie wird beim Erstellen der Polylinie darunter angezeigt.

TypeScript

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 14,
      center: { lat: 34.366, lng: -89.519 },
    }
  );
  const poly = new google.maps.Polyline({
    strokeColor: "#000000",
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map,
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, "click", (event) => {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(
  latLng: google.maps.LatLng,
  poly: google.maps.Polyline
) {
  const path = poly.getPath();

  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  const encodeString = google.maps.geometry.encoding.encodePath(path);

  if (encodeString) {
    (document.getElementById("encoded-polyline") as HTMLInputElement).value =
      encodeString;
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 14,
    center: { lat: 34.366, lng: -89.519 },
  });
  const poly = new google.maps.Polyline({
    strokeColor: "#000000",
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map,
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, "click", (event) => {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  const path = poly.getPath();

  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  const encodeString = google.maps.geometry.encoding.encodePath(path);

  if (encodeString) {
    document.getElementById("encoded-polyline").value = encodeString;
  }
}

window.initMap = initMap;
Beispiel ansehen

Beispiel ausprobieren

Polygon- und Polylinienfunktionen

Der poly-Namespace der Geometriebibliothek enthält Dienstfunktionen, die bestimmen, ob ein bestimmter Punkt innerhalb oder in der Nähe eines Polygons oder einer Polylinie liegt.

containsLocation()

containsLocation(point:LatLng, polygon:Polygon)

Um herauszufinden, ob ein bestimmter Punkt in ein Polygon fällt, übergeben Sie den Punkt und das Polygon an google.maps.geometry.poly.containsLocation(). Die Funktion gibt „true“ zurück, wenn sich der Punkt innerhalb des Polygons oder auf seinem Rand befindet.

Wenn der Nutzer in das definierte Dreieck fällt, wird mit dem folgenden Code & in die Browserkonsole geschrieben; ansonsten wird 'false' geschrieben.

function initialize() {
  var mapOptions = {
    zoom: 5,
    center: new google.maps.LatLng(24.886, -70.269),
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var bermudaTriangle = new google.maps.Polygon({
    paths: [
      new google.maps.LatLng(25.774, -80.190),
      new google.maps.LatLng(18.466, -66.118),
      new google.maps.LatLng(32.321, -64.757)
    ]
  });

  google.maps.event.addListener(map, 'click', function(event) {
    console.log(google.maps.geometry.poly.containsLocation(event.latLng, bermudaTriangle));
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

Eine andere Version dieses Codes zeichnet ein blaues Dreieck auf der Karte, wenn der Klick in das Bermudadreieck fällt, ansonsten einen roten Kreis:

Beispiel ansehen

isLocationOnEdge()

isLocationOnEdge(point:LatLng, poly:Polygon|Polyline, tolerance?:number)

Um festzustellen, ob ein Punkt auf oder in der Nähe einer Polylinie oder auf oder nahe dem Rand eines Polygons liegt, übergeben Sie den Punkt, die Polylinie/das Polygon und optional einen Toleranzwert in Grad an google.maps.geometry.poly.isLocationOnEdge(). Die Funktion gibt „true“ zurück, wenn die Entfernung zwischen dem Punkt und dem nächstgelegenen Punkt auf der Linie oder dem Rand innerhalb der angegebenen Toleranz liegt. Der Standardwert für die Toleranz beträgt 10–9 Grad.

function initialize() {
  var myPosition = new google.maps.LatLng(46.0, -125.9);

  var mapOptions = {
    zoom: 5,
    center: myPosition,
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var cascadiaFault = new google.maps.Polyline({
    path: [
      new google.maps.LatLng(49.95, -128.1),
      new google.maps.LatLng(46.26, -126.3),
      new google.maps.LatLng(40.3, -125.4)
    ]
  });

  cascadiaFault.setMap(map);

  if (google.maps.geometry.poly.isLocationOnEdge(myPosition, cascadiaFault, 10e-1)) {
    alert("Relocate!");
  }
}

google.maps.event.addDomListener(window, 'load', initialize);