Protocol Documentation

Table of Contents

CompressedInlinePoints

CompressedInlinePoints stores a short inline ring segment as polyline bytes.

CompressedPolygon

CompressedRingSegment

CompressedRingSegment mirrors RingSegment with polyline-encoded inline points.

CompressedSharedEdge

CompressedSharedEdge stores a shared boundary edge with its point sequence

polyline-encoded (delta + zigzag, same algorithm as CompressedPolygon).

CompressedTimezone

CompressedTimezonesItem designed for binary file as small as possible.

CompressedTimezones

CompressedTopoPolygon

CompressedTopoPolygon mirrors TopoPolygon with compressed ring segments.

CompressedTopoTimezone

CompressedTopoTimezone mirrors TopoTimezone with compressed polygons.

CompressedTopoTimezones

CompressedTopoTimezones combines shared-edge deduplication with polyline

coordinate compression. Shared edge point sequences and inline segments are

stored as polyline bytes instead of repeated Point messages, significantly

reducing file size on top of the deduplication savings.

grid_index is an optional embedded 1°×1° candidate-reduction index built

at compress time. When present, Finder uses it to skip full linear scans.

GridIndex

GridIndex is the complete 1°×1° candidate-reduction index.

Only cells with at least one intersecting timezone are stored.

GridIndexCell

GridIndexCell records the timezone indices that intersect a single 1°×1° cell.

tz_indices are 0-based positions into the timezones array of the companion

CompressedTopoTimezones (or Timezones) file, matching the order used by Finder.items.

InlinePoints

Wrapper for a sequence of inline points used inside a RingSegment oneof.

(proto3 does not allow repeated fields directly in a oneof.)

Point

Basic point data define.

Polygon

Define a polygon, mostly based on GeoJSON's Polygon define.

Excerpt from RFC-9476 section 'Polygon'

- A linear ring is a closed LineString with four or more positions.

- The first and last positions are equivalent, and they MUST contain

identical values; their representation SHOULD also be identical.

- A linear ring is the boundary of a surface or the boundary of a

hole in a surface.

- A linear ring MUST follow the right-hand rule with respect to the

area it bounds, i.e., exterior rings are counterclockwise, and

holes are clockwise.

Note: the [GJ2008] specification did not discuss linear ring winding

order. For backwards compatibility, parsers SHOULD NOT reject

Polygons that do not follow the right-hand rule.

Though a linear ring is not explicitly represented as a GeoJSON

geometry type, it leads to a canonical formulation of the Polygon

geometry type definition as follows:

- For type "Polygon", the "coordinates" member MUST be an array of

linear ring coordinate arrays.

- For Polygons with more than one of these rings, the first MUST be

the exterior ring, and any others MUST be interior rings. The

exterior ring bounds the surface, and the interior rings (if

present) bound holes within the surface.

[GJ2008]: https://geojson.org/geojson-spec

PreindexTimezone

PreindexTimezone tile item.

The X/Y/Z are OSM style like map tile index values.

PreindexTimezones

PreindexTimezones is all preindex timezone's dumps.

RingSegment

A ring segment: either inline points or a reference to a shared edge.

Shared edges are stored once in TopoTimezones.shared_edges and referenced

by their index; edge_reversed references the same edge but traversed in

the opposite direction.

SharedEdge

A shared boundary edge stored once in the global edge library.

Rings reference it by index (forward or reversed) instead of repeating

the point sequence.

Timezone

Timezone is a timezone's all data.

Timezones

TopoPolygon

A timezone polygon in topology format.

The exterior ring is represented as an ordered sequence of segments.

Holes are nested TopoPolygons.

TopoTimezone

A timezone in topology format.

TopoTimezones

Timezones in topology format with shared-edge deduplication.

Shared timezone boundaries are stored exactly once in shared_edges;

rings reference them by ID rather than duplicating the point sequences.

This format targets full-precision data where ~43% of boundary edges are

shared, reducing the 96 MB full dataset by ~30–35 MB.

CompressMethod

Scalar Value Types