Clarify 'extent` description

artemp commented 5 years ago

Current comment (which doubles up as a developer documentation) on extent field is lacking clarity and description. Consider current text evolution from v1.0.0 to v2.1

v1.0.0/1.0.1

// The bounding box in this tile spans from 0..4095 units
optional uint32 extent = 5 [ default = 4096 ];

v.2.0

// The bounding box in this tile spans from 0..4095 units
// Although this is an "optional" field it is required by the specification.
// See https://github.com/mapbox/vector-tile-spec/issues/47
optional uint32 extent = 5 [ default = 4096 ];

v2.1

// Although this is an "optional" field it is required by the specification.
// See https://github.com/mapbox/vector-tile-spec/issues/47
optional uint32 extent = 5 [ default = 4096 ];

Proposed clarification/add-on

// Positive number that denotes the size of a side of a square tile. 
// This in turn, defines unambiguously bounding box (extent) of a Vector Tile.
// Commonly used value is 4096, which is default but can be increased 
// to maintain higher coordinate precision. 
optional uint32 extent = 5 [ default = 4096 ];

Clarification of clarification :)

Positive number - number greater than zero.
It's optional by definition
...size of side of a square.. - we consider all VTs to be regular quadrilateral which leads to =>
This in turn, defines unambiguously bounding box (extent) - explaining connection between size (what this really is) and extent ( used to unambiguously define).
and finally ..can be increased to maintain higher coordinate precision indicates usage e.g why it might have a different value in some context (via @springmeyer )

Maybe someone can help to make it more concise :sos: /cc @springmeyer @kkaefer @flippmoke @ericfischer

ahocevar commented 5 years ago

It even seems to me that there is a breaking change between v2.0 and v2.1:

2.0:

A point at (0,10) or (4095,10) is within the extent of the tile. A point at (-1,10) or (4096,10) is outside the extent of the tile.

2.1:

A point at (1,10) or (4095,10) is within the extent of the tile. A point at (0,10) or (4096,10) is on the edge of the extent. A point at (-1,10) or (4097,10) is outside the extent of the tile.

Am I right to assume that an extent of 4096 previously meant values from 0 to 4095 inside or on the edge, and now means values from 0 to 4096 inside or on the edge?

flippmoke commented 5 years ago

@ahocevar It was more or less a bug in 2.0 as it was written. The existing encoder/decoders followed the behavior in 2.1 and it was just a mistake in the writing of 2.0, this is why it was not considered a breaking change honestly.

Overall, the language here needs to be definitely improved by the 3.0 specification though.

ahocevar commented 5 years ago

Thanks for the clarification @flippmoke.

mapbox / vector-tile-spec