org.davidmoten.hilbert

Class SmallHilbertCurve

java.lang.Object

org.davidmoten.hilbert.SmallHilbertCurve

public final class SmallHilbertCurve
extends Object

Converts between Hilbert index (BigInteger) and N-dimensional points.

Note: This algorithm is derived from work done by John Skilling and published in "Programming the Hilbert curve". (c) 2004 American Institute of Physics. With thanks also to Paul Chernoch who published a C# algorithm for Skilling's work on StackOverflow and GitHub).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SmallHilbertCurve.Builder

Method Summary

Modifier and Type	Method and Description
int	bits()
int	dimensions()
long	index(long... point) Converts a point to its Hilbert curve index.
long	maxIndex()
long	maxOrdinate()
long[]	point(long index) Converts a long index (distance along the Hilbert Curve from 0) to a point of dimensions defined in the constructor of this.
void	point(long index, long[] x)
Ranges	query(long[] a, long[] b) Returns index ranges exactly covering the region bounded by a and b.
Ranges	query(long[] a, long[] b, int maxRanges) Returns index ranges covering the region bounded by a and b.
Ranges	query(long[] a, long[] b, int maxRanges, int bufferSize) Returns index ranges covering the region bounded by a and b.

Methods inherited from class java.lang.Object

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

Method Detail

bits

public int bits()

dimensions

public int dimensions()

index

public long index(long... point)

Converts a point to its Hilbert curve index.

Parameters:

point - an array of long. Each coordinate can be between 0 and 2^bits-1.

Returns:

index long in the range 0 to 2^{bits * dimensions} - 1

Throws:

IllegalArgumentException - if length of point array is not equal to the number of dimensions.

point

public long[] point(long index)

Converts a long index (distance along the Hilbert Curve from 0) to a point of dimensions defined in the constructor of this.

Parameters:

index - index along the Hilbert Curve from 0. Maximum value 2 ^{bits * dimensions}-1.

Returns:

array of longs being the point

Throws:

IllegalArgumentException - if index is negative

point

public void point(long index,
                  long[] x)

maxOrdinate

public long maxOrdinate()

maxIndex

public long maxIndex()

query

public Ranges query(long[] a,
                    long[] b)

Returns index ranges exactly covering the region bounded by a and b. The list will be in increasing order of the range bounds (there should be no overlaps).

Parameters:

a - one vertex of the region

b - the opposing vertex to a

Returns:

ranges

query

public Ranges query(long[] a,
                    long[] b,
                    int maxRanges)

Returns index ranges covering the region bounded by a and b. The list will be in increasing order of the range bounds (there should be no overlaps). The index ranges may cover a larger region than the search box because the set of exact covering ranges will have been reduced by joining ranges with minimal gaps. The buffer size used by this method is 1024.

Parameters:

a - one vertex of the region

b - the opposing vertex to a

maxRanges - the maximum number of ranges to be returned. If 0 then all ranges are returned.

Returns:

ranges

query

public Ranges query(long[] a,
                    long[] b,
                    int maxRanges,
                    int bufferSize)

Returns index ranges covering the region bounded by a and b. The list will be in increasing order of the range bounds (there should be no overlaps). The index ranges may cover a larger region than the search box because the set of exact covering ranges will have been reduced by joining ranges with minimal gaps. A buffer of ranges is used and has a size that is generally speaking a fair bit larger than maxRanges to increase the probability that minimal extra coverage be returned.

Parameters:

a - one vertex of the region

b - the opposing vertex to a

maxRanges - the maximum number of ranges to be returned. If 0 then all ranges are returned.

bufferSize - the buffer size of ranges to use. A larger buffer size will increase the probability that ranges have been joined optimally (we want to join ranges that have minimal gaps to minimize the resultant extra coverage). If 0 is passed to bufferSize then all ranges will be buffered before shrinking to maxRanges.

Returns:

ranges