Firefly-2020: render HiPS more accurately

[robyww]

Firefly-2020: render HiPS more accurately

• zoom in HiPS should be very close to the extracted hips pixel when WCS matched
• render subtile to create more accuracy
• Fixed: HiPS sometimes loses WCS lock with image

Testing

• https://firefly-2120-hips-accuracy.irsakubedev.ipac.caltech.edu/firefly
• try the spherex hips or the panstarrs
  • https://irsadev.ipac.caltech.edu/data/hips/SPHEREx/spherex_allsky_cube_alpha1
• extract a fits tile
• using mouse lock, click on a pixel, the marker will be very close to the same location

[tgoldina]

For spectrum extraction, the tile display must be accurate to better than one tile pixel. Firefly
reads the spectrum from the correct cube pixel for the clicked position, but if the image is
displaced, the user clicks where a source appears and extracts a spectrum from the wrong location.

The branch reaches sub-pixel accuracy for most tiles when zoomed in past the deepest HiPS order.
Two cases remain:

• (1) Zoomed in past the deepest order: tiles touching a pole, and tiles on the HEALPix fold
  (Dec ±41.81°) near its vertices, are still off by up to about 17–18 tile pixels. Example: Pan-STARRS g star Gaia DR3 384271381105076096 (0.81758 +41.80969).
• (2) At normal zoom (not past the deepest order): tiles are drawn as before, so most tiles are
  still off by more than one pixel (2.4–2.8 px at mid-latitudes at SPHEREx order 5), and pole tiles
  by about 120 px at every order. Example: Polaris.

To reproduce:

• HiPS URL: https://alasky.cds.unistra.fr/Pan-STARRS/DR1/g

• Zoomed in past the deepest order:

  • Target: 0.81758 +41.80969
  • Field of View: 0.01
  • Notice that the target marker is in the middle of the extracted view, but on the side in the HiPS
  • 

• At normal zoom (not past the deepest order)

  • Target: 13.96396 +89.95997
  • Field of View: 0.05
  • Notice how the target marker os offset in Normal zoom, it jumps when zoomed in
  • 

[tgoldina]

CLAUDE REVIEW FINDINGS

1. High: sub-cells are still drawn as 4 triangles around the average of their corners

drawOneHiPSTile (iv/HiPSSingleTileRender.js:57) is unchanged:

const triangles= norder > isMaxOrder && desiredNorder>norder ? 4 : 2;

normalCaseDrawOneCell passes it the parent's norder and desiredNorder, so every sub-cell is
drawn with 4 triangles meeting at the average of its projected corners. On fold tiles those
triangles cross the crease. The fold-vertex error is 18 px at n = 4 at every order: about 3.6″ on
Pan-STARRS at order 11, down from 14.6″ but not fixed.

Fix: draw sub-cells with 2 triangles split along the current corner 1–3 diagonal, or keep 4
triangles but use the projected true centre of each sub-cell. Either brings the fold vertex to
0.18 px at order 5 and 0.003 px at order 11. The general rule: never draw a HEALPix tile with
triangles whose edges cross the polar facets' x + y = 1 diagonal; the corner 1–3 split
always follows it.

2. High: subdivision stops at 2 levels, which isn't enough near the poles

computeDeeperTiles goes at most to grandchildren (n = 4). Pole tiles stay about 17 px off and
the worst polar tile about 5.6 px. At the pole the error in each order's own pixels is the same at
every order, so Pan-STARRS still shows about 3.4″ at the pole when zoomed in.

Fix: refine deeper at high |Dec| (n ≥ 16 above about 80°), and for the 8 tiles at each order
that touch a pole keep splitting only the cell that contains the pole. Getting the pole piece
under 0.5 px needs it to be about 1/128–1/256 of the tile, only about 20–25 extra pieces.

3. Medium: nothing changes when not zoomed past the deepest order

computeDeeperTiles returns early and normalCaseDrawOneCell draws the tile whole unless
desiredNorder > norder. At normal zoom tiles are still drawn from 4 corners with 2 triangles:

• SPHEREx at its order-5 zoom: 2.4–2.8 px at mid-latitudes, 62–120 px near the poles.
• Pan-STARRS near the pole: about 120 px at every intermediate order. Elsewhere the error falls
  quickly with order (the fold vertex is 1.4 px at order 6 and 0.04 px at order 11).

Fix: subdivide independently of desiredNorder, e.g. always at least n = 4 at order ≥ 3, and
deeper at high |Dec|. With n = 8 and the current diagonal, 12 208 of the 12 288 order-5 tiles are
under 0.5 px and every tile below |Dec| 75° is under 0.2 px; the rest are handled by (2).

4. Medium: ZoomTask.js:133–137 checks the wrong plot view

else if (isHiPS(primePlot(pv))) {
   let imagePv= getPlotViewById(visRoot, visRoot.mpwWcsPrimId);
   if (!isImage(primePlot(pv))) {          // pv is the HiPS view here -> always true
       imagePv= visRoot.plotViewAry.find( (pv) => isImage(primePlot(pv)));
   }
   if (imagePv) matchImageToHips(pv, imagePv);
}

Inside the isHiPS(primePlot(pv)) branch, !isImage(primePlot(pv)) is always true. The
WCS-primary view (mpwWcsPrimId) is always ignored and the first image in plotViewAry is used,
so with several images open, WCS lock can align to the wrong one. It should be
!isImage(primePlot(imagePv)). The callback parameter pv also shadows the outer pv.

5. Low

• The commit message says "Firefly-2020" and "accuratly"; the branch is FIREFLY-2120.
• With the depth fixed at n = 4, the error in screen pixels grows as you zoom further (0.18 tile
  px is about 46 screen px at 256× past the tile order), though it stays under a fifth of a tile
  pixel. Worth a comment, or tie the subdivision depth to the tile's size on screen.

Suggested change set

1. Draw sub-cells with 2 triangles along the current diagonal (finding 1).
2. Subdivide at normal zoom too, n = 8 by default (finding 3).
3. Refine deeper near the poles (finding 2).
4. Fix the ZoomTask condition (finding 4).

With 1–3, every order-5 tile would be under 0.5 px.

[tgoldina]

Approved. Apart from the ZoomTask bug, the rest can go into a follow-up ticket. This PR is a definite improvement.

[robyww]

Fixing

• item 4: will fix the bug.
• item 1: Use two triangles: have been wrestling with the 2 vs 4 for years so the advice is good and appears to help the rendering.

new ticket

• item 2: need to think about this, I think it makes sense at max order (that is still a lot of tiles!). I am not so sure a maxOrder-1. There are also performance issue I need to evaluate.
• item 3: dealing with the poles: I think that can be done. It needs a lot of testing, recognition of polar hips tiles, and sensitivity to performance.