Introduction

Our Geo Coordinates lets you map a Matterport 3D model to real-world locations using latitude, longitude, and altitude. This is useful for aligning your model with Geo Coordinates data, especially in outdoor or large-scale environments.

How it works

Matterport uses a special point inside the model called the GeoAnchor Point. This point is usually the centroid of the model, chosen by our vision pipeline (Note: Centroid is different from the origin 0, 0, 0).

The API provides a translation value that shows how far the GeoAnchor Point is from the origin. If you want to align the GeoAnchor Point with the origin, set translation to { x: 0, y: 0, z: 0 }.

What you can do

With the GeoCoordinates API, you can:

  • Get the Geo Coordinates of a model.
  • Convert a point in the model to Geo Coordinates.
  • Convert Geo Coordinates to a point in the model.
  • Patch or reset the GeoAnchor Point for a model.

Sample Queries

Get the Geo Coordinates (GeoAnchor Point) of a model 
query getGeoCoordinates($modelId: ID!) {
  model(id: $modelId) {
    id
    geocoordinates {
        ... GeoCoordinateFragment
    }
  }
}

fragment GeoCoordinateFragment on GeoCoordinate {
  source
  altitude
  latitude
  longitude
  translation { x y z }
  rotation { x y z w }
}

Variable Arguments:

{
  "modelId": "[YOUR MODEL ID]"
}

Sample Response:

{
  "data": {
    "model": {
      "id": "DpFVgQXVTmD",
      "geocoordinates": {
        "source": "processing",
        "altitude": 0,
        "latitude": 33.276006298034105,
        "longitude": -96.80354127176122,
        "translation": {
          "x": 0.3076627708815243,
          "y": 3.3566522639732987,
          "z": 0
        },
        "rotation": {
          "x": 0,
          "y": 0,
          "z": -0.3681099881862502,
          "w": 0.929782252249159
        }
      }
    }
  }
}

Try this query in our interactive console

Convert a point in the model to Geo Coordinates

Sample Query:

query getGeoCoordinatesOf($modelId: ID!, $point: IPoint3D!) {
  model(id: $modelId) {
    id
    geocoordinates {
      GeoCoordinatesOf(modelLocation: $point) {
          lat
          long
      }
    }
  }
}

Variable Arguments:

{
  "modelId": "[YOUR MODEL ID]]",
  "point": {
    "x": 3.11,
    "y": 3.14,
    "z": 5.4
  }
}

Sample Response:

{
  "data": {
    "model": {
      "id": "[YOUR MODEL ID]]",
      "geocoordinates": {
        "GeoCoordinatesOf": {
          "lat": "33.27603743078501",
          "long": "-96.8034845051858"
        }
      }
    }
  }
}

Try this query in our interactive console

Convert Geo Coordinates to a point in the model

Sample Query:

query getModelLocationOf($modelId: ID!, $lat: Float!, $lon: Float!) {
  model(id: $modelId) {
    id
    geocoordinates {
      modelLocationOf(
          latitude: $lat,
          longitude: $lon,
      ) { x y z }
    }
  }
}

Variable Arguments:

{
  "modelId": "[YOUR MODEL ID]",
  "lat": 33.27603743078501,
  "lon": -96.8034845051858
}

Sample Response:

{
  "data": {
    "model": {
      "id": "[YOUR MODEL ID]",
      "geocoordinates": {
        "modelLocationOf": {
          "x": 3.5507595647023336,
          "y": 3.4784207745132183,
          "z": -0.0000031264498829841614
        }
      }
    }
  }
}

Try this query in our interactive console

Sample Mutations

Patch the GeoAnchor Point for a model

Sample Query:

mutation patchGeoCoordinates(
    $modelId: ID!
    $altitude: Float
    $latitude: Float
    $longitude: Float
    $translation: IPoint3D
    $rotation: IQuaternion
) {
    patchModelGeoCoordinates(
      id: $modelId,
      altitude: $altitude,
      latitude: $latitude,
      longitude: $longitude,
      translation: $translation,
      rotation: $rotation
    ) {
        ... GeoCoordinateFragment
    }
}
fragment GeoCoordinateFragment on GeoCoordinate {
  source
  altitude
  latitude
  longitude
  translation { x y z }
  rotation { x y z w }
}

Variable Arguments:

{
  "modelId": "",
  "altitude": 0,
  "latitude": 0,
  "longitude": 0,
  "translation": { "x": 0, "y": 0, "z": 0 },
  "rotation": { "x": 0, "y": 0, "z": 0, "w": 0 }
}

Try this query in our interactive console

Reset the GeoAnchor Point for a model.

Sample Mutation:


mutation resetGeoCoordinates(
    $modelId: ID!
) {    
    resetModelGeoCoordinates(id: $modelId) {
        ... GeoCoordinateFragment
    }
}

fragment GeoCoordinateFragment on GeoCoordinate {
  source
  altitude
  latitude
  longitude
  translation { x y z }
  rotation { x y z w }
}

Variable Arguments:

{
  "modelId": ""
}

Try this query in our interactive console