Georeference Map

Georeference API

Georeference a 3D map by tying its map-local coordinate frame to real-world WGS84 coordinates. You provide a set of control points, each pairing a map-local position (x, y, z in meters) with a known geographic location (latitude, longitude, altitude). The server solves the map's origin and heading from these pairs, so no compass heading is required.

The local (3D) coordinates must be in the map's left-handed (LHS / Unity) coordinate system, the same frame as the position field returned by a successful localization query (isRightHanded: false). If your data is in a right-handed system (e.g. ROS, Three.js), convert it to LHS before sending.

Once a map is georeferenced, you can use GPS-based localization features such as GeoHint and receive results in geographic coordinates. See Georeferencing Maps for the underlying concept.

Provide at least 3 control points. They must not all lie on the same vertical line (they cannot be horizontally coincident), otherwise the heading cannot be resolved. More well-distributed points improve accuracy. Use at least 6 decimal places for latitude and longitude to reach centimetre-level accuracy.

Georeference a map from control points

post

Georeferences a 3D map by fitting its map-local coordinate frame to real-world WGS84 coordinates using a set of control point pairs. Each control point ties a map-local position (x, y, z in meters) to a known geographic location (latitude, longitude, altitude). The origin and heading are solved from the point pairs, so no compass heading needs to be supplied. Requires at least 3 control points. Re-running overwrites the map's existing georeference.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

mapCodestringRequired

The public code of the map to georeference.

Example: MAP_RJFKKWQ1787J

Body

application/json

solveScalebooleanOptional

When true, also solve a uniform scale factor. Useful as a data-quality check: a correctly scaled metric scan should return a scale close to 1.0. The scale is reported only and is not applied at query time.

Default: falseExample: false

rejectOutliersbooleanOptional

When true (default), iteratively drop control points whose horizontal residual exceeds outlierThresholdMeters, then re-fit. Recommended, since real GPS surveys usually contain a few bad fixes. The fit will not drop below 3 points.

Default: trueExample: true

outlierThresholdMetersnumberOptional

Horizontal residual (in meters) above which a control point is rejected as an outlier. Only applies when rejectOutliers is true.

Default: 2.5Example: 2.5

Responses

200

Map georeferenced successfully

application/json

messagestringOptionalExample: Map geo-referenced successfully

mapIdstringOptional

Internal ID of the georeferenced map.

headingnumberOptional

Solved heading in degrees (0 to 360, clockwise from true north).

scalenumberOptional

Solved uniform scale factor (1.0 for a metric scan). Reported only; not applied at query time.

rmseMetersnumberOptional

3D root-mean-square residual across inlier control points.

horizontalRmseMetersnumberOptional

Horizontal-only RMSE across inliers. This is the reliable accuracy metric, since GPS altitude is noisy.

maxErrorMetersnumberOptional

Largest residual among the inlier control points.

numControlPointsintegerOptional

Total number of control points provided.

numInliersintegerOptional

Number of control points kept after outlier rejection.

inliersstring[]Optional

Names of the control points used in the final fit (null for unnamed points).

rejectedstring[]Optional

Names of the control points dropped as outliers (null for unnamed points).

400

Bad request (fewer than 3 control points, missing or invalid fields, or horizontally coincident points)

application/json

401

Unauthorized (missing or invalid token)

application/json

403

Forbidden (the map does not belong to the authenticated account)

application/json

404

Map not found

application/json

post/vps/map/{mapCode}/georeference

HTTPcURLJavaScriptPython

POST /v1/vps/map/{mapCode}/georeference HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 447

{
  "controlPoints": [
    {
      "name": "corner-A",
      "geo": {
        "latitude": 37.774912,
        "longitude": -122.419425,
        "altitude": 12
      },
      "local": {
        "x": 0,
        "y": 0,
        "z": 0
      }
    },
    {
      "name": "corner-B",
      "geo": {
        "latitude": 37.775012,
        "longitude": -122.419525,
        "altitude": 11.8
      },
      "local": {
        "x": 10.5,
        "y": 0,
        "z": -8.2
      }
    },
    {
      "name": "point-3",
      "geo": {
        "latitude": 37.774812,
        "longitude": -122.419225,
        "altitude": 12.3
      },
      "local": {
        "x": -5,
        "y": 1.2,
        "z": 12
      }
    }
  ],
  "solveScale": false,
  "rejectOutliers": true,
  "outlierThresholdMeters": 2.5
}

