LSST Applications  21.0.0-147-g0e635eb1+1acddb5be5,22.0.0+052faf71bd,22.0.0+1ea9a8b2b2,22.0.0+6312710a6c,22.0.0+729191ecac,22.0.0+7589c3a021,22.0.0+9f079a9461,22.0.1-1-g7d6de66+b8044ec9de,22.0.1-1-g87000a6+536b1ee016,22.0.1-1-g8e32f31+6312710a6c,22.0.1-10-gd060f87+016f7cdc03,22.0.1-12-g9c3108e+df145f6f68,22.0.1-16-g314fa6d+c825727ab8,22.0.1-19-g93a5c75+d23f2fb6d8,22.0.1-19-gb93eaa13+aab3ef7709,22.0.1-2-g8ef0a89+b8044ec9de,22.0.1-2-g92698f7+9f079a9461,22.0.1-2-ga9b0f51+052faf71bd,22.0.1-2-gac51dbf+052faf71bd,22.0.1-2-gb66926d+6312710a6c,22.0.1-2-gcb770ba+09e3807989,22.0.1-20-g32debb5+b8044ec9de,22.0.1-23-gc2439a9a+fb0756638e,22.0.1-3-g496fd5d+09117f784f,22.0.1-3-g59f966b+1e6ba2c031,22.0.1-3-g849a1b8+f8b568069f,22.0.1-3-gaaec9c0+c5c846a8b1,22.0.1-32-g5ddfab5d3+60ce4897b0,22.0.1-4-g037fbe1+64e601228d,22.0.1-4-g8623105+b8044ec9de,22.0.1-5-g096abc9+d18c45d440,22.0.1-5-g15c806e+57f5c03693,22.0.1-7-gba73697+57f5c03693,master-g6e05de7fdc+c1283a92b8,master-g72cdda8301+729191ecac,w.2021.39
LSST Data Management Base Package
Classes | Functions
lsst.afw.geom._hpxUtils Namespace Reference

Classes

class  _ZOrderCurve2DInt
 

Functions

def makeHpxWcs (hips_order, pixel, shift_order=9)
 

Function Documentation

◆ makeHpxWcs()

def lsst.afw.geom._hpxUtils.makeHpxWcs (   hips_order,
  pixel,
  shift_order = 9 
)
Make a SkyWcs object with HEALPix grid projection (HPX).

The SkyWcs generated by this function is suitable to be used with a
Hierarchical Progressive Survey (HiPS) FITS image as described in
https://www.ivoa.net/documents/HiPS/20170519/REC-HIPS-1.0-20170519.pdf

A HiPS image covers one HEALPix cell, with the HEALPix nside equal to
2**hips_order. Each cell is 'shift_order' orders deeper than the HEALPix
cell, with 2**shift_order x 2**shift_order sub-pixels on a side, which
defines the target resolution of the HiPS image. The IVOA recommends
shift_order=9, for 2**9=512 pixels on a side.  See Notes below to
convert from hips_order to image resolution.

Parameters
----------
hips_order : `int`
    HiPS order, such that HEALPix nside=2**hips_order.
    Must be a positive integer.
pixel : `int`
    Pixel number in the nest ordering scheme.
shift_order : `int`, optional
    Shift order for subpixels, such that there are 2**shift_order
    sub-pixels on a side of the HiPS cell.
    Must be a positive integer.

Returns
-------
wcs : `lsst.geom.SkyWcs`

Raises
------
`ValueError`: Raise if hips_order is <=0, or if shift_order is <=0, or
    if pixel number is out of range for the given hips_order
    (0 <= pixel < 12*nside*nside).

Notes
-----
Table 5 from
https://www.ivoa.net/documents/HiPS/20170519/REC-HIPS-1.0-20170519.pdf
shows the relationship between hips_order, number of tiles (full
sky coverage), cell size, and sub-pixel size/image resolution (with
the default shift_order=9):

