From d5d93f96098b73f3f870a0dfaba4b0c610b12a93 Mon Sep 17 00:00:00 2001 From: Scott Crosby Date: Wed, 1 Sep 2010 15:22:39 -0500 Subject: [PATCH] Clean up protocolbuffer definitions and document them. --- src/fileformat.proto | 31 +------------------------ src/osmformat.proto | 54 ++++++++++++++++---------------------------- 2 files changed, 21 insertions(+), 64 deletions(-) diff --git a/src/fileformat.proto b/src/fileformat.proto index d6e3a2e..73e7d79 100644 --- a/src/fileformat.proto +++ b/src/fileformat.proto @@ -9,45 +9,16 @@ option java_package = "crosby.binary"; message Blob { optional bytes raw = 1; // No compression optional int32 raw_size = 2; // When compressed, the uncompressed size + // Possible compressed versions of the data. optional bytes zlib_data = 3; optional bytes lzma_data = 4; optional bytes bzip2_data = 5; } - -/* Future message to store an index of all of the fileblocks in a -file. Always stored at the end of the file with its offset given in -the FileHeader message. (If the FileDirectory message is not the last -block, assume that we have concatenated files, and the next message is -a file header.) */ - - -message FileDirectory { -} - - -/* First block in a file. */ -message FileHeaderBlock { - required fixed32 version = 1; // Future expansion - file format version number. - required fixed32 unused1 = 2; // Future expansion - required fixed64 unused2 =3; // Relative offset to filedirectory. -} - - -/* Author program for a file */ -message AuthorBlock { - required string fullname = 1; // Full name of the program (name, build number, build date, etc) - optional string shortname = 2; // Short name. - optional int64 version = 3; // Version numbers, hopefully comparable with > -} - - /* A file contains an sequence of fileblock headers, each prefixed by their length, followed by a data block containing the actual data. types staring with a "_" are reserved. -The "_FileHeader" block is customarily written first. -The "_Author" block identifies the writer and written second. */ message BlockHeader { diff --git a/src/osmformat.proto b/src/osmformat.proto index 52b0337..b0cf577 100644 --- a/src/osmformat.proto +++ b/src/osmformat.proto @@ -48,32 +48,14 @@ message HeaderBlock { optional string writingprogram = 19; // TODO: WANT THIS? /* Additional tags to aid in parsing this dataset */ - repeated string required_features = 4; // TODO: WANT THIS? - repeated string optional_features = 5; // TODO: WANT THIS? + repeated string required_features = 4; + repeated string optional_features = 5; } -/* - -Required features are features that an implementation must -understand in order to be able to parse the OSM entities in the -file. If a program sees a required feature that it does not -understand, it must error out. Currently the following features are -defined: - - "DenseNodes" -- File uses dense nodes. - - -Optional features are features that a file has that a program may -exploit if it chooses to. - - "Has_Metadata" -- Does the file contain author and timestamp metadata? - "Sort.Type_then_ID" -- Entites are sorted by type then ID. - "Sort.Geographic" -- Entities are in some form of geometric sort. - -*/ /** The bounding box field in the OSM header. BBOX, as used in the OSM -header. Units are in nanodegrees. */ +header. Units are always in nanodegrees -- they do not obey +granularity rules. */ message HeaderBBox { required sint64 left = 1; @@ -117,8 +99,8 @@ message PrimitiveGroup { /** String table, contains the common strings in each block. - Note that we reserve index '0' as a delimiter, so this entry in the table - is ALWAYS blank and unused. + Note that we reserve index '0' as a delimiter, so the entry at that + index in the table is ALWAYS blank and unused. */ message StringTable { @@ -131,10 +113,10 @@ message Info { optional int32 timestamp = 2; optional int64 changeset = 3; optional int32 uid = 4; - optional int32 user_sid = 5; + optional int32 user_sid = 5; // String IDs } -/* Optional metadata that may be included into each primitive. */ +/** Optional metadata that may be included into each primitive. Special dense format used in DenseNodes. */ message DenseInfo { repeated int32 version = 1 [packed = true]; repeated sint64 timestamp = 2 [packed = true]; // DELTA coded @@ -143,6 +125,7 @@ message DenseInfo { repeated sint32 user_sid = 5 [packed = true]; // String IDs for usernames. DELTA coded } + // TODO: REMOVE THIS? NOT in osmosis schema. message ChangeSet { required int64 id = 1; @@ -165,7 +148,7 @@ message Node { repeated uint32 keys = 2 [packed = true]; // String IDs. repeated uint32 vals = 3 [packed = true]; // String IDs. - optional Info info = 4; + optional Info info = 4; // May be omitted in omitmeta required sint64 lat = 8; required sint64 lon = 9; @@ -174,23 +157,26 @@ message Node { /* Used to densly represent a sequence of nodes that do not have any tags. We represent these nodes columnwise as five columns: ID's, lats, and -lons, all delta coded. And an optional info's column when metadata is not omitted. +lons, all delta coded. When metadata is not omitted, -We encode keys & vals for all nodes too in one array in the form of ONE array of integers containing key-id and val-id values, using 0 as a delimiter between nodes. +We encode keys & vals for all nodes as a single array of integers +containing key-stringid and val-stringid, using a stringid of 0 as a +delimiter between nodes. ( ( )* '0' )* */ + message DenseNodes { repeated sint64 id = 1 [packed = true]; // DELTA coded - repeated Info info = 4; - optional DenseInfo denseinfo = 5; // One of these + //repeated Info info = 4; + optional DenseInfo denseinfo = 5; repeated sint64 lat = 8 [packed = true]; // DELTA coded repeated sint64 lon = 9 [packed = true]; // DELTA coded - // Special packing of keys and vals into one array. - repeated int32 keys_vals = 10 [packed = true]; + // Special packing of keys and vals into one array. May be empty if all nodes in this block are tagless. + repeated int32 keys_vals = 10 [packed = true]; } @@ -202,7 +188,7 @@ message Way { optional Info info = 4; - repeated sint64 refs = 8 [packed = true]; // DELTA encoded + repeated sint64 refs = 8 [packed = true]; // DELTA coded } message Relation {