pub struct Cap {
pub center: Point,
pub radius: ChordAngle,
}
Expand description
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
Implementations§
source§impl Cap
impl Cap
sourcepub fn from_center_angle(center: &Point, angle: &Angle) -> Self
pub fn from_center_angle(center: &Point, angle: &Angle) -> Self
from_center_angle constructs a cap with the given center and angle.
sourcepub fn from_center_chordangle(center: &Point, radius: &ChordAngle) -> Self
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.
sourcepub fn from_center_height(center: &Point, height: f64) -> Self
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.
sourcepub fn from_center_area(center: &Point, area: f64) -> Self
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.
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
is_empty reports whether the cap is empty, i.e. it contains no points.
sourcepub fn is_full(&self) -> bool
pub fn is_full(&self) -> bool
is_full reports whether the cap is empty, i.e. it contains no points.
sourcepub fn height(&self) -> f64
pub fn height(&self) -> f64
height returns the height of the cap. This is the distance from the center point to the cutoff plane.
sourcepub fn radius(&self) -> Angle
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).
sourcepub fn contains(&self, other: &Self) -> bool
pub fn contains(&self, other: &Self) -> bool
contains reports whether this cap contains the other.
sourcepub fn intersects(&self, other: &Self) -> bool
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.
sourcepub fn interior_intersects(&self, other: &Self) -> bool
pub fn interior_intersects(&self, other: &Self) -> bool
interior_intersects reports whether this caps interior intersects the other cap.
sourcepub fn contains_point(&self, p: &Point) -> bool
pub fn contains_point(&self, p: &Point) -> bool
contains_point reports whether this cap contains the point.
sourcepub fn interior_contains_point(&self, p: &Point) -> bool
pub fn interior_contains_point(&self, p: &Point) -> bool
interior_contains_point reports whether the point is within the interior of this cap.
sourcepub fn complement(&self) -> 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.
source§impl Cap
impl Cap
sourcepub fn centroid(&self) -> Point
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.
Trait Implementations§
source§impl<'de> Deserialize<'de> for Cap
impl<'de> Deserialize<'de> for Cap
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
source§impl PartialEq<Cap> for Cap
impl PartialEq<Cap> for Cap
source§impl Region for Cap
impl Region for Cap
source§fn cap_bound(&self) -> Cap
fn cap_bound(&self) -> Cap
cap_bound returns a bounding spherical cap. This is not guaranteed to be exact.
source§fn rect_bound(&self) -> Rect
fn rect_bound(&self) -> Rect
rect_bound returns a bounding latitude-longitude rectangle. The bounds are not guaranteed to be tight.
source§fn contains_cell(&self, cell: &Cell) -> bool
fn contains_cell(&self, cell: &Cell) -> bool
contains_cell reports whether the cap contains the given cell.
source§fn intersects_cell(&self, cell: &Cell) -> bool
fn intersects_cell(&self, cell: &Cell) -> bool
intersects_cell reports whether the cap intersects the cell.
source§fn cell_union_bound(&self) -> Vec<CellID>
fn cell_union_bound(&self) -> Vec<CellID>
cell_union_bound computes a covering of the given cap. In general the covering consists of at most 4 cells (except for very large caps, which may need up to 6 cells). The output is not sorted.