1 // Copyright 2014 Google Inc. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package s2 16 17 // A Region represents a two-dimensional region on the unit sphere. 18 // 19 // The purpose of this interface is to allow complex regions to be 20 // approximated as simpler regions. The interface is restricted to methods 21 // that are useful for computing approximations. 22 type Region interface { 23 // CapBound returns a bounding spherical cap. This is not guaranteed to be exact. 24 CapBound() Cap 25 26 // RectBound returns a bounding latitude-longitude rectangle that contains 27 // the region. The bounds are not guaranteed to be tight. 28 RectBound() Rect 29 30 // ContainsCell reports whether the region completely contains the given region. 31 // It returns false if containment could not be determined. 32 ContainsCell(c Cell) bool 33 34 // IntersectsCell reports whether the region intersects the given cell or 35 // if intersection could not be determined. It returns false if the region 36 // does not intersect. 37 IntersectsCell(c Cell) bool 38 39 // ContainsPoint reports whether the region contains the given point or not. 40 // The point should be unit length, although some implementations may relax 41 // this restriction. 42 ContainsPoint(p Point) bool 43 44 // CellUnionBound returns a small collection of CellIDs whose union covers 45 // the region. The cells are not sorted, may have redundancies (such as cells 46 // that contain other cells), and may cover much more area than necessary. 47 // 48 // This method is not intended for direct use by client code. Clients 49 // should typically use Covering, which has options to control the size and 50 // accuracy of the covering. Alternatively, if you want a fast covering and 51 // don't care about accuracy, consider calling FastCovering (which returns a 52 // cleaned-up version of the covering computed by this method). 53 // 54 // CellUnionBound implementations should attempt to return a small 55 // covering (ideally 4 cells or fewer) that covers the region and can be 56 // computed quickly. The result is used by RegionCoverer as a starting 57 // point for further refinement. 58 CellUnionBound() []CellID 59 } 60 61 // Enforce Region interface satisfaction. 62 var ( 63 _ Region = Cap{} 64 _ Region = Cell{} 65 _ Region = (*CellUnion)(nil) 66 _ Region = (*Loop)(nil) 67 _ Region = Point{} 68 _ Region = (*Polygon)(nil) 69 _ Region = (*Polyline)(nil) 70 _ Region = Rect{} 71 ) 72