+------------+-----------------+--------------+------------------+
| hips_order | Number of Tiles | Cell Size    | Image Resolution |
+============+=================+==============+==================+
| 0          | 12              | 58.63 deg    | 6.871 arcmin     |
| 1          | 48              | 29.32 deg    | 3.435 arcmin     |
| 2          | 192             | 14.66 deg    | 1.718 arcmin     |
| 3          | 768             | 7.329 deg    | 51.53 arcsec     |
| 4          | 3072            | 3.665 deg    | 25.77 arcsec     |
| 5          | 12288           | 1.832 deg    | 12.88 arcsec     |
| 6          | 49152           | 54.97 arcmin | 6.442 arcsec     |
| 7          | 196608          | 27.48 arcmin | 3.221 arcsec     |
| 8          | 786432          | 13.74 arcmin | 1.61 arcsec      |
| 9          | 3145728         | 6.871 arcmin | 805.2mas         |
| 10         | 12582912        | 3.435 arcmin | 402.6mas         |
| 11         | 50331648        | 1.718 arcmin | 201.3mas         |
| 12         | 201326592       | 51.53 arcsec | 100.6mas         |
| 13         | 805306368       | 25.77 arcsec | 50.32mas         |
+------------+-----------------+--------------+------------------+

Definition at line 31 of file _hpxUtils.py.

