Coverage for python/lsst/sphgeom/pixelization_abc.py: 75%
22 statements
« prev ^ index » next coverage.py v6.4, created at 2022-05-24 02:22 -0700
« prev ^ index » next coverage.py v6.4, created at 2022-05-24 02:22 -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 program is free software: you can redistribute it and/or modify
10# it under the terms of the GNU General Public License as published by
11# the Free Software Foundation, either version 3 of the License, or
12# (at your option) any later version.
13#
14# This program is distributed in the hope that it will be useful,
15# but WITHOUT ANY WARRANTY; without even the implied warranty of
16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17# GNU General Public License for more details.
18#
19# You should have received a copy of the GNU General Public License
20# along with this program. If not, see <http://www.gnu.org/licenses/>.
21__all__ = ["PixelizationABC"]
23import abc
24from ._sphgeom import RangeSet, Region, UnitVector3d
27class PixelizationABC(abc.ABC):
28 """Pixelization ABC class that should be a base for
29 Python implementations of pixelization.
30 """
32 @abc.abstractmethod
33 def universe(self) -> RangeSet:
34 """Return the set of all pixel indexes for this pixelization.
36 Returns
37 -------
38 rangeSet : `lsst.sphgeom.RangeSet`
39 """
40 pass
42 @abc.abstractmethod
43 def pixel(self, i) -> Region:
44 """Return the spherical region corresponding to the pixel index ``i``.
46 This region will contain all unit vectors v with ``index(v) == i``.
47 But it may also contain points with index not equal to ``i``.
48 To see why, consider a point that lies on the edge of a polygonal
49 pixel - it is inside the polygons for both pixels sharing the edge,
50 but must be assigned to exactly one pixel by the pixelization.
52 Parameters
53 ----------
54 i : `int`
55 Pixel index.
57 Returns
58 -------
59 region : `lsst.sphgeom.Region`
60 The spherical region corresponding to the pixel with index ``i``
62 Raises
63 ------
64 `InvalidArgumentException`
65 Raised if ``i`` is not a valid pixel index.
66 """
67 pass
69 @abc.abstractmethod
70 def index(self, v: UnitVector3d) -> int:
71 """ Compute the index of the pixel.
73 Parameters
74 ----------
75 v : `lsst.sphgeom.UnitVector3d`
77 Returns
78 -------
79 i : `int`
80 The index of the pixel.
81 """
82 pass
84 @abc.abstractmethod
85 def toString(self, i: int) -> str:
86 """Convert the given pixel index to a human-readable string.
88 Parameters
89 ----------
90 i : `int`
92 Returns
93 -------
94 s : `str`
95 """
96 pass
98 @abc.abstractmethod
99 def envelope(self, region: Region, maxRanges: int = 0):
100 """Return the indexes of the pixels intersecting the spherical region.
102 The ``maxRanges`` parameter can be used to limit both these costs -
103 setting it to a non-zero value sets a cap on the number of ranges
104 returned by this method. To meet this constraint, implementations are
105 allowed to return pixels that do not intersect the region along with
106 those, that do.
107 This allows two ranges [a, b) and [c, d), a < b < c < d, to be
108 merged into one range [a, d) (by adding in the pixels [b, c)). Since
109 simplification proceeds by adding pixels, the return value will always
110 be a superset of the intersecting pixels.
112 Parameters
113 ----------
114 region : `lsst.sphgeom.Region`
115 maxRanges : `int`
117 Returns
118 -------
119 rangeSet : `lsst.sphgeom.RangeSet`
120 """
121 pass
123 @abc.abstractmethod
124 def interior(self, region: Region, maxRanges: int = 0):
125 """Return the indexes of the pixels within the spherical region.
127 The ``maxRanges`` argument is analogous to the identically named
128 envelope() argument. The only difference is that implementations must
129 remove interior pixels to keep the number of ranges at or below the
130 maximum. The return value is therefore always a subset of the interior
131 pixels.
133 Parameters
134 ----------
135 region : `lsst.sphgeom.Region`
136 maxRanges : `int`
138 Returns
139 -------
140 rangeSet : `lsst.sphgeom.RangeSet`
141 """
142 pass