org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree Maven / Gradle / Ivy
Show all versions of lucene-spatial-extras Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.lucene.spatial.prefix.tree;
import org.apache.lucene.util.BytesRef;
import org.locationtech.spatial4j.context.SpatialContext;
import org.locationtech.spatial4j.shape.Shape;
/**
* 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.
*
* @lucene.experimental
*/
public abstract class SpatialPrefixTree {
protected final int maxLevels;
protected final SpatialContext ctx;
public SpatialPrefixTree(SpatialContext ctx, int maxLevels) {
assert maxLevels > 0;
this.ctx = ctx;
this.maxLevels = maxLevels;
}
public SpatialContext getSpatialContext() {
return ctx;
}
public int getMaxLevels() {
return maxLevels;
}
@Override
public String toString() {
return getClass().getSimpleName() + "(maxLevels:" + maxLevels + ",ctx:" + ctx + ")";
}
/**
* Returns the level of the largest grid in which its longest side is less than or equal to the
* provided distance (in degrees). Consequently {@code 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.
*
* @param dist {@code >= 0}
* @return level [1 to maxLevels]
*/
public abstract int getLevelForDistance(double dist);
/**
* Given a cell having the specified level, returns the distance from opposite corners. Since this
* might vary depending on where the cell is, this method may over-estimate.
*
* @param level [1 to maxLevels]
* @return {@code > 0}
*/
public abstract double getDistanceForLevel(int level);
/**
* Returns the level 0 cell which encompasses all spatial data. Equivalent to {@link
* #readCell(BytesRef,Cell)} with no bytes.
*/
public abstract Cell getWorldCell(); // another possible name: getTopCell
/**
* This creates a new Cell (or re-using {@code scratch} if provided), initialized to the state as
* read by the bytes. Warning: An implementation may refer to the same byte array (no copy). If
* {@link Cell#setLeaf()} is subsequently called, it would then modify these bytes.
*/
public abstract Cell readCell(BytesRef term, Cell scratch);
/**
* 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. For
* cells at detailLevel, they are marked as leaves too, unless it's a point.
*
*
IMPORTANT: Cells returned from the iterator can be re-used for cells at the same level. So
* you can't simply iterate to subsequent cells and still refer to the former cell nor the bytes
* returned from the former cell, unless you know the former cell is a parent.
*
* @param shape the shape; possibly null but the caller should liberally call {@code remove()} if
* so.
* @param detailLevel the maximum detail level to get cells for
* @return the matching cells
*/
public CellIterator getTreeCellIterator(Shape shape, int detailLevel) {
if (detailLevel > maxLevels) {
throw new IllegalArgumentException("detailLevel > maxLevels");
}
return new TreeCellIterator(shape, detailLevel, getWorldCell());
}
}