failing to display healpix fits file

[vincentberenz]

I generated a healpix fits file (nside 1024) using the healpy.write_map function.
I can open with success the generated file on the Aladin desktop application.

I run this cell in a jupyter lab notebook:

from ipyaladin import Aladin, Marker
from pathlib import Path
aladin = Aladin()
aladin

Aladin is displayed correctly.

Followed is this cell:

fits = Path("/path/to/the/file")
aladin.add_fits(Path(fits), name="nightskycam")

(I saw something similar being done here: https://youtu.be/E98vouSlbU4?si=imWYcjPuuaSC3KWa&t=434)

But when running this, nothing seems to get displayed. I see no error message (including in the jupyter lab terminal) or any change in the aladin widget.

Ideally I would like the content of the file, and only the content of the file.

Any pointer on what the issue could be would be welcome.

In case this is useful, the file I am trying to display: https://owncloud.tuebingen.mpg.de/index.php/s/sdxfNgcEaaXoBp7

[bmatthieu3]

Hi @vincentberenz

It does not work because for the moment it is not possible to plot a HEALPix map in aladin lite although this would be a very nice feature to have. aladin.add_fits only plot fits images extensions: https://cds-astro.github.io/ipyaladin/autoapi/ipyaladin/widget/index.html#ipyaladin.widget.Aladin.add_fits

One workaround would be for you to use the aladin.add_moc method (https://cds-astro.github.io/ipyaladin/autoapi/ipyaladin/widget/index.html#ipyaladin.widget.Aladin.add_moc)
where you could pass in the list of HEALPix cell indices of your HEALPix map like that:

aladin.add_moc({"3": [2, 3, 10, ...]})

for a HEALPix map at order 3 that contains the cell 2, 3, 10 and possibly more of this order.

Hope it helps,

[vincentberenz]

Thanks for the answer !

I am new to astronomy, and I am a bit confused about fits format. It seems to me this format is some kind of container for data which can be of different shape and type, and will be parsed based on header specification. In this specific case, it is unclear to me what type of data and headers are supported by ipyaladin, e.g. would it be 2d images and related wcs/sip transforms ? Likely this is either common knowledge or well documented somewhere, apologies if I am missing something obvious.

I am also confused about moc dictionaries. I get the intuition that it is related to healpix hierarchical pixels ordering. But the actual values of the "final" healpix pixels do not seem to be included in the dictionary ?

[bmatthieu3]

FITS is exactly the type of container you describe. You can put in it image, tabular or binary tabular extensions. HEALPix map are stored in FITS file as binary tabular extension. For ipyaladin/aladin lite, only image extension reading is supported for the moment. When parsing an image extension, it may indeed contain some WCS/SIP transforms keywords in the header of that extension that helps to know where the image pixels are precisely located on the sky so this is all related to image extension indeed. There is a thing, it is that image can also be stored as binary table (essentially for compressed images). Then in that case, you might also find WCS/SIP keywords in the header of a binary table extension.

MOC is a HEALPix coverage but it is optimized to minimize the number of HEALPix cell while keeping the coverage intact. When you create it from a healpix map (i.e. a bunch of HEALPix cells at a given order) some 4 neighboring cells that are touching together can be merged into 1 cell of order - 1. The MOC is the addition of all those merged HEALPix cells. Therefore, the coverage of the original HEALPix map and the MOC resulted from it are exactly the same but the cells inside them are not. The MOC contains usually a lot less of cells because some are merged into less resolued HEALPix cells.

Now it depends on what you need/want. If you want to see the full coverage of your healpix map then it is ok to create a MOC from it and plot it in ipyaladin.

But if you want to see all the individual HEALPix cell of your original HEALPix map then you must plot it one by one. For that you can maybe use this method instead: https://cds-astro.github.io/ipyaladin/autoapi/ipyaladin/widget/index.html#ipyaladin.widget.Aladin.add_graphic_overlay_from_region
It plots astropy regions. You can convert one HEALPix cell of your HEALPIx map to an astropy region. Do it for all your HEALPix cells in your map and send that list to that method.

[vincentberenz]

thanks again for your answer.

My final goal: I have an image of the sky encoded as a 1d numpy healpix array nside 1024 (i.e size 12_582_912) and dtype uint8. I would like to display it (or part of it) in ipyaladin.

"HEALPix map are stored in FITS file as binary tabular extension".

I hope I understood your answer. I will try the following function to "convert" my array, but I am always confused about what data FITS header should contain.

import numpy as np
from astropy.io import fits

def nested_array_to_binary_table(data_array, nside=1024, index_scheme='NESTED'):
    """
    Convert a HEALPix array to a FITS binary table extension
    
    Parameters:
    - data_array: numpy array with HEALPix nested ordering
    - nside: HEALPix resolution parameter
    """
    # Create columns for the data and ordering information
    pixel_data = fits.Column(name='PIXEL_VALUES', 
                            format='D',  # Double precision float
                            array=data_array)
    
    # Add HEALPix-specific metadata
    coldefs = fits.ColDefs([pixel_data])
    
    # Create the binary table HDU
    hdu = fits.BinTableHDU.from_columns(coldefs)
    
    # Add essential HEALPix metadata
    hdu.header['PIXTYPE'] = 'HEALPIX'
    hdu.header['ORDERING'] = 'NESTED'  # Specify nested ordering
    hdu.header['NSIDE'] = nside
    hdu.header['INDXSCHM'] = index_scheme
    hdu.header['FIRSTPIX'] = 0
    hdu.header['LASTPIX'] = len(data_array) - 1
    
    return hdu```

[bmatthieu3]

I understood more clearly what is your data. Your file has grayscale values associated to HEALPix cells (covering all the sky at a HEALPix order of 10 i.e. NSIDE = 2^10 = 1024

Unfortunately like I said before, aladin lite (therefore ipyaladin) does not directly read the FITS files storing a hpx map in a binary table.

I did some research and what comes to my mind as a workaround would be to convert a subpart of your hpx map you want to see in a FITS image file (aladin lite can display them).

For that, there is the reproject library which has a method to reproject a hpx map into an image by specifying the wcs you want: https://reproject.readthedocs.io/en/stable/api/reproject.reproject_from_healpix.html

Here is a snippet of code that creates an image of center (lon, lat) = (278.225208, 2.16241667) and resolution = 0.0575 deg/px

from astropy.io import fits
from astropy.wcs import WCS
from reproject import reproject_from_healpix
filename = "nightskycam3_2025_08_07_05_17_30_healpix1024_red.fits"

hdus = fits.open(filename)

target_header = fits.Header.fromstring("""
NAXIS   =                    2
NAXIS1  =                  2048
NAXIS2  =                  2048
CTYPE1  = 'RA---HPX'
CRPIX1  =                  1024
CRVAL1  =           278.225208
CDELT1  =               -0.0575
CUNIT1  = 'deg     '
CTYPE2  = 'DEC--HPX'
CRPIX2  =                 1024
CRVAL2  =           2.16241667
CDELT2  =                0.0575
CUNIT2  = 'deg     '
""", sep='\n')

array, footprint = reproject_from_healpix((hdus[1].data['T'].flatten(), 'galactic'), target_header, nested=True, order="nearest-neighbor")
hdu = fits.PrimaryHDU(array, header=target_header)
hdu.writeto("hpx_image.fits", overwrite=True)

Then you can just drag and drop the fits file into ipyaladin or call the add_fits method on it (I did not test the latter)

[tboch]

Hi,
Don't know if that's use ful in your contexte, but: you can easily convert a HEALPix map to a HiPS structure using Hipsgen (see MAP action in Hipsgen doc: https://aladin.cds.unistra.fr/hips/HipsgenManual.pdf )

[vincentberenz]

@bmatthieu3 @tboch Many thanks for both feedbacks, really helpful. I will try them soon.