Datums and precision#

A coordinate only means something together with its datum — the reference used to measure the Earth. The same spot of a farm has different coordinates in each datum Brazil has used: Córrego Alegre, then SAD69, and SIRGAS 2000 since 2005. Between SAD69 and SIRGAS 2000 the difference reaches about 65 m.

shapelib’s rule is simple: coordinates are transformed with the best accuracy known, or not at all. A transformation that would silently move the data by metres is refused with a DatumTransformationError (a ValueError) that says why.

Brazil’s legacy datums#

Data in SAD69, SAD69(96), Córrego Alegre 1961 and Córrego Alegre 1970-72 is supported. These datums are converted with IBGE’s official correction grids, which ship with shapelib and work offline:

from shapelib import read_file

rows = read_file("rows_sad69.shp")   # SAD69 / UTM zone 23S
rows.to_utm()                        # SIRGAS 2000 / UTM 23S, via the IBGE grid

Without the grids (pyproj ships none), the same conversion would fall back to a formula — up to ~7.5 m off for SAD69 — or, for Córrego Alegre 1961, to no datum shift at all (~50 m off).

Even with the official grid, data in a legacy datum cannot be more accurate than the legacy survey itself. Such data is flagged when read, and a warning is logged:

rows.legacy_datum            # True
rows.datum_shift_accuracy    # 2.0 — metres, as published by EPSG

The accuracy depends on where the data lies: with the grid, SAD69 is accurate to 2 m (1 m to SIRGAS 2000); west of the grid’s coverage (Acre, Rondônia, western Amazonas) the best shift known is a 5 m formula. Data in modern datums (WGS 84, SIRGAS 2000) is not flagged.

What is refused#

  • A datum the file does not declare. A .prj that names only an ellipsoid — Esri’s GCS_GRS_1980 (EPSG:4019, “Not a valid datum”) is a common case — gives no defined way to place the data. shapelib does not guess: confirm the datum with whoever produced the data and declare it in the file.

  • A datum whose grid is not installed — e.g. NAD27 in the USA.

  • A datum shift outside its area of use. When no transformation between two datums is defined where the data lies, PROJ would still apply one defined elsewhere (Mexico’s NAD27 shift to a point in São Paulo, say), producing meaningless coordinates. This is also how a wrongly declared datum is caught — data in Brazil labelled NAD27 or ED50, or Córrego Alegre data in Pará, where that datum was never used.

A refused transformation leaves the data unchanged.

Note

A file with no CRS at all (no .prj) whose coordinates are all lon/lat is still taken as WGS 84 — see Reading & saving.

Note

PROJ treats SIRGAS 2000 and WGS 84 as identical (no shift). Physically, a point on the ground has moved about 34 cm since SIRGAS 2000’s reference epoch (2000.4), with the South American plate; whether that matters depends on how the surveys and the machines are referenced.