Skip to content
nyurikPublic

About

A fast reader and writer of TWKB, Tiny Well-Known Binary geometry format

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

twkb

GitHub repo crates.io version crate usage docs.rs status crates.io license CI build status Codecov

A fast reader and writer of TWKB (Tiny Well-Known Binary), a compact geometry encoding: coordinates are rounded to a chosen number of decimal digits and stored as varint deltas from the previous point, typically several times smaller than WKB. PostGIS writes it with ST_AsTWKB and reads it with ST_GeomFromTWKB.

  • All geometry types and format options: z and m, sizes, bounding boxes, empty geometries, and ID lists (read only).
  • The same bytes as PostGIS, except at negative precisions, where this crate rounds exactly and PostGIS does not.
  • geo-traits both ways: writes any geometry that implements them (geo-types, wkt, wkb, and others), and the geometries it reads implement them.
  • Integer coordinates as stored, without float rounding: write_scaled_line_string and stored_coords.
  • Bad or hostile input is an error, never a panic or an unbounded allocation; [ReadOptions] caps memory and nesting.

Usage

use geo_traits::{CoordTrait as _, LineStringTrait as _};
use twkb::{write_geometry, Precision, Twkb, WriteOptions};

fn write_and_read() -> Result<(), twkb::TwkbError> {
    let line = geo_types::LineString::from(vec![
        (-71.036_671_8, 42.373_449_3),
        (-71.036_761_9, 42.373_312),
    ]);
    let mut buf = Vec::new();
    let opts = WriteOptions {
        precision: Precision::xy(7),
        ..WriteOptions::default()
    };
    write_geometry(&mut buf, &line, &opts)?;

    let Twkb::LineString(read) = Twkb::new(&buf)? else {
        unreachable!()
    };
    assert_eq!(
        read.coord(1).map(|c| c.x_y()),
        Some((-71.036_761_9, 42.373_312))
    );
    assert_eq!(
        read.stored_coords(),
        [-710_366_718, 423_734_493, -710_367_619, 423_733_120]
    );
    Ok(())
}

Examples

examples/ converts between TWKB and WKT or WKB, through geo-traits and the wkt and wkb crates:

# WKT or hex WKB to hex TWKB, with 7 decimal digits for x and y
cargo run --example encode -- 'LINESTRING(-71.0366718 42.3734493,-71.0367619 42.373312)' --precision 7
cargo run --example encode -- 0101000000000000000000f03f0000000000000040
# with z, its own precision, the size and the bounding box
cargo run --example encode -- 'POINT Z (1.25 2.5 3)' --precision 1,0 --size --bbox

# hex TWKB to WKT and hex WKB, with what its header holds
cargo run --example decode -- e20002fbd7baa505bab38d9403890eb915
cargo run --example decode -- 04070b0004020402000200020404

Performance

A 1,000-point line string at OpenStreetMap's 7 digits (just bench, Intel i9-10885H):

twkb wkb
size 3,481 bytes (78% smaller) 16,009 bytes
write from geo-types 11.7 µs (596% slower) 1.7 µs
read, sum the f64 ordinates 5.8 µs (55% slower) 3.7 µs

Tested against PostGIS, the test suites of other TWKB implementations, and fuzzing.

Development

  • This project is easier to develop with just, a modern alternative to make. Install it with cargo install just.
  • To get a list of available commands, run just.
  • To run tests, use just test.

License

Licensed under either of

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

About

A fast reader and writer of TWKB, Tiny Well-Known Binary geometry format

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages