geo: github.com/golang/geo/s1 Index | Files

package s1

import "github.com/golang/geo/s1"

Package s1 implements types and functions for working with geometry in S¹ (circular geometry).

See ../s2 for a more detailed overview.

Index

Package Files

angle.go chordangle.go doc.go interval.go

Constants

const (
    // NegativeChordAngle represents a chord angle smaller than the zero angle.
    // The only valid operations on a NegativeChordAngle are comparisons,
    // Angle conversions, and Successor/Predecessor.
    NegativeChordAngle = ChordAngle(-1)

    // RightChordAngle represents a chord angle of 90 degrees (a "right angle").
    RightChordAngle = ChordAngle(2)

    // StraightChordAngle represents a chord angle of 180 degrees (a "straight angle").
    // This is the maximum finite chord angle.
    StraightChordAngle = ChordAngle(4)
)

type Angle Uses

type Angle float64

Angle represents a 1D angle. The internal representation is a double precision value in radians, so conversion to and from radians is exact. Conversions between E5, E6, E7, and Degrees are not always exact. For example, Degrees(3.1) is different from E6(3100000) or E7(310000000).

The following conversions between degrees and radians are exact:

    Degree*180 == Radian*math.Pi
Degree*(180/n) == Radian*(math.Pi/n)     for n == 0..8

These identities hold when the arguments are scaled up or down by any power of 2. Some similar identities are also true, for example,

Degree*60 == Radian*(math.Pi/3)

But be aware that this type of identity does not hold in general. For example,

Degree*3 != Radian*(math.Pi/60)

Similarly, the conversion to radians means that (Angle(x)*Degree).Degrees() does not always equal x. For example,

(Angle(45*n)*Degree).Degrees() == 45*n     for n == 0..8

but

(60*Degree).Degrees() != 60

When testing for equality, you should allow for numerical errors (floatApproxEq) or convert to discrete E5/E6/E7 values first.

const (
    Radian Angle = 1
    Degree       = (math.Pi / 180) * Radian

    E5  = 1e-5 * Degree
    E6  = 1e-6 * Degree
    E7  = 1e-7 * Degree
)

Angle units.

func InfAngle Uses

func InfAngle() Angle

InfAngle returns an angle larger than any finite angle.

func (Angle) Abs Uses

func (a Angle) Abs() Angle

Abs returns the absolute value of the angle.

func (Angle) Degrees Uses

func (a Angle) Degrees() float64

Degrees returns the angle in degrees.

func (Angle) E5 Uses

func (a Angle) E5() int32

E5 returns the angle in hundred thousandths of degrees.

func (Angle) E6 Uses

func (a Angle) E6() int32

E6 returns the angle in millionths of degrees.

func (Angle) E7 Uses

func (a Angle) E7() int32

E7 returns the angle in ten millionths of degrees.

func (Angle) Normalized Uses

func (a Angle) Normalized() Angle

Normalized returns an equivalent angle in [0, 2π).

func (Angle) Radians Uses

func (a Angle) Radians() float64

Radians returns the angle in radians.

func (Angle) String Uses

func (a Angle) String() string

type ChordAngle Uses

type ChordAngle float64

ChordAngle represents the angle subtended by a chord (i.e., the straight line segment connecting two points on the sphere). Its representation makes it very efficient for computing and comparing distances, but unlike Angle it is only capable of representing angles between 0 and π radians. Generally, ChordAngle should only be used in loops where many angles need to be calculated and compared. Otherwise it is simpler to use Angle.

