How to find which corner is which in tile drawing

[cdeil]

@adl1995 and I started to play with healpy.boundaries and try to prototype the affine transformation drawing method (see end of this notebook):
https://github.com/adl1995/HIPS-to-Py/blob/master/examples/draw-healpix-stuff.ipynb

One issue we ran into is healpy/healpy#393 , the other (somewhat related) blocker for implementing a first working version is that we don't know how to find out which of the four corners returned by healpy.boundaries corresponds to which corner of the HIPS tile. I don't see anything in healpy that would let us compute this directly.

@tboch - Could you clarify this point in the description?
https://hips.readthedocs.io/en/latest/drawing_algo.html#naive-algorithm
(or directly here in a comment if you prefer).

[tboch]

Figure 4, page 10 of HiPS document http://ivoa.net/documents/HiPS/20170406/PR-HIPS-1.0-20170406.pdf should help
I'll update the drawing algo document to detail this.

[tboch]

Looking closely after this, I found out that healpy.boundaries always returns the corners in this order: N, W, S, E where N (resp. W, S, E) is the corner roughly pointing towards the North (resp. West, South and East) :

The corresponding tile corners are as follow:

To summarize, if we consider the origin of the tile to be at the lower left, and a tile of size 512x512:

• 1st corner (N) returned by healpy.boundaries corresponds to tile coordinate (511, 0)
• 2nd one (W) corresponds to coordinate (511, 511)
• 3rd (S) corresponds to (0, 511)
• 4th (E) corresponds to (0, 0)

[cdeil]

@tboch - Thanks!

We should make sure this info makes it into our docs before closing this issue.

@adl1995 - one thing you could do now is make a PR to improve the docstring of https://hips.readthedocs.io/en/latest/api/hips.utils.boundaries.html to mention the order of corners returned.
Actually the docstring currently only says

Returns an array containing the angle (theta and phi) in radians.
and doesn't mention "corners" at all -> please change this.
Another change I would suggest is to go from default nest=False to nest=True, because this is just a helper function we use in hips, and HiPS always uses the nested scheme.
Finally, I notice that from our docstring the link to healpy.boundaries works, but the one to healpy.vec2ang is broken. The reason, I think is that you have to link to healpy.pixelfunc.vec2ang instead, because you're creating an "instersphinx" link and healpy.pixelfunc.vec2ang is the location the function appears in their API docs:
https://healpy.readthedocs.io/en/latest/generated/healpy.pixelfunc.vec2ang.html

@tboch - Another question I have concerning https://hips.readthedocs.io/en/latest/drawing_algo.html is how to get the tile pixel corner coordinates you mention exactly right. Above you mention that the corners are at coordinates 0 and 511. If we used the common convention in Numpy / Astropy image processing (described here: https://photutils.readthedocs.io/en/stable/photutils/overview.html#coordinate-conventions), then 0 and 511 would be the centers of the corner pixels. The real outermost edge of the tile would be at -0.5 and 511.5, right? There's also this step 6 which is a bit vague:

We extend the tile by 1 pixel in all directions in order to hide “stitches” with other tiles drawing.

Do you mean to call e.g. https://docs.scipy.org/doc/numpy/reference/generated/numpy.pad.html with pad_width=1 and mode=edge, resulting in an array or size 513 x 513?
In this case, @adl1995 should use pixel coordinates of +0.5 and 512.5 as the "control points" to define the affine transform mapping, right?

I think it could be helpful to spell out these details in the drawing description, but @tboch of course if you prefer to keep it higher level, it'll also work and we'll just have to make sure there's no 0.5 or 1 pix errors in the implementation once the pull request by @adl1995 comes in.

[cdeil]

I added a utility function with a docstring in #78 that describes which corner is which.

I'm keeping this issue open because of the last point mentioned in my previous comment: I'm not sure if our corner coordinates are currently correct, or whether we're off by 0.5 or 1 pix. This will need a detailed look and checks.