package mil.nga.giat.geowave.core.index.sfc;

import java.math.BigInteger;

import mil.nga.giat.geowave.core.index.Persistable;
import mil.nga.giat.geowave.core.index.sfc.data.MultiDimensionalNumericData;

/***
 * Base class which defines common methods for any space filling curve. Hosts
 * standard access methods shared between implementation. A space filling curve
 * is expected to provide a reversible n-dimensional <-> 1-dimensional mapping.
 *
 */
public interface SpaceFillingCurve extends
		Persistable
{
	/***
	 * Maps a n-dimensional value to a single dimension, i.e. [12,33] -> 0033423
	 *
	 * @param values
	 *            n-dimensional value to be encoded in the SFC. The size of
	 *            value corresponds to the number of dimensions
	 * @return value derived from the the SFC transform. The value is left
	 *         padded based on the number if bits in the SFC dimension
	 */
	public byte[] getId(
			double[] values );

	/***
	 * Gets n-dimensional ranges from a single dimension, i.e. 0033423 ->
	 * [12,33]
	 *
	 * @param id
	 *            the SFC ID to calculate the ranges of values represented.
	 * @return the valid ranges per dimension of a single SFC ID derived from
	 *         the the SFC transform.
	 */
	public MultiDimensionalNumericData getRanges(
			byte[] id );

	/***
	 * Gets n-dimensional coordinates from a single dimension
	 *
	 * @param id
	 *            the SFC ID to calculate the coordinates for each dimension.
	 * @return the coordinate in each dimension for the given ID
	 */
	public long[] getCoordinates(
			byte[] id );

	/***
	 * Returns a collection of ranges on the 1-d space filling curve that
	 * correspond to the n-dimensional range described in the query parameter.
	 *
	 * This method will decompose the range all the way down to the unit
	 * interval of 1.
	 *
	 * @param query
	 *            describes the n-dimensional query window that will be
	 *            decomposed
	 * @return an object containing the ranges on the SFC that overlap the
	 *         parameters supplied in the query object
	 *
	 */
	public RangeDecomposition decomposeRangeFully(
			MultiDimensionalNumericData query );

	/***
	 * Returns a collection of ranges on the 1-d space filling curve that
	 * correspond to the n-dimensional range described in the query parameter.
	 *
	 * This method will roll up the ranges based on the maxRanges parameter.
	 * Ranges will be "connected" based on the minimization of distance between
	 * the end of one range and the start of the next.
	 *
	 * @param query
	 *            describes the n-dimensional query window that will be
	 *            decomposed
	 * @return an object containing the ranges on the SFC that overlap the
	 *         parameters supplied in the query object
	 *
	 */
	public RangeDecomposition decomposeRange(
			MultiDimensionalNumericData query,
			boolean overInclusiveOnEdge,
			int maxRanges );

	/***
	 * Determines the estimated number of rows a multi-dimensional range will
	 * span within this space filling curve
	 *
	 * @param query
	 *            describes the n-dimensional range to estimate the row count
	 *            for
	 * @return an estimate of the row count for the ranges given within this
	 *         space filling curve
	 *
	 */
	public BigInteger getEstimatedIdCount(
			MultiDimensionalNumericData data );

	/***
	 * Determines the coordinates within this space filling curve for a
	 * dimension given a range
	 *
	 * @param minValue
	 *            describes the minimum of a range in a single dimension used to
	 *            determine the SFC coordinate range
	 * @param maxValue
	 *            describes the maximum of a range in a single dimension used to
	 *            determine the SFC coordinate range
	 * @param dimension
	 *            the dimension
	 * @return the range of coordinates as an array where the first element is
	 *         the min and the second element is the max
	 *
	 */
	public long[] normalizeRange(
			double minValue,
			double maxValue,
			int dimension );

	/***
	 * Get the range/size of a single insertion ID for each dimension
	 *
	 * @return the range of a single insertion ID for each dimension
	 */
	public double[] getInsertionIdRangePerDimension();
}