Coverage for python/lsst/sphgeom/pixelization_abc.py: 82%

22 statements  

« prev     ^ index     » next       coverage.py v7.5.0, created at 2024-05-02 03:12 -0700

1# This file is part of sphgeom. 

2# 

3# Developed for the LSST Data Management System. 

4# This product includes software developed by the LSST Project 

5# (http://www.lsst.org). 

6# See the COPYRIGHT file at the top-level directory of this distribution 

7# for details of code ownership. 

8# 

9# This software is dual licensed under the GNU General Public License and also 

10# under a 3-clause BSD license. Recipients may choose which of these licenses 

11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt, 

12# respectively. If you choose the GPL option then the following text applies 

13# (but note that there is still no warranty even if you opt for BSD instead): 

14# 

15# This program is free software: you can redistribute it and/or modify 

16# it under the terms of the GNU General Public License as published by 

17# the Free Software Foundation, either version 3 of the License, or 

18# (at your option) any later version. 

19# 

20# This program is distributed in the hope that it will be useful, 

21# but WITHOUT ANY WARRANTY; without even the implied warranty of 

22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

23# GNU General Public License for more details. 

24# 

25# You should have received a copy of the GNU General Public License 

26# along with this program. If not, see <http://www.gnu.org/licenses/>. 

27__all__ = ["PixelizationABC"] 

28 

29import abc 

30 

31from ._sphgeom import RangeSet, Region, UnitVector3d 

32 

33 

34class PixelizationABC(abc.ABC): 

35 """Pixelization ABC class that should be a base for 

36 Python implementations of pixelization. 

37 """ 

38 

39 @abc.abstractmethod 

40 def universe(self) -> RangeSet: 

41 """Return the set of all pixel indexes for this pixelization. 

42 

43 Returns 

44 ------- 

45 rangeSet : `lsst.sphgeom.RangeSet` 

46 """ 

47 pass 

48 

49 @abc.abstractmethod 

50 def pixel(self, i) -> Region: 

51 """Return the spherical region corresponding to the pixel index ``i``. 

52 

53 This region will contain all unit vectors v with ``index(v) == i``. 

54 But it may also contain points with index not equal to ``i``. 

55 To see why, consider a point that lies on the edge of a polygonal 

56 pixel - it is inside the polygons for both pixels sharing the edge, 

57 but must be assigned to exactly one pixel by the pixelization. 

58 

59 Parameters 

60 ---------- 

61 i : `int` 

62 Pixel index. 

63 

64 Returns 

65 ------- 

66 region : `lsst.sphgeom.Region` 

67 The spherical region corresponding to the pixel with index ``i`` 

68 

69 Raises 

70 ------ 

71 `InvalidArgumentException` 

72 Raised if ``i`` is not a valid pixel index. 

73 """ 

74 pass 

75 

76 @abc.abstractmethod 

77 def index(self, v: UnitVector3d) -> int: 

78 """Compute the index of the pixel. 

79 

80 Parameters 

81 ---------- 

82 v : `lsst.sphgeom.UnitVector3d` 

83 

84 Returns 

85 ------- 

86 i : `int` 

87 The index of the pixel. 

88 """ 

89 pass 

90 

91 @abc.abstractmethod 

92 def toString(self, i: int) -> str: 

93 """Convert the given pixel index to a human-readable string. 

94 

95 Parameters 

96 ---------- 

97 i : `int` 

98 

99 Returns 

100 ------- 

101 s : `str` 

102 """ 

103 pass 

104 

105 @abc.abstractmethod 

106 def envelope(self, region: Region, maxRanges: int = 0): 

107 """Return the indexes of the pixels intersecting the spherical region. 

108 

109 The ``maxRanges`` parameter can be used to limit both these costs - 

110 setting it to a non-zero value sets a cap on the number of ranges 

111 returned by this method. To meet this constraint, implementations are 

112 allowed to return pixels that do not intersect the region along with 

113 those, that do. 

114 This allows two ranges [a, b) and [c, d), a < b < c < d, to be 

115 merged into one range [a, d) (by adding in the pixels [b, c)). Since 

116 simplification proceeds by adding pixels, the return value will always 

117 be a superset of the intersecting pixels. 

118 

119 Parameters 

120 ---------- 

121 region : `lsst.sphgeom.Region` 

122 maxRanges : `int` 

123 

124 Returns 

125 ------- 

126 rangeSet : `lsst.sphgeom.RangeSet` 

127 """ 

128 pass 

129 

130 @abc.abstractmethod 

131 def interior(self, region: Region, maxRanges: int = 0): 

132 """Return the indexes of the pixels within the spherical region. 

133 

134 The ``maxRanges`` argument is analogous to the identically named 

135 envelope() argument. The only difference is that implementations must 

136 remove interior pixels to keep the number of ranges at or below the 

137 maximum. The return value is therefore always a subset of the interior 

138 pixels. 

139 

140 Parameters 

141 ---------- 

142 region : `lsst.sphgeom.Region` 

143 maxRanges : `int` 

144 

145 Returns 

146 ------- 

147 rangeSet : `lsst.sphgeom.RangeSet` 

148 """ 

149 pass