Struct s2::cap::Cap

pub struct Cap {
    pub center: Point,
    pub radius: ChordAngle,
}

Cap represents a disc-shaped region defined by a center and radius. Technically this shape is called a "spherical cap" (rather than disc) because it is not planar; the cap represents a portion of the sphere that has been cut off by a plane. The boundary of the cap is the circle defined by the intersection of the sphere and the plane. For containment purposes, the cap is a closed set, i.e. it contains its boundary.

For the most part, you can use a spherical cap wherever you would use a disc in planar geometry. The radius of the cap is measured along the surface of the sphere (rather than the straight-line distance through the interior). Thus a cap of radius π/2 is a hemisphere, and a cap of radius π covers the entire sphere.

The center is a point on the surface of the unit sphere. (Hence the need for it to be of unit length.)

A cap can also be defined by its center point and height. The height is the distance from the center point to the cutoff plane. There is also support for "empty" and "full" caps, which contain no points and all points respectively.

Here are some useful relationships between the cap height (h), the cap radius (r), the maximum chord length from the cap's center (d), and the radius of cap's base (a).

    h = 1 - cos(r)
      = 2 * sin^2(r/2)
  d^2 = 2 * h
      = a^2 + h^2

The zero value of Cap is an invalid cap. Use EmptyCap to get a valid empty cap.

Fields

center: Point

radius: ChordAngle

Methods

impl Cap

pub fn from_center_angle(center: &Point, angle: &Angle) -> Self

from_center_angle constructs a cap with the given center and angle.

pub fn from_center_chordangle(center: &Point, radius: &ChordAngle) -> Self

from_center_chordangle constructs a cap where the angle is expressed as an s1.ChordAngle. This constructor is more efficient than using an s1.Angle.

pub fn from_center_height(center: &Point, height: f64) -> Self

from_center_height constructs a cap with the given center and height. A negative height yields an empty cap; a height of 2 or more yields a full cap. The center should be unit length.

pub fn from_center_area(center: &Point, area: f64) -> Self

from_center_area constructs a cap with the given center and surface area. Note that the area can also be interpreted as the solid angle subtended by the cap (because the sphere has unit radius). A negative area yields an empty cap; an area of 4*π or more yields a full cap.

pub fn empty() -> Cap

empty returns a cap that contains no points.

pub fn full() -> Cap

full returns a cap that contains all points.

pub fn is_valid(&self) -> bool

is_valid reports whether the Cap is considered valid.

pub fn is_empty(&self) -> bool

is_empty reports whether the cap is empty, i.e. it contains no points.

pub fn is_full(&self) -> bool

is_full reports whether the cap is empty, i.e. it contains no points.

pub fn center(&self) -> &Point

center returns the cap's center point.

pub fn height(&self) -> f64

height returns the height of the cap. This is the distance from the center point to the cutoff plane.

pub fn radius(&self) -> Angle

radius returns the cap radius as an Angle. (Note that the cap angle is stored internally as a ChordAngle, so this method requires a trigonometric operation and may yield a slightly different result than the value passed to Cap::from_center_angle).

pub fn area(&self) -> f64

area returns the surface area of the Cap on the unit sphere.

pub fn contains(&self, other: &Self) -> bool

contains reports whether this cap contains the other.

pub fn intersects(&self, other: &Self) -> bool

intersects reports whether this cap intersects the other cap. i.e. whether they have any points in common.

pub fn interior_intersects(&self, other: &Self) -> bool

interior_intersects reports whether this caps interior intersects the other cap.

pub fn contains_point(&self, p: &Point) -> bool

contains_point reports whether this cap contains the point.

pub fn interior_contains_point(&self, p: &Point) -> bool

interior_contains_point reports whether the point is within the interior of this cap.

pub fn complement(&self) -> Cap

complement returns the complement of the interior of the cap. A cap and its complement have the same boundary but do not share any interior points. The complement operator is not a bijection because the complement of a singleton cap (containing a single point) is the same as the complement of an empty cap.

pub fn approx_eq(&self, other: &Self) -> bool

approx_eq reports whether this cap is equal to the other cap within the given tolerance.

pub fn expanded(&self, distance: &Angle) -> Cap

expanded returns a new cap expanded by the given angle. If the cap is empty, it returns an empty cap.

impl Cap

pub fn centroid(&self) -> Point

Centroid returns the true centroid of the cap multiplied by its surface area The result lies on the ray from the origin through the cap's center, but it is not unit length. Note that if you just want the "surface centroid", i.e. the normalized result, then it is simpler to call Center.

The reason for multiplying the result by the cap area is to make it easier to compute the centroid of more complicated shapes. The centroid of a union of disjoint regions can be computed simply by adding their Centroid() results. Caveat: for caps that contain a single point (i.e., zero radius), this method always returns the origin (0, 0, 0). This is because shapes with no area don't affect the centroid of a union whose total area is positive.

pub fn union(&self, other: &Self) -> Self

union returns the smallest cap which encloses this cap and other.

Trait Implementations

impl Clone for Cap

fn clone(&self) -> Cap

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cap

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a> From<&'a Point> for Cap

fn from(p: &'a Point) -> Self

constructs a cap containing a single point.

impl Region for Cap

fn cap_bound(&self) -> Cap

cap_bound returns a bounding spherical cap. This is not guaranteed to be exact.

fn rect_bound(&self) -> Rect

rect_bound returns a bounding latitude-longitude rectangle. The bounds are not guaranteed to be tight.

fn contains_cell(&self, cell: &Cell) -> bool

contains_cell reports whether the cap contains the given cell.

fn intersects_cell(&self, cell: &Cell) -> bool

intersects_cell reports whether the cap intersects the cell.

impl PartialEq for Cap

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> Add<&'a Point> for Cap

type Output = Cap

The resulting type after applying the + operator.

fn add(self, p: &'a Point) -> Self::Output

increases the cap if necessary to include the given point. If this cap is empty, then the center is set to the point with a zero height. p must be unit-length.

impl<'a> Add<&'a Cap> for Cap

type Output = Cap

The resulting type after applying the + operator.

fn add(self, other: &'a Cap) -> Self::Output

increases the cap height if necessary to include the other cap. If this cap is empty, it is set to the other cap.

impl Add<Cap> for Cap

type Output = Cap

The resulting type after applying the + operator.

fn add(self, other: Cap) -> Self::Output

Performs the + operation.

impl Display for Cap

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.