org.locationtech.jts.io

Class WKBWriter

java.lang.Object

org.locationtech.jts.io.WKBWriter

public class WKBWriter
extends Object

Writes a Geometry into Well-Known Binary format. Supports use of an OutStream, which allows easy use with arbitrary byte stream sinks.

The WKB format is specified in the OGC Simple Features for SQL specification (section 3.3.2.6).

There are a few cases which are not specified in the standard. The implementation uses a representation which is compatible with other common spatial systems (notably, PostGIS).

• LinearRings are written as LineStrings
• Empty geometries are output as follows:
  • Point: a WKBPoint with NaN ordinate values
  • LineString: a WKBLineString with zero points
  • Polygon: a WKBPolygon with zero rings
  • Multigeometries: a WKBMulti geometry of appropriate type with zero elements
  • GeometryCollections: a WKBGeometryCollection with zero elements

This implementation supports the Extended WKB standard. Extended WKB allows writing 3-dimensional coordinates and the geometry SRID value. The presence of 3D coordinates is indicated by setting the high bit of the wkbType word. The presence of a SRID is indicated by setting the third bit of the wkbType word. EWKB format is upward-compatible with the original SFS WKB format.

SRID output is optimized, if specified. Only the top-level geometry has the SRID included. This assumes that all geometries in a collection have the same SRID as the collection (which is the JTS convention).

This class supports reuse of a single instance to read multiple geometries. This class is not thread-safe; each thread should create its own instance.

Syntax

The following syntax specification describes the version of Well-Known Binary supported by JTS.

The specification uses a syntax language similar to that used in the C language. Bitfields are specified from high-order to low-order bits.

 
 byte = 1 byte
 uint32 = 32 bit unsigned integer (4 bytes)
 double = double precision number (8 bytes)
 
 abstract Point { }
 
 Point2D extends Point {
        double x;
        double y;
 }
 
 Point3D extends Point {
        double x;
        double y;
        double z;
 }
 
 LinearRing {
        uint32 numPoints;
        Point points[numPoints];
 }
 
 enum wkbGeometryType {
        wkbPoint = 1,
        wkbLineString = 2,
        wkbPolygon = 3,
        wkbMultiPoint = 4,
        wkbMultiLineString = 5,
        wkbMultiPolygon = 6,
        wkbGeometryCollection = 7
 }
 
 enum byteOrder {
        wkbXDR = 0,     // Big Endian
        wkbNDR = 1      // Little Endian
 }
 
 WKBType {
        uint32 wkbGeometryType : 8; // values from enum wkbGeometryType
 }
 
 EWKBType {
        uint32 is3D : 1;         // 0 = 2D, 1 = 3D
        uint32 noData1 : 1; 
        uint32 hasSRID : 1;      // 0, no, 1 = yes
        uint32 noData2 : 21; 
        uint32 wkbGeometryType : 8; // values from enum wkbGeometryType
 }
 
 abstract WKBGeometry {
        byte byteOrder;          // values from enum byteOrder
        EWKBType wkbType
        [ uint32 srid; ]         // only if hasSRID = yes
 }
 
 WKBPoint extends WKBGeometry {
        Point point;
 }
 
 WKBLineString extends WKBGeometry {
        uint32 numCoords;
        Point points[numCoords];
 }
 
 WKBPolygon extends WKBGeometry {
        uint32 numRings;
        LinearRing rings[numRings];
 }
 
 WKBMultiPoint extends WKBGeometry {
        uint32 numElems;
        WKBPoint elems[numElems];
 }
 
 WKBMultiLineString extends WKBGeometry {
        uint32 numElems;
        WKBLineString elems[numElems];
 }
 
 wkbMultiPolygon extends WKBGeometry {
        uint32 numElems;
        WKBPolygon elems[numElems];
 }
 
 WKBGeometryCollection extends WKBGeometry {
        uint32 numElems;
        WKBGeometry elems[numElems];
 }
 
 

See Also:

WKBReader

Constructor Summary

Constructors

Constructor and Description
WKBWriter() Creates a writer that writes Geometrys with output dimension = 2 and BIG_ENDIAN byte order
WKBWriter(int outputDimension) Creates a writer that writes Geometrys with the given dimension (2 or 3) for output coordinates and ByteOrderValues.BIG_ENDIAN byte order.
WKBWriter(int outputDimension, boolean includeSRID) Creates a writer that writes Geometrys with the given dimension (2 or 3) for output coordinates and ByteOrderValues.BIG_ENDIAN byte order.
WKBWriter(int outputDimension, int byteOrder) Creates a writer that writes Geometrys with the given dimension (2 or 3) for output coordinates and byte order If the input geometry has a small coordinate dimension, coordinates will be padded with Coordinate.NULL_ORDINATE.
WKBWriter(int outputDimension, int byteOrder, boolean includeSRID) Creates a writer that writes Geometrys with the given dimension (2 to 4) for output coordinates and byte order.

