Package com.google.common.geometry

Class S2Projections

java.lang.Object

com.google.common.geometry.S2Projections

public final class S2Projections
extends Object

This class specifies the details of how the cube faces are projected onto the unit sphere. This includes getting the face ordering and orientation correct so that sequentially increasing cell ids follow a continuous space-filling curve over the entire sphere, and defining the transformation from cell-space to cube-space (see s2.h) in order to make the cells more uniform in size. We have implemented three different projections from cell-space (s,t) to cube-space (u,v): linear, quadratic, and tangent. They have the following tradeoffs: Linear - This is the fastest transformation, but also produces the least uniform cell sizes. Cell areas vary by a factor of about 5.2, with the largest cells at the center of each face and the smallest cells in the corners. Tangent - Transforming the coordinates via atan() makes the cell sizes more uniform. The areas vary by a maximum ratio of 1.4 as opposed to a maximum ratio of 5.2. However, each call to atan() is about as expensive as all of the other calculations combined when converting from points to cell ids, i.e. it reduces performance by a factor of 3. Quadratic - This is an approximation of the tangent projection that is much faster and produces cells that are almost as uniform in size. It is about 3 times faster than the tangent projection for converting cell ids to points, and 2 times faster for converting points to cell ids. Cell areas vary by a maximum ratio of about 2.1. Here is a table comparing the cell uniformity using each projection. "Area ratio" is the maximum ratio over all subdivision levels of the largest cell area to the smallest cell area at that level, "edge ratio" is the maximum ratio of the longest edge of any cell to the shortest edge of any cell at the same level, and "diag ratio" is the ratio of the longest diagonal of any cell to the shortest diagonal of any cell at the same level. "ToPoint" and "FromPoint" are the times in microseconds required to convert cell ids to and from points (unit vectors) respectively. Area Edge Diag ToPoint FromPoint Ratio Ratio Ratio (microseconds) ------------------------------------------------------- Linear: 5.200 2.117 2.959 0.103 0.123 Tangent: 1.414 1.414 1.704 0.290 0.306 Quadratic: 2.082 1.802 1.932 0.116 0.161 The worst-case cell aspect ratios are about the same with all three projections. The maximum ratio of the longest edge to the shortest edge within the same cell is about 1.4 and the maximum ratio of the diagonals within the same cell is about 1.7. This data was produced using s2cell_unittest and s2cellid_unittest.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	S2Projections.Projections

Field Summary

Fields

Modifier and Type	Field	Description
static S2.Metric	AVG_ANGLE_SPAN
static S2.Metric	AVG_AREA
static S2.Metric	AVG_DIAG
static S2.Metric	AVG_EDGE
static S2.Metric	AVG_WIDTH
static S2.Metric	MAX_ANGLE_SPAN
static S2.Metric	MAX_AREA
static S2.Metric	MAX_DIAG
static double	MAX_DIAG_ASPECT
static S2.Metric	MAX_EDGE
static double	MAX_EDGE_ASPECT
static S2.Metric	MAX_WIDTH
static S2.Metric	MIN_ANGLE_SPAN
static S2.Metric	MIN_AREA
static S2.Metric	MIN_DIAG
static S2.Metric	MIN_EDGE
static S2.Metric	MIN_WIDTH

Method Summary

Modifier and Type	Method	Description
static S2Point	faceUvToXyz(int face, double u, double v)	Convert (face, u, v) coordinates to a direction vector (not necessarily unit length).
static R2Vector	faceXyzToUv(int face, S2Point p)
static S2Point	getNorm(int face)
static S2Point	getUAxis(int face)
static S2Point	getUNorm(int face, double u)
static S2Point	getVAxis(int face)
static S2Point	getVNorm(int face, double v)
static double	stToUV(double s)
static double	uvToST(double u)
static R2Vector	validFaceXyzToUv(int face, S2Point p)
static int	xyzToFace(S2Point p)

Methods inherited from class java.lang.Object

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

Field Detail

MIN_AREA

public static final S2.Metric MIN_AREA

MAX_AREA

public static final S2.Metric MAX_AREA

AVG_AREA

public static final S2.Metric AVG_AREA

MIN_ANGLE_SPAN

public static final S2.Metric MIN_ANGLE_SPAN

MAX_ANGLE_SPAN

public static final S2.Metric MAX_ANGLE_SPAN

AVG_ANGLE_SPAN

public static final S2.Metric AVG_ANGLE_SPAN

MIN_WIDTH

public static final S2.Metric MIN_WIDTH

MAX_WIDTH

public static final S2.Metric MAX_WIDTH

AVG_WIDTH

public static final S2.Metric AVG_WIDTH

MIN_EDGE

public static final S2.Metric MIN_EDGE

MAX_EDGE

public static final S2.Metric MAX_EDGE

AVG_EDGE

public static final S2.Metric AVG_EDGE

MIN_DIAG

public static final S2.Metric MIN_DIAG

MAX_DIAG

public static final S2.Metric MAX_DIAG

AVG_DIAG

public static final S2.Metric AVG_DIAG

MAX_EDGE_ASPECT

public static final double MAX_EDGE_ASPECT

MAX_DIAG_ASPECT

public static final double MAX_DIAG_ASPECT

Method Detail

stToUV

public static double stToUV(double s)

uvToST

public static double uvToST(double u)

faceUvToXyz

public static S2Point faceUvToXyz(int face,
                                  double u,
                                  double v)

Convert (face, u, v) coordinates to a direction vector (not necessarily unit length).

validFaceXyzToUv

public static R2Vector validFaceXyzToUv(int face,
                                        S2Point p)

xyzToFace

public static int xyzToFace(S2Point p)

faceXyzToUv

public static R2Vector faceXyzToUv(int face,
                                   S2Point p)

getUNorm

public static S2Point getUNorm(int face,
                               double u)

getVNorm

public static S2Point getVNorm(int face,
                               double v)

getNorm

public static S2Point getNorm(int face)

getUAxis

public static S2Point getUAxis(int face)

getVAxis

public static S2Point getVAxis(int face)