Isohypse Binary File

From OpenStreetMap Wiki
Jump to: navigation, search


This page describes a new format, called isohypse binary file (or IBF in short). It is intended for storing isohypses (a.k.a. contour lines, relief contours) in a compact form. The format was created by User:Breki, author of several OSM tools (Srtm2Osm, Kosmos) which can generate isohypses using SRTM data.

Why A New Format?

Tools like Srtm2Osm can use SRTM data provided by Nasa to generate isohypses for a given area. Isohypses are then saved in an OSM XML file. Past experience has shown that this is not a good approach. The main deficiencies are:

  • OSM XML is a very verbose format and the generated file can have a size in hundreds of megabytes even for a small country.
  • In order to use contours from an OSM XML file, all the file data has to be loaded in memory. One of the reasons for this is that an isohypse is represented as an OSM way and a collection of OSM nodes, which are stored separately in the file.

Goals For The New Format

  • To hold the data in a condensed non-compressed lossless form.
  • To make fetching of the isohypse data for a particular geographical area relatively easy (i.e. without requiring the whole file to be loaded and processed in memory).

Current Status

Currently the C# library for IBF is being developed by me (User:Breki). I've rewritten the isopleting algorithm and now I'm developing a new command line tool to generate IBF files from SRTM data for a given area (and other IBF-related functions). Additionally, Kosmos and GroundTruth tools will be extended to support the IBF format in the future. --Breki 20:46, 9 March 2009 (UTC)

Format Description

General Architecture

The IBF file holds isohypses for one or more rectangular (min lat, max lat, min long, max long) geographical areas. Typically these areas will be of the same size and will be disjunct, but this is not enforced by the specifications. Also, the optimal size of a single area still has to be determined by experiment - it should be small enough to enable normal processing of isohypses on a typical PC, but large enough not to cause the relief to be split into too many small pieces. The size will also depend on the resolution of the data - areas with isohypses generated from SRTM3 dataset will probably be larger that those generated from SRTM1, because SRTM3 uses a lower resolution grid.

IBF File Header

Length: 8 bytes

position (in bytes) length (in bytes) description value (example)
0 3 IBF format marker IBF
3 1 IBF format version (major) 1
4 1 IBF format version (minor) 0
5 3 currently not used

Area Directory

Length: 4408 bytes

position (in bytes) length (in bytes) description value (example)
0 44 area directory entry 1 0 if empty
44 44 area directory entry 2 0 if empty
4356 44 area directory entry 100 0 if empty
4400 8 offset (in bytes) of the next area directory 0 if this is the last directory. Otherwise, it's calculated relative to the start of first area definition of this directory

Area Directory Entry

Length: 44 bytes

position (in bytes) length (in bytes) description value (example)
0 8 area definition offset (in bytes) relative from the starting position of this entry in the file
8 1 type 0 represents a raster-based isohypse area (like that from SRTM3)
9 3 currently not used
12 8 area's minimum latitude (double)
20 8 area's maximum latitude (double)
28 8 area's minimum longitude (double)
36 8 area's maximum longitude (double)

Area Definition Header

Length: 12 bytes

position (in bytes) length (in bytes) description value (example)
0 2 elevation entries count
2 1 elevation units 0 for meters, 1 for feet
3 1 currently not used
4 4 latitudinal resolution in points per degree. Example: SRTM3 has a resolution of 1200 points per degree
4 4 longitudinal resolution in points per degree. Example: SRTM3 has a resolution of 1200 points per degree

Elevation Header

Length: variable

position (in bytes) length (in bytes) description value (example)
0 2 elevation (in units)
2 4 isohypses count
6 4 1st isohypse length (in points)
8 4 2nd isohypse length (in points)
n*4 + 4 2 n isohypse length (in points)

Isohypse Definition

Length: variable

position (in bytes) length (in bytes) description value (example)
0 4 isohypse points count
4 8 starting X coordinate
12 8 starting Y coordinate
20 1 flags - the first two bits indicate initial direction of the isohypse. The third bit indicates whether the isohypse is closed or not (closed isohypses do not duplicate the first/last point)
21 Math.Ceiling (points / 4) isohypse movements each 2 bits represent a single movement of the isohypse (0 for left, 1 for forward, 2 for right, 3 for initial point without movement)
x points elevation factor from 0 to 255

Practical Implications

I did some initial tests on the new isopleting algorithm which uses IBF structure. I created isohypses with 20 meters interval for the area of Sicily. Stored on the disk, the IBF file is about 4.5 MB of size. Compare this to the 450 MB for the file containing isohypses in the OSM format for the same area - the IBF file is thus around 100 times smaller, which makes it much more suitable for storing isohypses of the whole world. --Breki 20:19, 7 March 2009 (UTC)