SVN checkout 11/12/2010
[monav:monav.git] / plugins / osmimporter / protobuff definitions / osmformat.proto
1 package PBF;
2
3 /* OSM Binary file format 
4
5 This is the master schema file of the OSM binary file format. This
6 file is designed to support limited random-access and future
7 extendability.
8
9 A binary OSM file consists of a sequence of FileBlocks (please see
10 fileformat.proto). The first fileblock contains a serialized instance
11 of HeaderBlock, followed by a sequence of PrimitiveBlock blocks that
12 contain the primitives.
13
14 Each primitiveblock is designed to be independently parsable. It
15 contains a string table storing all strings in that block (keys and
16 values in tags, roles in relations, usernames, etc.) as well as
17 metadata containing the precision of coordinates or timestamps in that
18 block.
19
20 A primitiveblock contains a sequence of primitive groups, each
21 containing primitives of the same type (nodes, densenodes, ways,
22 relations). Coordinates are stored in signed 64-bit integers. Lat&lon
23 are measured in units <granularity> nanodegrees. The default of
24 granularity of 100 nanodegrees corresponds to about 1cm on the ground,
25 and a full lat or lon fits into 32 bits.
26
27 Converting an integer to a lattitude or longitude uses the formula:
28 $OUT = IN * granularity / 10**9$. Many encoding schemes use delta
29 coding when representing nodes and relations.
30
31 */
32
33 //////////////////////////////////////////////////////////////////////////
34 //////////////////////////////////////////////////////////////////////////
35
36 /* Contains the file header. */
37
38 message HeaderBlock {
39   optional HeaderBBox bbox = 1;
40   /* Additional tags to aid in parsing this dataset */
41   repeated string required_features = 4;
42   repeated string optional_features = 5;
43
44   optional string writingprogram = 16; 
45   optional string source = 17; // From the bbox field.
46 }
47
48
49 /** The bounding box field in the OSM header. BBOX, as used in the OSM
50 header. Units are always in nanodegrees -- they do not obey
51 granularity rules. */
52
53 message HeaderBBox {
54    required sint64 left = 1;
55    required sint64 right = 2;
56    required sint64 top = 3;
57    required sint64 bottom = 4;
58 }
59
60
61 ///////////////////////////////////////////////////////////////////////
62 ///////////////////////////////////////////////////////////////////////
63
64
65 message PrimitiveBlock {
66   required StringTable stringtable = 1;
67   repeated PrimitiveGroup primitivegroup = 2;
68
69   // Granularity, units of nanodegrees, used to store coordinates in this block
70   optional int32 granularity = 17 [default=100]; 
71   // Offset value between the output coordinates coordinates and the granularity grid in unites of nanodegrees.
72   optional int64 lat_offset = 19 [default=0];
73   optional int64 lon_offset = 20 [default=0]; 
74
75 // Granularity of dates, normally represented in units of milliseconds since the 1970 epoch.
76   optional int32 date_granularity = 18 [default=1000]; 
77
78
79   // Proposed extension:
80   //optional BBox bbox = 19;
81 }
82
83 // Group of OSMPrimitives. All primitives in a group must be the same type.
84 message PrimitiveGroup {
85   repeated Node     nodes = 1;
86   optional DenseNodes dense = 2;
87   repeated Way      ways = 3;
88   repeated Relation relations = 4;
89   repeated ChangeSet changesets = 5;
90 }
91
92
93 /** String table, contains the common strings in each block.
94
95  Note that we reserve index '0' as a delimiter, so the entry at that
96  index in the table is ALWAYS blank and unused.
97
98  */
99 message StringTable {
100    repeated bytes s = 1;
101 }
102
103 /* Optional metadata that may be included into each primitive. */
104 message Info {
105    optional int32 version = 1 [default = -1];
106    optional int64 timestamp = 2;
107    optional int64 changeset = 3;
108    optional int32 uid = 4;
109    optional int32 user_sid = 5; // String IDs
110 }
111
112 /** Optional metadata that may be included into each primitive. Special dense format used in DenseNodes. */
113 message DenseInfo {
114    repeated int32 version = 1 [packed = true]; 
115    repeated sint64 timestamp = 2 [packed = true]; // DELTA coded
116    repeated sint64 changeset = 3 [packed = true]; // DELTA coded
117    repeated sint32 uid = 4 [packed = true]; // DELTA coded
118    repeated sint32 user_sid = 5 [packed = true]; // String IDs for usernames. DELTA coded
119 }
120
121
122 // THIS IS STUB DESIGN FOR CHANGESETS. NOT USED RIGHT NOW.
123 // TODO:    REMOVE THIS?
124 message ChangeSet {
125    required int64 id = 1;
126 //   
127 //   // Parallel arrays.
128 //   repeated uint32 keys = 2 [packed = true]; // String IDs.
129 //   repeated uint32 vals = 3 [packed = true]; // String IDs.
130 //
131 //   optional Info info = 4;
132
133 //   optional int64 created_at = 8;
134 //   optional int64 closetime_delta = 9;
135 //   optional bool open = 10;
136 //   optional HeaderBBox bbox = 11;
137 }
138
139
140 message Node {
141    required sint64 id = 1;
142    // Parallel arrays.
143    repeated uint32 keys = 2 [packed = true]; // String IDs.
144    repeated uint32 vals = 3 [packed = true]; // String IDs.
145
146    optional Info info = 4; // May be omitted in omitmeta
147
148    required sint64 lat = 8;
149    required sint64 lon = 9;
150 }
151
152 /* Used to densly represent a sequence of nodes that do not have any tags.
153
154 We represent these nodes columnwise as five columns: ID's, lats, and
155 lons, all delta coded. When metadata is not omitted, 
156
157 We encode keys & vals for all nodes as a single array of integers
158 containing key-stringid and val-stringid, using a stringid of 0 as a
159 delimiter between nodes.
160
161    ( (<keyid> <valid>)* '0' )*
162  */
163
164 message DenseNodes {
165    repeated sint64 id = 1 [packed = true]; // DELTA coded
166
167    //repeated Info info = 4;
168    optional DenseInfo denseinfo = 5;
169
170    repeated sint64 lat = 8 [packed = true]; // DELTA coded
171    repeated sint64 lon = 9 [packed = true]; // DELTA coded
172
173    // Special packing of keys and vals into one array. May be empty if all nodes in this block are tagless.
174    repeated int32 keys_vals = 10 [packed = true]; 
175 }
176
177
178 message Way {
179    required int64 id = 1;
180    // Parallel arrays.
181    repeated uint32 keys = 2 [packed = true];
182    repeated uint32 vals = 3 [packed = true];
183
184    optional Info info = 4;
185
186    repeated sint64 refs = 8 [packed = true];  // DELTA coded
187 }
188
189 message Relation {
190   enum MemberType {
191     NODE = 0;
192     WAY = 1;
193     RELATION = 2;
194   } 
195    required int64 id = 1;
196
197    // Parallel arrays.
198    repeated uint32 keys = 2 [packed = true];
199    repeated uint32 vals = 3 [packed = true];
200
201    optional Info info = 4;
202
203    // Parallel arrays
204    repeated int32 roles_sid = 8 [packed = true];
205    repeated sint64 memids = 9 [packed = true]; // DELTA encoded
206    repeated MemberType types = 10 [packed = true];
207 }
208