{
  "message": "Map geo-referenced successfully",
  "mapId": "67e12d4bff7ecf561f2f8a0c",
  "origin": {
    "latitude": 37.77491234,
    "longitude": -122.41942567,
    "altitude": 12.045
  },
  "heading": 37.5003,
  "scale": 1,
  "rmseMeters": 1.182,
  "horizontalRmseMeters": 0.587,
  "maxErrorMeters": 2.9,
  "numControlPoints": 4,
  "numInliers": 3,
  "inliers": [
    "corner-A",
    "corner-B",
    "point-3"
  ],
  "rejected": [
    "outlier-point"
  ],
  "tiltCheck": {
    "tiltAngleDeg": 0.0006,
    "tiltDirectionDeg": 66.9,
    "thresholdDeg": 1.5,
    "gravityAlignmentLikelyOk": true
  },
  "residuals": [
    {
      "name": "corner-A",
      "errorMeters": 1.15,
      "horizontalMeters": 0.53,
      "verticalMeters": 0.94,
      "isInlier": true
    }
  ]
}

Sample Request

{
    "controlPoints": [
        {
            "name": "corner-A",
            "geo": { "latitude": 37.774912, "longitude": -122.419425, "altitude": 12.0 },
            "local": { "x": 0, "y": 0, "z": 0 }
        },
        {
            "name": "corner-B",
            "geo": { "latitude": 37.775012, "longitude": -122.419525, "altitude": 11.8 },
            "local": { "x": 10.5, "y": 0, "z": -8.2 }
        },
        {
            "name": "point-3",
            "geo": { "latitude": 37.774812, "longitude": -122.419225, "altitude": 12.3 },
            "local": { "x": -5.0, "y": 1.2, "z": 12.0 }
        }
    ],
    "solveScale": false,
    "rejectOutliers": true,
    "outlierThresholdMeters": 2.5
}

Sample Response

{
    "message": "Map geo-referenced successfully",
    "mapId": "67e12d4bff7ecf561f2f8a0c",
    "origin": { "latitude": 37.77491234, "longitude": -122.41942567, "altitude": 12.045 },
    "heading": 37.5003,
    "scale": 1.0,
    "rmseMeters": 1.182,
    "horizontalRmseMeters": 0.587,
    "maxErrorMeters": 2.9,
    "numControlPoints": 4,
    "numInliers": 3,
    "inliers": ["corner-A", "corner-B", "point-3"],
    "rejected": ["outlier-point"],
    "tiltCheck": {
        "tiltAngleDeg": 0.0006,
        "tiltDirectionDeg": 66.9,
        "thresholdDeg": 1.5,
        "gravityAlignmentLikelyOk": true
    },
    "residuals": [
        {
            "name": "corner-A",
            "errorMeters": 1.15,
            "horizontalMeters": 0.53,
            "verticalMeters": 0.94,
            "isInlier": true
        }
    ]
}

Reading the Result

The response reports both the solved georeference and quality metrics so you can judge the fit:

• origin and heading are the solved values applied to the map. origin is the WGS84 location of map-local (0, 0, 0), and heading is degrees clockwise from true north.

• horizontalRmseMeters is the most reliable accuracy indicator. GPS altitude is noisy, so horizontal error is the number to watch.

• scale is reported only when solveScale is true and is not applied at query time. A metric scan should return a value close to 1.0; a value far from 1.0 suggests a scaling problem in the scan.

• inliers / rejected and residuals show which control points were used and how far each landed from the final fit, so you can spot and remove bad GPS readings.

• tiltCheck verifies that the solved up axis is close to true vertical, confirming the map is gravity aligned.

Georeferencing is idempotent: calling the endpoint again overwrites the map's existing georeference with the new solution.