[GRASS5] g3d notes

[John Harrop]

I've been doing some detailed code review and testing on the g3d related 
routines and library.  I've been using it with vis5d on some production 
work (real data in other words) and I've had to kludge my 3d import 
utility to reverse elevation and north values across the region of 
interest.  The result is that vis5d displays look correct (wrt the real 
world), but by site files are now inconsistent with my grid3 files as 
shown by nviz.  I've managed to isolate a number of inconsistencies - 
largely similar to what MN and HM have posted notes about, but with a 
few additions.  For example, the consistency of r3.in.ascii and 
r3.out.ascii results looks like it might be due to a double reversal, 
not correctness.  The fact that r3.out.v5d and r3.mk/showdspf result in 
consistent displays may also only be confirming the consistency of bugs 
in the two codes :-)

Before I make too many changes to (my local copy of) the code I wanted 
to get some clarification on what the design intentions were.  In one 
post HM stressed that consistency with 2D grass was very important 
indicating that at least among the development team there was a 
semi-formal understanding of requirements.  I have not been able to 
track that down in the src tree (I've read the notes in libes/g3d and 
GMSL/g3d) or in the archive.  Since some of this dates back to CERL days 
perhaps I should be asking if there was an Ops Order or at least a 
Warning Order!   ;-)

Looking at the source for G3d_getValue(map, x, y, z, value, type) and 
comparing it to G3d_putValue(map, x, y, z, value, type) is quite 
revealing.  When writing data, xyz seems to be mapped directly to 
respective indices to storage (no reordering for y or z).  When reading, 
the behaviour is quite different.  There are two stages to the mapping 
even though the intermediate values are not used.

x -> east -> col
y -> north -> row
z -> top -> depth

This means that:
- a low x value maps to a low east value (centre of cell) which maps to 
a low column value.  (Sounds good; W-E order)
- a low y value maps to a low north value (centre of cell) which maps to 
a low row value.  (Hmmm; S-N order)
- a low z value maps to a low top value (centre of cell) which maps to a 
low depth (!) value.  (Hmmm; B-T order even though variable is called 
DEPTH)

The result is xyz all map straight through (column = x, row = y, depth = 
z) without any reversals, just like in the write function.  (AV modified 
the code to remove reversal of y/North/row)  But what was the intent of 
this double mapping?  I wonder if the original intent of at least one 
developer was to have:

x, y, z names refer to a Cartesian indexing system (W-E, S-N, and B-T)
east, north, depth(?) refer to a physical (geographic) coordinate system 
(W-E, S-N, B-T(?) or was the idea to be depth rather than elevation 
oriented)
col, row, depth refer to a storage/display/maths indexing system (W-E, 
N-S and T-B) aka 2D grass compatible.


So if one is consistent with x,y,z usage in loops and calls then 
everything works out for g3d-ONLY routines.  But that also means x,y,z 
must be used in r,c,d form to maintain compatibility with 2D grass.  
Perhaps the meaning of x,y,z and col, row, depth should be standardized 
in 3D grass coding.  I suggest that for clarity x, y, z NOT be used 
interchangeably with col, row, depth.

That leads to the questions: What should the notation be in the get and 
putValue functions?  Should the mapping be straight through, and leave 
it up to the module coders to keep it consistent?  Would it help if the 
get and putValue functions existed in xyz and rcd forms?

I'd like to get this level clarified before I start further 
changing/fixing or writing new modules.

Regards,

John Harrop