grid convergence should be computed for all georeferenced data

[Eric C. Landgraf]

Currently, grid convergence is calculated only when *declination auto is set (with a representative coordinate). For normal people dealing with normal data, this is fine.

However, if any survey has *declination set to a fixed value, this is treated as the difference between Magnetic north and North in the output coordinate system (i.e. grid north).

IF input and output coordinates systems are set, we should *always* compute grid convergence, as that is an expected (and potentially impactful) difference.

[Olly Betts]

Most of this we've now covered in chat, but summarising so it's all together somewhere less ephemeral:

IF input and output coordinates systems are set, we should *always* compute grid convergence, as that is an expected (and potentially impactful) difference.

We need a location to compute convergence at, so it's not possible to always compute it for current datasets because *declination 3.1 doesn't specify a location (nor does the total absence of a *declination command being in force for some/all survey data).

Therion calculates convergence (and declination) at the average of all fixed point locations, but I really don't like that approach as it means the convergence (and declination) values all change each time you add a fixed point (albeit probably not by very much), and also if you have a lot of fixed points off in one direction that will skew the location used towards that side of the survey. The other benefit of requiring a location to be specified is that multiple locations can be specified for different areas of a large cave system. Really the only thing going for Therion's approach is that the user doesn't need to concern themselves with where the location is (but that also means they can't even if they want to).

Doing something automatic based on fixed points in Survex would also mean we'd then have two different ways of determining the location to compute convergence at, which seems an unnecessary complication for users to have to understand.

It would also be much harder than you might expect to implement in cavern because we compute an x,y,z vector for each leg as we read it which requires the convergence value which requires knowing where all the fixed points are but we may not have seen all (or indeed any) of them yet - to use the average of fixed points or even to reliably use a/some fixed points, we'd need to read the data twice, or buffer up all the read data.

I think we need to extend *declination to allow a location with an explicit value, not just with auto, e.g.:

*declination 3.1 36670.37        83317.43        1903.97

Then we issue a warning for *declination 3.1 saying we need a location to compute convergence (in the case where we have coordinate systems specified).

It's possible that some people are specifying explicit *declination values which include convergence currently, though probably unlikely as we do explicitly document *declination as the magnetic/true difference, not magnetic/grid. I tend to think we probably shouldn't support that and should just recommend that anyone currently doing that should remove the convergence from the explicit value (or just move to using auto which is already recommended by the manual).

Perhaps we can allow inheritance of location, so this works:

*declination auto  36670.37        83317.43        1903.97

; ...

*begin
*declination 3.1 ; uses the location already in effect

; ...
*end

If we do, perhaps the location should be omittable for auto too, so you can switch back to auto explicitly (and for consistency between auto and explicit variants).

We could perhaps also allow just setting the location:

*declination - 36670.37        83317.43        1903.97

This would allow setting a location in one place for explicit declinations in each survey to inherit, but without having that one place needing to use either auto or an explicit declination value which would end up being a default. Then we could warn about data processed without a declination value.

[Eric C. Landgraf]

I think "inheriting" the *declination auto location by default is a reasonable and "expected" behaviour. allowing nil (different from 0°) declinations seems worrysome, but may be moot in practice. My guess is most survex users who *care* about grid convergence and declination shifts over an area do set local *declination auto statements with centerpoints.

One thing missing in your example: *declination 3.1 degrees is the format (and we do error when there are no units). There is also a potential for *calibrate declination -3.1 degrees: grid convergence should still be applied in that case, as well (although it need not allow a location).

Since grid convergence depends both on location and output projection, I wonder if it would be semantically cleaner to set grid convergence centerpoint using e.g. *cs out epsg:1234 <x> <y> <z>. But handling it as part of declination is not inappropriate, and the coordinate system needs to be set for *declination auto to work, regardless.

[Olly Betts]

allowing nil (different from 0°) declinations seems worrysome

I'm unclear why this is a worry - did you miss the "Then we could warn about data processed without a declination value" part?

One thing missing in your example: *declination 3.1 degrees is the format (and we do error when there are no units).

Oh yes, should have the units of course.

*calibrate declination -3.1 degrees

That's handled by the same mechanism as *declination so should just work. It's not been the recommended way to specify declination since 2015 so definitely no need to try to extend it to support a location.

*cs out epsg:1234 <x> <y> <z>

There's some logic to that, but it seems a feature few users will actually care enough to use and nobody has actually even asked for. Also we'd also need to come up with rules for precedence (given most existing data we be relying on the documented use of the declination location for calculating convergence we need to still support that) which is then more complexity to have to explain to users (and to implement and write tests for). Overall I think it makes more sense to stick with the scheme of calculating them at the same location (I'll also note that this is forced by therion's approach, and you don't even get direct control of the location used with therion).

[Olly Betts]

allowing nil (different from 0°) declinations seems worrysome

I'm unclear why this is a worry - did you miss the "Then we could warn about data processed without a declination value" part?

Rather than thinking about this as "nil" (which seems to be a term you've invented rather than one I've used to refer to this anywhere) perhaps it's more helpful to think of it as "implicit 0" vs "explicit 0". In fact this is really already the case - if you don't set a declination then 0 is used, but you can also set the declination to zero explicitly - these have the same effect but are really different cases. We don't currently distinguish between them, but it would probably be useful to warn if that "implicit 0" is actually used somewhere because that's probably a bug in the data.