Ground control points (GCPs) are landmarks with known geospatial positions, marked in one or more images. They are the most accurate way to georeference a reconstruction and to set its output coordinate system. GCPs complement — or replace — the GPS positions read from image EXIF.
OpenSfM uses GCPs in two steps, both of which require a point to be observed in at least two reconstructed images (the point's position is triangulated from its image rays; a point seen in fewer than two reconstructed shots is ignored):
- Alignment: globally rotates, translates and scales the reconstruction so the triangulated GCPs match their survey positions.
- Bundle adjustment: adds each GCP as a position prior plus per-observation reprojection constraints, refining the reconstruction.
Each point also carries a role:
gcp(default) — used in both alignment and bundle adjustment.checkpoint— excluded from optimization and used only to measure accuracy; checkpoint residuals are reported separately in the quality report.
Key config parameters: bundle_use_gcp, gcp_horizontal_sd, gcp_vertical_sd, gcp_global_weight, gcp_annealing_steps, gcp_reprojection_error_threshold. See the configuration reference. Per-point standard deviations (see below) override gcp_horizontal_sd / gcp_vertical_sd for that point.
GCPs can be supplied in two interchangeable formats — ground_control_points.json or gcp_list.txt — placed at the dataset root. Use convert_gcp to convert between them (it backs up the target file as .bak first).
Add a file named ground_control_points.json at the dataset root:
{
"crs": "WGS84",
"points": [
{
"id": "gcp_id",
"role": "gcp",
"position": {
"latitude": 52.519,
"longitude": 13.400,
"altitude": 14.946,
"latitude_std": 0.02,
"longitude_std": 0.02,
"altitude_std": 0.05
},
"observations": [
{
"shot_id": "image.jpg",
"projection": [0.1, -0.2]
}
]
}
]
}Fields:
crs(optional, defaultWGS84) — coordinate reference system of the point positions. AcceptsWGS84,EPSG:xxxx, a compound EPSG (e.g.EPSG:2056+5773for an explicit vertical datum), or a raw+proj=…string. A projectedcrsalso sets the reconstruction's output coordinate system.id— identifier of the point; observations sharing anidbelong to the same physical landmark.role(optional, defaultgcp) —gcporcheckpoint(see above).position— either geographiclatitude/longitude(degrees) or projectedeasting/northing(incrsunits, transformed internally to WGS84).altitudeis optional (the point is treated as horizontal-only when omitted). The optionallatitude_std/longitude_std/altitude_stdare positional standard deviations in metres — all three must be present to take effect, and they override the globalgcp_horizontal_sd/gcp_vertical_sdfor this point.observations— list of{shot_id, projection}.projectionis in normalized image coordinates.
A
coordinatesarray (topocentric[x, y, z]) may also appear on a point. It is written by the pipeline and is not needed in hand-authored files.
Add a file named gcp_list.txt at the dataset root:
-
First line: the CRS / projection string.
-
Following lines: one observation per line —
<geo_x> <geo_y> <geo_z> <im_x> <im_y> <image_name> [<gcp_id>]<im_x> <im_y>are pixel coordinates (not normalized).<geo_z>may beNaNwhen the altitude is unknown.<gcp_id>(optional) names the point: lines sharing the same name are grouped into one GCP. When omitted, observations are grouped by identical 3-D position and the point is auto-namedunnamed-N.
#comments and blank lines are ignored. The TXT format carries neither roles nor per-point standard deviations — use the JSON format for those.
Supported CRS strings (same set for the JSON crs and the TXT header line):
WGS84:geo_x = longitude,geo_y = latitude,geo_z = altitudeWGS84 UTM 32N(or any UTM zone):geo_x = easting,geo_y = northing,geo_z = altitude- Any valid proj4 string, e.g.
+proj=utm +zone=32 +north +ellps=WGS84 +datum=WGS84 +units=m +no_defs
Example gcp_list.txt (two points, two observations each):
WGS84
13.400740745 52.519134104 12.0792090446 2335.0 1416.7 01.jpg corner_A
13.400740745 52.519134104 12.0792090446 2639.1 938.0 02.jpg corner_A
13.400502446 52.519251158 16.7021233002 766.0 1133.1 01.jpg corner_B
13.400502446 52.519251158 16.7021233002 1090.2 1499.0 02.jpg corner_B