Getting the Well-Known Binary representation of geometries using the JTS Topology Suite

In this post we will see how to get the Well-Known Binary[1] (WKB) representation of geometries using the Java library JTS Topology Suite. WKB is a binary, serialized form of the Well-Known Text (WKT) representation of geometries.

In the first section a sample program getting the WKB representation of two simple geometries is shown. The second section covers potential issues related with endiannesss.

1. Simple Java code

JTS Topology Suite package com.vividsolutions.jts.io provides classes to get both WKB and WKT representations of geometries. Let’s see how to get the WKB representation of a point and a polygon using them; the key class is WKBWriter.

import com.vividsolutions.jts.geom.Coordinate;
import com.vividsolutions.jts.geom.Geometry;
import com.vividsolutions.jts.geom.GeometryFactory;
import com.vividsolutions.jts.geom.LinearRing;
import com.vividsolutions.jts.geom.Point;
import com.vividsolutions.jts.geom.Polygon;

import com.vividsolutions.jts.geom.impl.CoordinateArraySequence;

import com.vividsolutions.jts.io.ByteOrderValues;
import com.vividsolutions.jts.io.WKBWriter;

public class JTSTest {
        public static void main(String[] args) {
              GeometryFactory gm = new GeometryFactory();

               Point thePoint = 
                        gm.createPoint(new Coordinate(591499.980, 4784943.070));

                Coordinate[] polCoords = new Coordinate[4];
                polCoords[0] = new Coordinate(591498.310, 4784942.970);
                polCoords[1] = new Coordinate(591495.970, 4784932.020);
                polCoords[2] = new Coordinate(591496.640, 4784935.530);
                polCoords[3] = polCoords[0];
                LinearRing lr = 
                        new LinearRing(new CoordinateArraySequence(polCoords), gm);
                Polygon thePolygon = gm.createPolygon(lr, null);

                WKBWriter w =
                        new WKBWriter(2, ByteOrderValues.LITTLE_ENDIAN);

                byte[] pnt = w.write(thePoint);
                System.out.printf("point: WKT = %s WKB = %s\n", thePoint.toText(), WKBWriter.toHex(pnt));

		byte[] plg = w.write(thePolygon);
		System.out.printf("polygon: WKT = %s WKB = %s\n", thePolygon.toText(), WKBWriter.toHex(plg));
        }
}

Java and JTS Topology Suite versions are respectively 6 and 1.11.

2. Endianness can matter

Endianness[2] depends on operating system (OS) and computer architecture, and it affects the WKB representation of geometries. One of the three available constructors of the WBKWriter class – lines #29 and #30 of the code shown in the previous section – will accept a given endianness as parameter (ByteOrderValues.LITTLE_ENDIAN in our example), no matter the underlying OS or architecture we have. The other two constructors of the WKBWriter class will not accept a parameter like this, and the byte order will always be ByteOrderValues.BIG_ENDIAN [note 1].

If the WKB data is to be used by another software or system, endianness should be taken into account. The geometry in WKB format can, for example, be transmited over a LAN and reach a destination machine whose endianness is different than we have used to format the data before it was sent. Although WKB formatted data has a byte indicating little-endian or big-endian storage, assuming that the receiving software will always be smart enough to look at this byte, and apply the needed transform if needed, might be an error.

notes

[note 1] The Java class java.nio.ByteOrder allows knowing the order byte used by the underlying system.

references

[1] Well-Known Text and Well-Known Binary is part of the Simple feature access – Part 2: SQL option specification, that can be found at http://www.opengeospatial.org/standards/sfs.

[2] There is a complete article about endianness in the Wikipedia that can be found at http://en.wikipedia.org/wiki/Endianness.