Coordinate systems in Hyz tools

Why it matters¶

Every vector layer is drawn in a coordinate system: a rule that turns the numbers in the file into places on the Earth. The same pair of numbers means a street corner in Riyadh in one system and a point in the Atlantic in another. A tool that guesses the system gives a confident wrong answer, so Hyz tools do not guess: they read the system the file declares, ask when it declares none, and tell you which one the result is in.

The systems Saudi work uses¶

The picker opens on these; a few letters or a number search the whole EPSG registry.

System	Code	Use it for
WGS 84	EPSG:4326	Longitude and latitude in degrees. What GPS, GeoJSON, KML and web maps use.
KSA-GRF17	EPSG:9333	The Saudi national reference frame, in degrees.
KSA-GRF17 / UTM zone 36N–40N	EPSG:9356–EPSG:9360	The national frame in metres. The zone depends on longitude — see below.
WGS 84 / UTM zone 36N–40N	EPSG:32636–EPSG:32640	Metres on WGS 84. Common in engineering and survey files.
Ain el Abd / UTM zone 36N–39N	EPSG:20436–EPSG:20439	Older Saudi mapping. Converting it to a modern system shifts positions by a datum change.
WGS 84 / Pseudo-Mercator	EPSG:3857	What web maps draw in. Not for measuring.

Which UTM zone¶

A UTM zone is six degrees of longitude wide. The Kingdom crosses five:

Zone	Longitude	Roughly
36N	30°E – 36°E	The far north-west: Tabuk's coast, Haql
37N	36°E – 42°E	The west: Jeddah, Makkah, Madinah, Tabuk, Abha
38N	42°E – 48°E	The centre: Riyadh, Qassim, Hail, Najran
39N	48°E – 54°E	The east: Dammam, Al-Ahsa, Jubail
40N	54°E – 60°E	The far south-east of the Empty Quarter

A layer that crosses a zone edge is still one layer. Keep it in one zone's system if it was made that way, or in degrees.

A file that does not say its system¶

Some files carry no coordinate system at all — most often a shapefile whose .prj was left out of the archive. A tool cannot know what the numbers mean, so it stops and asks:

• On a tool's page, Coordinate system of the file appears and the run tells you to choose it.
• Through the API, the run answers 422 with meta.engineCode CRS_REQUIRED and, in meta.details, the file's bounds and whether they look like degrees. Send the run again with source_crs.

source_crs only fills a gap. A file that declares its own system is read in that system whatever you send.

The result's system¶

A result comes back in the input's own coordinate system. Send UTM zone 38N, get UTM zone 38N.

• To get another, choose Coordinate system of the result, or send output_crs through the API.
• GeoJSON, KML and KMZ are always WGS 84. Their own standards fix it, so the choice is not offered for those formats and output_crs is ignored for them.
• A tool with two layers — a clip boundary, a join layer — answers in the system of the first one, the layer being worked on.

Every vector result says which system it is in and why (crs, and crsReason: input, requested or format), and names the transformation that was applied when the two systems differ.

How tools measure¶

A tool does not measure in whatever system the file happens to be in.

• Area, length, perimeter, distance and bearing are measured on the ellipsoid — the true shape of the Earth. The answer does not depend on a projection, at any latitude, for a layer of any size.
• A buffer, a centroid or a spacing needs a flat plane, so each feature is worked in a plane chosen for it: its own UTM zone, or a projection centred on the feature when it is wider than a zone. A 10 km buffer is 10 km in Tabuk and in the Empty Quarter alike.

So a distance you give in metres is metres on the ground, whichever system the file is in.

Converting between datums¶

Systems on the same datum convert exactly. Systems on different datums — Ain el Abd to WGS 84 or KSA-GRF17, for example — convert through a published transformation with a stated accuracy — from about a metre to several metres, depending on the transformation. A run that changes datum records the transformation it used and its accuracy, so you can say later how a file was produced.