Method Summary

Modifier and Type	Method and Description
static String	bytesToHex(byte[] bytes) Deprecated.
EnumSet<Ordinate>	getOutputOrdinates() Gets a bit-pattern defining which ordinates should be
void	setOutputOrdinates(EnumSet<Ordinate> outputOrdinates) Sets the Ordinate that are to be written.
static String	toHex(byte[] bytes) Converts a byte array to a hexadecimal string.
byte[]	write(Geometry geom) Writes a Geometry into a byte array.
void	write(Geometry geom, OutStream os) Writes a Geometry to an OutStream.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WKBWriter

public WKBWriter()

Creates a writer that writes Geometrys with output dimension = 2 and BIG_ENDIAN byte order

WKBWriter

public WKBWriter(int outputDimension)

Creates a writer that writes Geometrys with the given dimension (2 or 3) for output coordinates and ByteOrderValues.BIG_ENDIAN byte order. If the input geometry has a small coordinate dimension, coordinates will be padded with Coordinate.NULL_ORDINATE.

Parameters:

outputDimension - the coordinate dimension to output (2 or 3)

WKBWriter

public WKBWriter(int outputDimension,
                 boolean includeSRID)

Creates a writer that writes Geometrys with the given dimension (2 or 3) for output coordinates and ByteOrderValues.BIG_ENDIAN byte order. This constructor also takes a flag to control whether srid information will be written. If the input geometry has a smaller coordinate dimension, coordinates will be padded with Coordinate.NULL_ORDINATE.

Parameters:

outputDimension - the coordinate dimension to output (2 or 3)

includeSRID - indicates whether SRID should be written

WKBWriter

public WKBWriter(int outputDimension,
                 int byteOrder)

Creates a writer that writes Geometrys with the given dimension (2 or 3) for output coordinates and byte order If the input geometry has a small coordinate dimension, coordinates will be padded with Coordinate.NULL_ORDINATE.

Parameters:

outputDimension - the coordinate dimension to output (2 or 3)

byteOrder - the byte ordering to use

WKBWriter

public WKBWriter(int outputDimension,
                 int byteOrder,
                 boolean includeSRID)

Creates a writer that writes Geometrys with the given dimension (2 to 4) for output coordinates and byte order. This constructor also takes a flag to control whether srid information will be written. If the input geometry has a small coordinate dimension, coordinates will be padded with Coordinate.NULL_ORDINATE. The output follows the following rules:

• If the specified output dimension is 3 and the z is measure flag is set to true, the Z value of coordinates will be written if it is present (i.e. if it is not Double.NaN)
• If the specified output dimension is 3 and the z is measure flag is set to false, the Measure value of coordinates will be written if it is present (i.e. if it is not Double.NaN)
• If the specified output dimension is 4, the Z value of coordinates will be written even if it is not present when the Measure value is present. The Measure value of coordinates will be written if it is present (i.e. if it is not Double.NaN)

See also setOutputOrdinates(EnumSet)

Parameters:

outputDimension - the coordinate dimension to output (2 to 4)

byteOrder - the byte ordering to use

includeSRID - indicates whether SRID should be written

Method Detail

bytesToHex

public static String bytesToHex(byte[] bytes)

Deprecated.

Converts a byte array to a hexadecimal string.

Parameters:

bytes -

Returns:

a string of hexadecimal digits

toHex

public static String toHex(byte[] bytes)

Converts a byte array to a hexadecimal string.

Parameters:

bytes - a byte array

Returns:

a string of hexadecimal digits

setOutputOrdinates

public void setOutputOrdinates(EnumSet<Ordinate> outputOrdinates)

Sets the Ordinate that are to be written. Possible members are:

• Ordinate.X
• Ordinate.Y
• Ordinate.Z
• Ordinate.M

Values of Ordinate.X and Ordinate.Y are always assumed and not particularly checked for.

Parameters:

outputOrdinates - A set of Ordinate values

getOutputOrdinates

public EnumSet<Ordinate> getOutputOrdinates()

Gets a bit-pattern defining which ordinates should be

Returns:

an ordinate bit-pattern

See Also:

setOutputOrdinates(EnumSet)

write

public byte[] write(Geometry geom)

Writes a Geometry into a byte array.

Parameters:

geom - the geometry to write

Returns:

the byte array containing the WKB

write

public void write(Geometry geom,
                  OutStream os)
           throws IOException

Writes a Geometry to an OutStream.

Parameters:

geom - the geometry to write

os - the out stream to write to

Throws:

IOException - if an I/O error occurs