ChordAngle loses some accuracy as the angle approaches π radians. Specifically, the representation of (π - x) radians has an error of about (1e-15 / x), with a maximum error of about 2e-8 radians (about 13cm on the Earth's surface). For comparison, for angles up to π/2 radians (10000km) the worst-case representation error is about 2e-16 radians (1 nanonmeter), which is about the same as Angle.

ChordAngles are represented by the squared chord length, which can range from 0 to 4. Positive infinity represents an infinite squared length.

func ChordAngleFromAngle Uses

func ChordAngleFromAngle(a Angle) ChordAngle

ChordAngleFromAngle returns a ChordAngle from the given Angle.

func ChordAngleFromSquaredLength Uses

func ChordAngleFromSquaredLength(length2 float64) ChordAngle

ChordAngleFromSquaredLength returns a ChordAngle from the squared chord length. Note that the argument is automatically clamped to a maximum of 4 to handle possible roundoff errors. The argument must be non-negative.

func InfChordAngle Uses

func InfChordAngle() ChordAngle

InfChordAngle returns a chord angle larger than any finite chord angle. The only valid operations on an InfChordAngle are comparisons, Angle conversions, and Successor/Predecessor.

func (ChordAngle) Add Uses

func (c ChordAngle) Add(other ChordAngle) ChordAngle

Add adds the other ChordAngle to this one and returns the resulting value. This method assumes the ChordAngles are not special.

func (ChordAngle) Angle Uses

func (c ChordAngle) Angle() Angle

Angle converts this ChordAngle to an Angle.

func (ChordAngle) Cos Uses

func (c ChordAngle) Cos() float64

Cos returns the cosine of this chord angle. This method is more efficient than converting to Angle and performing the computation.

func (ChordAngle) Expanded Uses

func (c ChordAngle) Expanded(e float64) ChordAngle

Expanded returns a new ChordAngle that has been adjusted by the given error bound (which can be positive or negative). Error should be the value returned by either MaxPointError or MaxAngleError. For example:

a := ChordAngleFromPoints(x, y)
a1 := a.Expanded(a.MaxPointError())

func (ChordAngle) MaxAngleError Uses

func (c ChordAngle) MaxAngleError() float64

MaxAngleError returns the maximum error for a ChordAngle constructed as an Angle distance.

func (ChordAngle) MaxPointError Uses

func (c ChordAngle) MaxPointError() float64

MaxPointError returns the maximum error size for a ChordAngle constructed from 2 Points x and y, assuming that x and y are normalized to within the bounds guaranteed by s2.Point.Normalize. The error is defined with respect to the true distance after the points are projected to lie exactly on the sphere.

func (ChordAngle) Predecessor Uses

func (c ChordAngle) Predecessor() ChordAngle

Predecessor returns the largest representable ChordAngle less than this one.

Note the following special cases:

InfChordAngle.Predecessor == StraightChordAngle
ChordAngle(0).Predecessor == NegativeChordAngle
NegativeChordAngle.Predecessor == NegativeChordAngle

func (ChordAngle) Sin Uses

func (c ChordAngle) Sin() float64

Sin returns the sine of this chord angle. This method is more efficient than converting to Angle and performing the computation.

func (ChordAngle) Sin2 Uses

func (c ChordAngle) Sin2() float64

Sin2 returns the square of the sine of this chord angle. It is more efficient than Sin.

func (ChordAngle) Sub Uses

func (c ChordAngle) Sub(other ChordAngle) ChordAngle

Sub subtracts the other ChordAngle from this one and returns the resulting value. This method assumes the ChordAngles are not special.

func (ChordAngle) Successor Uses

func (c ChordAngle) Successor() ChordAngle

Successor returns the smallest representable ChordAngle larger than this one. This can be used to convert a "<" comparison to a "<=" comparison.

Note the following special cases:

NegativeChordAngle.Successor == 0
StraightChordAngle.Successor == InfChordAngle
InfChordAngle.Successor == InfChordAngle

func (ChordAngle) Tan Uses

func (c ChordAngle) Tan() float64

Tan returns the tangent of this chord angle.

type Interval Uses

type Interval struct {
    Lo, Hi float64
}

Interval represents a closed interval on a unit circle. Zero-length intervals (where Lo == Hi) represent single points. If Lo > Hi then the interval is "inverted". The point at (-1, 0) on the unit circle has two valid representations, [π,π] and [-π,-π]. We normalize the latter to the former in IntervalFromEndpoints. There are two special intervals that take advantage of that:

- the full interval, [-π,π], and
- the empty interval, [π,-π].

Treat the exported fields as read-only.

func EmptyInterval Uses

func EmptyInterval() Interval

EmptyInterval returns an empty interval.

func FullInterval Uses

func FullInterval() Interval

FullInterval returns a full interval.

func IntervalFromEndpoints Uses

func IntervalFromEndpoints(lo, hi float64) Interval

IntervalFromEndpoints constructs a new interval from endpoints. Both arguments must be in the range [-π,π]. This function allows inverted intervals to be created.

func IntervalFromPointPair Uses

func IntervalFromPointPair(a, b float64) Interval

IntervalFromPointPair returns the minimal interval containing the two given points. Both arguments must be in [-π,π].

func (Interval) AddPoint Uses

func (i Interval) AddPoint(p float64) Interval

AddPoint returns the interval expanded by the minimum amount necessary such that it contains the given point "p" (an angle in the range [-Pi, Pi]).

func (Interval) Center Uses

func (i Interval) Center() float64

Center returns the midpoint of the interval. It is undefined for full and empty intervals.

func (Interval) Contains Uses

func (i Interval) Contains(p float64) bool

Contains returns true iff the interval contains p. Assumes p ∈ [-π,π].

func (Interval) ContainsInterval Uses

func (i Interval) ContainsInterval(oi Interval) bool

ContainsInterval returns true iff the interval contains oi.

func (Interval) Expanded Uses

func (i Interval) Expanded(margin float64) Interval

Expanded returns an interval that has been expanded on each side by margin. If margin is negative, then the function shrinks the interval on each side by margin instead. The resulting interval may be empty or full. Any expansion (positive or negative) of a full interval remains full, and any expansion of an empty interval remains empty.

func (Interval) InteriorContains Uses

func (i Interval) InteriorContains(p float64) bool

InteriorContains returns true iff the interior of the interval contains p. Assumes p ∈ [-π,π].

func (Interval) InteriorContainsInterval Uses

func (i Interval) InteriorContainsInterval(oi Interval) bool

InteriorContainsInterval returns true iff the interior of the interval contains oi.

func (Interval) InteriorIntersects Uses

func (i Interval) InteriorIntersects(oi Interval) bool

InteriorIntersects returns true iff the interior of the interval contains any points in common with oi, including the latter's boundary.

func (Interval) Intersection Uses

func (i Interval) Intersection(oi Interval) Interval

Intersection returns the smallest interval that contains the intersection of the interval and oi.

func (Interval) Intersects Uses

func (i Interval) Intersects(oi Interval) bool

Intersects returns true iff the interval contains any points in common with oi.

func (Interval) Invert Uses

func (i Interval) Invert() Interval

Invert returns the interval with endpoints swapped.

func (Interval) IsEmpty Uses

func (i Interval) IsEmpty() bool

IsEmpty reports whether the interval is empty.

func (Interval) IsFull Uses

func (i Interval) IsFull() bool

IsFull reports whether the interval is full.

func (Interval) IsInverted Uses

func (i Interval) IsInverted() bool

IsInverted reports whether the interval is inverted; that is, whether Lo > Hi.

func (Interval) IsValid Uses

func (i Interval) IsValid() bool

IsValid reports whether the interval is valid.

func (Interval) Length Uses

func (i Interval) Length() float64

Length returns the length of the interval. The length of an empty interval is negative.

func (Interval) String Uses

func (i Interval) String() string

func (Interval) Union Uses

func (i Interval) Union(oi Interval) Interval

Union returns the smallest interval that contains both the interval and oi.

Bugs

The major differences from the C++ version are: - no unsigned E5/E6/E7 methods - no S2Point or S2LatLng constructors - no comparison or arithmetic operators

The major differences from the C++ version are: - no validity checking on construction, etc. (not a bug?) - a few operations

Package s1 imports 2 packages (graph) and is imported by 17 packages. Updated 2017-11-07. Refresh now. Tools for package owners.