A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision. Each string corresponds to a rectangular spatial region. This approach is also referred to "Grids", "Tiles", and "Spatial Tiers".

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

Constructors

SpatialPrefixTree(SpatialContext, int)

Initializes a new instance of SpatialPrefixTree with the specified spatial context and maxLevels.

Declaration

protected SpatialPrefixTree(SpatialContext ctx, int maxLevels)

Parameters

Type	Name	Description
SpatialContext	ctx	The spatial context.
int	maxLevels	The maximum number of levels in the tree.

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

Exceptions

Type	Condition
ArgumentNullException	`ctx` is `null`.
ArgumentOutOfRangeException	`maxLevels` is less than or equal to 0.

Fields

m_ctx

A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision.

Declaration

protected readonly SpatialContext m_ctx

Field Value

Type	Description
SpatialContext

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

m_maxLevels

A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision.

Declaration

protected readonly int m_maxLevels

Field Value

Type	Description
int

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

Properties

MaxLevels

A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision.

Declaration

public virtual int MaxLevels { get; }

Property Value

Type	Description
int

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

SpatialContext

A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision.

Declaration

public virtual SpatialContext SpatialContext { get; }

Property Value

Type	Description
SpatialContext

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

WorldCell

Returns the level 0 cell which encompasses all spatial data.

Declaration

public virtual Cell WorldCell { get; }

Property Value

Type	Description
Cell

Remarks

Returns the level 0 cell which encompasses all spatial data. Equivalent to GetCell(string) with Empty. This cell is threadsafe, just like a spatial prefix grid is, although cells aren't generally threadsafe.

Methods

CellsToTokenStrings(ICollection<Cell>)

Will add the trailing leaf byte for leaves. This isn't particularly efficient.

Declaration

[Obsolete("TODO remove; not used and not interesting, don't need collection in & out")]
public static IList<string> CellsToTokenStrings(ICollection<Cell> cells)

Parameters

Type	Name	Description
ICollection<Cell>	cells

Returns

Type	Description
IList<string>

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

GetCell(IPoint, int)

Returns the cell containing point p at the specified level.

Declaration

protected virtual Cell GetCell(IPoint p, int level)

Parameters

Type	Name	Description
IPoint	p
int	level

Returns

Type	Description
Cell

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

GetCell(byte[], int, int)

A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision.

Declaration

public abstract Cell GetCell(byte[] bytes, int offset, int len)

Parameters

Type	Name	Description
byte[]	bytes
int	offset
int	len

Returns

Type	Description
Cell

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

GetCell(byte[], int, int, Cell?)

A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision.

Declaration

public Cell GetCell(byte[] bytes, int offset, int len, Cell? target)

Parameters

Type	Name	Description
byte[]	bytes
int	offset
int	len
Cell	target

Returns

Type	Description
Cell

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

GetCell(string)

The cell for the specified token.

Declaration

public abstract Cell GetCell(string token)

Parameters

Type	Name	Description
string	token

Returns

Type	Description
Cell

Remarks

The cell for the specified token. The empty string should be equal to WorldCell. Precondition: Never called when token length > maxLevel.

GetCells(IPoint, int, bool)

A Point-optimized implementation of GetCells(IShape?, int, bool, bool). That method in facts calls this for points.

This implementation depends on GetCell(string) being fast, as its called repeatedly when incPlarents is true.

Declaration

public virtual IList<Cell> GetCells(IPoint p, int detailLevel, bool inclParents)

Parameters

Type	Name	Description
IPoint	p
int	detailLevel
bool	inclParents

Returns

Type	Description
IList<Cell>

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.

Exceptions

Type	Condition
ArgumentNullException	`p` is `null`.

GetCells(IShape?, int, bool, bool)

Gets the intersecting cells for the specified shape, without exceeding detail level.

Declaration

public virtual IList<Cell> GetCells(IShape? shape, int detailLevel, bool inclParents, bool simplify)

Parameters

Type	Name	Description
IShape	shape	the shape
int	detailLevel	the maximum detail level to get cells for
bool	inclParents	if true then all parent cells of leaves are returned too. The top world cell is never returned.
bool	simplify	for non-point shapes, this will simply/aggregate sets of complete leaves in a cell to its parent, resulting in ~20-25% fewer cells.

Returns

Type	Description
IList<Cell>	a set of cells (no dups), sorted, immutable, non-null

Remarks

Gets the intersecting cells for the specified shape, without exceeding detail level. If a cell is within the query shape then it's marked as a leaf and none of its children are added.

This implementation checks if shape is a Spatial4n.Shapes.IPoint and if so returns GetCells(IPoint, int, bool).

GetDistanceForLevel(int)

Given a cell having the specified level, returns the distance from opposite corners.

Declaration

public virtual double GetDistanceForLevel(int level)

Parameters

Type	Name	Description
int	level	[1 to maxLevels]

Returns

Type	Description
double	0

Remarks

Given a cell having the specified level, returns the distance from opposite corners. Since this might very depending on where the cell is, this method may over-estimate.

GetLevelForDistance(double)

Returns the level of the largest grid in which its longest side is less than or equal to the provided distance (in degrees).

Declaration

public abstract int GetLevelForDistance(double dist)

Parameters

Type	Name	Description
double	dist	= 0

Returns

Type	Description
int	level [1 to maxLevels]

Remarks

Returns the level of the largest grid in which its longest side is less than or equal to the provided distance (in degrees). Consequently dist acts as an error epsilon declaring the amount of detail needed in the grid, such that you can get a grid with just the right amount of precision.

ToString()

Returns a string that represents the current object.

Declaration

public override string ToString()

Returns

Type	Description
string	A string that represents the current object.

Overrides

object.ToString()

Remarks

Implementations of this class should be thread-safe and immutable once initialized.

Note

This API is experimental and might change in incompatible ways in the next release.