31 def makeHpxWcs(hips_order, pixel, shift_order=9):
32  """
33  Make a SkyWcs object with HEALPix grid projection (HPX).
34 
35  The SkyWcs generated by this function is suitable to be used with a
36  Hierarchical Progressive Survey (HiPS) FITS image as described in
37  https://www.ivoa.net/documents/HiPS/20170519/REC-HIPS-1.0-20170519.pdf
38 
39  A HiPS image covers one HEALPix cell, with the HEALPix nside equal to
40  2**hips_order. Each cell is 'shift_order' orders deeper than the HEALPix
41  cell, with 2**shift_order x 2**shift_order sub-pixels on a side, which
42  defines the target resolution of the HiPS image. The IVOA recommends
43  shift_order=9, for 2**9=512 pixels on a side. See Notes below to
44  convert from hips_order to image resolution.
45 
46  Parameters
47  ----------
48  hips_order : `int`
49  HiPS order, such that HEALPix nside=2**hips_order.
50  Must be a positive integer.
51  pixel : `int`
52  Pixel number in the nest ordering scheme.
53  shift_order : `int`, optional
54  Shift order for subpixels, such that there are 2**shift_order
55  sub-pixels on a side of the HiPS cell.
56  Must be a positive integer.
57 
58  Returns
59  -------
60  wcs : `lsst.geom.SkyWcs`
61 
62  Raises
63  ------
64  `ValueError`: Raise if hips_order is <=0, or if shift_order is <=0, or
65  if pixel number is out of range for the given hips_order
66  (0 <= pixel < 12*nside*nside).
67 
68  Notes
69  -----
70  Table 5 from
71  https://www.ivoa.net/documents/HiPS/20170519/REC-HIPS-1.0-20170519.pdf
72  shows the relationship between hips_order, number of tiles (full
73  sky coverage), cell size, and sub-pixel size/image resolution (with
74  the default shift_order=9):
75 
76  +------------+-----------------+--------------+------------------+
77  | hips_order | Number of Tiles | Cell Size | Image Resolution |
78  +============+=================+==============+==================+
79  | 0 | 12 | 58.63 deg | 6.871 arcmin |
80  | 1 | 48 | 29.32 deg | 3.435 arcmin |
81  | 2 | 192 | 14.66 deg | 1.718 arcmin |
82  | 3 | 768 | 7.329 deg | 51.53 arcsec |
83  | 4 | 3072 | 3.665 deg | 25.77 arcsec |
84  | 5 | 12288 | 1.832 deg | 12.88 arcsec |
85  | 6 | 49152 | 54.97 arcmin | 6.442 arcsec |
86  | 7 | 196608 | 27.48 arcmin | 3.221 arcsec |
87  | 8 | 786432 | 13.74 arcmin | 1.61 arcsec |
88  | 9 | 3145728 | 6.871 arcmin | 805.2mas |
89  | 10 | 12582912 | 3.435 arcmin | 402.6mas |
90  | 11 | 50331648 | 1.718 arcmin | 201.3mas |
91  | 12 | 201326592 | 51.53 arcsec | 100.6mas |
92  | 13 | 805306368 | 25.77 arcsec | 50.32mas |
93  +------------+-----------------+--------------+------------------+
94  """
95  if shift_order <= 0:
96  raise ValueError(f"shift_order {shift_order} must be positive.")
97  hips_tilepix = 2**shift_order
98 
99  if hips_order <= 0:
100  raise ValueError(f"order {hips_order} must be positive.")
101  nside_cell = 2**hips_order
102 
103  if pixel < 0 or pixel >= 12*nside_cell*nside_cell:
104  raise ValueError(f"pixel value {pixel} out of range.")
105 
106  # The HEALPix grid projection (HPX) is defined in the FITS standard
107  # https://fits.gsfc.nasa.gov/standard40/fits_standard40aa-le.pdf
108  # from Calabretta & Roukema (2007)
109  # https://ui.adsabs.harvard.edu/abs/2007MNRAS.381..865C/abstract
110  # which defines the standard H = 4, K = 3 pixelization parameters
111  # encoded in PV2_1 = H, PV2_2 = K.
112  # The CRVAL1, CRVAL2 values should always be 0, 0 according to
113  # the FITS standard.
114  # The CD matrix is defined in wcslib HPXcvt.c.
115  # The Calabretta & Roukema (2007) paper and wcslib HPXcvt.c only
116  # define full-sky HPX projections. For single pixels we
117  # use the code from AladinSrc.jar Tile2HPX.java to compute
118  # CRPIX1, CRPIX2.
119 
120  # The nside of the sub-pixels is the product of the tile nside
121  # and the number of sub-pixels on a side.
122  nside_pix = nside_cell*hips_tilepix
123  # All tiles are rotated 45 degrees.
124  cos45 = np.sqrt(2.0)/2.0
125  # This defines the pixel scale.
126  scale = 90.0/nside_pix/np.sqrt(2.0)
127  cos45_scale = cos45*scale
128  # The projected center of the pixel used for the HPX header is
129  # a non-trivial computation, and typically is outside of the
130  # tile pixel itself. Therefore, these values are not the same
131  # as the values computed from healpy.pix2ang().
132  cent_ra_proj, cent_dec_proj = _hpx_projected_center(hips_order, pixel)
133 
134  md = PropertySet()
135  md['CD1_1'] = -cos45_scale
136  md['CD1_2'] = -cos45_scale
137  md['CD2_1'] = cos45_scale
138  md['CD2_2'] = -cos45_scale
139  md['CTYPE1'] = 'RA---HPX'
140  md['CTYPE2'] = 'DEC--HPX'
141  md['CRVAL1'] = 0.0
142  md['CRVAL2'] = 0.0
143  md['PV2_1'] = 4
144  md['PV2_2'] = 3
145  md['CRPIX1'] = ((hips_tilepix + 1)/2.0) - 0.5*(-cent_ra_proj/cos45_scale + cent_dec_proj/cos45_scale)
146  md['CRPIX2'] = ((hips_tilepix + 1)/2.0) - 0.5*(-cent_ra_proj/cos45_scale - cent_dec_proj/cos45_scale)
147 
148  return makeSkyWcs(md)
149 
150 
def makeHpxWcs(hips_order, pixel, shift_order=9)
Definition: _hpxUtils.py:31
std::shared_ptr< SkyWcs > makeSkyWcs(daf::base::PropertySet &metadata, bool strip=false)
Construct a SkyWcs from FITS keywords.
Definition: SkyWcs.cc:521